> ## 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.

# Space でのカスタム API コネクタ

> Swagger/OpenAPI ドキュメントのインポートまたは手動定義で、Workspace のコネクタページから REST API コネクタを作成・表示・編集・削除します。

<Info icon="plug">
  **REST API コネクタ**は、REST API の各操作（operation）を Agent が呼び出せるツールに変換します。Connector の作成と管理は Workspace の**コネクタ**ページで行い、Agent の詳細画面で各 Agent に追加して、操作ごとに権限を設定します。
</Info>

## 機能の入口

| 入口 | 操作手順 | 用途 |
| - | - | - |
| コネクタページ | 左サイドバー → **コネクタ** → **Custom Connectors** タブ → **コネクタを追加** → **REST API** | Connector の作成・表示・編集・削除 |
| 空の状態の画面 | Connector がまだない **Custom Connectors** タブ → 中央の**コネクタを追加**ボタン | 最初の Connector の作成 |
| Agent の詳細画面 | **マイエージェント** → Agent を開く → **ビルド** → **設定**パネル → **コネクタ**セクション → **+** | Agent への追加、権限設定、Agent からの削除 |
| Agent のコネクタ選択画面 | コネクタ選択ダイアログ → **コネクタを作成** → **REST API** | Agent 画面を離れずに Connector を作成 |

## 始める前に

* **API ドキュメント**: OpenAPI 3.x または Swagger 2.0 のファイル（JSON/YAML、最大 2 MB）。ドキュメントがない場合は、手動で定義するためにベース URL とエンドポイントの一覧を用意します。
* **公開されたベース URL**: ローカルマシンやプライベート IP 帯（例: `localhost`、`169.254.169.254`）を指すアドレスは登録できません。できるだけ `https` を使ってください。
* **認証情報**: API キー / トークン、または API の OAuth 2.1 情報。
* **上限**: 1 つの Connector に登録できる操作は最大 200 件です。それより多い場合は、先頭の 200 件だけがインポートされます。

## Connector を作成する

### 方法 1: Swagger/OpenAPI ドキュメントをインポートする

<Steps>
  <Step title="Custom Connectors タブを開く">
    左サイドバーの**コネクタ**をクリックし、**Custom Connectors** タブを選びます。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_empty.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=bdecb09f94d66c8e87b8e03dab68c6f4" alt="Connector がまだない Custom Connectors タブ" width="1568" height="706" data-path="images/ja_custom_api_empty.jpg" />
  </Step>

  <Step title="コネクタを追加 → REST API を選ぶ">
    メニューには **REST API**（Swagger/OpenAPI のインポートまたは手動定義）と **MCP サーバー**（URL で MCP サーバーを接続）があります。**REST API** を選びます。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_add_menu.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=8163b3d76199984e9c63e25e3a1f04aa" alt="REST API と MCP サーバーが表示されたコネクタを追加メニュー" width="1568" height="706" data-path="images/ja_custom_api_add_menu.jpg" />
  </Step>

  <Step title="ステップ 1 ソース: ドキュメントを読み込む">
    **Swagger/OpenAPI をインポート**タブで、ファイルを枠内にドロップするか**ファイルを選択**をクリックします。**またはドキュメントの内容を貼り付け**の欄に内容を貼り付けることもできます。**次へ**をクリックします。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_source_import.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=8fbe690de74a1c996343c86f0a70fa7a" alt="OpenAPI ドキュメントを貼り付けたソースステップ" width="1568" height="706" data-path="images/ja_custom_api_source_import.jpg" />
  </Step>

  <Step title="ステップ 2 接続: 接続情報を確認する">
    名前、**ベース URL**、**認証**の種類はドキュメントから自動入力され、**ドキュメントから取得**のラベルが付きます。内容を確認し、API にキーが必要なら**値**を入力して**次へ**をクリックします。各項目の説明は下の「接続ステップの項目」を参照してください。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_connection.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=b4567b5977e75a2889d9283121b45fc1" alt="ドキュメントから取得したベース URL と認証が表示された接続ステップ" width="1568" height="706" data-path="images/ja_custom_api_connection.jpg" />
  </Step>

  <Step title="ステップ 3 操作: Agent に許可する操作を選ぶ">
    各操作には、メソッド、パス、リスクのラベル、Agent に表示されるツール名（例: `demo-orders-api__list_orders`）、説明が表示されます。不要な操作のチェックを外す、メソッドで絞り込む、操作を展開して説明やパラメータを編集する、といった調整ができます。**コネクタを作成**をクリックします。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_operations.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=ef369a59cf746475418b01ea248ef322" alt="5 件の操作を選択した操作ステップ" width="1568" height="706" data-path="images/ja_custom_api_operations.jpg" />
  </Step>

  <Step title="結果を確認する">
    「**N 件の操作でコネクタを作成しました。**」と表示され、**接続済み**のステータスで Connector のカードが追加されます。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_card.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=2fd2f20517562ebbb2a182d02604d9e4" alt="接続済みと表示された新しい Connector のカード" width="1568" height="706" data-path="images/ja_custom_api_card.jpg" />
  </Step>
