AIP 使用指南 — Agent Intent Protocol

适用版本: Python SDK ≥ 2.3.0 (jarvisclaw) / Go SDK (github.com/api-jarvisclaw/go-sdk/v2)

AIP 已内置于主 SDK，无需额外安装。

在线演示

查看 AIP 交互式演示 — 包含真实 API 调用流程。

---

安装

Python

pip install jarvisclaw

Go

go get github.com/api-jarvisclaw/go-sdk/v2@latest

---

快速开始

Python

from jarvisclaw import IntentClient

client = IntentClient(api_key="YOUR_API_KEY")

# 一步到位：解析最优 provider + 执行
# intent 与 payload 是位置参数；execute() 原样返回上游响应体
result = client.execute(
    "chat_completion",
    {
        "messages": [{"role": "user", "content": "Hello AIP!"}],
        "temperature": 0.7,
    },
    constraints={"max_price_usd": 0.01},
    preferences={"optimize_for": "cost"},
)
print(result["choices"][0]["message"]["content"])

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

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

func main() {
    ctx := context.Background()
    client, err := jc.NewClient(jc.WithAPIKey("YOUR_API_KEY"))
    if err != nil {
        log.Fatal(err)
    }

    // Constraints 字段为指针类型，需取变量地址
    maxPrice := 0.01

    raw, err := client.Execute(ctx, jc.ExecuteRequest{
        Intent: "chat_completion",
        Payload: map[string]any{
            "messages":    []map[string]any{{"role": "user", "content": "Hello AIP!"}},
            "temperature": 0.7,
        },
        Preferences: &jc.Preferences{OptimizeFor: "cost"},
        Constraints: &jc.Constraints{MaxPriceUSD: &maxPrice},
    })
    if err != nil {
        log.Fatal(err)
    }

    // Execute 返回 json.RawMessage —— 上游响应原文
    var out map[string]any
    _ = json.Unmarshal(raw, &out)
    fmt.Println(out)
}

---

意图类型详解

调用约定

以下所有示例遵循同一组规则，与实际 SDK 一致：

• Python 的 intent 与 payload 是位置参数，不是关键字参数
• 优化偏好放在 preferences={"optimize_for": ...} 里，没有顶层 optimize_for= 参数
• optimize_for 合法取值只有 cost / quality / latency / budget（默认 cost）； speed、balance 会被静默当作 cost
• execute() 返回的是上游响应原文，没有 result 包装层，也没有 settlement 字段 （只有网络资源执行才会返回 settlement）
• Go 的 Constraints.MaxPriceUSD 是 *float64，需取变量地址

1. 聊天补全 (chat_completion)

Python

result = client.execute(
    "chat_completion",
    {
        "messages": [
            {"role": "system", "content": "你是一个有帮助的助手"},
            {"role": "user", "content": "解释量子计算"},
        ],
        "temperature": 0.7,
        "max_tokens": 500,
    },
    constraints={"max_price_usd": 0.05},
    preferences={"optimize_for": "quality"},
)
print(result["choices"][0]["message"]["content"])
print(f"费用: ${result['price']['amount']} USD")

Go

maxPrice := 0.05

raw, err := client.Execute(ctx, jc.ExecuteRequest{
    Intent:      "chat_completion",
    Preferences: &jc.Preferences{OptimizeFor: "quality"},
    Constraints: &jc.Constraints{MaxPriceUSD: &maxPrice},
    Payload: map[string]any{
        "messages": []map[string]any{
            {"role": "system", "content": "你是一个有帮助的助手"},
            {"role": "user", "content": "解释量子计算"},
        },
        "temperature": 0.7,
        "max_tokens":  500,
    },
})

---

2. 图像生成 (image_generation)

Python

result = client.execute(
    "image_generation",
    {
        "prompt": "一座赛博朋克城市的日落景象",
        "size": "1024x1024",
        "quality": "hd",
    },
    constraints={"max_price_usd": 0.10},
    preferences={"optimize_for": "quality"},
)
image_url = result["data"][0]["url"]
print(f"图像: {image_url}")
print(f"费用: ${result['price']['amount']} USD")

Go

maxPrice := 0.10

raw, err := client.Execute(ctx, jc.ExecuteRequest{
    Intent: "image_generation",
    Preferences: &jc.Preferences{OptimizeFor: "quality"},
    Constraints: &jc.Constraints{MaxPriceUSD: &maxPrice},
    Payload: map[string]any{
        "prompt":  "一座赛博朋克城市的日落景象",
        "size":    "1024x1024",
        "quality": "hd",
    },
})

