> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agents.fpt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 外部エージェントを接続する

> FPT AI Platform の外ですでに動いている Agent を Workspace に取り込む。接続を登録し、検証を通し、ほかの Agent と同じように管理します

すでに自社の環境で Agent を動かしていて、ここで作り直したくはない。そんなときに、その Agent を Workspace に登録する方法です。管理、デプロイチャネル、レポートはプラットフォームが受け持ち、考える部分はあなたの側に残ります。

<Info icon="globe">
  Console の左メニュー、**構築** グループの **外部エージェント** から開きます。
</Info>

## こんなときに向いています

* Agent がすでに自社の環境、たとえば n8n、LangGraph、社内サービス、パートナー製品の上で動いている。
* Agent のロジックを書き直さずに、Workspace とデプロイチャネルとレポートだけを使いたい。
* データを自分で握っておきたい。知識と処理は自社のインフラの中にとどまります。

プラットフォームの上で Agent を作るなら、代わりに **マイエージェント** を使ってください。

## 始める前に用意するもの

| もの | 理由 |
| - | - |
| Base URL | Agent のルートアドレス。たとえば `https://agent.acme.com/ai`。プラットフォームはその下の `/health` と `/runs` を呼びます |
| `fpt-v1` の規約 | Agent がプラットフォームのエージェントプロトコルを話せること。これは Agent を作ったチームの担当範囲です |
| 認証情報 | 呼び出し元を確認するシステムであれば、プラットフォームが送るべきヘッダーと値 |

<Note>
  一覧画面の右上にある **統合ガイド** ボタンは、パートナー側のエンジニア向けに書かれています。このフォームを埋めるだけなら、先方から渡される Base URL と認証情報があれば足ります。
</Note>

## Agent を登録する

<Steps>
  <Step title="外部エージェントを開く">
    Console の左メニュー、**構築** グループです。
  </Step>

  <Step title="外部エージェントを接続を押す">
    右上の青いボタンです。まだ 1 件もない場合は、同じボタンが画面の中央にあります。
  </Step>

  <Step title="接続情報を入れる">
    Agent 名、説明、Base URL、そしてプラットフォームがどう認証するか。各項目は下で説明します。
  </Step>

  <Step title="接続を検証を押す">
    プラットフォームがあなたのシステムを呼び、5 つの検証を行います。すべて通るまで保存は押せません。
  </Step>

  <Step title="保存を押す">
    Agent が **下書き** として作られ、Console が詳細ページを開きます。保存を押すまで何も書き込まれません。
  </Step>
</Steps>

<img src="https://mintcdn.com/fpt-62e894b4/jfePhRHunhqLSFUS/images/en_ext_form.jpg?fit=max&auto=format&n=jfePhRHunhqLSFUS&q=85&s=80933065f634da5343380b6112dc419b" alt="外部エージェントを接続するフォーム" width="1568" height="677" data-path="images/en_ext_form.jpg" />

### 入力項目

| 項目 | 必須 | 内容 | 例 |
| - | - | - | - |
| Agent 名 | はい | 一覧やチャネルで表示される名前。60 文字まで | 倉庫アシスタント |
| 説明 | いいえ | 何をする Agent で、どんなときに使うか。200 文字まで | 在庫数と注文状況を照会します |
| Base URL | はい | Agent のルートアドレス。https と http のどちらも受け付けます | `https://agent.acme.com/ai` |
| 認証 | はい | **認証あり** か **認証なし** | 認証あり |
| 認証ヘッダー | 認証ありの場合は必須 | ヘッダー名と値。**ヘッダーを追加** で増やせます | `Authorization` / `Bearer abc123` |

<Warning>
  Base URL は `http` も受け付けますが、その場合、認証情報が平文で流れます。`http` は社内のパートナー向けにとどめ、それ以外では `https` を使ってください。
</Warning>

### 2 つの認証方式

* **認証あり**: プラットフォームは入力したとおりのヘッダーを送り、自分では何も足しません。ベアラートークンを使うなら、値の前に `Bearer ` を自分で書いてください。値は保存され、二度と表示されません。
* **認証なし**: プラットフォームは何も送りません。IP 範囲などの別の方法でパートナー側がすでにアクセスを制限している場合にだけ選んでください。

### 5 つの検証

<img src="https://mintcdn.com/fpt-62e894b4/jfePhRHunhqLSFUS/images/en_ext_check.jpg?fit=max&auto=format&n=jfePhRHunhqLSFUS&q=85&s=f1ba716b2c573a265baa761f37b6df37" alt="5 つの接続検証" width="1568" height="677" data-path="images/en_ext_check.jpg" />

