AIP: Agent Intent Protocol 规范

版本: 1.0.0-draft
状态: 草案
日期: 2026-06-24
作者: JarvisClaw 团队

摘要

Agent Intent Protocol (AIP) 是一个开放协议，使 AI Agent 能够通过声明式意图来发现、协商和支付其他 AI Agent 或 API 提供者的服务。与传统的 API 集成需要为每个服务编写适配器不同，AIP 允许 Agent 表达需要什么而不是如何获取。

AIP 将三种能力整合到单一协议中：

意图解析 — 将 Agent 需求语义匹配到可用的提供者
支付协商 — 内置价格发现和多轨道支付（x402、余额、信用）
执行编排 — 基于风险评分、预算约束的请求执行

1. 设计原则

原则	描述
意图优先	Agent 声明期望的结果，而非特定端点
支付原生	每次调用都有支付轨道；不存在免费层歧义
提供者无关	提供者注册能力；协议处理路由
风险感知	内置风险评分，防止预算超支和滥用
MCP 兼容	AIP 端点同时作为 MCP 工具暴露以便发现

2. 协议概览

┌──────────────┐         ┌───────────────────────────────┐
│   Agent A    │         │       AIP Gateway             │
│  (消费者)    │         │                               │
│              │  POST   │  ┌─────────┐  ┌───────────┐  │
│  "我需要     │────────▶│  │ 解析    │─▶│ 风险评分  │  │
│   GPT-4 对话 │         │  └─────────┘  └───────────┘  │
│   ≤$0.01"    │         │       │              │       │
│              │         │       ▼              ▼       │
│              │  Result │  ┌─────────┐  ┌───────────┐  │
│              │◀────────│  │ 执行    │◀─│ 支付路由  │  │
│              │         │  └─────────┘  └───────────┘  │
└──────────────┘         └───────────────────────────────┘

3. 核心概念

3.1 意图（Intent）

意图是 Agent 对期望结果的声明性描述。它不指定使用哪个提供者或调用哪个端点。

json

{
  "intent": "chat_completion",
  "preferences": {
    "optimize_for": "cost"
  },
  "constraints": {
    "max_price_usd": 0.01,
    "max_latency_ms": 3000
  },
  "payload": {
    "messages": [{"role": "user", "content": "Hello"}]
  }
}

3.2 支持的意图类型

本地定义 13 种意图类型：

意图	描述	典型提供者
`chat_completion`	LLM 对话补全	OpenAI, Anthropic, Google, DeepSeek
`image_generation`	文生图	GPT-Image, Nano Banana, CogView
`video_generation`	文生视频 / 图生视频	Sora 2, Seedance 2.0
`text_to_speech`	语音合成	ElevenLabs
`web_search`	网络搜索	Surf
`knowledge_search`	语义检索	Exa
`prompt_optimization`	Prompt 优化	平台内置
`code_generation`	代码生成	各 LLM
`translation`	文本翻译	各 LLM
`document_processing`	文档解析	网络节点
`data_analysis`	数据分析	网络节点
`code_execution`	沙箱代码执行	Modal
`utility`	其他工具类服务	网络节点

网络节点会额外贡献更多意图类型（blockchain、geo、dns、email、storage、web、 audio_generation、general 等）。

embedding 与 tool_call 不是有效意图

两者都不在服务端的意图常量表内。文本向量化请直接调用 POST /v1/embeddings；MCP 工具请通过 POST /mcp 的 tools/call 调用。请以 GET /v1/intent/types 返回的实时列表为准。

3.3 解析（Resolution）

解析是匹配意图到提供者的过程。网关考虑：

提供者能力（支持的模型/意图）
价格（匹配预算约束）
延迟（匹配性能约束）
风险评分（基于发送者声誉和请求复杂度）

3.4 支付轨道（Payment Rails）

AIP 支持多种支付机制：

balance — 预存平台余额，即时结算
x402 — 链上 USDC（通过 x402 协议），~2秒结算
credit_async — 后付费信用额度，延迟结算

4. API 端点

4.1 意图解析

POST /v1/intent/resolve

用途: 查找匹配意图的提供者并获取价格估算，不执行。

请求体:

字段	类型	必填	描述
`intent`	string	✅	意图类型
`preferences`	object	❌	优化偏好
`constraints`	object	❌	预算/延迟约束

响应:

json

{
  "matches": [
    {
      "provider_id": "anthropic/claude-sonnet-4.6",
      "score": 0.88,
      "estimated_price_usd": 0.0045,
      "pricing": { "input_per_million": 3.0, "output_per_million": 15.0 },
      "endpoint": "/v1/chat/completions",
      "model": "anthropic/claude-sonnet-4.6",
      "reason": "highest quality within budget"
    }
  ],
  "intent_type": "chat_completion",
  "total_available": 45
}