---

3. 视频生成 (video_generation)

视频生成是异步的：提交后拿到 job，再轮询。直接用 VideoClient 更省事，它会自动轮询。

Python

Python

# 推荐：专用客户端自动轮询
from jarvisclaw import VideoClient

video = VideoClient(api_key="YOUR_API_KEY")
job = video.generate("一只机器猫在草地上奔跑",
                     model="bytedance/seedance-2.0", duration=5)
print(job.url)

# 或走 AIP：返回的是 job 信封，需自行轮询
result = client.execute(
    "video_generation",
    {
        "prompt": "一只机器猫在草地上奔跑",
        "duration_seconds": 5,
        "resolution": "1080p",
    },
    constraints={"max_price_usd": 4.00},
    preferences={"optimize_for": "quality"},
)
print(result["id"], result["status"])   # 例如 "bytedance:video_24d2...", "queued"

Go

vc, _ := jc.NewVideoClient(jc.WithAPIKey("YOUR_API_KEY"))

job, err := vc.Generate(ctx, "一只机器猫在草地上奔跑",
    jc.WithVideoModel("bytedance/seedance-2.0"),
    jc.WithDuration(5),
    jc.WithWait(true))
if err != nil {
    log.Fatal(err)
}
fmt.Println(job.URL)

视频按秒计费

max_price_usd 要按「单价 × 秒数」估算：seedance-2.0 为 $0.227/秒，5 秒约 $1.14， 1080p 还要再乘约 2.25 倍。预算给小了会匹配不到提供商。详见 视频生成。

---

4. 语音合成 (text_to_speech)

Python

Python

result = client.execute(
    "text_to_speech",
    {
        "input": "欢迎使用 JarvisClaw Agent Intent Protocol。",
        "voice": "sarah",
    },
    constraints={"max_price_usd": 0.01},
)
# 返回 JSON，音频在 CDN 上
audio_url = result["data"][0]["url"]

# 或用 AudioClient，直接拿到字节流
from jarvisclaw import AudioClient
audio = AudioClient(api_key="YOUR_API_KEY")
res = audio.speech("欢迎使用 JarvisClaw。", model="elevenlabs/flash-v2.5", voice="sarah")
open("out.mp3", "wb").write(res.content)

Go

ac, _ := jc.NewAudioClient(jc.WithAPIKey("YOUR_API_KEY"))

res, err := ac.Speech(ctx, "欢迎使用 JarvisClaw。",
    jc.WithAudioModel("elevenlabs/flash-v2.5"),
    jc.WithVoice("sarah"))
if err != nil {
    log.Fatal(err)
}
os.WriteFile("out.mp3", res.Data, 0644)

音色用 ElevenLabs 别名（sarah、george、charlie、charlotte、aria）或原始 voice_id， 默认 sarah —— OpenAI 的 alloy 等音色不适用于此上游。响应是含 CDN 链接的 JSON，不是 base64 音频。

---

5. 网络搜索 (web_search)

web_search 意图映射到 surf 服务（/v1/marketplace/surf），需要用 endpoint 指定具体功能路径。 如果只想做通用网页搜索，直接调 /v1/search 更合适。

Python

Python

from jarvisclaw import SearchClient

# 通用网页搜索 —— 返回 AI 摘要 + 内联引用
search = SearchClient(api_key="YOUR_API_KEY")
for r in search.query("2026年最新AI研究论文", num_results=5):
    print(f"- {r.title}: {r.snippet[:80]}")

# 需要带 URL 的结构化结果时，直接调 Exa
import requests
resp = requests.post(
    "https://api.jarvisclaw.ai/v1/marketplace/exa/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"query": "2026年最新AI研究论文", "numResults": 5},
)
for item in resp.json()["results"]:
    print(f"- {item['title']}: {item['url']}")

Go

sc, _ := jc.NewSearchClient(jc.WithAPIKey("YOUR_API_KEY"))

resp, err := sc.Query(ctx, "2026年最新AI研究论文", jc.WithNumResults(5))
if err != nil {
    log.Fatal(err)
}
fmt.Println(resp.Summary, resp.SourcesUsed)
for _, r := range resp.Citations {
    fmt.Printf("- %s: %s\n", r.Title, r.URL)
}

query() 返回摘要而非链接列表

