Agent API 与 MCP

适用对象：LLM Agent、Tool Calling 运行时、MCP 客户端（Cursor、Claude Desktop 等）。人类后端与商城集成请用 /v1/* + OpenAPI 。

AI 集成：MCP 与 hiobuy-agent-api Skill 向 LLM Agent 暴露 1688、淘宝、微店 的 China sourcing 工具——关键词搜索、以图搜货、双语商品详情，适用于 Cursor / Claude Desktop 中的 shopping agent 工作流。

鉴权： 仅支持 hio_live_* Live 密钥。** 沙箱密钥（hio_test_*）与 沙箱环境 的 Fixture 不适用 /ai/v1 与 /mcp。

相关：鉴权 · 商品 · 响应结构 · 错误 · 限流

选用哪套接口

Tool 返回的 data 始终为 standard 结构，与 商品数据结构 及列表接口一致，无 upstream 原始格式。

前置条件（Live Key）

调用 /ai/v1 或 /mcp 前：

1. 在 HIOBuy 开发者门户  注册应用并通过审核。
2. 授权渠道（1688、淘宝、微店等）——与 门户授权 相同。
3. 在 API Keys 创建 Live 密钥（hio_live_*，创建时仅完整展示一次）。
4. 至少勾选 Phase 1 所需 scope：
   • product:detail — product.get_detail
   • product:search — product.search、product.upload_image、product.search_by_image

未授权渠道或 scope 不足 → 401 / 403。Live 调用计入渠道配额并写入请求日志，与 /v1 一致。

Base URL 与认证

与 Public API 相同，例如 https://api.hiobuy.com。

Authorization: Bearer hio_live_<your_key>

每个 tool 对应既有 API Key scope，没有单独的 tools:* scope。

HTTP 端点（/ai/v1）

列出 tools

curl -s https://api.hiobuy.com/ai/v1/tools \
  -H "Authorization: Bearer hio_live_xxx"

仅返回当前密钥 scope 允许的 tools；每项含 id、version、domain、description 与 JSON Schema input_schema。

调用 tool

POST /ai/v1/tools/call
Authorization: Bearer hio_live_xxx
Content-Type: application/json
 
{
  "tool_id": "product.get_detail",
  "arguments": {
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }
}

成功 envelope（所有 tool 统一）：

失败： HTTP 4xx/5xx，{ "error": { "code", "message", "request_id" } }，无 ok 字段。常见码见 错误（INVALID_API_KEY、FORBIDDEN、RATE_LIMITED 等）。

Phase 1 Tools（商品）

Live 模式使用履约工具前必须连接履约仓库。未连接时工具仍可被发现，但调用会返回 WAREHOUSE_NOT_CONNECTED，并带有 action_required.type = CONNECT_WAREHOUSE。运费试算是只读预算，不锁价；客户端必须保留 completeness、warnings、known_total、total 与待定费用，不得自行重算。

product.get_detail

• Channel： taobao | 1688 | weidian
• 必填： channel + id | product_id | url | mi_id | tao_password 之一
• 可选： language（默认 en）
• data： { "product": StandardProduct }
• 淘宝 id / mi_id 会周期性变化，请勿长期缓存；下单前重新拉取。

product.search

• 必填： channel、keyword
• 可选： page、page_size、language、sort_field、sort_order、price_start、price_end、ship_within_hours、category_ids、product_collection_id、experience_score_level、product_attrs、filter、sale_filters、keyword_translate、response_format
• data： StandardProductList（与 POST /v1/products/search 相同）
• 字段说明与渠道差异见 商品关键词搜索。

product.upload_image

• Channel： 1688 | taobao
• 1688： image_base64 与 image_url 二选一
• 淘宝： 必填 image_base64
• data： { "channel", "image_id" } — 翻页图搜时复用 image_id

product.search_by_image

• Channel： 1688 | taobao（不支持微店）
• 输入： image_id | image_url | image_base64
• 推荐翻页： 先 product.upload_image，再多次 product.search_by_image（仅传 image_id）

Agent 工作流（HTTP）

1. GET /ai/v1/tools → 缓存 metadata / input_schema
2. 根据用户意图选择 tool_id + arguments
3. POST /ai/v1/tools/call（Bearer hio_live_…）
4. 摘要 data 返回用户

典型链路：

• 单次图搜： product.search_by_image（image_url / image_base64）
• 翻页图搜： product.upload_image → product.search_by_image（image_id + page）
• 用户选中商品： product.get_detail

MCP 服务（/mcp）— AI Agent China 选品

在 Cursor、Claude Desktop 等 MCP 客户端中，Agent 可调用 1688（批发）、淘宝（零售）、微店 的 China sourcing 与 代购选品 工具——关键词搜索、以图搜货、上传商品图与双语详情。典型 shopping agent 链路：在 1688 比工厂价、找淘宝同款、浏览 微店 橱窗，再通过 product.get_detail 查看 SKU/库存。

同一套 Tool Runtime 以 Streamable HTTP 暴露为 MCP Server（Cursor、Claude Desktop 等）。

认证： 同上 Authorization: Bearer hio_live_*。

能力概览：

• Tools — tools/list、tools/call（与 /ai/v1 相同 tool_id）
• Prompts — 内置商品搜索 / 图搜 / 调研工作流
• Resources — hiobuy://agent/* URI（resources/list、resources/read、templates）
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp 开 SSE；POST 带 Accept: text/event-stream 可流式返回 JSON-RPC
• Sampling — 服务端经 SSE 发 sampling/createMessage；客户端 POST /mcp 回传（202）

推荐连接流程：

1. POST initialize → 保存响应头 Mcp-Session-Id
2. GET /mcp（带 session）打开 SSE
3. POST notifications/initialized
4. POST tools/list / tools/call

tools/call 成功时，result.content[0].text 与 /ai/v1/tools/call 的 JSON envelope 相同。

Cursor 配置（shopping agent MCP）

在 Settings → MCP 或 .cursor/mcp.json 中添加，为 Cursor 接入 1688 / 淘宝 / 微店 China sourcing 工具：

{
  "mcpServers": {
    "hiobuy": {
      "url": "https://api.hiobuy.com/mcp",
      "headers": {
        "Authorization": "Bearer hio_live_xxx"
      }
    }
  }
}

将 hio_live_xxx 替换为你的 Live 密钥。密钥仅放服务端，勿提交到公开仓库。

Cursor Agent Skill（hiobuy-agent-api）— China shopping agent

可选 hiobuy-agent-api Cursor Agent Skill 帮助编码 Agent 接入 1688、淘宝、微店 的 China sourcing 流程——Live 密钥 scope、/ai/v1 envelope、MCP 会话头，以及搜索 → 图搜 → 详情 tool 链路。商城 REST 集成请用 /v1/* 与 OpenAPI。

Skill 帮助模型理解：

• 1688 / 淘宝 / 微店 商品 tools 的 Live 密钥前置条件与 scope
• /ai/v1 请求/响应 envelope 与 Phase 1 参数
• China shopping 工作流的 MCP 会话头与 Cursor mcp.json 配置
• 错误码与 选品 链路（搜索 → 图搜 → 详情）

从公开仓库 hiobuy-agent-skills  克隆或复制 SKILL.md 到 Cursor skills 路径（见 Cursor Agent Skills ）。

git clone https://github.com/hubinjie/hiobuy-agent-skills.git

Skill 补充本文——本站仍是 scope、配额与字段语义的权威 API 参考。

速查

BASE=https://api.hiobuy.com
KEY=hio_live_xxx
 
curl -s "$BASE/ai/v1/tools" -H "Authorization: Bearer $KEY"
 
curl -s "$BASE/ai/v1/tools/call" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"product.search","arguments":{"channel":"1688","keyword":"phone case","page":1,"page_size":5}}'