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 フィールドに入力すれば、画像に関する質疑応答を完了できます。

チャット画像 / ファイル情報の取得ガイド

最終更新 | Gavin Guo (Medalsoft) | 2026年8月12日 GMT+8 14:23

本セクションでは、チャット（message）で画像・ファイル ID が返却された後に、「ID 取得」から「最終プレビュー/ダウンロード」まで到達するための API 呼び出し手順を整理します。

一、画像

フロー概要

message で画像 ID を取得
ekb-temporary を呼び出し、file_id から一時リンクを取得
authorization ヘッダー付きで一時リンクへアクセス
画像を表示/プレビュー

1. message で画像 ID を取得

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

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

7485579177907720192 が画像の file_id です。次の手順で実アクセス可能な一時ダウンロードリンクに変換します。

2. `file_id` で一時リンクを取得

エンドポイント：POST /webapi/knowledge/v1/file/ekb-temporary
目的：手順 1 の file_id を渡し、実アクセス可能な一時ファイルリンクを取得

リクエスト例：

curl 'https://demo.next.serviceme.com/webapi/knowledge/v1/file/ekb-temporary' \
	-H 'accept: application/json, text/plain, */*' \
	-H 'authorization: Bearer <token>' \
	-H 'content-type: application/json' \
	-H 'locale: zh-CN' \
	--data-raw '{"file_id":["7485579177907720192"]}'

主要パラメータ：

パラメータ	位置	説明
`authorization`	Header	Bearer Token。未指定時は拒否される
`file_id`	Body（配列）	一時リンクへ変換するファイル ID 一覧。複数指定可

返却値（例、署名は一部省略）：

https://demo.next.serviceme.com/webapi/knowledge/v1/file/ekb-temporary-file/83ba1459f010783229f5787c

3. 一時リンクへアクセス

返却された一時リンクに GET すれば画像を取得できますが、ここでも authorization は必須です。

GET https://demo.next.serviceme.com/webapi/knowledge/v1/file/ekb-temporary-file/<署名付き一時ファイル識別子>
authorization: Bearer <token>

チェックポイント：

メッセージ中の数値 ID は file_id であり、直接アクセス不可
一時リンクは匿名アクセス不可。必ず authorization を付与
画像が表示されない場合は file_id、Token 有効性、有効期限切れを優先確認

二、ファイル

フロー概要

message でファイル ID 情報を取得（category: "tool" が目印）
get_detail でファイル詳細（document_id 対応情報）を取得
ekb-preview でファイルをプレビュー

1. message でファイル ID を取得

チャットメッセージの category が "tool" の場合、通常はファイル関連メッセージであり、document_id などの識別子を含みます。

2. ファイル詳細を取得

エンドポイント：GET /webapi/knowledge/v1/rag/get_detail?document_id={document_id}
目的：ファイル名、種別、objectType などを取得し、プレビュー API の引数を組み立てる

リクエスト例：

curl 'https://demo.next.serviceme.com/webapi/knowledge/v1/rag/get_detail?document_id=7485164512316755968' \
	-H 'accept: application/json, text/plain, */*' \
	-H 'authorization: Bearer <token>' \
	-H 'content-type: application/json' \
	-H 'locale: zh-CN' \
	--data-raw '{}'

主要パラメータ：

パラメータ	位置	説明
`document_id`	Query String	message から取得する文書 ID
`authorization`	Header	Bearer Token が必須

3. ファイルをプレビュー

エンドポイント：POST /webapi/knowledge/v1/file/ekb-preview
目的：id、objectType、filetype を使ってプレビュー内容またはプレビュー URL を取得

リクエスト例：

curl 'https://demo.next.serviceme.com/webapi/knowledge/v1/file/ekb-preview' \
	-H 'accept: application/json, text/plain, */*' \
	-H 'authorization: Bearer <token>' \
	-H 'content-type: application/json' \
	-H 'locale: zh-CN' \
	--data-raw '{"id":"7485164641157386241","objectType":"2","filetype":1}'

主要パラメータ：

パラメータ	説明
`id`	ファイル ID（通常は `get_detail` の返却値。`document_id` と異なる場合あり）
`objectType`	オブジェクト種別（`get_detail` の返却値を使用）
`filetype`	ファイル種別識別子
`authorization`	Bearer Token が必須

チェックポイント：

ファイル関連メッセージは category: "tool" で識別
呼び出し順序は get_detail → ekb-preview
Token 期限切れは関連 API 全体で 401 の主因

三、画像 vs ファイル API 比較

シナリオ	メッセージ識別子	主要 API フロー	authorization 必要性
画像	Markdown 画像構文 `![](/api/workspace/file/TemporaryFile/{file_id})`	`ekb-temporary`（リンク変換）-> 一時リンクへアクセス	はい（2 ステップとも必要）
ファイル	`category: "tool"`	`get_detail`（詳細取得）-> `ekb-preview`（プレビュー）	はい（2 ステップとも必要）

共通ルール：すべての呼び出しで有効な 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. message で画像 ID を取得​

2. file_id で一時リンクを取得​

3. 一時リンクへアクセス​

二、ファイル​

フロー概要​

1. message でファイル ID を取得​

2. ファイル詳細を取得​

3. ファイルをプレビュー​

三、画像 vs ファイル API 比較​

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. message で画像 ID を取得

2. `file_id` で一時リンクを取得

3. 一時リンクへアクセス

二、ファイル

フロー概要

1. message でファイル ID を取得

2. ファイル詳細を取得

3. ファイルをプレビュー

三、画像 vs ファイル API 比較