Agent API の作成と外部呼び出し

目的：公開済みの Agent に対して外部システムから呼び出し可能な API Key を生成し、公式の呼び出しドキュメントを取得して連携することです。

API Key の作成

Agent の API Console に入る

Agent の編成ページ右上にある API Console をクリックします。
画面に入ると API channels の一覧ページが表示されます。

API Channel を作成する

Add a new channel をクリックします。
ポップアップで以下を入力します：
- Name：例 API
- Description：例 API
Save をクリックして保存します。

Channel のキー画面に入る

channel 一覧で、先ほど作成したレコードを見つけます。
Learn More をクリックして API Keys ページに入ります。

API Key を生成する

Add a key をクリックします。
ポップアップで以下を設定します：
- Name：例 API
- Deadline：要件に応じて有効期限を選択します（例：3 Months）
Save をクリックしてキーを生成します。
すぐに Key をコピーして安全に保存してください（通常、画面を閉じると完全な内容は再表示されません）。

呼び出しドキュメントを取得して連携する

API Keys ページで Access Document をクリックします。
ドキュメント内で、外部システム接続用に以下の情報をコピーします：
- リクエスト先アドレス（Endpoint）
- 認証方式（通常は Authorization: Bearer <API_KEY>）
- リクエストボディ例（入力パラメータ）
- レスポンスボディ例（出力フィールド）
外部システムはドキュメントの例に従って HTTP リクエストを送信することで、この Agent を呼び出せます。

インターフェースを呼び出して Agent とチャットする

API Key 認証

Method: POST
Endpoint: https://{host}/webapi/lite_api/v2/api/chat-with-bot/chat
Header: api-key: YOUR_API_KEY

リクエストボディ（JSON）の主要フィールド：

messages（必須）：会話メッセージ配列。role は user/ai/system/human/assistant をサポート
stream（任意、デフォルト false）：ストリーミングで返すかどうか
show_tool_result（任意、デフォルト false）：ツール結果または参照を返すかどうか
file_id（任意）：ファイル ID（文字列または文字列配列）
workspace_id（任意）：ワークスペース ID（文字列または文字列配列）
layout_mode（任意、デフォルト 0）：1 はナレッジ検索内容を返し、0 は通常チャット
skip_hint（任意、デフォルト false）：PII ヒントをスキップするかどうか

注意：

最後のメッセージの role には human または user の使用を推奨します
画像入力には、先に「画像アップロード API」を呼び出して image_ids を取得する必要があります

最小リクエスト例：

{
	"messages": [
		{"role": "system", "content": "Today is Monday"},
		{
			"role": "user",
			"content": [
				{"type": "text", "text": "Please describe the following images"},
				{"type": "image_ids", "image_ids": ["uuid1", "uuid2"]}
			]
		}
	],
	"stream": false,
	"show_tool_result": false
}

成功レスポンスの要点：

非ストリーミング：data.full_output が最終回答、data.tool_result が任意のツール結果
ストリーミング：イベントストリームには stream、tool_result、end が含まれます

Access Token の取得

Access Token は次の3ステップで取得します：Client を作成 → Client を照会して認証情報を取得 → Token を生成。

1. Client を作成する

Method: POST
Endpoint: https://{host}/webapi/lite_api/v1/admin/clients
Header: Authorization: Bearer YOUR_ADMIN_TOKEN

リクエストボディ（JSON）の主要フィールド：

name（必須）：Client 名称
description（任意）：説明
trusted domains（任意）：信頼済みドメインのリスト、デフォルトは空の配列

curl --location 'https://{host}/webapi/lite_api/v1/admin/clients' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ADMIN_TOKEN' \
  --data '{
    "name": "テスト",
    "description": "テスト",
    "trusted domains": []
  }'

成功レスポンスには client_id と client_secret が含まれます。安全に保管してください。

2. Client 一覧を照会する（任意）

作成済みの Client と client_id を確認するには、以下のエンドポイントを使用します：

Method: GET
Endpoint: https://{host}/webapi/lite_api/v1/admin/clients?page=1&page_size=10
Header: Authorization: Bearer YOUR_ADMIN_TOKEN

curl --location 'https://{host}/webapi/lite_api/v1/admin/clients?page=1&page_size=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_ADMIN_TOKEN'

3. Access Token を生成する

ステップ 1 で取得した client_id と client_secret を使ってアクセストークンを生成します：

Method: POST
Endpoint: https://{host}/webapi/lite_api/v1/iam/client_token

