概要

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

パスパラメータ

ヘッダー

リクエストボディ

json

{

"user_ids": [1, 2]

}

レスポンス

• Status：200 OK

• Body：作成されたチャットルーム UUID

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

エラーレスポンス

例

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. チャットルーム一覧を取得

Agent API で作成したチャットルームの一覧を、ページネーション形式で取得します。

GET /api/agent/{api_endpoint}/rooms

パスパラメータ

ヘッダー

クエリパラメータ

レスポンス

• Status：200 OK

• Body：

json

{

"data": [

{

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

"creator_id": 1,

"properties_json": {},

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

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

}

],

"page": {

"page_size": 10,

"page_number": 0,

"total_elements": 1,

"total_pages": 1

}

}

エラーレスポンス

例

bash

curl -X GET "{host}/api/agent/my-agent/rooms?page_index=0&page_size=10"

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

3. チャットルーム詳細を取得

特定のチャットルームの詳細情報を取得します。

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

パスパラメータ

ヘッダー

レスポンス

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

}

エラーレスポンス

例

bash

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

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

4. チャットルームを削除

チャットルームを削除します。

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

パスパラメータ

ヘッダー

レスポンス

• Status：200 OK

• Body：true（成功）または false（失敗）

エラーレスポンス

例

bash

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

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

5. 非同期チャットリクエストを送信

メッセージを送信し、すぐに request_id を受け取ります。結果は別の status/result API で取得するか、コールバック URL 経由で受け取れます。

POST /api/agent/{api_endpoint}/async

パスパラメータ

ヘッダー

リクエストボディ（multipart/form-data）

params_json の構造

json

{

"input_message": "Hello",

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

"input_files": [

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

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

]

}

レスポンス

• Status：200 OK

• Body：Request ID（string）

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

エラーレスポンス

例

bash

# テキストのみ送信

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

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

-F 'params_json={"input_message": "Hello", "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": "Analyze this image"}'

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

6. 非同期リクエストのステータス／結果を取得

非同期チャットリクエストの処理状況と結果を確認します。

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

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

どちらのエンドポイントも同じレスポンスを返します。

パスパラメータ

ヘッダー

レスポンス

• 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": "Agent response content"

},

"artifact_metadata_json": null,

"request_params_json": "{\"method\":\"POST\",\"client\":\"127.0.0.1\",\"params\":[{\"type\":\"text\",\"text\":\"Hello\"}]}",

"result_metadata_json": null,

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

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

}

ステータス値

例

bash

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

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

7. SSE ストリーミングチャット

エージェントとリアルタイムでストリーミングチャットします。Server-Sent Events を通じてエージェントの応答をリアルタイムに受け取ります。

POST /api/agent/{api_endpoint}/sse

パスパラメータ

ヘッダー

リクエストボディ（multipart/form-data）

params_json の構造

json

{

"input_message": "Hello",

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

"input_files": [

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

]

}

レスポンス

• Content-Type：text/event-stream

• 各イベントは JSON として配信されます：

json {"ability_node_id": 1, "ability_node_name": "LLM Node", "results": {"output": "Response text..."}}

ストリームが終了すると接続は閉じられます。

例

bash

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

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

-F 'params_json={"input_message": "Hello", "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: 'Hello',

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：非同期（ポーリング）

• 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：非同期（コールバック）

• 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 から繰り返し

Note: chat_room_id を指定しない場合、チャットルームが自動作成されることがあります。会話履歴を保持するには同じ chat_room_id を使用してください。