Agent 经济 (AIP)

Agent Intent Protocol 让自主 Agent 发现最优 AI 供应商、管理预算、并只为使用的部分付费 — 全部通过单一 API 完成。

工作原理

Agent 声明意图 → AIP 找到最佳供应商 → Agent 调用模型 → 钱包追踪消费

1. 意图解析（免费）— 声明你需要什么，获取排名后的供应商列表
2. 执行 — 用你的 API Key 或 x402 支付调用推荐的模型
3. 钱包管理 — 查看余额、设置限额、追踪消费池

快速开始

找到最佳模型

curl

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",
    "constraints": { "max_price_usd": 0.01 },
    "preferences": { "optimize_for": "cost" }
  }'

Python

from jarvisclaw import Agent

agent = Agent(api_key="sk-YOUR-KEY")

# 一行代码：找到最佳模型 + 调用它
result = agent.ask("解释量子计算", budget=0.01, optimize="cost")
print(result)

Go

import jc "github.com/api-jarvisclaw/go-sdk/v2"

c, _ := jc.NewClient(jc.WithAPIKey("sk-YOUR-KEY"))
text, _ := c.Ask(ctx, "解释量子计算",
    jc.AskOptions{Budget: 0.01, Optimize: "cost"})
fmt.Println(text)

响应

{
  "matches": [
    {
      "provider_id": "deepseek-chat",
      "score": 0.95,
      "estimated_price_usd": 0.0003,
      "endpoint": "/v1/chat/completions",
      "model": "deepseek-chat",
      "reason": "最低成本: $0.000300/请求"
    }
  ],
  "intent_type": "chat_completion",
  "total_available": 45
}

使用推荐的模型

curl https://api.jarvisclaw.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR-KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "你好！"}]}'

意图类型

意图	描述	示例模型
chat_completion	文本生成 / 对话	GPT-5.x, Claude 4.x, DeepSeek, Gemini 3.x
image_generation	图像创建	GPT-Image, Nano Banana, CogView, Grok Imagine
video_generation	视频合成	Sora 2, Seedance 2.0
text_to_speech	文本转语音	ElevenLabs
web_search	网络搜索	Surf (83 个端点)
knowledge_search	语义搜索	Exa

本地定义 13 种意图类型，网络节点还会贡献更多。详见 AIP → 支持的意图类型，或查询 GET /v1/intent/types 获取实时列表。

优化策略

策略	行为
cost	满足约束的最低成本模型 （默认）
quality	最高质量评分（基于基准测试）
latency	最快响应时间（P95 实测）
budget	重点权衡支付开销 —— 适合极紧的单次预算

约束条件

{
  "constraints": {
    "max_price_usd": 0.01,
    "max_latency_ms": 3000,
    "features": ["function_calling", "vision", "streaming"]
  }
}

认证

发现类接口免费且无需认证 —— GET /v1/intent/types、GET /v1/providers 和 GET /v1/network/stats 都不需要凭证。

排序解析和所有执行路径需要认证：它们会消耗 embedding 与上游资源。支持三种方式：

方式	请求头	使用场景
API Key	Authorization: Bearer sk-xxx	SDK 用户、开发者
x402 支付	PAYMENT-SIGNATURE: <signed>（或 X-PAYMENT）	自主 Agent（零注册）
会话 Cookie	（自动）	仪表盘用户

POST /v1/intent/resolve 需要认证

该路径的 GET 形式返回用法说明且免费；POST 形式执行真正的排序，需要凭证。

API 端点

方法	路径	认证	描述
POST	/v1/intent/resolve	必须	解析意图为排名后的供应商
POST	/v1/intent/resolve/natural	必须	自然语言解析
POST	/v1/intent/execute	必须	一次调用完成解析 + 执行
POST	/v1/intent/execute-budget	必须	带硬预算上限执行
GET	/v1/intent/types	无	列出支持的意图类型
GET	/v1/providers	无	列出所有已注册的供应商
GET	/v1/network/stats	无	网络规模聚合计数

完整参考：Agent 意图协议。