リクエストボディ（JSON）の主要フィールド：

client_id（必須）：Client 作成時に取得した ID
client_secret（必須）：Client 作成時に取得した Secret
username（必須）：関連付けるユーザー名

curl --location 'https://{host}/webapi/lite_api/v1/iam/client_token' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "username": "YOUR_USERNAME"
  }'

成功レスポンス例：

{
  "code": 200,
  "data": {
    "access_token": "eyJhbGci...",
    "token_type": "Bearer",
    "expires_in": 3600
  },
  "message": "success"
}

レスポンス中の access_token の値を、以下の API の YOUR_ACCESS_TOKEN として使用してください。

Access Token 認証

Method: POST
Endpoint: https://{host}/webapi/lite_api/v2/api/chat-with-bot/{agent_id}
Header: Authorization: Bearer YOUR_ACCESS_TOKEN

パスパラメータ：

agent_id：対象 Agent の UUID（Agent ページの URL から取得可能）

リクエストボディ（JSON）の主要フィールド：

messages（必須）：role は user/human のみに制限され、配列長は最大 1
stream、show_tool_result、file_id、workspace_id、layout_mode、skip_hint（上記と同じ）
conversation_id（任意）：マルチターン会話のセッション ID。未指定の場合はシステムが作成し、レスポンスで返します

最小リクエスト例：

{
	"messages": [
		{
			"role": "user",
			"content": [
				{"type": "text", "text": "Please describe the following images"},
				{"type": "image_ids", "image_ids": ["uuid1", "uuid2"]}
			]
		}
	],
	"stream": false,
	"show_tool_result": false,
	"layout_mode": 0,
	"conversation_id": null
}

成功レスポンスの要点：

data.conversation_id：後続のマルチターン会話で再利用するために使用
data.full_output：最終回答

画像をアップロードする

Method: POST
新しい Endpoint（推奨）：https://{host}/webapi/lite_api/v2/api/chat-with-bot/upload-images
旧 Endpoint（廃止予定）：https://{host}/webapi/lite_api/v2/api/chat-with-bot/{agent_id}/upload-images
Header（例）：api-key: YOUR_API_KEY
Content-Type: multipart/form-data

リクエストパラメータ：

files（必須）：1 つまたは複数の画像ファイル

成功レスポンス例：

{
	"code": 201,
	"data": {
		"ids": ["2973a321-905d-4f07-9ad4-ff0ef47a174f"]
	},
	"message": "success"
}

説明：

返された ids をチャットインターフェースの messages[].content 内の image_ids フィールドに入力すれば、画像に関する質疑応答を完了できます。

チャットメッセージからの画像・ファイルの取得

チャットメッセージで画像またはファイル ID が返された後、アクセス可能なリンクまたはプレビューコンテンツを取得するために追加の API 呼び出しが必要です。「ID 返却」から「最終プレビュー/ダウンロード」までの完全な呼び出しフローを以下に説明します。

画像の取得フロー

ステップ 1：メッセージから画像 ID を抽出する

チャットメッセージ内では、画像は Markdown の画像構文で返され、リンク内に一時ファイル ID が含まれます：

![](/api/workspace/file/TemporaryFile/7485579177907720192)

ここで 7485579177907720192 が file_id であり、次のステップでアクセス可能な一時リンクを取得するために使用します。

ステップ 2：file_id を一時リンクに交換する

Method: POST
Endpoint: https://{host}/webapi/knowledge/v1/file/ekb-temporary
Header: authorization: Bearer YOUR_TOKEN

リクエストボディ（JSON）の主要フィールド：

file_id（必須）：ファイル ID の配列。複数をまとめて渡せます

curl 'https://{host}/webapi/knowledge/v1/file/ekb-temporary' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"file_id":["7485579177907720192"]}'

成功レスポンスには実際にアクセスできる一時ファイルリンクが含まれます：

https://{host}/webapi/knowledge/v1/file/ekb-temporary-file/<署名済み一時ファイル識別子>

ステップ 3：一時リンクにアクセスする

前のステップで返された一時リンクに GET リクエストを送ることで画像を取得できます。authorization ヘッダーは必須であり、未指定の場合は 401/403 が返されます。

GET https://{host}/webapi/knowledge/v1/file/ekb-temporary-file/<署名済み一時ファイル識別子>
Header: authorization: Bearer YOUR_TOKEN

注意事項：

