# acp-py

Python Agent SDK - 基于 AgentCP 协议的智能体通信库

## 安装

```bash
pip install acp-py
```

## 快速开始

```bash
# 启动（默认 Web 模式，自动打开浏览器）
acp-py

# 指定种子密码
acp-py -p my_password

# 指定数据目录和端口
acp-py -d ./my-data --port 8080

# 不自动打开浏览器
acp-py --no-browser

# 使用 CLI 交互模式
acp-py --cli
```

启动后浏览器会自动打开 `http://localhost:9528`，在 Web 页面中可以创建 Agent、上线、发起会话和收发消息。

## CLI 参数

```
acp-py [选项]

选项:
  -d, --data <path>      数据目录 (默认: ./acp-data)
  -p, --password <pwd>   种子密码 (默认: agentcp@2025)
  -n, --name <name>      Agent 名称 (默认: 自动生成)
  -t, --target <aid>     目标 Agent AID (CLI 模式下直接发送消息)
  --ap <address>         AP 地址 (默认: aid.pub)
  --port <number>        Web 服务端口 (默认: 9528)
  --cli                  使用 CLI 交互模式 (不启动 Web)
  --no-browser           不自动打开浏览器
  --debug                启用调试模式
```

### 种子密码优先级

环境变量 > CLI 参数 > 默认值

```bash
# 通过环境变量设置（推荐用于部署）
export ACP_SEED_PASSWORD=my_password
acp-py
```

## CLI 交互命令

使用 `--cli` 模式启动后，可以使用以下命令：

| 命令 | 说明 |
|------|------|
| `/target <aid>` | 设置目标 Agent |
| `/session` | 显示当前会话信息 |
| `/aid` | 显示本机 AID |
| `/help` | 显示帮助 |
| `/quit` | 退出 |
| 其他输入 | 发送消息给目标 |

## 自定义 Agent 开发

```python
from agentcp import AgentCP

# 创建 AgentCP 实例
acp = AgentCP("./data", seed_password="your_password")

# 创建 Agent
aid = acp.create_aid(ap="aid.pub", agent_name="my_agent")
print(f"Agent AID: {aid.id}")

# 注册消息处理器
async def handle_message(data):
    print(f"收到消息: {data}")

aid.add_message_handler(handle_message)

# 上线
aid.online()

# 发送消息
session_id = aid.create_session("my_session", "测试会话")
aid.invite_member(session_id, "target_agent.aid.pub")
aid.send_message(session_id, ["target_agent.aid.pub"], "Hello!")

# 保持运行
acp.serve_forever()
```

## 调度器环境变量

以下环境变量用于调整消息调度器的并发参数（可选）：

- `AGENTCP_SCHED_CORE_WORKERS` — 核心线程数（常驻）
- `AGENTCP_SCHED_MAX_WORKERS` — 最大线程数（高峰扩展）
- `AGENTCP_SCHED_MAX_TASKS_PER_WORKER` — 每线程最大并发异步任务数

## 系统要求

- Python >= 3.8
- macOS / Linux / Windows

## License

MIT