解析结果不是预留

响应中没有 resolution_id、expires_at、recommended 或 risk_score 字段 —— 解析只是一次排序查询，不锁定价格。排在第一位的即为推荐项。

4.2 意图执行

POST /v1/intent/execute

用途: 解析并执行意图，一步完成。

请求体:

字段	类型	必填	描述
`intent`	string	二选一	意图类型；与 `resource_id` 二选一
`resource_id`	integer	二选一	直接指定网络资源 ID，跳过解析
`payload`	object	❌	转发给提供商的请求体；GET 类端点可省略
`preferences`	object	❌	优化偏好
`constraints`	object	❌	预算/延迟约束
`endpoint`	string	❌	多端点服务内的子路径（含查询串）
`method`	string	❌	转发使用的 HTTP 方法，默认 `POST`

响应（本地 / marketplace 提供商）： 原样透传上游响应体。chat_completion 即标准 OpenAI 格式的补全结果，附带 price 字段。

响应（网络提供商）：

json

{
  "success": true,
  "data": { "...": "上游响应体" },
  "tx_hash": "0xabc123...",
  "cost_usd": 0.0042,
  "upstream_cost": 0.0038,
  "latency_ms": 750,
  "settlement": { "tx_hash": "0xabc123...", "amount": "0.004200", "currency": "USDC", "chain": "base" }
}

没有 execution_id 与 payment_rail 字段，也没有统一的 result 包装层 —— 用 success/data 的存在与否区分两种形态。

4.3 预算执行

POST /v1/intent/execute-budget

注意路径是 execute-budget（连字符），不是 execute/budget。

用途: 在硬预算上限内执行意图：校验预算 → 风险评分 → 选择支付路径 → 预扣 → 执行 → 确认或回滚。

请求体:

json

{
  "intent": "chat_completion",
  "payload": { "messages": [] },
  "budget": {
    "max_total_usd": 1.00,
    "preferred_payment_method": "auto",
    "allow_overdraft": false
  }
}

budget 仅支持这三个字段：max_total_usd（必填）、preferred_payment_method （balance/credit/crypto/auto）、allow_overdraft。没有 prefer、per_call_limit_usd 或 monthly_limit_usd —— 持久化限额请用 PUT /v1/wallet/limits。

4.4 意图发现

GET /v1/intent/discover

用途: 发现平台可用的意图和提供者。

响应:

json

{
  "intents": ["chat_completion", "image_generation", "embedding", "web_search"],
  "providers": [
    { "name": "openai/gpt-4o", "intents": ["chat_completion"], "price_per_1k_tokens": 0.005 }
  ],
  "total": 40
}

4.5 流式执行 / 订阅

POST   /v1/intent/subscribe     # 执行并通过 SSE 流式返回
GET    /v1/intent/subscribe     # 列出当前订阅
DELETE /v1/intent/subscribe/:id # 取消订阅

用途: 通过 Server-Sent Events 流式获取执行结果。

请求体:

json

{
  "intent": "chat_completion",
  "payload": { "messages": [{"role": "user", "content": "写一首诗"}] },
  "stream": true,
  "budget": { "max_total_usd": 0.05 }
}

响应为 event: / data: 事件流。两个 SDK 都做了封装，见 SDK 参考。

没有 cron 调度

/v1/intent/subscribe 是流式执行端点，不是定时任务调度器。请求体不支持 schedule、 webhook_url、per_call_limit_usd 或 monthly_limit_usd；Accept: text/event-stream 也不会让 /v1/intent/execute 变成流式 —— 流式必须走 /subscribe。

4.7 审计日志

GET /v1/intent/audit

用途: 获取编排流水线最近的生命周期日志。不接受任何查询参数。

响应:

json

{
  "entries": [
    {
      "timestamp": "2026-07-06T14:22:01.482Z",
      "request_id": "b6f2c1de-...",
      "user_id": 42,
      "event_type": "settlement_confirmed",
      "details": { "amount_usd": 0.0089, "tx_hash": "0xabc..." }
    }
  ],
  "count": 142
}

event_type 是流水线事件（intent_resolved、budget_validated、risk_flagged、 payment_routed、pre_deducted、execution_started、execution_complete、 execution_failed、settlement_confirmed、settlement_rolled_back），不是意图名称。

不是可分页的账本

没有 from/to/intent/limit/cursor 参数，响应里也没有 next_cursor 或 total_count。数据来自容量 10000 条的内存环形缓冲区。要查消费历史请用下面的分析端点或 GET /v1/wallet/history。

