Agent API 및 MCP

대상: LLM 에이전트, 도구 호출 런타임, MCP 클라이언트(Cursor, Claude Desktop). 사람이 운영하는 백엔드·스토어프론트는 /v1/* + OpenAPI 를 사용하세요.

AI 연동: MCP와 hiobuy-agent-api Skill은 LLM 에이전트에 1688, Taobao, Weidian 라이브 China sourcing 도구를 제공합니다 — 키워드 검색, 이미지 검색, 이중 언어 상품 상세로 Cursor와 Claude Desktop의 shopping agent 워크플로.

인증: hio_live_* Live 키만. 샌드박스 키(hio_test_*)와 Sandbox 픽스처는 /ai/v1 및 /mcp에 적용되지 않습니다.

관련: 인증 · 상품 · 응답 형식 · 오류 · 속도 제한

어떤 인터페이스를 쓸지

도구 data 페이로드는 상품 응답 모델 및 목록 엔드포인트의 standard 형태와 일치 — upstream 원시 형식 없음.

사전 요건(Live 키)

/ai/v1 또는 /mcp 호출 전:

1. HIOBuy 개발자 포털 에서 가입·앱 생성; 승인 대기.
2. 채널 승인(1688, Taobao, Weidian 등) — 포털 승인과 동일.
3. API Keys에서 Live API 키 생성(hio_live_* — 생성 시 한 번만 전체 표시).
4. Phase 1 도구에 최소 스코프 부여:
   • product:detail — product.get_detail
   • product:search — product.search, product.upload_image, product.search_by_image

채널 미승인 또는 스코프 부족 → 401 / 403. Live 호출은 채널 할당량을 소비하며 /v1과 같이 로깅됩니다.

기본 URL 및 인증

Public API와 동일 호스트, 예: https://api.hiobuy.com.

Authorization: Bearer hio_live_<your_key>

각 도구는 기존 API Key 스코프에 매핑 — 별도 tools:* 스코프 없음.

HTTP 엔드포인트(/ai/v1)

도구 목록

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

키 스코프로 허용된 도구만 반환. 각 항목에 id, version, domain, description, JSON Schema input_schema 포함.

도구 호출

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

성공 봉투(모든 도구):

실패: HTTP 4xx/5xx, { "error": { "code", "message", "request_id" } } — ok 필드 없음. 공통 코드는 오류(INVALID_API_KEY, FORBIDDEN, RATE_LIMITED 등).

Phase 1 도구(상품)

product.get_detail

• 채널: taobao | 1688 | weidian
• 필수: channel + product_id | url | mi_id | tao_password 중 하나
• 선택: language(기본 en)
• data: { "product": StandardProduct }

product.search

• 필수: channel, keyword
• 선택: page, page_size, language, sort, price_start, price_end
• data: StandardProductList(POST /v1/products/search 본문과 동일)

product.upload_image

• 채널: 1688 | taobao
• 1688: image_base64 또는 image_url
• Taobao: image_base64 필수
• data: { "channel", "image_id" } — 페이지네이션 이미지 검색에 image_id 재사용

product.search_by_image

• 채널: 1688 | taobao(Weidian 아님)
• 입력: image_id | image_url | image_base64
• 페이지네이션 권장 흐름: product.upload_image 한 번 → image_id만으로 여러 번 product.search_by_image

에이전트 워크플로(HTTP)

1. GET /ai/v1/tools → 도구 메타데이터 / input_schema 캐시
2. 모델이 사용자 의도에서 tool_id + arguments 선택
3. POST /ai/v1/tools/call (Bearer hio_live_…)
4. 사용자에게 data 요약

일반적인 체인:

• 원샷 이미지 검색: image_url 또는 image_base64로 product.search_by_image
• 페이지네이션 이미지 검색: product.upload_image → product.search_by_image(image_id + page)
• 사용자가 항목 선택 후: product.get_detail

MCP 서버(/mcp) — AI 에이전트용 China sourcing

Cursor, Claude Desktop 등 MCP 클라이언트에서 에이전트는 1688(도매), Taobao(소매), Weidian China sourcing·대리 구매 도구를 호출합니다 — 키워드 검색, 이미지 업로드·검색, 이중 언어 상품 상세. 일반적인 shopping agent 체인: 1688 공장 견적 비교, Taobao 대안, Weidian 카탈로그 훑은 뒤 product.get_detail로 SKU/재고 확인.

동일 도구 런타임이 Streamable HTTP로 MCP Server에 노출됩니다(Cursor, Claude Desktop, 기타 MCP 클라이언트).

인증: 동일 Authorization: Bearer hio_live_* 헤더.

기능:

• Tools — tools/list, tools/call(/ai/v1과 동일 tool_id 값)
• Prompts — 내장 상품 검색 / 이미지 검색 / 리서치 워크플로
• Resources — hiobuy://agent/* URI(resources/list, resources/read, 템플릿)
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp로 SSE 시작; Accept: text/event-stream POST로 JSON-RPC 스트리밍 가능
• Sampling — 서버가 SSE로 sampling/createMessage 전송; 클라이언트는 POST /mcp(202)로 응답

권장 세션 흐름:

1. POST initialize → 응답 헤더 Mcp-Session-Id 저장
2. 세션으로 GET /mcp → SSE 리스너 열기
3. POST notifications/initialized
4. POST tools/list / tools/call

성공 시 tools/call → result.content[0].text는 /ai/v1/tools/call과 동일 JSON 봉투입니다.

Cursor 설정(shopping agent MCP + 1688/Taobao/Weidian China sourcing)

Settings → MCP 또는 .cursor/mcp.json에 추가해 Cursor에 1688 / Taobao / Weidian 라이브 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

선택적 Cursor Agent Skill **hiobuy-agent-api**는 코딩 에이전트가 1688, Taobao, Weidian China sourcing 플로를 연결하도록 돕습니다 — Live 키 스코프, /ai/v1 봉투, MCP 세션 헤더, 검색 → 이미지 검색 → 상세 체인. /v1/* REST 스토어프론트는 OpenAPI를 사용하세요.

모델에 다음을 가르칩니다:

• 1688 / Taobao / Weidian 상품 도구용 Live 키 사전 요건 및 스코프
• /ai/v1 요청/응답 봉투 및 Phase 1 도구 인수
• China shopping 워크플로용 MCP 세션 헤더 및 Cursor mcp.json
• 오류 코드 및 sourcing 도구 체인(검색 → 이미지 검색 → 상세)

공개 저장소 **hiobuy-agent-skills **에서 설치 — 클론하거나 SKILL.md를 Cursor skills 경로에 복사(Cursor Agent Skills  참고).

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

Skill은 이 페이지를 보완 — 스코프, 할당량, 상품 필드 의미에 대한 정식 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}}'