メッセージ内の数字 ID は file_id に過ぎず、直接アクセスはできません。まず ekb-temporary を呼び出して実際の一時リンクを取得する必要があります
一時リンクにアクセスする際も authorization ヘッダーは必須です
画像が表示されない場合は、まず次を確認してください：① file_id が正しいか ② Token が有効か ③ 一時リンクが期切れており再取得が必要か

ファイルの取得フロー

ステップ 1：ファイルメッセージを識別する

チャットメッセージの category フィールドが "tool" の場合、それはファイル関連のメッセージであり、対応する document_id が含まれます。

ステップ 2：ファイル詳細を取得する

Method: GET
Endpoint: https://{host}/webapi/knowledge/v1/rag/get_detail?document_id={document_id}
Header: authorization: Bearer YOUR_TOKEN

リクエストパラメータ：

document_id（Query String、必須）：メッセージから取得したドキュメント ID

curl 'https://{host}/webapi/knowledge/v1/rag/get_detail?document_id=7485164512316755968' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{}'

レスポンスには、プレビュー API に必要な id、objectType、filetype などのフィールドが含まれます。

ステップ 3：ファイルをプレビューする

Method: POST
Endpoint: https://{host}/webapi/knowledge/v1/file/ekb-preview
Header: authorization: Bearer YOUR_TOKEN

リクエストボディ（JSON）の主要フィールド：

パラメータ	説明
`id`	ファイル ID（`get_detail` レスポンスから取得。`document_id` と別の場合あり）
`objectType`	オブジェクトタイプ（`get_detail` レスポンスから取得）
`filetype`	ファイルタイプ識別子（`get_detail` レスポンスから取得）

curl 'https://{host}/webapi/knowledge/v1/file/ekb-preview' \
  -H 'accept: application/json, text/plain, */*' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'content-type: application/json' \
  --data-raw '{"id":"7485164641157386241","objectType":"2","filetype":1}'

注意事項：

ファイルメッセージは category: "tool" で識別します
まず get_detail を呼び出して完全な詳細情報（objectType、filetype などプレビュー API に必要なパラメータを含む）を取得し、その後 ekb-preview でプレビューを完了してください
Token の有効期限切れは、全ての API に対して 401 を返します

画像 vs. ファイルインターフェース比較

シナリオ	メッセージ識別子	主要 API	authorization 必要
画像	Markdown 画像構文 `![](/api/workspace/file/TemporaryFile/{file_id})`	`ekb-temporary` → 一時リンクにアクセス	はい（両ステップ共に）
ファイル	`category: "tool"`	`get_detail` → `ekb-preview`	はい（両ステップ共に）

注意：全ての API 呼び出しには有効な Bearer Token の携帯が必要です。Token の有効期限切れは最も一般的な問題の突破口です。

API Key の作成​

Agent の API Console に入る​

API Channel を作成する​

Channel のキー画面に入る​

API Key を生成する​

呼び出しドキュメントを取得して連携する​

インターフェースを呼び出して Agent とチャットする​

API Key 認証​

Access Token の取得​

1. Client を作成する​

2. Client 一覧を照会する（任意）​

3. Access Token を生成する​

Access Token 認証​

画像をアップロードする​

チャットメッセージからの画像・ファイルの取得​

画像の取得フロー​

ステップ 1：メッセージから画像 ID を抽出する​

ステップ 2：file_id を一時リンクに交換する​

ステップ 3：一時リンクにアクセスする​

ファイルの取得フロー​

ステップ 1：ファイルメッセージを識別する​

ステップ 2：ファイル詳細を取得する​

ステップ 3：ファイルをプレビューする​

画像 vs. ファイル インターフェース比較​

API Key の作成

Agent の API Console に入る

API Channel を作成する

Channel のキー画面に入る

API Key を生成する

呼び出しドキュメントを取得して連携する

インターフェースを呼び出して Agent とチャットする

API Key 認証

Access Token の取得

1. Client を作成する

2. Client 一覧を照会する（任意）

3. Access Token を生成する

Access Token 認証

画像をアップロードする

チャットメッセージからの画像・ファイルの取得

画像の取得フロー

ステップ 1：メッセージから画像 ID を抽出する

ステップ 2：file_id を一時リンクに交換する

ステップ 3：一時リンクにアクセスする

ファイルの取得フロー

ステップ 1：ファイルメッセージを識別する

ステップ 2：ファイル詳細を取得する

ステップ 3：ファイルをプレビューする

画像 vs. ファイルインターフェース比較