320 lines
9.3 KiB
Markdown
320 lines
9.3 KiB
Markdown
# 智能体网络协议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** |