개요

Agent API는 외부 서비스에서 에이전트와 대화하기 위한 REST API입니다. 채팅방 생성/조회/삭제, 비동기 채팅, SSE(Server-Sent Events) 스트리밍 채팅을 지원합니다.

• Base URL: {host}/api/agent

인증

모든 요청에 X-API-KEY 헤더가 필요합니다.

X-API-KEY: your-api-key-here

잘못된 API 키 또는 권한이 없는 경우 403 Forbidden이 반환됩니다.

엔드포인트

1. 채팅방 생성

에이전트와 대화할 채팅방을 생성합니다.

POST /api/agent/{api_endpoint}/rooms

Path Parameters

Headers

Request Body

json

{

"user_ids": [1, 2]

}

Response

• Status: 200 OK

• Body: 생성된 채팅방 UUID

json "e36644fa-0b2e-11f0-b130-143627ec67e9"

Error Responses

Example

bash

curl -X POST "{host}/api/agent/my-agent/rooms"

-H "X-API-KEY: your-api-key"

-H "Content-Type: application/json"

-d '{"user_ids": [1]}'

2. 채팅방 조회

특정 채팅방의 상세 정보를 조회합니다.

GET /api/agent/{api_endpoint}/rooms/{chat_room_id}

Path Parameters

Headers

Response

• Status: 200 OK

• Body:

json

{

"id": "e36644fa-0b2e-11f0-b130-143627ec67e9",

"participants_json": {

"users": {

"1": {

"id": 1,

"type": "USER",

"joined_time": "2026-01-15T10:30:00",

"name": null

}

},

"agents": {

"42": {

"id": 42,

"type": "AGENT",

"joined_time": "2026-01-15T10:30:00",

"name": "My Agent"

}

}

},

"creator_id": 1,

"properties_json": {},

"created_time": "2026-01-15T10:30:00",

"updated_time": "2026-01-15T10:30:00"

}

Error Responses

Example

bash

curl -X GET "{host}/api/agent/my-agent/rooms/e36644fa-0b2e-11f0-b130-143627ec67e9"

-H "X-API-KEY: your-api-key”

3. 채팅방 삭제

채팅방을 삭제합니다.

DELETE /api/agent/{api_endpoint}/rooms/{chat_room_id}

Path Parameters

Headers

Response

• Status: 200 OK

• Body: true (성공) 또는 false (실패)

Error Responses

Example

bash

curl -X DELETE "{host}/api/agent/my-agent/rooms/e36644fa-0b2e-11f0-b130-143627ec67e9"

-H "X-API-KEY: your-api-key"

4. 비동기 채팅 요청

에이전트에게 메시지를 보내고 request_id를 즉시 반환받습니다. 결과는 별도의 상태 조회 API 또는 콜백 URL로 받을 수 있습니다.

POST /api/agent/{api_endpoint}/async

Path Parameters

Headers

Request Body (multipart/form-data)

params_json 구조

json

{

"input_message": "안녕하세요",

"chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9",

"input_files": [

"https://example.com/image1.jpg",

"s3://bucket-name/image2.jpg"

]

}

Response

• Status: 200 OK

• Body: 요청 ID (string)

json "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Error Responses

Example

bash

# 텍스트만 전송

curl -X POST "{host}/api/agent/my-agent/async"

-H "X-API-KEY: your-api-key"

-F 'params_json={"input_message": "안녕하세요", "chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9"}'

-F 'debug=false'

# 파일과 함께 전송

curl -X POST "{host}/api/agent/my-agent/async"

-H "X-API-KEY: your-api-key"

-F 'params_json={"input_message": "이 이미지를 분석해줘"}'

-F 'callback_url=https://my-service.com/webhook' -F 'files=@/path/to/image.png'

5. 비동기 요청 상태/결과 조회

비동기 채팅 요청의 처리 상태 및 결과를 조회합니다.

• GET /api/agent/{api_endpoint}/{request_id}/status

• GET /api/agent/{api_endpoint}/{request_id}/result

두 엔드포인트는 동일한 응답을 반환합니다.

Path Parameters

Headers

Response

• Status: 200 OK

• Body:

json

{

"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

"chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9",

"status": "COMPLETED",

"failure_reason": null,

"results": {

"output": "에이전트 응답 내용"

},

"artifact_metadata_json": null,

"request_params_json": "{\"method\":\"POST\",\"client\":\"127.0.0.1\",\"params\":[{\"type\":\"text\",\"text\":\"안녕하세요\"}]}",

"result_metadata_json": null,

"requested_time": "2026-01-15T10:30:00",

"updated_time": "2026-01-15T10:31:00"

}

status 값

Example

bash

curl -X GET "{host}/api/agent/my-agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status"

-H "X-API-KEY: your-api-key"

6. SSE 스트리밍 채팅

에이전트와 실시간 스트리밍 채팅을 수행합니다. Server-Sent Events를 통해 에이전트의 응답을 실시간으로 수신합니다.

POST /api/agent/{api_endpoint}/sse

Path Parameters

Headers

Request Body (multipart/form-data)

params_json 구조

json

{

"input_message": "안녕하세요",

"chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9",

"input_files": [

"https://example.com/image1.jpg"

]

}

Response

• Content-Type: text/event-stream

• 각 이벤트는 JSON 형태로 전달됩니다:

json {"ability_node_id": 1, "ability_node_name": "LLM Node", "results": {"output": "응답 텍스트..."}}

스트림이 종료되면 연결이 닫힙니다.

Example

bash

curl -X POST "{host}/api/agent/my-agent/sse"

-H "X-API-KEY: your-api-key"

-F 'params_json={"input_message": "안녕하세요", "chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9"}'

-F 'debug=false'

--no-buffer

JavaScript 클라이언트 예시

javascript

const formData = new FormData();

formData.append('params_json', JSON.stringify({

input_message: '안녕하세요',

chat_room_id: 'e36644fa-0b2e-11f0-b130-143627ec67e9'

}));

formData.append('debug', 'false');

const response = await fetch(`${host}/api/agent/my-agent/sse`, {

method: 'POST',

headers: { 'X-API-KEY': 'your-api-key' },

body: formData

});

const reader = response.body.getReader();

const decoder = new TextDecoder();

while (true) {

const { done, value } = await reader.read();

if (done) break;

const text = decoder.decode(value);

const event = JSON.parse(text.trim());

console.log('Node:', event.ability_node_name, 'Result:', event.results);

}

일반적인 사용 흐름

흐름 1: 비동기 방식 (Polling)

• 1. POST /{api_endpoint}/rooms → 채팅방 생성, room_id 획득

• 2. POST /{api_endpoint}/async → 메시지 전송, request_id 획득

• 3. GET /{api_endpoint}/{request_id}/status → 상태 폴링 (COMPLETED가 될 때까지)

• 4. 결과 확인 후 필요 시 2번부터 반복

흐름 2: 비동기 방식 (Callback)

• 1. POST /{api_endpoint}/rooms → 채팅방 생성, room_id 획득

• 2. POST /{api_endpoint}/async → callback_url과 함께 메시지 전송

• 3. 콜백 URL로 결과 수신 (서버에서 POST 요청)

흐름 3: 실시간 스트리밍 방식

• 1. POST /{api_endpoint}/rooms → 채팅방 생성, room_id 획득

• 2. POST /{api_endpoint}/sse → SSE 연결, 실시간 응답 수신

• 3. 스트림 종료 후 필요 시 2번부터 반복

참고: chat_room_id를 지정하지 않으면 채팅방이 자동 생성될 수 있습니다. 대화 이력을 유지하려면 동일한 chat_room_id를 사용하세요.