</Steps>

<Tip>
  Agent は操作の説明を読んで、いつ API を呼び出すかを判断します。元のドキュメントに `summary` がある場合でも、操作の内容と使う場面がわかる説明に書き直すことをおすすめします。
</Tip>

### 方法 2: 手動で定義する

API に OpenAPI ドキュメントがない場合や、Agent に公開するエンドポイントを一部に絞りたい場合に使います。

<Steps>
  <Step title="手動で定義タブを選ぶ">
    **API コネクタを作成**ダイアログで**手動で定義**タブを選び、**次へ**をクリックします。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_source_manual.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=a0a30289379a10a96c4b5d12f5eee547" alt="ソースステップの手動で定義タブ" width="1568" height="706" data-path="images/ja_custom_api_source_manual.jpg" />
  </Step>

  <Step title="接続情報を入力する">
    方法 1 と同様に、**名前**と**ベース URL** を入力し、**認証**の種類を選びます。
  </Step>

  <Step title="操作を 1 件ずつ定義する">
    **メソッド**、**パス**、**名前**、**リスク**、**説明**、パラメータ、**返される内容**を入力します。操作を追加して定義を続け、最後に**コネクタを作成**をクリックします。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_manual_ops.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=82b625e0027ef63888a18a11159c2232" alt="注文詳細を取得する操作の定義フォーム" width="1568" height="706" data-path="images/ja_custom_api_manual_ops.jpg" />
  </Step>
</Steps>

<Tip>
  **パス**にパスパラメータを `{order_id}` の形式で書くと、Console が **Path** のパラメータを自動で追加します。
</Tip>

### 接続ステップの項目

| 項目 | 必須 | 説明 | 例 |
| - | - | - | - |
| **名前** | はい | Connector の表示名です。他の Connector と重複できません。ツール名の接頭辞にもなります | `Demo Orders API` |
| **ベース URL** | はい | API のルートアドレスです。各操作のパスはこの URL の後ろに連結されます | `https://api.example.com/v1` |
| **認証** | はい | **認証なし**、**API キー / トークン**、**OAuth 2.1 (Auto)**、**OAuth 2.1 (Manual)** のいずれか | API キー / トークン |
| **送信先** | API キー選択時 | キーを**ヘッダー**と**クエリ**のどちらで送るか | ヘッダー |
| **ヘッダー名** | API キー選択時 | キーを入れるヘッダー名またはクエリパラメータ名 | `X-API-Key`、`Authorization` |
| **値** | API キー選択時 | キーまたはトークン。暗号化して保存され、再表示されません | `sk-...` |
| **保存時に接続をテスト** | いいえ | パラメーター不要の GET 操作を呼び出して、キーが有効か確認します | オン |
| **詳細設定 → 説明（任意）** | いいえ | API の短い説明。Connector のカードに表示されます | 注文管理 API |
| **詳細設定 → テストに使う操作** | いいえ | 接続テストに使う GET 操作。既定では自動で選ばれます | `list_orders` |

