AIエージェントAPI

AIエージェントは、ボットの頭脳となる存在です。指示、性格、言語、知識、ツールなどが含まれます。エージェントを一度構築すれば、あとはトラフィックを向けるだけです。このガイドでは、APIを通じてエージェントに対して行えるすべての操作（作成、設定、知識やツールの付与、ドラフトの確認、会話のルーティングなど）について解説します。

ベースURL — https://api.youraiconnector.com/v1
認証 — APIキー（認証を参照）
エラーとページネーション — エラーとページネーションを参照

以下のすべての例では、cURLでの ?apiKey= クエリ形式と、JavaScriptおよびPythonでの X-API-Key ヘッダーを示しています。どちらの方法もすべてのエンドポイントで使用可能です。

エージェントという概念が初めての場合は、まずAIエージェントをお読みください。

エージェントの構成要素

4つの要素が個別に管理されています。作業を始める前に、それぞれの役割を理解しておくと役立ちます。

要素	内容	設定場所
構成 (Configuration)	指示、ルール、目標、性格、言語、AIティア、予約およびフォローアップの動作	`PUT /agents/{agentId}` または、より限定的な `PUT /agents/{agentId}/bot-config`
知識 (Knowledge)	FAQおよび知識ソース（プラットフォームが読み込んだページやドキュメント）	FAQ API および `POST /agents/{agentId}/kb-sources`
ツール (Tools)	会話中にエージェントが呼び出す可能性のあるカスタム関数およびMCPサーバー	`POST /agents/{agentId}/custom-functions` および `POST /agents/{agentId}/mcp-servers`
ルーティング (Routing)	どのチャネルや会話が実際にこのエージェントに到達するか	エントリポイント — `PUT /entry-points/channel-defaults` および `POST /agents/{agentId}/entry-points`

新しいエージェントは、ルーティングを設定するまで誰にも応答しません。 エージェントを作成しただけでは、チャネルには配置されません。これは多くの統合で見落とされがちなステップです。このページの最後にあるエージェントへの会話のルーティングを参照してください。

エージェントオブジェクト

完全なエージェントドキュメントは、FAQリスト、知識ソース、Webサイトから読み込まれたページコンテンツなどを含み、数百キロバイトに及ぶ大きなものです。そのため、リストを取得する際は、エージェントごとに短いサマリー行が返されます。

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

フィールド	型	説明
`id`	string	エージェントの一意の識別子。
`name`	string \| null	ダッシュボードに表示されるエージェント名。
`active`	boolean \| null	エージェントが現在応答を許可されているかどうか。
`language`	string \| null	エージェントが応答に使用する言語。
`goal`	string \| null	エージェントが目指す目標。最初の200文字に短縮されます（末尾の省略記号は短縮されたことを示します）。
`tags`	array \| null	エージェントのタグ付けルール。
`anthropic_model`	string \| null	AI品質ティア: `standard`、`economy`、`max`、または `mini`。
`ai_speed`	string \| null	エージェントが応答前に適用する推論のレベル: `fast`、`fast_thinker`、`balanced`、または `thorough`。
`enable_bookings`	boolean \| null	エージェントが予約を受け付けられるかどうか。
`enable_follow_ups`	boolean \| null	エージェントがフォローアップメッセージを送信するかどうか。
`faq_refs_count`	integer	このエージェントのナレッジベースに含まれるFAQの数。
`kb_source_refs_count`	integer	リンクされている知識ソースの数。
`created_at`	integer \| null	作成日時（エポックミリ秒）。
`last_modified_at`	integer \| null	最終更新日時（エポックミリ秒）。

完全なドキュメントには、その他すべて（instructions、rules、personality、availability、follow_up_config、リンクされたFAQおよび知識ソースのリスト、生成された文章ブロック、および実行状態（tag_generation、optimize_run））が含まれます。

一部のレスポンスには substrate_campaign_id も含まれます。これは古いアカウントで保持されている内部レコードであり、操作する必要はありません。新しいアカウントでは null であるか、存在しません。

エージェントのリスト取得

GET /agents — アカウント内のすべてのエージェントを、新しい順に取得します。

