# AIエージェントAPI

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

- **ベースURL** — `https://api.youraiconnector.com/v1`
- **認証** — APIキー（[認証](authentication.md)を参照）
- **エラーとページネーション** — [エラーとページネーション](errors-and-pagination.md)を参照

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

エージェントという概念が初めての場合は、まず[AIエージェント](../ai-agents/ai-agents.md)をお読みください。


---

## エージェントの構成要素

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

| 要素 | 内容 | 設定場所 |
|---|---|---|
| **構成 (Configuration)** | 指示、ルール、目標、性格、言語、AIティア、予約およびフォローアップの動作 | `PUT /agents/{agentId}` または、より限定的な `PUT /agents/{agentId}/bot-config` |
| **知識 (Knowledge)** | FAQおよび知識ソース（プラットフォームが読み込んだページやドキュメント） | [FAQ API](faqs.md) および `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` |

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

---

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

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

```json
{
  "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](#get-an-agent) で読み取ってください。

**クエリパラメータ**

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

**cURL**

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

**JavaScript**

```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**

```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`)

```json
{
  "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](#set-active-hours) を参照してください。 |
| `ai_speed` | string | `fast`、`fast_thinker`、`balanced`、または `thorough`。 |
| `anthropic_model` | string | `standard`、`economy`、`max`、または `mini`。 |
| `scrape_urls` | string[] | エージェントの指示を構築するために読み込むページ。 |

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

**cURL**

```bash
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**

```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**

```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`)

```json
{
  "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**

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

**JavaScript**

```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**

```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**

```bash
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**

```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**

```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`)

```json
{ "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` を伴って拒否されます。

```bash
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` で、単一の時間枠または時間枠のリストを指定します。省略した曜日は以前の設定が保持され、曜日以外のキーはすべて拒否されるため、タイプミスによって何も起こらないという事態を防げます。

```bash
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`)

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

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

---

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

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

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

```javascript
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`)

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

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

---

## エージェントの複製

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

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

**レスポンス** (`201`)

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

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

---

## エージェントの削除

`DELETE /agents/{agentId}`

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

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

**レスポンス** (`200`)

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

**ブロック済み** (`409`)

```json
{
  "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で最適化](#optimize-an-agent-with-ai)によって生成された書き換えは、公開するまで「**未公開の下書き**」として保持されます。それまでの間、稼働中のエージェントは現在の設定で応答を続けます。

### 下書きを公開する

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

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

**レスポンス** (`200`)

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

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

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

### 下書きを破棄する

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

```bash
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`を一緒に送信します。少なくともどちらか一方にはテキストを含める必要があります。

```bash
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`)

```json
{ "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`

```bash
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`)

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

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

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

```bash
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}` — エージェントはそのタグの適用を停止します。タグ自体、およびすでにそのタグが付与されている連絡先には影響しません。

```bash
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`はセットをゼロから設計します。 |

```bash
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`)

```json
{ "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`を使用して単一のソースを添付します。どちらか一方を送信してください。すでに添付されているものを添付しても何も変更されません。

```bash
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`)

```json
{
  "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のリストがボディに含まれるためです。

```bash
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](faqs.md) を参照してください。

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

---

## ツール

### カスタム関数

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

```bash
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` で行います。関数については [カスタム関数](../ai-automation/custom-functions.md) を参照してください。

### MCPサーバー

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

> 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` を渡すとすべてクリアされます。 |

```bash
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`)

```json
{
  "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}` — 登録を削除し、それが有効になっていたすべてのエージェントおよびキャンペーンからリンクを解除します。

```bash
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`）を使用 — 保存前テストであり、何も保存されません。

```bash
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`)

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

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

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

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

```bash
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`)

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

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

---

## メディアライブラリ

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

### メディアの一覧表示

`GET /agents/{agentId}/media-library`

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

**レスポンス** (`200`)

```json
{
  "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のボイスノートとして保存します。他のファイルタイプでは無視されます。 |

```bash
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`）。

```bash
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`)

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

### メディアアイテムの削除

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

```bash
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`は返信が一度もない連絡先へのメッセージのみを書き込みます。 |

```bash
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` が含まれます。

```bash
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`。特に指定しない限り、新しいルールは有効になります。

```bash
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`)

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

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

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

---

## AIエージェントAPIエラー

エージェントエンドポイントは、標準的なエラーエンベロープを返します：

```json
{
  "success": false,
  "error": "Agent not found"
}
```

| ステータス | エージェントエンドポイントで発生する場合 |
|---|---|
| `400` | 必須フィールドが欠落しているか無効です。空の更新ボディ、許可リスト外の値（`ai_speed`、`anthropic_model`、`booking_provider`、`mode`、`type`）、`availability`内の平日以外のキー、`bot-config`上のドット付きフィールド名、またはパス内の不正な形式のIDなどが該当します。 |
| `403` | アカウントが送信された設定の使用を許可されていない、プランのエージェント上限に達している、またはこのエンドポイントが必要とする機能（メディアライブラリ、フォローアップ、MCPサーバー用のカスタム関数）が無効になっています。プランで許可されている設定サイズを超える変更は、`400`で拒否されます。 |
| `404` | エージェント、タグルール、メディアアイテム、またはMCPサーバーが見つかりませんでした。存在しないか、別のアカウントに属しています。 |
| `409` | 何かが実行中であるか、妨げになっています。最適化やタグ生成が実行中である、エージェントがまだブロードキャスト、エントリーポイント、またはキャンペーンにアタッチされている、あるいは送信キャンペーンなしで`cold_only`が要求された場合です。 |

すべてのエンドポイントが返す共通コード（`401`、`403`（プランにAPIアクセスが含まれていない）、`429`（レート制限）、`500`）については、再試行のガイダンスと共に[エラーとページネーション](errors-and-pagination.md)に記載されています。

> **エクスプローラーに関する注記。** `/agents`エンドポイントは公開されているOpenAPI仕様に含まれているため、[APIリファレンス](reference.md)で正確なフィールドを確認し、ライブリクエストを実行できます。アカウントレベルの`/mcp-servers`エンドポイントも仕様に含まれているため、同様に探索可能です。


---

## 関連情報

- [AIエージェント](../ai-agents/ai-agents.md) — エージェントとは何かを平易な言葉で説明します。
- [エントリーポイント](../ai-agents/entry-points.md) — 会話がどのようにエージェントにルーティングされるかを説明します。
- [FAQ API](faqs.md) — エージェントが回答するための知識を構築・リンクします。
- [チャネルAPI](channels.md) — エージェントが回答するチャネルを接続します。
- [MCPサーバーをボットに接続する](../ai-automation/mcp-servers.md) · [カスタム関数](../ai-automation/custom-functions.md)
- [APIリファレンス](reference.md) — 完全な対話型エンドポイントエクスプローラーです。