본문으로 건너뛰기
Ankole

AIGateway API 사용법

AI Agent용: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/aigateway-api-usage/index.md에 있습니다. 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.

AIGateway는 Worker가 호출하는 내부 경계일 뿐만 아니라, 외부 애플리케이션, 엔터프라이즈 시스템, SDK가 직접 호출할 수 있는 REST API입니다. 이 페이지는 호출자를 위한 실용 가이드입니다 — endpoint, 인증, 두 가지 호출 모드, 작업 예시를 다룹니다. AIGateway 개념 페이지를 실사용과 함께 보완합니다.

가장 중요한 특성을 먼저 말하면: AIGateway API는 OpenResponses 호환이며 Principal 스코프입니다. 호출자는 bearer 토큰(agent 또는 admin)을 제시하고 OpenResponses 형태의 요청을 보내며, JSON 응답 또는 스트림을 받습니다. 호출자는 provider 자격 증명을 볼 수 없습니다 — 그 자격 증명은 control plane이 소유합니다.

인증

/api/v1/ai-gateway 아래의 모든 호출은 bearer 토큰을 필요로 합니다:

curl https://ankole.example.com/api/v1/ai-gateway/responses \
  -H "Authorization: Bearer $AIGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model": "primary", "input": "Hello" }'

두 가지 토큰 종류가 허용됩니다:

  • Agent token — 한 Agent의 모델 바인딩으로 스코프가 제한됩니다. 통합이 특정 Agent를 대신해 행동할 때 사용하세요.
  • Admin token — 모든 provider로 스코프가 제한됩니다. 운영자 측 스크립트와 Console용입니다.

토큰이 Principal로 어떻게 해석되는지는 Principal and AuthZ를 참조하세요.

상태비저장 응답(HTTP 및 SSE)

상태비저장 호출은 요청 하나에 응답 하나입니다. 전체 입력을 보내고 완전한 본문을 돌려받습니다:

curl https://ankole.example.com/api/v1/ai-gateway/responses \
  -H "Authorization: Bearer $AIGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model": "primary", "input": "Summarize this thread.", "store": false }'

스트리밍을 위해서는 "stream": true를 추가하면 같은 endpoint가 Server-Sent Events로 전환됩니다:

curl -N https://ankole.example.com/api/v1/ai-gateway/responses \
  -H "Authorization: Bearer $AIGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "model": "primary", "input": "Draft a release note.", "stream": true }'

상태비저장 HTTP와 SSE는 상태보존 필드(previous_response_id, conversation, store)를 거부합니다. 연속 작업에는 WebSocket 경로를 사용하세요.

기타 endpoint

엔드포인트 용도
GET /models 현재 사용 가능한 모델 나열
POST /embeddings 임베딩 생성
POST /rerank 문서 rerank
POST /web_search 웹 검색
POST /web_fetch 웹 페이지 가져오기

각각은 AIGateway 개념 페이지와 관련 User guide 기능 페이지에 문서화되어 있습니다.

이 가이드가 아닌 것

AIGateway 개념 페이지가 아닙니다. 전체 라우트 테이블, 상태보존 수명 주기, 오류 형식은 AIGateway를 읽으세요. SDK도 아닙니다. Ankole은 클라이언트 SDK를 제공하지 않습니다. 호출자는 REST API에 표준 HTTP 클라이언트를 사용합니다.

다음 단계