SearchClient.query() 走 /v1/search（model=auto/search），返回带内联引用的 AI 摘要。 当响应没有结构化引用时，Python SDK 会返回单条 url="" 的结果。需要逐条 URL 请直接调用 /v1/marketplace/exa/search。详见 网页搜索。

---

6. 知识搜索 (knowledge_search)

knowledge_search 意图映射到 Exa 服务（/v1/marketplace/exa），用 endpoint 选择具体功能。

Python

Python

result = client.execute(
    "knowledge_search",
    {"query": "如何配置 AIP 预算限制", "numResults": 3},
    constraints={"max_price_usd": 0.02},
    preferences={"optimize_for": "quality"},
)
for item in result["results"]:
    print(f"- [{item.get('score', 0):.2f}] {item['title']}: {item['url']}")

Go

maxPrice := 0.02

raw, err := client.Execute(ctx, jc.ExecuteRequest{
    Intent:      "knowledge_search",
    Preferences: &jc.Preferences{OptimizeFor: "quality"},
    Constraints: &jc.Constraints{MaxPriceUSD: &maxPrice},
    Payload: map[string]any{
        "query":      "如何配置 AIP 预算限制",
        "numResults": 3,
    },
})

Exa 的参数是 query / numResults，没有 namespace 或 top_k；结果在 results 数组里， 不是 chunks。这是对公开网页的语义检索，不是私有向量库。

---

7. 调用 MCP 工具

没有 tool_call 意图

tool_call 不在服务端的意图常量表内，作为 intent 传入会匹配不到提供商。MCP 工具请走 POST /mcp 的 JSON-RPC 接口。

import httpx

resp = httpx.post(
    "https://api.jarvisclaw.ai/mcp",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "chat",
            "arguments": {
                "model": "auto",
                "messages": [{"role": "user", "content": "上海未来三天天气"}],
            },
        },
    },
)
print(resp.json()["result"]["content"][0]["text"])

