# 智能体网络协议SDK

`智能体` `ANP协议` `DID认证` `Python` `开源SDK`

<div align="center">

[English](README.md) | [中文](README.cn.md)

</div>

# AgentConnect

## AgentConnect 是什么

AgentConnect 是 [智能体网络协议（ANP）](https://github.com/agent-network-protocol/AgentNetworkProtocol) 的开源 SDK 实现。

智能体网络协议（ANP）的目标是成为**智能体互联网时代的 HTTP**，为数十亿智能体构建一个开放、安全、高效的协作网络。

<p align="center">
  <img src="/images/agentic-web.png" width="50%" alt="Agentic Web"/>
</p>

## 🔐 为你的智能体添加 DID 认证

想为你的智能体添加去中心化身份认证？请查看 [DID WBA 认证集成指南](examples/python/did_wba_examples/DID_WBA_AUTH_GUIDE.en.md)，快速为任意 Python HTTP 服务添加 DID WBA 认证。

---

## 🚀 快速开始 - 30秒构建 ANP 智能体

OpenANP 是构建 ANP 智能体最简单的方式。只需几行代码即可完成一个完整服务端：

### 服务端（3步）

```python
from fastapi import FastAPI
from anp.openanp import AgentConfig, anp_agent, interface

@anp_agent(AgentConfig(
    name="My Agent",
    did="did:wba:example.com:agent",
    prefix="/agent",
))
class MyAgent:
    @interface
    async def hello(self, name: str) -> str:
        return f"Hello, {name}!"

app = FastAPI()
app.include_router(MyAgent.router())
```

运行：`uvicorn app:app --port 8000`

### 客户端（3行）

```python
from anp.openanp import RemoteAgent

agent = await RemoteAgent.discover("http://localhost:8000/agent/ad.json", auth)
result = await agent.hello(name="World")  # "Hello, World!"
```

### 自动生成的端点

| 端点 | 说明 |
|----------|-------------|
| `GET /agent/ad.json` | 智能体描述文档 |
| `GET /agent/interface.json` | OpenRPC 接口文档 |
| `POST /agent/rpc` | JSON-RPC 2.0 端点 |

📖 **完整示例**：[OpenANP 示例](examples/python/openanp_examples/)

---

## ANP SDK 的两种使用方式

### 🔧 方式一：OpenANP（推荐 - 构建智能体）

构建 ANP 智能体最优雅、最简洁的 SDK：

```python
from anp.openanp import anp_agent, interface, RemoteAgent

# 服务端：构建你的智能体
@anp_agent(AgentConfig(name="Hotel", did="did:wba:...", prefix="/hotel"))
class HotelAgent:
    @interface
    async def search(self, query: str) -> dict:
        return {"results": [...]}

# 客户端：调用远程智能体
agent = await RemoteAgent.discover("https://hotel.example.com/ad.json", auth)
result = await agent.search(query="Tokyo")
```

**特性：**
- **装饰器驱动**：`@anp_agent` + `@interface` = 完整智能体
- **自动生成**：ad.json、interface.json、JSON-RPC 端点
- **上下文注入**：自动管理会话和 DID
- **LLM 集成**：内置 OpenAI Tools 格式导出

📖 **完整文档**：[OpenANP README](anp/openanp/README.md)

---

### 🔍 方式二：ANP 爬虫（文档抓取）

爬虫风格的 SDK，用于抓取和解析 ANP 文档（类似 ANP 的网络爬虫）：

```python
from anp.anp_crawler import ANPCrawler

# 使用 DID 认证初始化爬虫
crawler = ANPCrawler(
    did_document_path="path/to/did.json",
    private_key_path="path/to/key.pem"
)

# 抓取智能体描述并获取 OpenAI Tools 格式
content, tools = await crawler.fetch_text("https://example.com/ad.json")

# 执行已发现的工具
result = await crawler.execute_tool_call("search_poi", {"query": "Beijing"})

# 或直接调用 JSON-RPC
result = await crawler.execute_json_rpc(
    endpoint="https://example.com/rpc",
    method="search",
    params={"query": "hotel"}
)
```

**特性：**
- **爬虫风格**：像网络爬虫一样抓取和解析 ANP 文档
- **OpenAI Tools 格式**：将接口转换为 LLM 集成所需格式
- **直接 JSON-RPC**：无需接口发现即可调用方法
- **无需 LLM**：确定性数据采集

📖 **完整文档**：[ANP Crawler README](anp/anp_crawler/README.md)

---

### RemoteAgent 与 ANPCrawler 对比

| 特性 | RemoteAgent | ANPCrawler |
|---------|-------------|------------|
| **风格** | 代理对象（类似本地方法） | 爬虫（抓取文档） |
| **使用方式** | `agent.search(query="Tokyo")` | `crawler.execute_tool_call("search", {...})` |
| **类型安全** | 完整类型提示、异常处理 | 基于字典的返回值 |
| **适用场景** | 代码中智能体间调用 | LLM 工具集成、数据采集 |

```python
# RemoteAgent：方法调用如同本地调用
agent = await RemoteAgent.discover(url, auth)
result = await agent.search(query="Tokyo")  # 像调用本地方法

# ANPCrawler：爬虫风格的文档抓取
crawler = ANPCrawler(did_path, key_path)
content, tools = await crawler.fetch_text(url)  # 抓取并解析文档
result = await crawler.execute_tool_call("search", {"query": "Tokyo"})
```

---

## 安装

### 方式一：通过 pip 安装
```bash
pip install anp
```

### 方式二：源码安装（推荐开发者使用）

```bash
# 克隆仓库
git clone https://github.com/agent-network-protocol/AgentConnect.git
cd AgentConnect

# 使用 UV 配置环境
uv sync

# 安装可选依赖
uv sync --extra api      # FastAPI/OpenAI 集成
uv sync --extra dev      # 开发工具

# 运行示例
uv run python examples/python/did_wba_examples/create_did_document.py
```

---

## 全部核心模块

| 模块 | 说明 | 文档 |
|--------|-------------|---------------|
| **OpenANP** | 装饰器驱动的智能体开发（推荐） | [README](anp/openanp/README.md) |
| **ANP Crawler** | 轻量级发现与交互 SDK | [README](anp/anp_crawler/README.md) |
| **FastANP** | FastAPI 插件框架 | [README](anp/fastanp/README.md) |
| **AP2** | 智能体支付协议 v2 | [README](anp/ap2/README.md) |
| **Authentication** | DID-WBA 身份认证 | [示例](examples/python/did_wba_examples/) |
| **E2EE HPKE** | 基于 HPKE 的端到端加密（私聊 + 群聊） | [示例](examples/python/e2e_encryption_hpke_examples/) |

---

## 各模块示例

### OpenANP 示例（推荐入门）
位置：`examples/python/openanp_examples/`

| 文件 | 说明 | 复杂度 |
|------|-------------|------------|
| `minimal_server.py` | 最简服务端（约30行） | ⭐ |
| `minimal_client.py` | 最简客户端（约25行） | ⭐ |
| `advanced_server.py` | 完整功能（Context、Session、Information） | ⭐⭐⭐ |
| `advanced_client.py` | 完整客户端（发现、LLM 集成） | ⭐⭐⭐ |

```bash
# 终端1：启动服务端
uvicorn examples.python.openanp_examples.minimal_server:app --port 8000

# 终端2：运行客户端
uv run python examples/python/openanp_examples/minimal_client.py
```

### ANP 爬虫示例
位置：`examples/python/anp_crawler_examples/`

```bash
# 快速开始
uv run python examples/python/anp_crawler_examples/simple_amap_example.py

# 完整演示
uv run python examples/python/anp_crawler_examples/amap_crawler_example.py
```

### DID-WBA 认证示例
位置：`examples/python/did_wba_examples/`

```bash
# 创建 DID 文档
uv run python examples/python/did_wba_examples/create_did_document.py

# 认证演示
uv run python examples/python/did_wba_examples/authenticate_and_verify.py
```

### FastANP 示例
位置：`examples/python/fastanp_examples/`

```bash
# 简单智能体
uv run python examples/python/fastanp_examples/simple_agent.py

# 酒店预订智能体（完整示例）
uv run python examples/python/fastanp_examples/hotel_booking_agent.py
```

### AP2 支付协议示例
位置：`examples/python/ap2_examples/`

```bash
# 完整 AP2 流程（商家 + 购物者）
uv run python examples/python/ap2_examples/ap2_complete_flow.py
```

### E2EE HPKE 加密示例
位置：`examples/python/e2e_encryption_hpke_examples/`

| 文件 | 说明 | 复杂度 |
|------|-------------|------------|
| `basic_private_chat.py` | 一步初始化 + 双向加密消息 + 密钥轮换 | ⭐ |
| `group_chat_example.py` | 三方群聊，使用 Sender Key + epoch 推进 | ⭐⭐⭐ |
| `key_manager_example.py` | 使用 HpkeKeyManager 管理多会话生命周期 | ⭐⭐⭐ |
| `error_handling_example.py` | 错误场景（过期会话、错误密钥、重放攻击） | ⭐⭐⭐ |

```bash
# 基础私聊演示
uv run python examples/python/e2e_encryption_hpke_examples/basic_private_chat.py

# 使用 Sender Key 的群聊
uv run python examples/python/e2e_encryption_hpke_examples/group_chat_example.py

# 密钥管理器与会话生命周期
uv run python examples/python/e2e_encryption_hpke_examples/key_manager_example.py

# 错误处理与边界情况
uv run python examples/python/e2e_encryption_hpke_examples/error_handling_example.py
```

---

## 工具

### ANP 网络探索器
使用自然语言探索智能体网络：[ANP 网络探索器](https://service.agent-network-protocol.com/anp-explorer/)

### DID 文档生成器
```bash
uv run python tools/did_generater/generate_did_doc.py <did> [--agent-description-url URL]
```

---

## 联系我们

- **作者**：GaoWei Chang
- **邮箱**：chgaowei@gmail.com
- **网站**：[https://agent-network-protocol.com/](https://agent-network-protocol.com/)
- **Discord**：[https://discord.gg/sFjBKTY7sB](https://discord.gg/sFjBKTY7sB)
- **GitHub**：[https://github.com/agent-network-protocol/AgentNetworkProtocol](https://github.com/agent-network-protocol/AgentNetworkProtocol)
- **微信**：flow10240

## 许可证

本项目基于 MIT 许可证开源，详情请参阅 [LICENSE](LICENSE) 文件。

---

**版权所有 (c) 2024 GaoWei Chang**