このエンドポイントはページネーションされません。デフォルトでは、各エージェントは完全な構成とともに返されますが、これは非常に大きなデータになります。エージェント1つで580 KBに達し、64エージェントのアカウントでは3 MBを超える可能性があります。代わりに view=summary を渡すとエージェントごとに短い行が返されるため、必要なものを Get an Agent で読み取ってください。

クエリパラメータ

パラメータ	説明
`view`	短い行にするには `summary` に設定します。それ以外の値を指定すると `400` が返されます。省略すると完全なドキュメントが返されます。
`fields`	`view=summary` と併用する場合のみ適用されます。保持する概要キーをカンマ区切りで指定します（例: `id,name,active`）。`id` は常に含まれ、不明な名前は無視されます。

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

レスポンス (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

エージェントの作成

POST /agents — 実際には name のみが必要です。すでに把握している構成があれば、それと一緒に送信してください。新しいエージェントはデフォルトでアクティブになります。

リクエストフィールド（name 以外はすべてオプション）

フィールド	型	説明
`name`	string	エージェント名。
`active`	boolean	すぐに応答可能かどうか。デフォルトは `true` です。
`language`	string	エージェントが応答する言語。
`instructions`	string	連絡先との対話方法を導く主要な指示。
`rules`	string	常に従わなければならない厳格なルール。
`goal`	string	目指すべき成果。
`personality`	string	口調と性格。
`availability`	object	曜日ごとの稼働時間 — Set active hours を参照してください。
`ai_speed`	string	`fast`、`fast_thinker`、`balanced`、または `thorough`。
`anthropic_model`	string	`standard`、`economy`、`max`、または `mini`。
`scrape_urls`	string[]	エージェントの指示を構築するために読み込むページ。

ウェブサイトからエージェントを構築する。 scrape_urls を含めると、プラットフォームがそれらのページを読み取り、指示を自動的に作成します。レスポンスには生成が開始されたかどうかが示されるため、エージェントの進捗状況をポーリングする必要があるかどうかがわかります。

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

レスポンス (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued は、提供されたページからプラットフォームが指示の作成を開始したときに true になります。

400 は、ボディがJSONオブジェクトではない、フィールドが拒否された、またはエージェントがプランで許可されている構成サイズを超えていることを意味します。403 は、アカウントが送信した設定のいずれか（アカウントプロバイダーが付与していないAIティアなど）を使用する権限がないことを意味します。

エージェントの取得

GET /agents/{agentId}

fields にカンマ区切りのリストを渡すと、必要なものだけを取得できます（例: fields=name,active,goal）。id は常に含まれ、エージェントに存在しない名前は拒否されず無視されます。省略するとドキュメント全体が取得されます。

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

アカウントに存在しないエージェントを指定すると 404 が返されます。

エージェントの更新

PUT /agents/{agentId} — 変更したいフィールドのみを送信してください。それ以外は変更されません。

ネストされた設定は、ドット区切りのキーを使用してリーフ（末端）ごとに指定できるため、"availability.monday" は月曜日のみを変更し、週の残りの部分はそのまま維持します。

注意点

エージェントが予約を入れる予約可能イベントタイプを変更するには、event_id（イベントのID、またはクリアする場合は null）を送信します。複数のイベントを一度にリンクするには、配列を指定して event_ids を送信します。最初のイベントがプライマリとなり、[] はすべてをリンク解除します。event_id と event_ids は相互に排他的であり、event フィールド自体を直接書き込むことはできません。
enable_bookings は真偽値である必要があり、booking_provider は default、zenchef、formitable のいずれかである必要があります。
所有権およびIDフィールドは無視されます。内部実行状態（生成および最適化の進捗）も同様です。
ルーティングはここでは設定されません。 チャネルの応答者としてエージェントを設定するには PUT /entry-points/channel-defaults を、キーワードおよびコメントルールには POST /agents/{agentId}/entry-points を、一時停止または再開には PATCH /agents/{agentId}/active を使用してください。

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

レスポンス (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

空のボディは "No fields to update" を伴う 400 を返します。

ボット設定の更新

PUT /agents/{agentId}/bot-config — 会話設定のみを変更するための限定的な方法です。

エージェントには個別のボットセクションはありません。設定はエージェントに直接配置されるため、ここでのフィールド名は PUT /agents/{agentId} に送信するものと同じです。このエンドポイントは、それらの一部を変更するための安全で焦点を絞った方法として存在します。少なくとも1つのフィールドが必要です。

フィールド	説明
`instructions`	エージェントが連絡先とどのように対話するかを導く主要な指示。
`rules`	エージェントが常に従わなければならない厳格なルール。
`goal`	各会話で目指すべき成果。
`personality`	口調や性格の説明。
`language`	エージェントが返信する言語。
`ai_speed`	`fast`、`fast_thinker`、`balanced`、または `thorough`。
`anthropic_model`	`standard`、`economy`、`max`、または `mini`。
`max_messages`	会話ごとのエージェントの最大メッセージ数。
`alert_human_when`	エージェントが人間のチームメンバーに通知すべきタイミング。
`ai_transparency`	エージェントがAIであることを開示するかどうか。

ここではフィールド名は単純な名前である必要があります — 文字、数字、アンダースコア、ハイフンのみ使用可能です。このエンドポイントではドット区切りのパスは受け入れられないため（PUT /agents/{agentId} とは異なります）、bot.goal は 400 を伴って拒否されます。

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

長いテキストはプランで許可されている設定サイズにカウントされるため、非常に大きな指示セットは 400 で拒否される可能性があります。

アクティブな時間帯の設定

PUT /agents/{agentId}/active-hours — エージェントが自動的に返信する時間帯です。これらの時間外は応答しません。

曜日（monday から sunday）をキーとする availability オブジェクトを送信します。各曜日には、24時間形式の HH:MM で、単一の時間枠または時間枠のリストを指定します。省略した曜日は以前の設定が保持され、曜日以外のキーはすべて拒否されるため、タイプミスによって何も起こらないという事態を防げます。

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

レスポンス (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

不正な曜日キーは 400 を返します: "Invalid availability keys: funday. Allowed keys: monday through sunday."

エージェントの一時停止または再開

PATCH /agents/{agentId}/active — エージェントのオン/オフを切り替えます。一時停止中のエージェントはすべての設定を保持しますが、即座に応答を停止します。再開すると直ちに有効になります。

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

レスポンス (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active は真のブール値である必要があります。それ以外の場合は "active (boolean) is required" を伴う 400 が返されます。

エージェントの複製

POST /agents/{agentId}/duplicate — 設定を保持したままコピーを作成します。コピーは、チャネルまたはエントリーポイントを割り当てるまで何も送信しません。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

レスポンス (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

複製は、ゼロから作成する場合と同様にプランのエージェント許容量としてカウントされるため、アカウントが上限に達している場合は 403 で拒否されます。

エージェントの削除

DELETE /agents/{agentId}

エージェントが削除されると機能しなくなるもの（ブロードキャスト、エントリーポイント、または古いアカウントの場合はキャンペーン）にまだ接続されている場合、削除は拒否されます。応答には、削除を妨げているものがリストされるため、それらを先に切り離してから再試行してください。

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

レスポンス (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

ブロック済み (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

下書き：変更を公開前に確認する

エディターで行った編集や、AIで最適化によって生成された書き換えは、公開するまで「未公開の下書き」として保持されます。それまでの間、稼働中のエージェントは現在の設定で応答を続けます。

下書きを公開する

POST /agents/{agentId}/publish-draft — 下書きを稼働中の設定に移行し、同時に下書きをクリアします。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

レスポンス (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys は、下書きから稼働中のエージェントに移行された設定をリスト表示するため、何が変更されたかを確認できます。

この呼び出しを行う前に、下書きが存在することを確認してください。 下書きのないエージェントを公開することはサポートされておらず、現時点では具体的なメッセージではなく汎用的なメッセージを伴う 500 が返されます。代わりに下書きを破棄するには、以下の破棄を使用してください。

下書きを破棄する

POST /agents/{agentId}/discard-draft — 下書きを破棄し、ライブ設定をそのままの状態に保ちます。下書きがない状態で呼び出しても安全で、何も起こりません。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

AIでエージェントを最適化する

POST /agents/{agentId}/optimize — フィードバック（「割引を提案し続ける」、「回答が長すぎる」など）に基づいてエージェントの設定を書き換え、その書き換え内容をライブにするのではなく、下書きとして保存します。

user_feedback（単純な指示）を送信するか、特定の不適切な回答に対して反応する場合は、thumbs_down_feedbackと問題のthumbs_down_messageを一緒に送信します。少なくともどちらか一方にはテキストを含める必要があります。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

レスポンス (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

処理はバックグラウンドで実行され、呼び出しは即座に返ります。GET /agents/{agentId}でエージェントを読み取り、optimize_run.statusを監視してください。Draftに戻れば、書き換え内容がエージェントの下書きとして待機しています。内容を確認し、公開するか破棄するかを選択してください。

エージェントごとに一度に実行できるのは1つだけです。実行中に2回目の呼び出しを行うと409が返されます。これにはAIクレジットが消費されます。

タグ付けルール

タグ付けルールは、タグと、それがいつ適用されるかの説明で構成されます。会話中、エージェントはその説明を読み取り、条件に合致したときに連絡先にタグを付けます。これがタグ駆動型の自動化がトリガーされる仕組みです。

ルールオブジェクト

フィールド	必須	説明
`name`	はい	適用するタグ（例: `hot-lead`）。
`description`	いいえ	エージェントがタグを適用するタイミング（従うべき指示として記述）。
`webhook`	いいえ	エージェントがこのタグを適用したときに呼び出されるURL。
`ai_can_remove`	いいえ	エージェントがタグを再度削除できるかどうか。デフォルトは`false`。
`tag_id`	いいえ	ルールをリンクさせるアカウント上の既存のタグのID。指定がない場合、ルールは同じ名前のタグにリンクされ、存在しない場合は作成されます。そのため、すべてのルールは後からタグIDで指定可能です。

タグ付けルールを追加する

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

レスポンス (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

タグ付けルールを置き換える

PUT /agents/{agentId}/tags/{tagId} — ルールはパス内のタグIDによって検索され、マージではなく全体が置き換えられます。そのため、変更する部分だけでなく、ルール全体を送信してください。ルールが指し示すタグは、tag_idを省略した場合でも保持されるため、編集によってルールがタグから切り離されることはありません。

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

タグ付けルールの削除

DELETE /agents/{agentId}/tags/{tagId} — エージェントはそのタグの適用を停止します。タグ自体、およびすでにそのタグが付与されている連絡先には影響しません。

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

エージェントが存在しない場合、またはそのタグに対するルールが存在しない場合、両方のエンドポイントが404を返します。

AIによるタグセットの生成

POST /agents/{agentId}/tags/generate — エージェント自身の指示と目標を読み取り、ルールセット全体（タグ名と各ルールの「適用条件」の文言）を設計します。

フィールド	説明
`mode`	`merge`（デフォルト）は、エージェントに既存のルールを保持したまま追加します。`replace`はセットをゼロから設計します。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

レスポンス (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

処理はバックグラウンドで実行されます。エージェントを読み取り、tag_generation.statusを監視してください。ルール自体はエージェントのtagsに反映されます。エージェントごとに一度に実行できるのは1つだけです（それ以外の場合は409となります）。また、AIクレジットを消費します。

ナレッジソース

ナレッジソースとは、プラットフォームが読み込んだページやドキュメントのことです。エージェントにナレッジソースを添付することで、その内容に基づいて回答できるようになります。

ソースIDの取得元。 ナレッジベースエンドポイントを使用してコンテンツを追加します。ページにはPOST /kb-sources/url、ドキュメントにはPOST /kb-sources/file、サイト全体にはPOST /kb-sources/bulk-importを使用します。これらは、準備が完了するまでGET /kb-sources/{sourceId}でポーリングするsource_idを返します。POST /kb-sources/urlはautoLinkToAgentIdも受け付けます。これにより、インポート完了と同時にソースがエージェントに添付されるため、以下の添付呼び出しを省略できます。

ナレッジソースの添付

POST /agents/{agentId}/kb-sources — リストを含むkb_source_idsを送信して一度にセット全体を添付する（サイトのクロール後に推奨）、またはkb_source_idを使用して単一のソースを添付します。どちらか一方を送信してください。すでに添付されているものを添付しても何も変更されません。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

レスポンス (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

ナレッジソースの切り離し

DELETE /agents/{agentId}/kb-sources/{kbSourceId} で1つ、または kb_source_ids を指定した POST /agents/{agentId}/kb-sources/bulk-remove で複数削除できます。一括削除は POST となります。これはIDのリストがボディに含まれるためです。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

ソース自体は削除されず、他のエージェントでも引き続き利用可能です。アタッチされていないものをデタッチしても何も変更されません。

よくある質問 (FAQ)

FAQは専用のエンドポイントで管理され、そこからエージェントにリンクされます。POST /faqs/{faqId}/link で { "agent_id": "ag7HkQ2ZpLxR3mNb" } を行い、POST /faqs/{faqId}/unlink で解除します。1つのFAQは、任意の数のエージェントで共有できます。FAQs API を参照してください。

FAQはリンクされたエージェントによってのみ使用されます。作成しただけでは使用されません。

ツール

カスタム関数

POST /agents/{agentId}/custom-functions を使用すると、エージェントは会話中にカスタム関数を呼び出せるようになります。同じアカウントに属する関数のみをアタッチでき、すでにアタッチされている関数を再度アタッチしても何も変更されません。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} でデタッチします。関数自体は削除されず、他のエージェントでも引き続き利用可能です。

関数自体の管理は /custom-functions で行います。関数についてはカスタム関数を参照してください。

MCPサーバー

MCPサーバーは、エージェントが独自に検出して呼び出せる、すぐに使えるツールバンドルです。ボットへのMCPサーバーの接続を参照してください。サーバーはアカウントごとに一度登録し、その後、使用させるエージェントにアタッチします。

MCPサーバーを使用するには、プランで カスタム関数 機能が必要です。この機能がない場合、アカウントレベルの /mcp-servers エンドポイントは 403 を返します。すでに登録済みのサーバーをエージェントにアタッチすることに制限はありません。

サーバーの登録

POST /mcp-servers

フィールド	必須	説明
`name`	はい	サーバーのラベル。
`url`	はい	サーバーのアドレス。パブリックインターネット経由で到達可能である必要があります。
`auth_type`	いいえ	静的認証ヘッダーの場合は `header` (デフォルト)、または `oauth2`。
`auth_header_name`	いいえ	資格情報を送信するためのヘッダー。デフォルトは `Authorization` です。
`auth_header_value`	いいえ	資格情報そのもの。レスポンスで返されることはありません。
`enabled`	いいえ	サーバーがエージェントに対して利用可能かどうか。デフォルトは `true` です。
`enabled_tools`	いいえ	ツール名の許可リスト。`null` は、サーバーが提供するすべてのツールが有効であることを意味します。
`tool_policies`	いいえ	ツールごとの制限（ツール名で指定）。ツールの実行頻度、結果のキャッシュ、読み取り専用のオーバーライドを設定します。`null` を渡すとすべてクリアされます。

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

レスポンス (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

保存時に、プラットフォームはサーバーに接続し、提供されるツールリストをキャッシュします。到達できないサーバーであっても保存は可能であり、その理由は last_error に記録され、ツールリストは空になります。これにより、先に登録を行い、後から接続性を修正することができます。

oauth2 の auth_type を指定すると、oauth_connected: false を設定してツールなしで登録が保存されます（トークンがまだ存在しないため）。OAuth サーバーの承認にはブラウザでのサインインが必要であり、API 経由ではなくダッシュボードから行われます。

サーバーのリスト表示、更新、削除

GET /mcp-servers — 登録済みのすべてのサーバーを、新しい順に servers の下に表示します。
PUT /mcp-servers/{serverId} — 変更したい項目のみを送信します。URL や認証フィールドを変更すると、接続が再テストされ、キャッシュされたツールリストが更新されます。
DELETE /mcp-servers/{serverId} — 登録を削除し、それが有効になっていたすべてのエージェントおよびキャンペーンからリンクを解除します。

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

シークレットが返されることはありません。 レスポンスには資格情報の代わりに auth_header_value_set（値が保存されていることを示す true/false フラグ）が含まれ、OAuth トークンやクライアントシークレットはサーバー側に保持されます。それ以外のすべて（name、url、enabled、auth_type、auth_header_name、tools、enabled_tools、tool_policies、oauth_connected、tools_cached_at、last_connected_at、last_error、created_at、updated_at）は返されます。

接続のテスト

POST /mcp-servers/test-connection — サーバーに接続し、そのツールをリストアップします。呼び出しには2つの方法があります：

server_id を使用 — 保存済みの構成をテストし、キャッシュされたツールリストを更新します。
インラインの url（および auth_header_name / auth_header_value）を使用 — 保存前テストであり、何も保存されません。

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

レスポンス (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

接続失敗は HTTP エラーではありません。200 に success: false と何が問題だったかを示す error が含まれて返されるため、オペレーターが編集中のフィールドの横にそれを表示できます。

エージェントへのサーバーの接続

サーバーを登録しただけでは、どのエージェントからもアクセスできません。接続を行う必要があります：

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

レスポンス (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} は接続を解除します。サーバー自体は削除されず、他のエージェントが引き続き利用可能です。すでにその状態にあるものを接続または解除しても、何も変更されません。

メディアライブラリ

メディアライブラリには、エージェントが会話中に送信できるファイル（メニュー、価格表、製品写真など）が保持されます。エージェントは最大 50個のアイテム を保持できます。

メディアの一覧表示

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

レスポンス (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

エージェントに保存されているアイテムが最初に表示され、次にそのエージェントの作成元となったキャンペーンに保存されている古いアイテムが表示されます。media_home（agentまたはcampaign）でどちらであるかを確認できます。各グループ内では、新しい順に並びます。

media_urlは7日で期限切れになります。 これはファイルがアップロードされた際に作成されるダウンロードリンクです。古いリンクは壊れているのではなく期限切れと見なし、リストを再読み込みして新しいリンクを取得してください。

メディアのアップロード

POST /agents/{agentId}/media-library — ファイルはbase64形式でインラインアップロードされ、最大10 MBまで対応しています。この呼び出しはファイルが保存されるまで待機するため、通常の要求よりも少し時間がかかる場合があります。このボディではcamelCaseのフィールド名が使用されていることに注意してください。

フィールド	必須	説明
`base64Data`	はい	base64エンコードされたファイルコンテンツ（data-URLプレフィックスなし）。
`mimeType`	はい	ファイルのMIMEタイプ。
`fileName`	はい	元のファイル名。保存されるファイルの名前として使用されます。
`title`	いいえ	ライブラリに表示される短いラベル。
`description`	いいえ	「エージェントがいつこれを送信すべきか」という指示。
`sendMessage`	いいえ	エージェントがアイテムを送信する際に使用する推奨文言。500文字に切り詰められます。
`maxSendsPerConversation`	いいえ	1回の会話で同じ連絡先に送信できる回数。デフォルトは`1`です。
`sendAsVoiceNote`	いいえ	音声アップロードのみ — ファイルをWhatsAppのボイスノートとして保存します。他のファイルタイプでは無視されます。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

2つの処理が自動的に行われます。アニメーションGIFはすべてのチャネルで再生できるように動画に変換され、プラットフォームはファイルの内容を短い要約として書き出すことで、エージェントがいつそのファイルを使用すべきかを判断できるようにします。

400は、フィールドの欠落、サポートされていないファイルタイプ、空または大きすぎるファイル、50アイテムの制限に達した場合に発生します。403は、そのアカウントでメディアライブラリが無効になっていることを意味します。

メディアアイテムの更新

PATCH /agents/{agentId}/media-library/{itemId} — メタデータのみ。ファイル自体を置き換えることはできません。新しいアイテムをアップロードし、古いアイテムを削除してください。このボディではsnake_caseが使用されます：title、description、send_message、max_sends_per_conversation（0以上の整数、または制限を解除する場合はnull）。

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

レスポンス (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

メディアアイテムの削除

DELETE /agents/{agentId}/media-library/{itemId} — アイテムとその保存ファイルを削除します。すでに削除済みのアイテムを削除しようとしても成功し、deleted: falseが返されるため、この呼び出しは安全に再試行できます。

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

フォローアップメッセージの生成

POST /agents/{agentId}/template-generation — エージェントの目的（何のためのエージェントか）に基づいて、エージェントのフォローアップメッセージ（会話が途切れた際に送信するナッジ）を作成します。

フィールド	説明
`type`	`all`（デフォルト）はセット全体を書き込みます。`cold_only`は返信が一度もない連絡先へのメッセージのみを書き込みます。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

これには2通りの戻り方があり、targetフィールドでどちらであるかを確認できます：

target: "agent" と 200 — メッセージは通話中に書き込まれ、結果は data にあります。エージェントの follow_up_config から読み取ってください。これが通常のケースです。
target: "campaign" と 202 — 作業は campaign_id で指定されたキャンペーンに対してキューに入れられました。そのキャンペーンの template_generation_status が完了するまで監視してください。

cold_only には発信キャンペーンが必要であり、キャンペーンが設定されていないエージェントに対しては 409 (reason: "cold_only_requires_campaign") で拒否されます。403 は、アカウントで自動フォローアップが有効になっていないことを意味します。これにはAIクレジットが使用されるため、"Insufficient credits." を伴う 400 はアカウントのクレジット不足を意味します。

エージェントへの会話のルーティング

エージェントは、エントリーポイントから送信された会話のみに応答します。チャネルにエントリーポイントが設定されるまで、一度も話したことのない相手からの最初のメッセージは保存されますが、誰もそれを取り出さず、アシスタントも返信しません。

実行したいこと	呼び出し
チャネル全体の応答者にエージェントを設定する	`{ "channel": "instagram", "agent_id": "AGENT_ID" }` を指定した `PUT /entry-points/channel-defaults`
より詳細なルール（キーワード、コメント、新規フォロワー）を追加する	`POST /agents/{agentId}/entry-points`
特定のエージェントに向けられたルールを確認する	`GET /agents/{agentId}/entry-points`
チャネルを応答者なしの状態にする	`DELETE /entry-points/channel-defaults?channel=instagram`

エージェントのエントリーポイントを一覧表示する

GET /agents/{agentId}/entry-points — このエージェントに会話を送信するルーティングルール。新しい順に表示されます。現在有効なルールと廃止されたルールの両方が返されます。廃止されたルールには enabled: false が含まれます。

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

チャネルを意図的に「応答者なし」に設定することを含む、アカウント全体のチャネルデフォルトについては、代わりに GET /entry-points/channel-defaults を読み取ってください。

エントリーポイントを作成する

POST /agents/{agentId}/entry-points — パス内のエージェントが常に優先されるため、URL内のエージェントとは異なるエージェントに対してルールを作成することはできません。

`type`	動作
`channel_default`	エージェントは、リストされたチャネル上のすべての新規連絡先に応答します。これには `PUT /entry-points/channel-defaults` を優先してください。これを使用すると以前の応答者が自動的に廃止されますが、ここで2つ目のデフォルトを作成してもそうはなりません。
`keyword`	最初のメッセージに `match_config.keywords` のいずれかが含まれている場合、エージェントが引き継ぎます。少なくとも1つのキーワードが必要です。
`instagram_comment` / `facebook_comment`	エージェントは投稿へのコメントに返信します。一致するチャネルは `channels` にリストされている必要があります。
`instagram_follower`	エージェントは新規フォロワーに挨拶します。

channels は必須であり、ルールが対象とするチャネルを指定します。例：whatsapp、whatsapp_web、instagram、messenger、telegram、sms、email、chat_widget、または custom_channel。特に指定しない限り、新しいルールは有効になります。

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

レスポンス (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

複数のルールが該当する場合の優先順位： 進行中の会話や手動割り当てがある場合は、既存のエージェントが維持されます。それ以外の場合は、キーワードルールがコメントルールよりも優先され、コメントルールはフォロワールールよりも優先されます。チャネルのデフォルトは最後の手段です。これらのルールがアカウント上で何かを決定するかどうかは、GET /entry-points/routing-status によって報告されます。

これは簡易版です。Entry Points APIガイドでは、ラダー、コメント、フォロワーに関するルール、WhatsApp番号1つにつき1つのエージェントという制限、ルールの変更や削除について網羅しています。コンセプトについてはEntry Pointsを、チャネル自体の接続についてはChannels APIを参照してください。