initialize、tools/list、resources/* 免费且无需认证；只有 tools/call 需要付费或 API Key。 可用工具列表见 MCP 配置。

---

8. Prompt 优化 (prompt_optimization)

Python

Python

result = client.execute(
    "prompt_optimization",
    {
        "prompt": "帮我写封邮件",
        "context": "商务场景，发给客户，关于项目延期",
        "optimize_for": "clarity",
    },
    constraints={"max_price_usd": 0.01},
)
print(result["optimized_prompt"])
print(f"评分: {result['score_before']} → {result['score_after']}")

Go

// 也可以用专用方法，返回类型化结果
res, err := client.PromptCoach(ctx, jc.PromptCoachRequest{
    Prompt:      "帮我写封邮件",
    Context:     "商务场景，发给客户，关于项目延期",
    OptimizeFor: "clarity",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("评分: %.1f → %.1f\n%s\n", res.ScoreBefore, res.ScoreAfter, res.OptimizedPrompt)

请求字段是 prompt（不是 original_prompt），optimize_for 取 clarity / technical / creative。固定 $0.002/次。

---

平台自营资源直调

除了标准意图（chat_completion / web_search 等），AIP 也能直接调用平台上架的 Marketplace 服务（如 surf 行情数据）和 网络资源（跨平台资源网络）。两类都通过标准 /v1/intent/execute 调用。

调用 Marketplace 服务（如 surf 行情）

Marketplace 服务通常包含多个功能端点（行情查询、交易对信息等）。调用时用 intent 指定服务类别，用 endpoint 指定服务内的具体功能路径：

curl -X POST https://api.jarvisclaw.ai/v1/intent/execute \
  -H "Authorization: Bearer $JC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "web_search",
    "endpoint": "exchange/price?pair=BTC-USDT",
    "method": "GET"
  }'

响应（HTTP 200）：

{
  "success": true,
  "data": { "pair": "BTC-USDT", "price": "64251.94" }
}

字段	说明
intent	服务对应的意图类别
endpoint	服务内的功能路径（含查询参数）
method	HTTP 方法，默认 POST —— 数据查询类端点需显式传 GET

意图与服务基础路径的映射：

意图	基础路径
web_search	/v1/marketplace/surf
knowledge_search	/v1/marketplace/exa
image_generation	/v1/images/generations
video_generation	/v1/videos/generations
text_to_speech	/v1/audio/speech
prompt_optimization	/v1/prompt-coach/optimize
其他	/v1/chat/completions

计费说明

与所有 AIP 调用一致，Marketplace 服务按次通过 x402 在链上结算（USDC），费用在执行时精确扣除。

调用网络资源（跨平台）

网络资源来自资源网络中的其他平台。先发现资源拿到数字 ID，再用 resource_id 执行，参数放在 payload 里。

第一步 — 发现资源（免费，无需认证）：

# 关键词搜索
curl "https://api.jarvisclaw.ai/v1/network/search?q=bitcoin&limit=5"

# 或按意图解析（需认证）
curl -X POST https://api.jarvisclaw.ai/v1/intent/resolve \
  -H "Authorization: Bearer $JC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "intent": "web_search" }'

第二步 — 用 resource_id 执行：

curl -X POST https://api.jarvisclaw.ai/v1/intent/execute \
  -H "Authorization: Bearer $JC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_id": 442,
    "payload": { "query": "bitcoin" }
  }'

响应（HTTP 200）：

{
  "success": true,
  "data": { "...": "..." },
  "cost_usd": 0.00115,
  "latency_ms": 2180,
  "tx_hash": "0xf0d9d9e1a6d7a9849a3f7616dc33d62e46f9b980b3f1f90d17a68d570f7b2b5c"
}

计费说明

网络资源在执行时通过 x402 链上结算，返回的 tx_hash 为链上结算凭证（Base USDC）。resolve 阶段候选的价格可能为空，这是正常的——定价在 execute 时结算，不影响实际扣费。

---

高级用法

解析优先模式

先获取候选列表，再决定是否执行：

Python

# 第一步：解析候选供应商
matches = client.resolve(
    "chat_completion",
    constraints={
        "max_price_usd": 0.05,
        "max_latency_ms": 3000,
    },
    preferences={"optimize_for": "quality"},
)

# 候选在 matches 数组里（不是 candidates）
for m in matches["matches"]:
    print(f"{m['provider_id']}: ${m['estimated_price_usd']}, {m['reason']}")
print(f"共 {matches['total_available']} 个可用提供商")

# 第二步：拿排名第一的模型直接调用
best = matches["matches"][0]
result = client.execute(
    "chat_completion",
    {"model": best["model"], "messages": [{"role": "user", "content": "你好"}]},
)

Go

// 第一步：解析候选供应商
maxPrice, maxLatency := 0.05, 3000

matches, err := client.Resolve(ctx, jc.ResolveRequest{
    Intent:      "chat_completion",
    Preferences: jc.Preferences{OptimizeFor: "quality"},
    Constraints: jc.Constraints{
        MaxPriceUSD:  &maxPrice,
        MaxLatencyMS: &maxLatency,
    },
})

for _, m := range matches.Matches {
    fmt.Printf("%s: $%.6f %s\n", m.ProviderID, m.EstimatedPriceUSD, m.Reason)
}

// 第二步：用排名第一的模型执行
raw, err := client.Execute(ctx, jc.ExecuteRequest{
    Intent: "chat_completion",
    Payload: map[string]any{
        "model":    matches.Matches[0].Model,
        "messages": []map[string]any{{"role": "user", "content": "你好"}},
    },
})

没有 provider_id 字段

ExecuteRequest 不支持 provider_id / ProviderID。要锁定某个提供商，把它的 model 放进 payload；网络资源则用 resource_id。候选数组字段名是 matches（Go: Matches）， 不是 candidates。ResolveRequest 的 Constraints/Preferences 是值类型，不是指针。

---

预算治理

设置硬性预算上限，超出则拒绝执行：

Python

# intent、payload、budget 三个都是位置参数
result = client.execute_budget(
    "chat_completion",
    {"messages": [{"role": "user", "content": "写一篇长文"}]},
    {"max_total_usd": 1.00},
)
# 如果预估成本 > $1.00，请求会被拒绝（不执行、不扣费）
print(result["status"])              # success | rejected | error | risk_blocked
print(result.get("risk_level"))
print(result.get("actual_cost_usd"))

Go

resp, err := client.ExecuteBudget(ctx, jc.ExecuteBudgetRequest{
    Intent: "chat_completion",
    Budget: jc.Budget{MaxTotalUSD: 1.00},
    Payload: map[string]any{
        "messages": []map[string]any{
            {"role": "user", "content": "写一篇长文"},
        },
    },
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("status=%s risk=%s\n", resp.Status, resp.RiskLevel)

budget 仅支持 max_total_usd（必填）、preferred_payment_method、allow_overdraft。 持久化的单次/每日/每月限额请用 PUT /v1/wallet/limits 设置。

---

审计日志

查询编排流水线的最近事件。该端点不接受任何参数：

Python

entries = client.audit()          # IntentClient.audit() 无参数
for e in entries["entries"]:
    print(f"[{e['timestamp']}] {e['event_type']} req={e['request_id']}")
    print(f"  详情: {e.get('details')}")
print(f"共 {entries['count']} 条")

Go

resp, err := client.Audit(ctx)    // 无参数
if err != nil {
    log.Fatal(err)
}
for _, e := range resp.Entries {
    fmt.Printf("[%s] %s req=%s %v\n", e.Timestamp, e.EventType, e.RequestID, e.Details)
}

不支持过滤和分页

没有 limit / intent_type 参数，也没有 jc.AuditRequest 这个类型。每条记录字段是 {timestamp, request_id, user_id, event_type, details}，event_type 是流水线事件 （settlement_confirmed 等）而非意图名，且没有 settlement 子对象。

要查消费历史请用分析端点（/api/analytics/aggregate）或 GET /v1/wallet/history。

成本分析

# 聚合后的消费与结算数据
print(client.spend(period="7d", group_by=["day", "model"]))

# spend() 的便捷包装
print(client.cost_by_model(period="7d"))
print(client.daily_trend(period="30d"))

# 从日志挖掘的质量指标与深度扫描汇总
print(client.quality(period="7d"))
print(client.insights(period="7d"))

对应 /api/analytics/{aggregate,quality,insights}。period 可取 24h、7d（默认）、 30d、90d。使用 API 令牌（sk-...）调用时只能看到自己的数据，user_id 会被忽略 （管理员令牌亦然）；只有控制台登录（会话鉴权）的管理员才能用 user_id 查看指定用户。

---

认证方式

方式	Header	描述
API Key	Authorization: Bearer sk-...	标准密钥认证；平台从托管钱包自动结算
x402 私钥	PAYMENT-SIGNATURE: <base64>	Agent 使用私钥直接签名支付，无需 API Key

X-PAYMENT 是 PAYMENT-SIGNATURE 的等价别名；两者同时存在时以 PAYMENT-SIGNATURE 为准。

Python

# API Key 认证
client = IntentClient(api_key="sk-your-api-key")

# x402 私钥认证 — Agent 直接用钱包支付
client = IntentClient(private_key="0x<your-evm-private-key>")

# 自定义端点 / 超时
client = IntentClient(
    api_key="sk-your-api-key",
    base_url="https://your-aip-gateway.com",
    timeout=60,
)

# 也可从环境变量读取：JARVISCLAW_API_KEY / JARVISCLAW_WALLET_KEY / JARVISCLAW_BASE_URL
client = IntentClient()

Go

// API Key 认证 —— 注意返回 (client, error)
client, err := jc.NewClient(jc.WithAPIKey("sk-your-api-key"))

// x402 私钥认证
client, err = jc.NewClient(jc.WithPrivateKey("0x<your-evm-private-key>"))

// 自定义端点
client, err = jc.NewClient(
    jc.WithAPIKey("sk-your-api-key"),
    jc.WithBaseURL("https://your-aip-gateway.com"),
    jc.WithTimeout(60*time.Second),
)

API Key 形如 sk-...。jc.NewClient 返回 (*Client, error)，忽略第二个返回值无法编译。

x402 模式

• 自主 Agent — 持有独立钱包，按需付费，无需托管 API Key
• 无信任环境 — Agent 独立签名，不依赖平台账户
• 多链支持 — EVM 私钥 (0x...) 使用 Base USDC；Base58 密钥使用 Solana USDC（Solana 仅 Python SDK 支持）

---

MCP 集成

部分 AIP 能力以 MCP Tools 形式暴露，工具名为扁平的下划线命名：

MCP Tool	对应
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	本地成本估算

/v1/intent/execute、/v1/intent/resolve/natural、/v1/intent/audit 没有对应的 MCP 工具， 需直接走 HTTP。详见 MCP 配置。

---

相关链接

• AIP 概览 — 协议介绍与完整端点参考
• AIP 协议规范 — 完整协议规范
• AIP 网络 — 跨平台发现与执行
• x402 协议 — 支付协议深度解析
• SDK 参考 — Python 与 Go SDK 完整文档