execute - 执行接口 按工具计费

执行接口用于调用指定的工具能力并返回结果。这是 Agent API 的核心接口，根据工具的计费规则消耗次数或 Credits。

接口地址

POST https://api.jisuapi.com/agent/execute

请求参数

请求头

响应格式

成功响应（status: 0）

{
  "status": 0,
  "msg": "ok",
  "data": {
    "province": "北京",
    "city": "北京",
    "company": "中国移动",
    "cardtype": "GSM",
    "areacode": "010",
    "zip": "100000"
  },
  "meta": {
    "tool_id": "shouji_query",
    "execution_id": "exe_20260603_120102_xxx",
    "charge": {
      "planned_layer": "free",
      "final_layer": "free",
      "calnum": 1,
      "unitprice": 0.0,
      "cost": 0.0,
      "credits_cost": 0,
      "layers": [
        {
          "layer": "free",
          "deducted": 1,
          "remain": 99
        }
      ]
    },
    "elapsed_ms": 138,
    "upstream_ms": 120
  },
  "request_id": "req_..."
}

失败响应

{
  "status": 302,
  "msg": "工具参数缺失或格式错误",
  "data": null
}

错误码

请求示例

基础执行

curl -X POST "https://api.jisuapi.com/agent/execute" \
  -H "Authorization: Bearer 你的APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "shouji_query",
    "params": {
      "mobile": "13800138000"
    }
  }'

带完整上下文的执行

curl -X POST "https://api.jisuapi.com/agent/execute" \
  -H "Authorization: Bearer 你的APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "weather_forecast",
    "search_id": "sch_20260603120001",
    "params": {
      "city": "北京",
      "days": 7
    }
  }'

幂等执行（防重复）

curl -X POST "https://api.jisuapi.com/agent/execute" \
  -H "Authorization: Bearer 你的APPKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "sms_send",
    "idempotency_key": "unique-key-12345",
    "params": {
      "mobile": "13800138000",
      "content": "验证码：123456"
    }
  }'

Python 示例

import requests

url = "https://api.jisuapi.com/agent/execute"
headers = {
    "Authorization": "Bearer 你的APPKEY",
    "Content-Type": "application/json"
}
data = {
    "tool_id": "shouji_query",
    "params": {"mobile": "13800138000"}
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result["status"] == 0:
    print("查询成功:")
    print(result["data"])
    print(f"执行ID: {result['meta']['execution_id']}")
    print(f"计费: {result['meta']['charge']['cost']} 元")
else:
    print(f"查询失败: {result['msg']}")

计费说明

三级计费层级

• free：免费层（每日免费额度）
• 套餐包：已购买的套餐包次数
• credits：Credits 余额（按量付费）

计费流程

系统按以下顺序扣费：免费额度 → 套餐包 → Credits。响应中的 charge.layers 显示实际扣费明细。

最佳实践

• 传递 search_id：将搜索返回的 search_id 传递给执行接口，便于追踪完整调用链
• 参数验证：在调用前验证参数格式和必填项
• 错误处理：实现完善的错误处理逻辑，区分客户端错误和服务端错误
• 幂等性：对于敏感操作（如发送短信），使用 idempotency_key 防止重复执行
• 查看执行记录：通过 execution_id 可以在统计接口查询详细执行信息

常见问题

Q: 如何知道工具需要哪些参数？

A: 先调用 search 接口搜索工具，返回结果中包含参数说明。也可以查看原接口文档。

Q: 执行失败会扣费吗？

A: 一般不会。只有成功返回数据时才会扣费。因参数错误等客户端问题导致的失败不计费。

Q: idempotency_key 的有效期是多久？

A: 幂等键默认有效期为 24 小时，期间使用相同的幂等键会返回首次执行的结果。