4.8 分析（成本智能）

GET /api/analytics/aggregate   — 聚合后的消费与结算数据
GET /api/analytics/quality     — 分模型的缓存命中率、错误率与延迟
GET /api/analytics/insights    — 对消费与市场日志的深度扫描汇总

公共查询参数：period（24h、7d 默认、30d、90d）、group_by（可取 day、 model、api_source、principal_type、channel、group、client_id，默认 day,model,api_source）、model、user_id，以及 filter_* 系列精确匹配过滤。

AIP 用量出现在同一批数据中，以 api_source="aip" 标识。旧的 /v1/aip/analytics/* 端点已被移除。

示例 — GET /api/analytics/aggregate?period=7d&group_by=day,model:

json

{
  "success": true,
  "data": [
    {
      "day": "2026-07-05",
      "model": "gpt-5.6-terra",
      "total_quota": 182400,
      "total_reqs": 280,
      "total_cost_usd": 9.12,
      "revenue_usd": 10.04,
      "settle_done": 278,
      "settle_failed": 2,
      "delivered": 280,
      "undelivered": 0,
      "loss_usd": 0.07
    }
  ]
}

4.9 网络

公开端点（无需认证）：

GET  /v1/network/search      — 全文搜索网络资源
GET  /v1/network/servers     — 列出网络节点
GET  /v1/network/apis   — 列出网络资源
GET  /v1/network/health      — 节点健康状态
POST /v1/network/recommend   — 资源推荐（deep 档需 x402 支付）

需认证：

POST /v1/network/execute     — 执行网络资源

管理端点（仅管理员）：

GET    /v1/aip/federation/peers   — 列出所有网络节点
POST   /v1/aip/federation/peers   — 添加新网络节点
DELETE /v1/aip/federation/peers   — 删除网络节点
POST   /v1/aip/federation/crawl   — 手动触发节点同步

资源网络允许你的平台发现并聚合来自其他 AIP 兼容平台的服务。网络提供者与本地结果一起出现在 /v1/intent/discover 中。

详见 AIP 网络。

5. 支付轨道

AIP 通过支付路由器支持多种支付机制：

轨道	描述	结算时间	最小金额
`balance`	预存平台余额	即时	$0.0001
`x402`	链上 USDC（通过 x402 协议）	~2秒（Base L2）	$0.001
`credit_async`	后付费信用额度	延迟	$0.01

5.1 x402 支付流程

Agent → AIP Gateway: POST /v1/intent/execute（无支付 header）
                   ← 402 Payment Required + 价格报价
Agent → AIP Gateway: POST /v1/intent/execute + PAYMENT-SIGNATURE header
                   ← 200 OK + 结果 + 结算收据

PAYMENT-SIGNATURE header 包含一个 EIP-712 类型签名，授权在 Base（EIP-155 链 ID 8453）上的 USDC 转账。 X-PAYMENT 是等价的别名，两者同时存在时以 PAYMENT-SIGNATURE 为准。402 响应体同时也会以 base64 编码放在 PAYMENT-REQUIRED 响应头中。

5.2 支付协商

Agent 可以在不执行的情况下探测价格：

POST /v1/intent/resolve → 获取价格估算

然后根据预算约束决定是否继续。

6. MCP 集成

AIP 也可通过 MCP（Model Context Protocol）工具访问，允许任何兼容 MCP 的客户端使用 AIP：

json

POST /mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discover_agents",
    "arguments": {"capability": "image_generation", "max_price": 0.05}
  }
}

可用的 MCP 工具：

网关通用工具：

list_models — 列出可用 AI 模型
chat — 调用任意模型（按次付费）
search_apis — 在市场中查找 API
get_api_detail — 获取 API 定价和 schema
discover_agents — 按能力查找 Agent
uapi_{slug} — 每个已发布用户 API 各对应一个工具

AIP 专用工具：

aip_resolve — 对应 POST /v1/intent/resolve
aip_execute_with_budget — 对应 POST /v1/intent/execute-budget
aip_list_intents — 对应 GET /v1/intent/types
aip_estimate_cost — 本地成本估算，无对应 HTTP 端点

工具名均为扁平的下划线命名，不带 jarvisclaw/ 前缀。/v1/intent/execute、 /v1/intent/resolve/natural 和 /v1/intent/audit 没有对应的 MCP 工具，需直接走 HTTP。

7. 风险评分

每次执行在处理前都会经过风险评分器：

风险评分 = f(金额, 频率, 发送者声誉, 意图复杂度)

评分范围	操作
0.0 – 0.3	允许（低风险）
0.3 – 0.7	允许，增强日志
0.7 – 0.9	要求额外验证
0.9 – 1.0	拒绝

8. 错误处理

AIP 端点返回扁平的 {"error": "<消息>"} 结构，没有稳定的机器可读错误码字段。请按 HTTP 状态码分支处理：

状态码	场景
400	请求体格式错误，或约束值非法（如 `max_price_usd` 非正数）；`resource_id` 与 `intent` 均缺失
401	预算执行/网络调用缺少认证上下文
402	需要 x402 支付，或网络结算失败
403	预算被拒绝（`status: "rejected"`）或被风险拦截（`"risk_blocked"`）
404	没有提供者匹配意图，或 `resource_id` 不在注册表中
429	触发限流（如推荐端点 20 次/分钟）
500	解析器或编排器内部错误（`status: "error"`）
502	上游执行失败且无本地回退
503	节点被禁用或不健康

/v1/intent/execute-budget 会同时用响应体的 status 字段表达结果（success、rejected、 error、risk_blocked），两处都需要检查。

9. 与现有协议对比

特性	AIP	x402	A2A (Google)	MCP
意图解析	✅	❌	❌	❌
支付原生	✅	✅	❌	❌
提供者发现	✅	❌	✅	✅ (tools/list)
风险评分	✅	❌	❌	❌
预算约束	✅	❌	❌	❌
多支付轨道	✅	仅 USDC	N/A	N/A
流式传输	✅ (SSE)	❌	✅	✅ (SSE)

10. 实现状态

Gateway: api.jarvisclaw.ai
MCP 端点: api.jarvisclaw.ai/mcp
A2A 端点: api.jarvisclaw.ai/a2a（发现文件 /.well-known/agent-card.json）
支持的意图: 本地 13 种 + 网络节点贡献的更多类型（以 GET /v1/intent/types 为准）
支付轨道: balance, x402 (Base / Solana USDC), credit_async
提供者: 本地 72 个模型 + 资源网络（规模见 GET /v1/network/stats）

11. 快速开始

bash

# 1. 查看支持的意图类型（免费，无需认证）
curl https://api.jarvisclaw.ai/v1/intent/types

# 2. 解析意图（需认证 —— POST 形式会消耗 embedding 资源）
curl -X POST https://api.jarvisclaw.ai/v1/intent/resolve \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"intent":"chat_completion","preferences":{"optimize_for":"cost"}}'

# 3. 使用 API Key 执行
curl -X POST https://api.jarvisclaw.ai/v1/intent/execute \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"intent":"chat_completion","payload":{"messages":[{"role":"user","content":"Hello"}]}}'

# 4. 使用 x402 执行（无需账户）
# 首次调用不带支付头会返回 402 + 报价，签名后重试即可
curl -X POST https://api.jarvisclaw.ai/v1/intent/execute \
  -H "PAYMENT-SIGNATURE: <eip712-signed-usdc-authorization>" \
  -H "Content-Type: application/json" \
  -d '{"intent":"chat_completion","payload":{"messages":[{"role":"user","content":"Hello"}]}}'

AIP 是一个开放协议。欢迎实现和扩展。

AIP: Agent Intent Protocol 规范 ​

摘要 ​

1. 设计原则 ​

2. 协议概览 ​

3. 核心概念 ​

3.1 意图（Intent） ​

3.2 支持的意图类型 ​

3.3 解析（Resolution） ​

3.4 支付轨道（Payment Rails） ​

4. API 端点 ​

4.1 意图解析 ​

4.2 意图执行 ​

4.3 预算执行 ​

4.4 意图发现 ​

4.5 流式执行 / 订阅 ​

4.7 审计日志 ​

4.8 分析（成本智能） ​

4.9 网络 ​

5. 支付轨道 ​

5.1 x402 支付流程 ​

5.2 支付协商 ​

6. MCP 集成 ​

7. 风险评分 ​

8. 错误处理 ​

9. 与现有协议对比 ​

10. 实现状态 ​

11. 快速开始 ​

AIP: Agent Intent Protocol 规范

摘要

1. 设计原则

2. 协议概览

3. 核心概念

3.1 意图（Intent）

3.2 支持的意图类型

3.3 解析（Resolution）

3.4 支付轨道（Payment Rails）

4. API 端点

4.1 意图解析

4.2 意图执行

4.3 预算执行

4.4 意图发现

4.5 流式执行 / 订阅

4.7 审计日志

4.8 分析（成本智能）

4.9 网络

5. 支付轨道

5.1 x402 支付流程

5.2 支付协商

6. MCP 集成

7. 风险评分

8. 错误处理

9. 与现有协议对比

10. 实现状态

11. 快速开始