Agent API & MCP

Đối tượng: agent LLM, runtime gọi công cụ và client MCP (Cursor, Claude Desktop). Với backend và storefront do con người vận hành, dùng /v1/* + OpenAPI .

Tích hợp AI: MCP và Skill hiobuy-agent-api cung cấp cho agent LLM công cụ China sourcing trực tiếp trên 1688, Taobao và Weidian — tìm từ khóa, tìm ảnh và chi tiết sản phẩm song ngữ cho quy trình shopping agent trong Cursor và Claude Desktop.

Xác thực: chỉ khóa Live hio_live_*. Khóa sandbox (hio_test_*) và fixture Sandbox không áp dụng cho /ai/v1 hoặc /mcp.

Liên quan: Xác thực · Sản phẩm · Định dạng phản hồi · Lỗi · Giới hạn tốc độ

Chọn giao diện nào

Payload data của tool khớp dạng standard từ mô hình phản hồi sản phẩm và endpoint danh sách — không bao giờ định dạng upstream thô.

Điều kiện tiên quyết (khóa Live)

Trước khi gọi /ai/v1 hoặc /mcp:

1. Đăng ký và tạo app trên Cổng nhà phát triển HIOBuy ; chờ phê duyệt.
2. Ủy quyền kênh (1688, Taobao, Weidian, …) — giống ủy quyền cổng.
3. Tạo khóa API Live trong API Keys (hio_live_* — chỉ hiển thị đầy đủ một lần khi tạo).
4. Cấp scope tối thiểu cho tools Phase 1:
   • product:detail — product.get_detail
   • product:search — product.search, product.upload_image, product.search_by_image

Thiếu ủy quyền kênh hoặc scope → 401 / 403. Cuộc gọi Live tiêu thụ hạn mức kênh và được ghi log như /v1.

URL cơ sở & xác thực

Cùng host với Public API, ví dụ https://api.hiobuy.com.

Authorization: Bearer hio_live_<your_key>

Mỗi tool ánh xạ tới scope API Key hiện có — không có scope riêng tools:*.

Endpoint HTTP (/ai/v1)

Liệt kê tools

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

Chỉ trả về tools được phép bởi scope của khóa. Mỗi mục gồm id, version, domain, description và JSON Schema input_schema.

Gọi 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"
  }
}

Bọc thành công (mọi tool):

Thất bại: HTTP 4xx/5xx với { "error": { "code", "message", "request_id" } } — không có trường ok. Xem Lỗi cho mã dùng chung (INVALID_API_KEY, FORBIDDEN, RATE_LIMITED, …).

Tools Phase 1 (sản phẩm)

product.get_detail

• Kênh: taobao | 1688 | weidian
• Bắt buộc: channel + một trong product_id | url | mi_id | tao_password
• Tùy chọn: language (mặc định en)
• data: { "product": StandardProduct }

product.search

• Bắt buộc: channel, keyword
• Tùy chọn: page, page_size, language, sort, price_start, price_end
• data: StandardProductList (giống body POST /v1/products/search)

product.upload_image

• Kênh: 1688 | taobao
• 1688: image_base64 hoặc image_url
• Taobao: bắt buộc image_base64
• data: { "channel", "image_id" } — tái sử dụng image_id cho tìm ảnh phân trang

product.search_by_image

• Kênh: 1688 | taobao (không Weidian)
• Đầu vào: image_id | image_url | image_base64
• Luồng phân trang khuyến nghị: product.upload_image một lần → nhiều lần product.search_by_image chỉ với image_id

Quy trình agent (HTTP)

1. GET /ai/v1/tools → cache metadata tool / input_schema
2. Mô hình chọn tool_id + arguments theo ý định người dùng
3. POST /ai/v1/tools/call (Bearer hio_live_…)
4. Tóm tắt data cho người dùng

Chuỗi điển hình:

• Tìm ảnh một bước: product.search_by_image với image_url hoặc image_base64
• Tìm ảnh phân trang: product.upload_image → product.search_by_image (image_id + page)
• Sau khi người dùng chọn mặt hàng: product.get_detail

Máy chủ MCP (/mcp) — China sourcing cho agent AI

Trong Cursor, Claude Desktop và client MCP khác, agent gọi công cụ China sourcing và mua hộ trên 1688 (sỉ), Taobao (lẻ) và Weidian — tìm từ khóa, tải/tìm ảnh, chi tiết sản phẩm song ngữ. Chuỗi shopping agent điển hình: so giá xưởng 1688, thay thế Taobao, duyệt catalog Weidian, rồi xem SKU/tồn qua product.get_detail.

Cùng runtime công cụ được expose dưới dạng MCP Server qua Streamable HTTP (Cursor, Claude Desktop và client MCP khác).

Auth: cùng header Authorization: Bearer hio_live_*.

Khả năng:

• Tools — tools/list, tools/call (cùng giá trị tool_id như /ai/v1)
• Prompts — quy trình tìm sản phẩm / ảnh / nghiên cứu tích hợp sẵn
• Resources — URI hiobuy://agent/* (resources/list, resources/read, mẫu)
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp mở SSE; POST với Accept: text/event-stream có thể stream JSON-RPC
• Sampling — máy chủ có thể gửi sampling/createMessage qua SSE; client trả lời qua POST /mcp (202)

Luồng phiên khuyến nghị:

1. POST initialize → lưu header phản hồi Mcp-Session-Id
2. GET /mcp với phiên → mở listener SSE
3. POST notifications/initialized
4. POST tools/list / tools/call

Khi thành công, tools/call → result.content[0].text là cùng bọc JSON như /ai/v1/tools/call.

Cấu hình Cursor (MCP shopping agent + China sourcing 1688/Taobao/Weidian)

Thêm vào Settings → MCP hoặc .cursor/mcp.json để Cursor có công cụ China sourcing trực tiếp cho 1688 / Taobao / Weidian:

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

Thay hio_live_xxx bằng khóa Live của bạn. Giữ khóa phía máy chủ — không commit vào repo công khai.

Cursor Agent Skill (hiobuy-agent-api) — China shopping agent

Cursor Agent Skill tùy chọn hiobuy-agent-api giúp agent lập trình nối luồng China sourcing trên 1688, Taobao và Weidian — scope khóa Live, bọc /ai/v1, header phiên MCP và chuỗi tìm → tìm ảnh → chi tiết. Với storefront REST trên /v1/*, dùng OpenAPI.

Skill dạy mô hình:

• điều kiện tiên quyết và scope khóa Live cho công cụ 1688 / Taobao / Weidian
• bọc yêu cầu/phản hồi /ai/v1 và tham số tool Phase 1
• header phiên MCP và cấu hình Cursor mcp.json cho quy trình China shopping
• mã lỗi và chuỗi sourcing (tìm → tìm ảnh → chi tiết)

Cài từ repo công khai hiobuy-agent-skills  — clone hoặc sao SKILL.md vào thư mục skills Cursor (xem Cursor Agent Skills ).

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

Skill bổ sung trang này — site này vẫn là tài liệu API chính thức về scope, hạn mức và ngữ nghĩa trường sản phẩm.

Tham chiếu nhanh

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}}'