에이전트 연동 가이드

1. 외부 에이전트 엔드포인트 준비

내 에이전트(백엔드)가 HTTPS로 요청을 받을 수 있는 URL을 준비합니다. 클라이밋팟은 이 URL로 사용자의 메시지를 HTTP 요청으로 전달합니다.

• HTTPS 엔드포인트 1개 (예: https://your-service.example.com/chat)
• 메서드는 POST 권장 (GET도 가능하나 대화 히스토리 미전달)
• 호출 측 타임아웃은 300초

2. 요청(Request) 형식 맞추기

클라이밋팟은 사용자 메시지를 아래 JSON 바디로 보냅니다. message는 필수이며, 설정에 따라 대화 히스토리와 식별자가 함께 전달됩니다.

• message: 이번 턴의 사용자 발화 (필수)
• conversation_history: 이전 턴들의 role·content 배열 (설정에 따라 포함)
• user_id · conversation_id: 사용자/대화 식별자 (항상 함께 전송)

POST https://your-service.example.com/chat
Content-Type: application/json
Authorization: Bearer <등록된_키>
x-api-key: <등록된_키>

{
  "user_id": "<호출 사용자 식별자>",
  "conversation_id": "<클라이밋팟 대화 스레드 ID>",
  "message": "서울의 기후 위험을 알려줘",
  "conversation_history": [
    { "role": "user", "content": "안녕" },
    { "role": "assistant", "content": "무엇을 도와드릴까요?" }
  ]
}

3. 인증 처리

클라이밋팟 어드민에 비밀키를 등록하면, 호출 시 Authorization 헤더와 x-api-key 헤더가 함께 전달됩니다. 서비스가 실제 검증하는 방식 하나만 구현해도 됩니다.

• Authorization: Bearer <key>
• x-api-key: <key>
• 두 헤더 모두 올 수 있으므로 편한 쪽으로 검증

4. 응답(Response) 반환

응답은 SSE 스트리밍 / 단일 JSON / plain text 중 하나로 맞추면 됩니다. 실시간 타이핑 효과가 필요하면 SSE를 권장합니다.

• SSE: Content-Type: text/event-stream, data: 라인마다 델타 전송
• JSON: { "content": "최종 답변" } 형태 한 덩어리
• OpenAI 호환(choices[].delta.content)·Anthropic 스타일도 인식

Content-Type: text/event-stream

data: {"content":"서울"}

data: {"content":"의 기후 위험을"}

data: {"content":" 분석해 드리겠습니다."}

data: [DONE]

5. (선택) 구조화 UI 컴포넌트

카드·리포트·지도·비교 리스트 등 리치 UI가 필요하면 응답에 ui_components 배열을 실어 보낼 수 있습니다. 텍스트 델타와 같은 스트림에 섞어도 됩니다.

• 루트 또는 content_block 안에 ui_components 배열
• index / block_index / step_index로 진행 구간에 묶기
• ui_components만 있는 이벤트는 답변 텍스트를 늘리지 않음

6. (선택) 정산·usage 이벤트

토큰량과 원가를 알고 있다면 응답 마지막에 billing_usage 이벤트로 전달할 수 있습니다. 이 값은 채팅 본문에 표시되지 않고 정산에만 사용됩니다.

• type: "billing_usage", cost(float), cost_currency("USD"/"KRW")
• total_tokens · prompt_tokens · completion_tokens (선택)
• SSE에서는 답변 텍스트 뒤, [DONE] 앞에 배치