# ACP SDK Full Documentation

> ACP Python SDK - 智能体通信协议标准库完整文档

ACP Python SDK 是基于 ACP 协议的 Agent 标准通信库，用于解决 Agent 间的身份认证及通信问题。

---

## 安装

```bash
pip install agentcp
```

---

## 核心类

### AgentCP

ACP 实例，管理 Agent 生命周期。

```python
from agentcp import AgentCP

acp = AgentCP(
    agent_data_path=".",      # ACP数据路径
    seed_password="123456",   # 加密种子
    debug=True                # 调试模式
)
```

### AgentID

Agent 身份对象，处理消息收发。

---

## API 参考

### 初始化

```python
acp = AgentCP(agent_data_path, seed_password="", debug=False)
```

参数:
- agent_data_path: ACP 数据存储路径
- seed_password: 私钥加密种子
- debug: 是否开启调试日志

### 创建身份

```python
aid = acp.create_aid(ap, name)
```

参数:
- ap: 接入点域名 (如 "agentunion.cn")
- name: Agent 名称标识

返回: AgentID 对象

### 加载身份

```python
aid = acp.load_aid(aid_string)
```

参数:
- aid_string: 完整 AID (如 "myagent.agentunion.cn")

返回: AgentID 对象或 None

### 获取身份列表

```python
aid_list = acp.get_aid_list()
```

返回: AID 字符串列表

### 上线

```python
aid.online()
```

使 Agent 上线，开始监听消息。

### 消息处理器

装饰器方式:

```python
@aid.message_handler()
async def handler(msg):
    content = aid.get_content_from_message(msg)
    aid.reply_message(msg, "回复内容")
    return True
```

方法方式:

```python
aid.add_message_handler(handler)
aid.add_message_handler(handler, session_id=session_id)
aid.remove_message_handler(handler, session_id=session_id)
```

### 消息解析

```python
# 获取消息内容
content = aid.get_content_from_message(msg)

# 获取发送者
sender = aid.get_sender_from_message(msg)

# 获取接收者
receiver = aid.get_receiver_from_message(msg)

# 获取会话ID
session_id = aid.get_session_id_from_message(msg)
```

### 发送消息

快速回复:

```python
aid.reply_message(msg, "回复内容")
```

快速发送:

```python
aid.quick_send_messsage_content(to_aid, content, callback)
aid.quick_send_messsage(to_aid, message, callback)
```

会话消息:

```python
# 创建会话
session_id = aid.create_session(name="会话名", subject="主题")

# 发送文本
aid.send_message_content(to_aid_list, session_id, content)

# 发送消息对象
aid.send_message(session_id, to_aid_list, message)

# 发送流式消息 (可选 type 参数，默认 text/event-stream)
await aid.send_stream_message(to_aid_list, session_id, response, type)
```

### 数据路径

```python
# 公有数据路径
public_path = aid.get_agent_public_path()

# 私有数据路径
private_path = aid.get_agent_private_path()

# 同步公有数据到AP
aid.sync_public_files()
```

### 持续运行

```python
acp.serve_forever()
```

---

## 完整示例

### Hello World

```python
import agentcp

acp = agentcp.AgentCP(".", seed_password="888777")

# 创建接收者
recv = acp.create_aid("agentunion.cn", "receiver")

@recv.message_handler()
async def handler(msg):
    print("收到:", recv.get_content_from_message(msg))
    recv.reply_message(msg, "hello world")
    return True

recv.online()

# 创建发送者
send = acp.create_aid("agentunion.cn", "sender")
send.online()

# 发送消息
send.quick_send_messsage_content(recv.id, "你好", lambda msg: print("回复:", msg))

acp.serve_forever()
```

### LLM Agent

```python
import agentcp
from openai import OpenAI

acp = agentcp.AgentCP(".", seed_password="888777", debug=True)
aid = acp.load_aid("myagent.agentunion.cn")
client = OpenAI(api_key="your_key", base_url="https://api.example.com/v1")

@aid.message_handler()
async def handler(msg):
    content = aid.get_content_from_message(msg)
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": content}]
    )
    aid.reply_message(msg, response.choices[0].message.content)
    return True

aid.online()
acp.serve_forever()
```

### 流式响应

```python
@aid.message_handler()
async def handler(msg):
    content = aid.get_content_from_message(msg)
    sender = aid.get_sender_from_message(msg)
    session_id = aid.get_session_id_from_message(msg)

    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": content}],
        stream=True
    )

    await aid.send_stream_message([sender], session_id, response)
    return True
```

---

## 环境要求

- Python 3.8+
- agentcp 库

---

## 相关资源

- PyPI: https://pypi.org/project/agentcp/
- GitHub: https://github.com/auliwenjiang/agentcp
- Official Site: https://agentunion.cn