| 検証 | 確かめること |
| - | - |
| エンドポイントに到達できる | Agent がヘルスチェックに応答した |
| パートナーが認証情報を受け入れた | 送った内容をあなたのシステムが受け付けた |
| パートナーが `fpt-v1` に対応している | Agent がプラットフォームのプロトコルを話せる |
| 認証情報が保存された | 認証情報が保存済み。公開はこれを待ちます |
| Agent が実際の 1 ターンに応答した | プラットフォームが `/runs` に 1 ターン送り、Agent が規約どおりに応答した。ヘルスチェックだけでは分からない部分です |

一覧の下には、パートナー側が名乗る名前とバージョン、そして往復にかかった時間が表示されます。失敗した検証は理由を説明するので、フォームを直して **接続を検証** をもう一度押してください。

## 接続済み Agent の一覧

<img src="https://mintcdn.com/fpt-62e894b4/jfePhRHunhqLSFUS/images/en_ext_list.jpg?fit=max&auto=format&n=jfePhRHunhqLSFUS&q=85&s=22f31ec8be48d8873efce77a5535c014" alt="外部エージェントの一覧" width="1568" height="677" data-path="images/en_ext_list.jpg" />

Agent ごとに、名前、状態、説明、最終更新を載せたカードが並びます。上のフィルタは状態ごとの件数を示します。**すべて**、**下書き**、**公開済み**、**一時停止**。右の **Agent を検索** は名前で絞り込みます。

## Agent の中身

<img src="https://mintcdn.com/fpt-62e894b4/jfePhRHunhqLSFUS/images/en_ext_detail.jpg?fit=max&auto=format&n=jfePhRHunhqLSFUS&q=85&s=944708b9ce52fb17f0c50da7794e0cda" alt="外部エージェントの詳細ページ" width="1568" height="677" data-path="images/en_ext_detail.jpg" />

詳細ページには 4 つのタブがあります。**ビルド**、**テスト**、**チャネル**、**インサイト**。

接続の情報は **ビルド** タブにあります。

| 行 | 分かること |
| - | - |
| Base URL | 使用中のアドレス |
| 認証 | 認証ありかどうか |
| 認証情報 | 保存済みか、不要か |
| ヘルス | 直近の検証結果と **再確認** ボタン |

**エンドポイント** の表には、プラットフォームが Agent に対して呼ぶアドレスと、それぞれの状態が並びます。`/health` と `/runs` は必須で、残りは任意、この段階では無効です。

## 接続が動き出したあと

ここから先、外部エージェントはプラットフォーム上で作った Agent とまったく同じように振る舞います。

* **テスト** タブは実際に 1 ターン送るので、ほかの人より先に回答を読めます。
* **チャネル** タブで Workspace の公開範囲と、外部のチャネル(Web ウィジェット、API、Zalo)を選びます。
* 右上の **Publish** でバージョンを稼働させます。

この 3 つは通常の Agent とまったく同じなので、[公開](/ja/publishing) と [デプロイチャネルの管理](/ja/manage-channels) を参照してください。

## 編集、再検証、削除

<Steps>
  <Step title="接続を編集する">
    詳細ページで **Publish** の横の鉛筆、または **接続を編集** ボタンを押します。Agent を作ったときと同じダイアログで、保存前に同じ検証が走ります。
  </Step>

  <Step title="検証をやり直す">
    接続カードの **再確認**、またはエンドポイント表の **今すぐ再確認**。**...** メニューの **今すぐ検証** も同じ動きで、詳細ページでも一覧のカードでも使えます。
  </Step>

  <Step title="Agent を削除する">
    **...** メニューから **Agent を削除** を選びます。Console が確認を求めます。
  </Step>
</Steps>

<Warning>
  Base URL や認証情報を変えても、実際の利用者に届くのは再度公開してからです。Agent を削除すると、稼働中のすべてのチャネルから外れ、会話の途中だった顧客は返答を受け取れなくなります。
</Warning>

## 次に読むもの

<CardGroup cols={3}>
  <Card title="デプロイチャネルの管理" icon="share-nodes" href="/ja/manage-channels">
    Agent を出すチャネルと公開範囲を選びます。
  </Card>

  <Card title="Live Chat チャネル" icon="comments" href="/ja/live-chat-channel">
    用意されたチャット画面で、自社サイトに Agent を載せます。
  </Card>

  <Card title="API 連携" icon="code" href="/ja/api-integration">
    自前のチャット画面がすでにある場合に。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.