内容
# 异步简单代理协议（ASAP）
*✨ 为代理而生，由代理创造。尽早交付可靠性。*
> 面向代理间通信和任务协调的实用协议。
**快速信息**：[`v2.5.4`](https://github.com/asap-protocol/asap-protocol/releases/tag/v2.5.4) · PyPI [`asap-protocol`](https://pypi.org/project/asap-protocol/) | `Apache 2.0` | `Python 3.13+` | [文档](docs/index.md) | [更新日志](CHANGELOG.md)
> 📦 **安装** — [`asap-protocol` **2.5.4** on PyPI](https://pypi.org/project/asap-protocol/) (Python) · [`@asap-protocol/client` on npm](https://www.npmjs.com/package/@asap-protocol/client) (TypeScript)
🚀 **立即启动** 我们的 [**代理市场**](https://asap-protocol.com/) — 浏览代理，注册您的代理，请求验证。
## 为什么选择 ASAP？
多代理系统面临三个挑战，而点对点代理协议往往会留下这些问题：
1. **连接扩展** — 成对 HTTP 无法扩展，因为协调器逐渐增加。
2. **状态漂移** — 长工作流在没有持久任务状态和可恢复性的情况下停滞。
3. **碎片化** — 委托、工件和 MCP 工具调用最终出现在不兼容的层中。
**ASAP** 通过以下方式回答这些问题：
- **可恢复的编排** — 任务状态机、快照存储、SSE 流式传输和内置 `trace_id` / `correlation_id`。
- **一种类型化的信封** — 任务、MCP 工具执行和工件交换在同一 JSON 模式契约上。
- **生产信任** — Ed25519 签名清单、主机/代理 JWT、约束能力、OAuth2、选择性 WebAuthn — 以及 **MCP 授权桥**（v2.5.0）用于作用域原生 `tools/call`。
- **生态系统就绪** — [代理市场](https://asap-protocol.com/)、Lite 注册表、边缘 AI 发现、OpenAPI 导入和框架适配器（[Python 和 npm](#框架生态系统)）。
普通的 HTTP 代理间通信足以应对最简单的场景。ASAP 适用于 **多代理编排**、**有状态工作流** 和 **受控能力访问** 在生产环境中 — 请参阅 [文档](docs/index.md) 和下面的功能表。
### 主要功能
| 领域 | 亮点 | 文档 |
| --- | --- | --- |
| 有状态编排 | 任务状态机、快照、可恢复的工作流 | [状态管理](docs/state-management.md) |
| 模式优先 | Pydantic v2 + JSON 模式用于跨代理交换 | [API 参考](docs/api-reference.md) |
| 异步原生 | `asyncio` + `httpx`；同步和异步处理程序 | [传输](docs/transport.md) |
| MCP 集成 | 工具执行和协调在一个信封中（模式 B） | [MCP 集成](docs/mcp-integration.md) |
| MCP 授权桥 | 选择加入代理 JWT + 原生 stdio MCP `tools/call` 上的能力授予（模式 A） | [MCP 授权桥](docs/adapters/mcp-auth-bridge.md) |
| 可观察性 | 用于调试的 `trace_id` 和 `correlation_id` | [可观察性](docs/observability.md) |
| 安全性 | OAuth2/JWT、Ed25519 清单、mTLS、速率限制 | [安全性](docs/security.md) |
| 身份和能力 | 主机/代理 JWT、约束授予、批准流程、选择性 WebAuthn | [能力](docs/capabilities/index.md) |
| 流式传输和线缆协议 | SSE `/asap/stream`、JSON-RPC 批处理、`ASAP-Version` 协商 | [传输](docs/transport.md) |
| 采用工具 | OpenAPI 适配器、`@asap-protocol/client`、自动注册、升级 | [迁移（v2.2 → v2.3）](docs/migration.md#upgrading-from-v22x-to-v230) |
| 边缘 AI 发现 | 硬件/推理清单、注册表镜像、市场过滤器 | [ShellClaw 指南](docs/guides/shellclaw-registry.md) |
| 框架适配器（npm） | `@asap-protocol/mastra` 和 `@asap-protocol/openai-agents` 工具桥 | [Mastra](docs/integrations/mastra.md) · [OpenAI 代理](docs/integrations/openai-agents.md) |
| 经济学 | 使用计量、委托令牌、SLA 违规警报 | [审计日志](docs/audit.md) |
完整概述和升级路径：[docs/index.md](docs/index.md).
### 框架生态系统
ASAP 在代理运行时提供支持 — 可选的 Python 额外功能、npm 工具桥和协议原生 MCP。
| 运行时 | 集成 | 文档 |
| --- | --- | --- |
| **Python** | LangChain、CrewAI、LlamaIndex、PydanticAI、SmolAgents、OpenClaw (`pip install "asap-protocol[extra]"`); Vercel AI SDK 路由器；MCP；MCP 授权桥；A2H；OpenAPI 工作流连接器（实验室 II） | [OpenClaw](docs/guides/openclaw-integration.md) · [Vercel AI SDK](docs/guides/vercel-ai-sdk.md) · [MCP](docs/mcp-integration.md) · [MCP 授权桥](docs/adapters/mcp-auth-bridge.md) · [工作流连接器](docs/integrations/workflow-connectors.md) · [NeMo 代理工具包](docs/integrations/nemo-agent-toolkit.md)（实验性） |
| **TypeScript**（npm） | `@asap-protocol/client`（Vercel AI / OpenAI / Anthropic 适配器）、`@asap-protocol/mastra`、`@asap-protocol/openai-agents` | [TypeScript SDK](docs/sdks/typescript.md) · [Mastra](docs/integrations/mastra.md) · [OpenAI 代理](docs/integrations/openai-agents.md) · [微软代理框架](docs/integrations/microsoft-agent-framework.md)（研究） |
## 安装
我们推荐使用 [uv](https://github.com/astral-sh/uv) 进行依赖管理：
```bash
uv add asap-protocol # PyPI 上最新的 asap-protocol（目前为 2.5.4）
```
或使用 pip：
```bash
pip install asap-protocol==2.5.4
```
**TypeScript**（npm，**`2.4.1`** — 不变的 v2.5.4；`@asap-protocol/mcp-auth` HTTP 中间件仍延迟）：
- [`@asap-protocol/client`](https://www.npmjs.com/package/@asap-protocol/client) — [SDK 文档](docs/sdks/typescript.md)
- [`@asap-protocol/mastra`](https://www.npmjs.com/package/@asap-protocol/mastra) — [文档](docs/integrations/mastra.md) · [演示](apps/example-mastra/README.md)
- [`@asap-protocol/openai-agents`](https://www.npmjs.com/package/@asap-protocol/openai-agents) — [文档](docs/integrations/openai-agents.md) · [演示](apps/example-openai-agents/README.md)
```bash
npm install @asap-protocol/client@2.4.1
npm install @asap-protocol/mastra@2.4.1 @asap-protocol/client @mastra/core zod
npm install @asap-protocol/openai-agents@2.4.1 @asap-protocol/client @openai/agents zod
```
**Python v2.5.4**（分发循环）已**发布** — 请参阅 [迁移（v2.5.3 → v2.5.4）](docs/migration.md#upgrading-from-v253-to-v254)。从这里开始：[为代理构建](docs/guides/build-for-agents.md) · [启动器](examples/starters/README.md).
## 快速入门
**运行演示**（回声代理 + 协调器在一个命令中）：
```bash
uv run python -m asap.examples.run_demo
```
**构建您的第一个代理** [此处](docs/tutorials/first-agent.md) — 服务器设置、客户端代码、逐步指南（~15 分钟）。
[19 个示例](src/asap/examples/README.md)：编排、状态迁移、MCP、OAuth2、WebSocket、弹性。
## 测试
```bash
uv run pytest -n auto --tb=short
```
使用覆盖率（单独运行 — 不要与 `-n auto` 结合）：
```bash
uv run pytest --tb=short --cov=asap --cov-report=term-missing --cov-fail-under=85
```
[测试指南](https://github.com/asap-protocol/asap-protocol/blob/main/docs/testing.md)（结构、固定装置、属性/负载/混沌测试）。 [贡献](https://github.com/asap-protocol/asap-protocol/blob/main/CONTRIBUTING.md)（开发设置、CI）。
### 合规性测试
验证您的代理是否遵循 ASAP 协议：
```bash
uv add "asap-compliance>=1.3.0"
pytest --asap-agent-url https://your-agent.example.com -m asap_compliance
```
对于 **MCP 授权桥** stdio 门（`mcp-auth-bridge` 配置文件），请使用 **`asap-compliance` 1.3.0+** 和 **`asap-protocol` 2.5.0+** — 在 PyPI 上通过标签 [`v2.5.0.1`](https://github.com/asap-protocol/asap-protocol/releases/tag/v2.5.0.1) 发布。
请参阅 [合规性测试指南](https://github.com/asap-protocol/asap-protocol/blob/main/docs/guides/compliance-testing.md)，了解握手、模式和状态机验证。
## 文档
**学习**
- [文档](docs/index.md) | [API 参考](docs/api-reference.md)
- [MCP 授权桥](docs/adapters/mcp-auth-bridge.md) — v2.5.0 选择加入 JWT + 原生 stdio MCP
- [TypeScript 客户端 SDK](docs/sdks/typescript.md) — `@asap-protocol/client`（身份、能力、流式传输、适配器）
- [教程](https://github.com/asap-protocol/asap-protocol/tree/main/docs/tutorials) — 从第一个代理到生产环境的检查清单
- [迁移自 A2A/MCP](https://github.com/asap-protocol/asap-protocol/blob/main/docs/migration.md)
- [原始 Fetch（非 Python）](https://github.com/asap-protocol/asap-protocol/blob/main/docs/raw-fetch.md) — 使用 curl/fetch 获取 registry.json 和 revoked_agents.json；实现您自己的客户端。
**深入探讨**
- [状态管理](https://github.com/asap-protocol/asap-protocol/blob/main/docs/state-management.md) | [最佳实践：故障转移和迁移](https://github.com/asap-protocol/asap-protocol/blob/main/docs/best-practices/agent-failover-migration.md) | [错误处理](https://github.com/asap-protocol/asap-protocol/blob/main/docs/error-handling.md)
- [传输](https://github.com/asap-protocol/asap-protocol/blob/main/docs/transport.md) | [安全性](https://github.com/asap-protocol/asap-protocol/blob/main/docs/security.md) | [安全模型](https://github.com/asap-protocol/asap-protocol/blob/main/docs/security/v1.1-security-model.md)（OAuth2 信任、自定义声明）
- [身份签名](https://github.com/asap-protocol/asap-protocol/blob/main/docs/guides/identity-signing.md) | [合规性测试](https://github.com/asap-protocol/asap-protocol/blob/main/docs/guides/compliance-testing.md) | [迁移 v1.1 到 v1.2](https://github.com/asap-protocol/asap-protocol/blob/main/docs/guides/migration-v1.1-to-v1.2.md) | [mTLS](https://github.com/asap-protocol/asap-protocol/blob/main/docs/security/mtls.md)
- [可观察性](https://github.com/asap-protocol/asap-protocol/blob/main/docs/observability.md) | [测试](https://github.com/asap-protocol/asap-protocol/blob/main/docs/testing.md)
**决策与运营**
- [ADR](https://github.com/asap-protocol/asap-protocol/tree/main/docs/adr) — 19 个架构决策记录
- [技术栈](https://github.com/asap-protocol/asap-protocol/blob/main/engineering/architecture/tech-stack-decisions.md) — Python、Pydantic、Next.js 选择的理由
- [部署](https://github.com/asap-protocol/asap-protocol/blob/main/docs/deployment/kubernetes.md) | [故障排除](https://github.com/asap-protocol/asap-protocol/blob/main/docs/troubleshooting.md)
**发布**
- [更新日志](https://github.com/asap-protocol/asap-protocol/blob/main/CHANGELOG.md) | **[PyPI 列表](https://pypi.org/project/asap-protocol/)** — `https://pypi.org/project/asap-protocol/`（安装：`pip install asap-protocol`)
## 命令行界面
```bash
asap --version # 显示版本
asap list-schemas # 列出 JSON 模式
asap export-schemas # 将模式导出到磁盘
asap validate-schema payload.json # 验证 JSON 是否符合模式
asap compliance-check --url https://agent.example # 远程合规性测试 v2
asap audit export --store memory --format json # 导出审计日志（标准输出）
asap keys generate -o key.pem # Ed25519 密钥对
asap manifest sign -k key.pem manifest.json # 签名代理清单
asap delegation create -d <urn> -s read -k key.pem --delegator <urn>
asap trace <trace-id> --log-file asap.log # 从日志中可视化请求流
```
请参阅 [docs/cli.md](docs/cli.md) 获取委托令牌、模式验证、跟踪可视化、REPL 和完整的标志引用。运行 `asap --help` 获取您已安装的版本。
## 版本历史
仅限高级别 — 请参阅 **[更新日志](https://github.com/asap-protocol/asap-protocol/blob/main/CHANGELOG.md)** 和 **[文档索引](https://github.com/asap-protocol/asap-protocol/blob/main/docs/index.md#v11-features-api-reference--guides)** 获取完整的注释。
| 版本 | 已发布内容 |
| :-- | :-- |
| **v2.5.4** | **分发循环** — **[GitHub Release `v2.5.4`](https://github.com/asap-protocol/asap-protocol/releases/tag/v2.5.4)** · 精简启动器（`examples/starters/`）、[为代理构建](docs/guides/build-for-agents.md)、主页代理优先 CTAs、遥测操作（无公共指标 UI）。请参阅 [CHANGELOG](CHANGELOG.md#254---2026-07-18)、[PRD](product/prd/prd-v2.5.4-distribution-loop.md) 和 [迁移（v2.5.3 → v2.5.4）](docs/migration.md#upgrading-from-v253-to-v254) |
| **v2.5.3** | **适配器实验室 II** — **[GitHub Release `v2.5.3`](https://github.com/asap-protocol/asap-protocol/releases/tag/v2.5.3)** · 工作流 OpenAPI 连接器 + 安全指南、实验性 MAF / NeMo 指南、JSON 安全 `-32602`、MCP 示例客户端 DX。请参阅 [CHANGELOG](CHANGELOG.md#253---2026-07-14)、[PRD](product/prd/prd-v2.5.3-adapter-lab-ii.md) 和 [迁移（v2.5.2 → v2.5.3）](docs/migration.md#upgrading-from-v252-to-v253) |
| **v2.5.2** | **安全和正确性后续工作** — 选择加入操作员 API 身份验证、`extra="forbid"` 引入、Redis JTI 重放、Web 分布式速率限制、v2.5.1 CR 后续工作（#245–#249）、注册表签名清单/400 修复。请参阅 [CHANGELOG](CHANGELOG.md#252---2026-07-08)、[PRD](product/prd/prd-v2.5.2-security-follow-up.md) 和 [迁移（v2.5.1 → v2.5.2）](docs/migration.md#upgrading-from-v251) |
| **v2.5.1** | **代码质量补丁** — 行为保留重构（传输/服务器、客户端、WebSocket、SQLite 存储、身份验证、集成）+ 六个正确性/安全修复（原子 `revoke_cascade`、`usage_events` DDL、统一主机 JWT 验证器、**WebSocket 现在使用 OAuth2**、OpenAPI 处理程序清理、客户端 `correlation_id` 绑定）。已弃用 v2.6.0 中的导入路径。请参阅 [CHANGELOG](CHANGELOG.md#251---2026-06-25) 和 [迁移（v2.5.0 → v2.5.1）](docs/migration.md#upgrading-from-v250-to-v251) |
| **v2.5.0.1** | **合规发布** — **[GitHub Release `v2.5.0.1`](https://github.com/asap-protocol/asap-protocol/releases/tag/v2.5.0.1)** · PyPI **`asap-compliance` 1.3.0**（`mcp-auth-bridge` 配置文件；需要 `asap-protocol>=2.5.0`）。无 `asap-protocol` API 更改。请参阅 [CHANGELOG](CHANGELOG.md#2501---2026-06-24) |
| **v2.5.0** | **MCP 授权桥** — **[GitHub Release `v2.5.0`](https://github.com/asap-protocol/asap-protocol/releases/tag/v2.5.0)** · 选择加入 `protect_server` 以获取 stdio MCP；代理 JWT + 能力授予；参考示例 `examples/mcp_auth_bridge/`。请参阅 [CHANGELOG](CHANGELOG.md#250---2026-06-24) 和 [迁移（v2.4.1 → v2.5.0）](docs/migration.md#upgrading-from-v241-to-v250) |
| **v2.4.1** | **安全强化** — OAuth2 `iss`/`aud`、故障关闭身份绑定、Web SSRF/重定向修复、依赖项提升。请参阅 [CHANGELOG](CHANGELOG.md#241---2026-06-14) 和 [迁移（v2.4.0 → v2.4.1）](docs/migration.md#upgrading-from-v240-to-v241) |
| **v2.4.0** | **边缘 AI 发现** — 可选 `hardware` / `inference` 清单字段、注册表镜像、市场过滤器、 **`@asap-protocol/client@2.4.0`**、ShellClaw 入站文档。请参阅 [CHANGELOG](CHANGELOG.md#240---2026-05-24) 和 [迁移（v2.3.x → v2.4.0）](docs/migration.md#upgrading-from-v23x-to-v240) |
| **v2.3.1** | **npm TypeScript 补丁** — **[GitHub Release `v2.3.1`](https://github.com/asap-protocol/asap-protocol/releases/tag/v2.3.1)** · **`@asap-protocol/mastra`**、 **`@asap-protocol/openai-agents`**、 **`@asap-protocol/client@2.3.1`**（添加适配器导出）。Python **2.3.0** 不变。请参阅 [CHANGELOG](https://github.com/asap-protocol/asap-protocol/blob/main/CHANGELOG.md#231---2026-05-20) 和 [迁移（v2.3.0 → v2.3.1）](https://github.com/asap-protocol/asap-protocol/blob/main/docs/migration.md#upgrading-from-v230-to-v231) |
| **v2.3.0** | **OpenAPI 适配器** (`[openapi]`) · **TypeScript 客户端** (`@asap-protocol/client`) · **自动注册** · **能力升级** · **ASAP HTTP 挑战** — 请参阅 [CHANGELOG](https://github.com/asap-protocol/asap-protocol/blob/main/CHANGELOG.md#230---2026-05-04) 和 [迁移](https://github.com/asap-protocol/asap-protocol/blob/main/docs/migration.md#upgrading-from-v22x-to-v230) |
| **v2.2.1** | 选择加入 **WebAuthn** (`asap-protocol[webauthn]`) · `asap compliance-check` & `asap audit export` · 严格的 `ResolvedAgent.run()` · `AuditChainBroken` · [固定安全依赖项](https://github.com/asap-protocol/asap-protocol/blob/main/SECURITY.md#dependency-policy) |
| **v2.2** | 每个运行时身份和能力身份验证 · SSE `POST /asap/stream` · `ASAP-Version` · JSON-RPC 批处理 · 防篡改审计 · 异步状态存储 · 合规性测试 v2 |
| **v2.1.1** | 补丁：JWT 允许列表 · SQLite 异步桥 · 可选 Redis 速率限制 · Web SSRF 强化 |
| **v2.1** | `MarketClient` · 框架额外功能（LangChain、CrewAI、LlamaIndex、…）· 注册表 UX |
| **v2.0** | 市场网络应用 · 精简注册表（GitHub Pages）· 问题操作 · OAuth · 验证流程 |
| **v1.3** | `asap delegation create` / `revoke` |
| **v1.2** | Ed25519 清单 · 信任级别 · 可选 mTLS · [合规性测试](https://github.com/asap-protocol/asap-protocol/blob/main/asap-compliance/README.md) |
| **v1.1** | OAuth2 · WebSocket · 发现（知名 + 精简注册表）· SQLite 状态 · Webhook |
## 🔭 下一步是什么？
[代理市场](https://asap-protocol.com/) 和精简注册表已上线。 **v2.5.x 列车** 关注互操作性和采用：
- **v2.5.5** — 正式规范和互操作性（RFC、内省、私人保护）
- **`@asap-protocol/mcp-auth`**（npm）— HTTP/SSE MCP 中间件
- **正式规范轨道**（v2.5.5）— 内省、私人保护、跨协议互操作，迈向 v3.0 经济
请参阅 [v2.5 路线图 PRD](https://github.com/asap-protocol/asap-protocol/blob/main/product/prd/prd-v2.5-roadmap.md) 和 [ADR 索引](https://github.com/asap-protocol/asap-protocol/blob/main/product/decision-records/README.md).
## 贡献
**社区反馈和贡献** 对于 ASAP 协议的演进至关重要。 我们正在改进，您们的输入有助于塑造协议的未来。
每种贡献，从错误报告到功能建议、文档改进和代码贡献，都产生了真正的影响。
查看我们的 [贡献指南](https://github.com/asap-protocol/asap-protocol/blob/main/CONTRIBUTING.md) 以开始。 这比您想象的要容易！ 🚀
## 联系
| 频道 | 用途 |
| --- | --- |
| [GitHub Discussions](https://github.com/asap-protocol/asap-protocol/discussions) 或 [Issues](https://github.com/asap-protocol/asap-protocol/issues) | 公共问题、错误和功能想法 |
| [info@asap-protocol.com](mailto:info@asap-protocol.com) | 私人协调 — 协议、市场、合作伙伴、新闻 |
| [SECURITY.md](SECURITY.md) | 仅限安全漏洞 — **不要** 使用电子邮件或公共问题 |
## 隐私
请参阅 [PRIVACY.md](PRIVACY.md)，了解公共网站和维护者遥测如何使用聚合指标（包括 Vercel Web Analytics），而无需收集代理 ID 或最终用户 PII。
## 许可证
该项目根据 Apache 2.0 许可证获得许可 — 请参阅 [许可证](https://github.com/asap-protocol/asap-protocol/blob/main/LICENSE) 文件以获取详细信息。
---
**由 [Cursor](https://cursor.com/) 构建**，使用 Composer、Opus、Gemini、Kimi 等。
连接信息
猜你喜欢
暂无推荐服务器