OAuth 2.1 の場合:

| 種類 | 入力する内容 | 補足 |
| - | - | - |
| **OAuth 2.1 (Auto)** | 追加の入力は不要 | Console がベース URL から OAuth エンドポイントを検出し（RFC 9728、RFC 8414）、クライアントを自動で登録します（RFC 7591） |
| **OAuth 2.1 (Manual)** | **Authorize URL**、**Token URL**、**Client ID**。任意: **Client secret**、**スコープ**（スペースまたはカンマ区切り） | OAuth メタデータを公開していない、またはクライアント登録を許可しない API 向けです |

どちらの OAuth でも、保存後に認可用のウィンドウが開きます。

### 操作ステップの項目

| 項目 | 必須 | 説明 | 例 |
| - | - | - | - |
| **メソッド** | はい | `GET`、`POST`、`PUT`、`PATCH`、`DELETE` | `GET` |
| **パス** | はい | ベース URL の後ろに連結されるパス。パスパラメータは `{id}` の形式で書きます | `/orders/{order_id}` |
| **名前** | はい | ツール名です。Agent には `コネクタ名__名前` の形式で表示されます | `get_order` |
| **リスク** | はい | **読み取りのみ**、**データを書き込む**、**データを削除する可能性あり**のいずれか。Agent に追加したときの既定の権限が決まります | 読み取りのみ |
| **説明** | 推奨 | Agent はこの説明を読んで、操作を呼び出すタイミングを判断します | 注文 ID を指定して注文の詳細を取得します。 |
| **パラメータ** | いいえ | 名前、位置（**Path**、**Query**、**Header**、**ボディのフィールド（JSON）**、**ボディ全体（JSON）**、**フォームのフィールド**）、型、説明、**必須**のチェックで構成します。**表**または **JSON** で編集できます | `order_id`、Path、string |
| **返される内容** | いいえ | API が返すデータの説明。最大 1000 文字です | 注文ステータス、合計金額、顧客名。 |

ドキュメントをインポートすると、リスクはメソッドから推定されます。`GET` は**読み取りのみ**、`POST`/`PUT`/`PATCH` は**データを書き込む**、`DELETE` は**データを削除する可能性あり**です。操作を展開すれば変更できます。

## Connector の一覧を確認する

**Custom Connectors** タブには Connector の件数と、Connector ごとのカードが表示されます。

* Connector の**名前**と**説明**。
* **ステータス**（例: **接続済み**）。
* **操作の件数**と作成元（ドキュメントからインポートした場合は **OpenAPI**）。
* 削除用の**ごみ箱**アイコンと、編集用の**管理**ボタン。

Connector が増えたら、**カスタムコネクタを検索...** の欄で名前を絞り込めます。

## Connector を編集する

カードの**管理**をクリックすると、**API コネクタを編集**ダイアログが開きます。**ソース**、**接続**、**操作**の 3 つのタブがあります。編集が終わったら**変更を保存**をクリックします。

### 接続情報を変更する

**接続**タブでは、名前、ベース URL、認証の種類を変更できます。保存済みのキーは「**•••• 保存済み**」と表示されます。新しいキーを入力するには**キーを変更**をクリックします。

<img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_edit_connection.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=2fa0ef594cac5ebedce901b21f115a06" alt="API コネクタを編集ダイアログの接続タブ" width="1568" height="706" data-path="images/ja_custom_api_edit_connection.jpg" />

ベース URL または認証の種類を変更すると、既存の接続はすべて切断され再接続が必要になる旨の警告が表示されます。

<img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_auth_warning.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=f6256a87b5047a2c5534373e372d8881" alt="アドレスや認証方式を変更したときの警告" width="1568" height="706" data-path="images/ja_custom_api_auth_warning.jpg" />

### API の変更に合わせてドキュメントを再インポートする

<Steps>
  <Step title="新しいバージョンのドキュメントを読み込む">
    **ソース**タブで、新しいファイルをドロップするか、新しい内容を貼り付けます。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_reimport.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=6f22104fb05fce8e1b0aaa19e02353e3" alt="バージョン 1.1.0 のドキュメントを貼り付けたソースタブ" width="1568" height="706" data-path="images/ja_custom_api_reimport.jpg" />
  </Step>

  <Step title="操作タブを確認する">
    **操作**タブを開いてインポート後の一覧を確認し、使う操作を選び直します。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_reimport_operations.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=889611c0967b4b4b8663bf1b48fce7ef" alt="再インポート後に返金の操作が追加された操作タブ" width="1568" height="706" data-path="images/ja_custom_api_reimport_operations.jpg" />
  </Step>

  <Step title="変更を保存する">
    **変更を保存**をクリックします。Connector のカードの操作件数が更新されます。
  </Step>
</Steps>

<Warning>
  再インポートすると、**操作の一覧全体**が新しいドキュメントの内容に置き換わります。新しいドキュメントで削除または名前変更された操作は、この Connector を使っている Agent から使えなくなります。保存後は該当する Agent を開いて各操作の権限を確認し、もう一度テスト実行してください。
</Warning>

未保存の変更があるまま**キャンセル**をクリックすると、「**変更を破棄しますか？**」と確認されます。**破棄する**で終了し、**編集を続ける**で編集に戻ります。

## Connector を削除する

<Steps>
  <Step title="Connector のカードのごみ箱アイコンをクリックする">
    確認ダイアログが表示されます。

    <img src="https://mintcdn.com/fpt-62e894b4/jYSFnnhVhNufAeQM/images/ja_custom_api_delete.jpg?fit=max&auto=format&n=jYSFnnhVhNufAeQM&q=85&s=c93504e3155df8fea446b104e208dc95" alt="Connector の削除確認ダイアログ" width="1568" height="706" data-path="images/ja_custom_api_delete.jpg" />
  </Step>

  <Step title="コネクタを削除をクリックする">
    「**コネクタを削除しました。**」と表示され、Connector を使っていたすべての Agent から自動的に外されます。
  </Step>
</Steps>

<Warning>
  Connector の削除は**元に戻せません**。この Connector の操作を使っている Agent は、すぐにアクセスできなくなります。ダイアログには影響を受ける Agent が表示されないため、削除前に確認してください。
</Warning>

<Note>
  Connector には一時停止の状態はありません。特定の Agent で一時的に使えなくしたい場合は、その Agent から Connector を外すか、操作を**ブロック**に設定してください。
</Note>

作成した Connector は、[Agent でカスタム API を使う](/ja/agent-custom-api-connectors) の手順で Agent に追加します。

## よくあるエラー

| 現象 | 原因 | 対処 |
| - | - | - |
| 同じ名前のコネクタが既にあるというメッセージ | 名前が既存の Connector と重複している | 接続ステップで名前を変更する |
| コネクタを作成したときに、ベース URL は公開アドレスにする必要があるというメッセージ | ベース URL がローカルマシンやプライベート IP を指している | API の公開アドレスを使う |
| 200 件の操作しかインポートされない | ドキュメントに 200 件を超える操作がある | 業務ごとにドキュメントを分け、複数の Connector にする |
| ドキュメントを読み込めない | JSON/YAML の構文エラー、または OpenAPI/Swagger 形式ではない | OpenAPI のバリデーターで確認してから再インポートする |
| `api-n-h-ng-demo__...` のような不自然なツール名になる | Connector 名にアクセント付き文字が含まれ、`-` に置き換えられた | `Orders API` のように ASCII 文字だけの名前にする |

## 関連ページ

<CardGroup cols={2}>
  <Card title="Agent でカスタム API を使う" icon="robot" href="/ja/agent-custom-api-connectors">
    Connector を Agent に追加し、権限を設定してテストします。
  </Card>
</CardGroup>


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