---
title: "コネクタ"
description: "コネクタと接続によって、エージェントに外部ツールへのスコープ付きアクセスを提供する仕組み。"
---

コネクタは、プロジェクトを外部ツールまたはサービスに接続します。エージェントはそれをツールとして呼び出します。Beeuniが各呼び出しを仲介するため、サンドボックスにコネクタの認証情報が保持されることはありません。

ほとんどのコネクタは`beeuni.yaml`で宣言します。すべてのフィールドについては、[マニフェストリファレンス](/docs/ja/project/manifest)をご覧ください。チャットプラットフォームまたはマシンを接続すると、Beeuniがチャンネルコネクタとコンピューターコネクタを宣言します。

<a id="browse-and-add-a-connector"></a>

## コネクタを参照して追加する

**Connectors**を開くと、管理対象カタログを参照できます。デフォルトの一覧には、プロバイダー管理の認証、または有効化されたカスタム認証設定で接続できる、管理対象プロバイダーのツールキットが表示されます。プロジェクトに既存の接続がある必要はありません。未検証のカスタムOAuth設定を必要とするツールキットは、その設定が検証可能になるまで表示されません。

直接接続先を参照するには、プロジェクトの機能フラグで**Connectors API Discover**を有効にし、同じページで**API / MCP**を選択します。このフラグを有効にしても、管理対象カタログがデフォルトでなくなるわけではありません。直接カタログには、公開済みのOpenAPI、MCP、GraphQL、PostmanなどのAPIサーフェスが分類されて表示されます。カードを選択し、公開済みのサーフェスを選んで、接続フォームに入力してください。ドキュメントのみのサーフェスはプロバイダーのドキュメントを開くもので、すぐに接続できるテンプレートとしては表示されません。カタログにない未加工のAPIやスキーマには、**Add → Manual**を使用してください。直接検索は、管理対象プロバイダーを設定していなくても利用できます。

<a id="connectors-connections-and-accounts"></a>

## コネクタ、接続、アカウント

コネクタは、エージェントが利用するためのアクセスパッケージです。つまり、宣言された機能（どのアクションを、どのようにサービスへ到達して実行するか）です。ロールではなく、Beeuniの権限も持ちません。エージェントがコネクタにアクセスできるのは、マニフェストの許可にそのスラッグが記載され、ロールの判定で呼び出しが許可された場合だけです。[1つの用語、2つのバインド](/docs/ja/accounts#one-vocabulary-two-bindings)をご覧ください。コネクタには以下が含まれます。

- プロジェクト内で一意のスラッグ
- 表示名
- プロバイダーアプリ
- コネクタポリシー

接続とは、コネクタに対する1つの**アカウント**、つまり1つの認証済みIDです。認証情報、OAuth許可、またはAPIキーを指します。1つのコネクタに複数のアカウントを並行して登録できます。すべてのアカウントにコネクタのポリシーが適用されます。各アカウントの`owner_type`によって、そのアカウントとして誰が呼び出しを実行できるかが決まります。

- `project` — **共有**アカウント。人間またはサービスアカウント（エージェント、トリガー）を問わず、コネクタの許可対象であれば誰でも利用できます。
- `member` — プロジェクトメンバー（`owner_id`）1人が所有する**プライベート**アカウント。そのメンバーだけが、**プライベート**セッションで利用できます。サービスアカウント（無人で動作するエージェントまたはトリガー）が、メンバーのプライベートアカウントとして実行することはできません。

複数のコネクタから同じプロバイダーアプリを参照できます。1つのアプリで異なるポリシーが必要な場合は、コネクタを分けてください。

<a id="add-an-account"></a>

### アカウントを追加する

**Customize → Connectors**でコネクタを開きます。**Accounts**タブには、利用または管理できるすべてのアカウントが一覧表示されます。各カードには、そのアカウントを利用できる対象（**Only you**、**Everyone in project**、または共有先のグループとユーザー）が表示されます。

**Add account**を選択してアカウント名を入力し、**Who can use it**を選びます。

- **Only you** — プライベートアカウント。どのメンバーでも追加できます。
- **Everyone in the project** — 共有アカウント。
- **Specific people or groups** — 選択したユーザー、グループ、エージェントに利用者を限定した共有アカウント。

2つの共有オプションには`project.connector.connections.manage`が必要です。**Specific people or groups**を選ぶと、Beeuniはアカウントの認証を行う前に許可を設定するため、認証情報がプロジェクト全体に公開された状態になることはありません。同じ所有者の別アカウントがすでに使っている名前は拒否されるため、アカウント名は新しいものにする必要があります。

エージェントがアカウントを必要とすると、チャットに**Connect**カードが表示されます。このカードを開くと同じダイアログが表示され、エージェントが提案した名前があらかじめ入力され、希望した利用対象が選択されています。Beeuniは既存のアカウントを再認証せず、必ず新しいアカウントを作成します。また、そのアカウントとして呼び出しを実行できるよう、新しいアカウント名をエージェントに伝えます。

<a id="choose-who-can-use-a-shared-account"></a>

### 共有アカウントの利用者を選ぶ

共有アカウントは、利用者を限定するまでプロジェクト内の全員が利用できます。アカウントカードの**Share**を選択します。ダイアログは、エージェントに使うものと同じ**Grant access**ダイアログです。現在の利用者が一覧表示され、次の対象を追加できます。

- **Everyone in the project** — デフォルト。
- **Groups** — 選択した各グループの全メンバー。
- **People** — メンバーを1人ずつ指定します。自分だけを選択すると、自分だけがアカウントを利用できます。
- **Agents** — トリガーや共有セッションを含む、そのエージェントのすべてのセッション。エージェントを実行できる人は誰でも、そのエージェントを通じてアカウントを利用できます。

**Save**を選択するまで変更は適用されません。最後のグループまたはユーザーを削除すると、アカウントは再び全員が利用できるようになります。保存前にダイアログにその結果が表示されます。

利用者を限定したアカウントには、所有者の代わりに利用対象が設定されることを除き、プライベートアカウントと同じルールが適用されます。

- 利用対象に含まれるユーザーは、プライベートセッションでのみ利用できます。
- 利用対象に含まれるエージェントは、すべてのセッションで利用できます。
- その他のエージェントや、その他のエージェントのトリガーは利用できません。
- アカウントをバインドしたセッションは、そのセッション自身のエージェントにアカウントが共有されていない限り、共有できません。
- アカウントの利用者を変更できるのはユーザーだけです。エージェントセッションには`403`が付与されます。

利用対象に含まれないユーザーには、そのアカウントは表示されません。プロジェクトの接続を管理できるユーザーには、利用者の変更ができるよう、**Not shared with you**と表示されます。

<a id="share-your-own-private-account"></a>

### 自分のプライベートアカウントを共有する

自分の**Only you**アカウントにも**Share**ボタンがあります。共有すると、選択したユーザーとグループ（自分を除外しない限り、自分も引き続き利用可能）またはプロジェクト内の全員が使える共有アカウントになります。それ以降は共有アカウントとして扱われ、プロジェクトの接続を管理するユーザーも管理できるようになります。

- 共有には、共有アカウントの追加と同じ権限である`project.connector.connections.manage`が必要です。この権限がない場合、ボタンは無効になり、その理由が表示されます。
- Beeuniは最初に許可を設定し、1回の更新でアカウントを共有状態にするため、その間にプロジェクト全体へ公開されることはありません。
- コネクタに同じ名前の共有アカウントがある場合、共有できません（`409`）。先にどちらかの名前を変更してください。

```text
POST /projects/{projectId}/connections/{connectionId}/share
     {"principals": [{"principal_type": "group", "principal_id": "<group-id>"}]}
```

`principals`の一覧が空の場合、全員と共有されます。CLIからは次のとおりです。
`beeuni connectors connections share <connection-id> --group <group-id>`
（`--user <email|id>`も使用できます。繰り返し指定するか、`--everyone`を使用してください。）

利用対象の各項目は、許可ストア内の1つの`connection`オブジェクト割り当てに対応します。

```text
POST   /accounts/{accountId}/iam/assignments
       {"principal_type": "group", "principal_id": "<group-id>",
        "role_key": "agent-user", "scope_type": "project", "scope_id": "<project-id>",
        "object_type": "connection", "object_id": "<connection-id>"}
DELETE /accounts/{accountId}/iam/assignments/{assignmentId}
```

CLIから同じ設定を行うには、次のとおりです。

```bash
beeuni access grant --group <group-id> --connection <connection-id>
beeuni access grant --everyone --connection <connection-id>
beeuni access revoke <assignment-id>
beeuni connectors connections ls   # the WHO CAN USE column
```

- `principal_type`は`user`、`group`、または`project`です（プロジェクト内の全員を指し、`principal_id`はプロジェクトIDです）。
- 許可の付与または取り消しには`project.connector.connections.manage`が必要です。
- 共有アカウントだけが、これらの許可による利用者の限定に対応します。プライベートアカウント、またはこのプロジェクトの接続ではないIDに対しては、`404`が返されます。自分のプライベートアカウントを共有するには、上記の`share`ルートを使用してください。
- `GET /projects/{projectId}/connections`は各共有アカウントの許可を`shared_with`で返します。また、呼び出し元に管理目的でのみ表示されるアカウントでは`usable: false`を返します。セッションの選択画面に表示されるのは、利用可能なアカウントだけです。

<a id="which-identity-an-account-acts-as"></a>

### アカウントがどのIDとして動作するか

アカウントの`label`は、認証前に選んだ名前です。どのログインが使われたかは示しません。`connected_as`が示すのは、認証済みアカウントについてプロバイダーが報告するメールアドレス、ログイン名、または表示名です。

- Beeuniは管理対象の認証が完了したときにこれを読み取ります。まず接続済みアカウントの表示名を確認し、次にツールキットの「who am I」ツールを確認します（Gmail、Google Calendar、Google Drive、Linear、GitHub、Slack、Notion、Outlook、Microsoft Teams、HubSpot、Jira、Asana、Figma、Airtable、Salesforce、Trello、Dropbox、Calendly）。Google DocsとGoogle Sheetsにはそのようなツールがないため、`connected_as`は`null`のままです。
- 既定のラベル（`Private connection`、`Project connection`、またはコネクタ名）のままのアカウントは、そのIDに合わせてラベルが変更されます。ユーザーが選んだラベルが置き換えられることはありません。
- アカウントが接続ページに表示されるとすぐに「Connected as …」が表示されるため、個人のログインで認証した共有アカウントもすぐに確認できます。
- `connected_as`は、すべての接続（`GET /projects/{projectId}/connections`）、アカウント一覧、`beeuni connectors accounts <slug>`と`beeuni connectors connections ls`（`CONNECTED AS`列）、および**Customize → Connectors**のアカウント行に表示されます。

<a id="rename-an-account"></a>

### アカウント名を変更する

再認証せずにアカウント名を変更できます。

```text
PUT /projects/{projectId}/connections/{connectionId}/label   {"label": "Support inbox"}
beeuni connectors connections rename <connection-id> Support inbox
```

ダッシュボードでコネクタを開き、アカウント行の**⋯ → Rename**を選択します。変更されるのはラベルだけです。認証済みアカウント、その所有者、既定フラグ、プロバイダーの状態はそのままです。切断と同じ条件が適用されます。自分の非公開アカウント、または共有アカウントの場合は`project.connector.connections.manage`です。

`me`、`project`、またはUUID形式のラベルは、`--account`がラベルより先にそれらを解決するため、`400`で変更が拒否されます。同じ所有者の別のアカウントに同じラベルがすでに付いている場合は、大文字と小文字を区別せずに比較され、`409`で変更が拒否されます。

<a id="connect-a-different-account"></a>

### 別のアカウントを接続する

有効なアカウントがすでにあるスロットの接続リンクでは、再認証されません。プロバイダーはそのアカウントを再利用し、接続ページに**Already connected**と表示します。別のログインを使うには、コネクタに新しいアカウントを追加して既定に設定し、その後、古いアカウントを切断します。

アカウントを指定しない呼び出しでは、まず呼び出し元自身の既定の非公開アカウントが選ばれ、次にプロジェクトの既定の共有アカウントが選ばれます。すべての呼び出し結果には、どのアカウントとして実行されたか（`account: { connection_id, label, owner_type }`）が示されるため、トランスクリプトでツール呼び出しに使われたIDを常に確認できます。コネクタで呼び出しに使えるアカウントを、既定のものから順に一覧表示するには`GET /connectors/projects/{projectId}/connectors/{slug}/accounts`を使います。

> **Warning**
>
> `authorization_strategy`（`project` | `user`）は、プロジェクト所有とメンバー所有のアカウントを相互排他的にする、コネクタレベルのMODEでした。`user`戦略のコネクタでは共有アカウントを提供できず、サービスアカウントが使える場所には接続フローがありませんでした。これは非推奨です。マニフェストと`PUT .../authorization-strategy`では引き続き受け付けられ、エラーなく応答しますが、もうどこからも読み取られません。現在のアクセスルールは、各接続の`owner_type`だけです。

<a id="providers"></a>

## プロバイダー

コネクタは、次のいずれか1つのプロバイダータイプを使用します。

- **composio** — 対応するSaaSアプリ向けの管理型OAuth
- **pipedream** — ロールバック専用のレガシー管理型OAuth
- **openapi**、**postman**、**graphql**、**http** — 直接APIコネクタ
- **mcp** — HTTPまたはSSE経由のリモートMCPサーバー
- **channel** — チャットプラットフォームへの接続
- **computer** — 各メンバーが接続したマシンを1つのアカウントとして扱う

管理型プロバイダーフローについては、[Slackとチャネル](/docs/ja/connect/slack)および[コンピューター](/docs/ja/connect/computers)を参照してください。

<a id="apps-that-need-your-own-oauth-app"></a>

### アプリの利用可否

コネクターのカタログには、現在接続できるアプリが表示されます。一部のアプリは追加の認証設定が必要で、設定が完了するまで表示されない場合があります。

## 認証とポリシー

接続の認証には、次の方法が使われます。

- 管理対象のOAuth、チャネルのインストール、またはネイティブOAuth2グラント
- ダッシュボードで入力したAPIキーまたはトークン

Beeuniは接続データを暗号化し、ツール呼び出しごとにサーバー側で解決します。エージェントがアクションを要求すると、Beeuniは認証情報を付加し、エージェントの許可とコネクタ接続ポリシーを確認して、外部APIを呼び出し、結果を返します。

コネクタポリシーはコネクタに適用されます。接続がポリシーを上書きすることはできません。プロジェクトのガードレールは、コネクタ接続ポリシーより上位で適用されます。

既定では、ポリシーに一致しないコネクタアクションは承認なしで実行されます。`policy.default_mode: risk`を設定すると、ルールに一致しない書き込みアクションと破壊的アクションに承認が必要になります。`sensitive: true`を設定すると、読み取りも含め、ルールに一致しないアクションのコネクタ既定値が`require_approval`になります。明示的なプロジェクトルールまたはコネクタ接続ルールは、引き続き先に適用されます。

<a id="approve-one-governed-call"></a>

### ガバナンス対象の呼び出しを1件承認する

`require_approval`は、コネクタ呼び出し1件に対する判定を作成します。コネクタは`202 pending_approval`とともに`approval_url`、`approval_summary`、`execution_id`を返します。HTTPリクエストを開いたままにはしません。

`approval_url`はチームメイトに共有できます。このURLはリクエストを識別しますが、権限は付与しません。ページを利用するには、Beeuniアカウントへのサインインが必要です。その後Beeuniは、そのアカウントがプロジェクト内のアクションにアクセスし、承認できることを確認します。

承認ページには、コネクタに渡される、機密情報が伏せられたパラメーターが表示されます。呼び出し元は`approval_context`（CLI: `--reason`）を追加して、結果を説明できます。パラメーターが参照情報だけの場合に使用してください。`gmail.send_draft`は下書きIDを受け取るため、エージェントは宛先、件名、本文を記述します。このテキストはエージェントの説明としてページに表示され、検証済みの情報ではありません。根拠となるのはパラメーターです。Beeuniが`approval_context`をプロバイダーに送信することはありません。

呼び出しを一度だけ承認または拒否します。判定に任意のメッセージを追加できます。メッセージは判定とともにエージェントに返されるため、拒否する場合に代わりに何をすべきか伝えられます。

保留中の呼び出しはすべて、プロジェクトの**Review → Needs you**にも表示されます。サイドバーから**Review**を開くと、対応が必要な項目数が表示されます。呼び出しを開くと、承認リンクと同じ承認画面が表示されるため、決定する前にコネクタ、パラメーター、エージェントの説明を確認できます。

呼び出しがSlackまたはTeamsのセッションから行われた場合、Beeuniはそのスレッドに承認カードを投稿します。カードにはエージェントの説明、パラメーター、**Approve** / **Deny**が表示されます。Slackでは**Reply…**を開くとエージェントへのメッセージ入力欄が表示されます。Teamsではカード内にメッセージ入力欄があります。判断できるのはプロジェクトマネージャーまたはセッションを開始した人だけです。どこで判断しても（スレッド、Beeuni、承認ページ）、カードのボタンは結果に置き換わり、エージェントは同じスレッドで処理を続けます。Beeuniは永続的なコールバックを通じて判断をセッションに返します。承認は正確に一致するリクエストダイジェストにのみ適用されます。宛先、件名、本文、チャンネル、URL、その他のパラメーターが変わった場合は、新たな判断が必要です。

セッションの**Audit**パネルを開くと、同じパラメーター表示を確認できます。過去のエントリーは読み取り専用です。セッション全体を対象とする承認オプションはありません。コネクターのアクションを無人で実行する必要がある場合に限り、明示的な`always_run`ポリシーを使用してください。

<a id="connect-with-oauth"></a>

## OAuthで接続する

1. **プロジェクトのConnectorsページを開く**

    プロジェクトを開きます。**Connectors**を選択し、アプリを選択します。

2. **アカウントのスコープを選択する**

    共有アカウントには**Project**を選択します。コネクターへのアクセスを許可された人なら誰でも利用できます。プライベートアカウントには**User**を選択します。アカウントはあなたが所有し、あなたのみがプライベートセッションで利用できます。

3. **認証を完了する**

    OAuthフローを完了します。Beeuniは接続したアカウントをコネクションとして保存します。

<a id="connect-an-mcp-server-that-uses-oauth-21"></a>

## OAuth 2.1を使用するMCPサーバーに接続する

BeeuniはMCP認証仕様を実装しています。コネクターを開き、**Add credential**を選択してから、**OAuth 2.0**タブを選択します。Beeuniはサーバーをプローブし、メタデータを読み取ります。

1. 認証なしのプローブは、`401`を`WWW-Authenticate: Bearer resource_metadata="…"`とともに返します。
2. BeeuniはそのURL、または`/.well-known/oauth-protected-resource`にある保護リソースメタデータ（RFC 9728）を読み取ります。
3. Beeuniは、リソースが最初に指定する認可サーバーの認可サーバーメタデータ（RFC 8414またはOpenID Connect discovery）を読み取ります。

そのサーバーが`registration_endpoint`を公開している場合、BeeuniはOAuthクライアント（RFC 7591）として自身を登録し、**Connect &lt;server&gt;**というボタンを1つ表示します。アプリケーションを作成する必要も、クライアントIDやシークレットをコピーする必要もありません。Beeuniはその後、PKCE（S256）を使用する認可コードフローを実行し、`resource`パラメーター（RFC 8707）でトークンをサーバーにバインドします。

サーバーが事前にリダイレクトURIを必要とする場合は、次を登録してください。

```text
https://api.beeuni.ai/v1/connectors/oauth2/callback
```

サーバーがエンドポイントを公開していても`registration_endpoint`を公開していない場合、Beeuniは認可URL、トークンURL、スコープを事前入力します。そのプロバイダーで作成したアプリのクライアントIDを入力してください。サーバーがメタデータを公開していない場合は、すべてのフィールドを入力します。

BeeuniはMCPセッションを維持します。必要に応じて`initialize`と`notifications/initialized`を実行し、以降の呼び出しでは`Mcp-Session-Id`を送信します。セッションなしで応答するサーバーには、ハンドシェイクは行われません。

Beeuniは各コネクションを、そのコネクションを発行した認可サーバーにバインドします。コールバックに`iss`パラメーター（RFC 9207）が含まれる場合、記録された発行者と一致しなければBeeuniは拒否します。別のサーバーが発行したコードは、引き換え前に拒否されます。

<a id="authorize-from-the-cli"></a>

### CLIから認証する

ダッシュボードはこのフローを実行する方法の1つであり、唯一の方法ではありません。`beeuni.yaml`でコネクターを宣言し、ターミナルまたはエージェントセッションから認証します。

```yaml
connectors:
  - slug: read-ai
    name: Read AI
    provider: mcp
    url: 'https://api.read.ai/mcp'
    auth:
      type: bearer
```

```text
beeuni connectors authorize read-ai --json
```

このコマンドはコネクションを作成し、検出チェーンを実行します。サーバーがRFC 7591をサポートしている場合はBeeuniをクライアントとして登録し、承認用のURLを返します。

```json
{
  "connection_id": "7b1a16b2-...",
  "registered": true,
  "scopes": ["openid", "offline_access", "mcp:execute", "meeting:read"],
  "authorization_url": "https://authn.read.ai/oauth2/auth?response_type=code&...",
  "expires_at": "2026-08-19T14:48:26.345Z"
}
```

エージェントは作業相手に`authorization_url`を返します。相手が承認した後、エージェントは次のように確認します。

```text
beeuni connectors authorize read-ai --status
```

ステータスが`error`の間、コマンドはゼロ以外の終了コードで終了します。要求する範囲を絞るには`--scope`を使用します。動的クライアント登録をサーバーがサポートしていない場合は、`--client-id`と`--client-secret`を使用します。

認証が完了すると、Beeuniはコネクターのツールカタログをすぐに再取得するため、手動で同期しなくてもコネクターは`error`状態を抜けます。

<a id="connect-a-direct-api-with-oauth2"></a>

## OAuth2で直接APIに接続する

直接接続するコネクターは、次をサポートしています。

- クライアント資格情報
- PKCEを使用する認可コードフロー
- デバイス認可
- 動的クライアント登録（RFC 7591）

クライアント資格情報の場合は、トークンURL、クライアントID、スコープ、クライアントシークレットを入力します。トークンエンドポイントの認証方式には`client_secret_basic`、`client_secret_post`、`client_secret_jwt`、`private_key_jwt`を使用できます。

認可コードの場合は、認可URLとトークンURLを入力します。デバイス認可の場合は、デバイス認可URLとトークンURLを入力します。RFC 8414の検出URLからこれらのエンドポイントを取得できます。

BeeuniはOAuth2の設定とトークンを暗号化します。アクセストークンは有効期限が切れる前に更新し、ローテーションされた更新トークンはそれぞれ保存します。コネクションを取り消すと、次回のコネクター呼び出しがブロックされます。

Microsoft Graphでは、次を使用します。

```text
https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token
https://graph.microsoft.com/.default
```

SharePoint RESTを直接呼び出す場合は、SharePointリソーススコープを使用します。

```text
https://{tenant}.sharepoint.com/.default
```

<a id="connect-with-an-api-key"></a>

## APIキーで接続する

1. **コネクターを宣言する**

    ```yaml
    connectors:
      - slug: stripe-read
        name: Stripe read access
        provider: openapi
        spec: 'https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json'
        auth:
          type: bearer
        policies:
          - match: 'get_*'
            action: always_run
          - match: '*'
            action: block
    ```

    下位互換性のため、マニフェストでは引き続き`authorization_strategy`キーを受け付けます。Beeuniはこれを無視します。代わりに、認証情報を追加するときに、コネクションごとに所有者（共有またはプライベート）を設定してください。

2. **変更リクエストをマージする**

    Beeuniはデフォルトブランチからマニフェストを読み取ります。変更リクエストをマージすると、コネクターが有効になります。

3. **コネクションを追加する**

    コネクターを開き、認証情報を設定します。Beeuniは値を暗号化して保存し、マニフェストには書き込みません。

<a id="grant-an-agent-access"></a>

## エージェントにアクセスを許可する

エージェントの`connectors`フィールドにコネクターのスラッグを追加します。

```yaml
agents:
  release-bot:
    connectors: [stripe-read]
```

`connectors`を省略すると、エージェントには`none`が付与されます。有効にするには、変更をマージしてください。

`connectors_required`は非推奨です。マニフェストでは引き続き受け付けられますが、参照されません。利用可能なアカウントがないコネクターを理由に、セッション作成時に拒否されることはありません。コネクターに対するセッション作成の拒否は、実際には発生しませんでした。プライベート専用のコネクターには共有アカウントがないため、拒否されても呼び出し元が対処できる手段がなかったからです。現在はコネクターの**呼び出し**時にチェックします。`stripe-read`が付与されたエージェントはすぐにターンを開始でき、実際にコネクターを必要とする呼び出しのみが拒否されます（[呼び出しが拒否された場合](#when-a-call-is-denied)を参照）。拒否には対処方法が添付されます。

<a id="select-an-account"></a>

## アカウントを選択する

呼び出しに使用するアカウントを選ぶ方法は2つあります。セッション全体で1つのアカウントを固定する方法と、単一の呼び出しでアカウントを指定する方法です。

<a id="pin-a-session-wide-default"></a>

### セッション全体のデフォルトを固定する

セッションでは、すべての呼び出しに対してコネクターのデフォルトアカウントを上書きできます。

```json
{
  "connector_bindings": {
    "stripe-read": {
      "connection_id": "00000000-0000-4000-8000-000000000000"
    }
  }
}
```

バインドキーはコネクターのスラッグです。値は、このセッションの呼び出し元が利用できるアカウント（コネクション）です。

有効なバインドを確認するには`GET /projects/{projectId}/sessions/{sessionId}/scope`を使用します。同じパスで`PUT`を使用すると置き換えられます。置き換えはセッションを再起動しなくても、次のツール呼び出しから適用されます。

<a id="name-an-account-on-one-call"></a>

### 1回の呼び出しでアカウントを指定する

コネクターを呼び出す際に使用できるアカウントを、デフォルトを先頭にして一覧表示するには、次を実行します。

```text
GET /connectors/projects/{projectId}/connectors/{slug}/accounts
```

```json
{
  "connector": "stripe-read",
  "accounts": [
    { "connection_id": "...", "label": "Shared workspace", "owner_type": "project", "is_default": true, "connected_as": "billing@example.com" },
    { "connection_id": "...", "label": "My Stripe", "owner_type": "member", "is_default": false, "connected_as": null }
  ]
}
```

次に、接続 ID またはラベル（大文字と小文字を区別しません）で、呼び出しに使用するアカウントを指定します。または、2 つのセレクター語 `me`（自分のデフォルトのプライベートアカウント）と `project`（プロジェクトのデフォルトの共有アカウント）を使用します。

```text
beeuni connectors call stripe-read get_balance '{}' --account me
beeuni connectors call stripe-read get_balance '{}' --account "Shared workspace"
```

アカウントを指定しない呼び出しは、まず呼び出し元自身のデフォルトのプライベートアカウント、次にプロジェクトのデフォルトの共有アカウントに解決されます。コネクタが複数のアカウントを保持できるようになる前から変更はありません。指定したアカウントが見つからない場合、別のアカウントに暗黙に置き換えられることはなく、**拒否**されます（[呼び出しが拒否された場合](#when-a-call-is-denied)を参照）。成功した呼び出しの結果には、実行に使用したアカウントが必ず含まれます: `account: { connection_id, label,
owner_type }`。

<a id="use-a-connector-in-a-session"></a>

## セッションでコネクタを使う

セッション内では Connector CLI を使用します:

```text
beeuni connectors ls
beeuni connectors accounts stripe-read
beeuni connectors call stripe-read <action> '<json-args>' [--account <id|label|me|project>]
```

`connectors` はスコープ内のコネクタを一覧表示します。`accounts` は、この呼び出し元が `stripe-read` として呼び出せるアカウントを一覧表示します。各グループ内では、デフォルトが先、共有がプライベートより先に表示されます。`call` は指定した `--account` として、または省略した場合は、コネクタが複数のアカウントを保持できるようになる前と同じデフォルト解決で、1 つのアクションを実行します。

<a id="large-results"></a>

### 大きな結果

一覧取得や検索の呼び出しでは、モデルが読み取れる量を超える結果が返ることがあります。ツール出力が約 50 KB を超えると切り詰められます。結果をファイルに保存し、コードで処理してください:

```text
beeuni connectors call linear graphql.issues '{"first":250}' --out /workspace/output/issues.json
# → { "ok": true, "account": …, "saved_to": "/workspace/output/issues.json",
#     "bytes": 93037, "shape": { "issues": { "nodes": "array(250) of {id,title,…}",
#     "pageInfo": { "hasNextPage": true, "endCursor": "…" } } } }
jq '.data.issues.nodes[] | {id, title}' /workspace/output/issues.json
```

`--out` は完全な JSON 結果を書き込み、親ディレクトリも作成します。標準出力には `data` を除いた呼び出しエンベロープと、`saved_to`、`bytes`、`shape` が出力されます。これらは `data` の概要（キー、配列の長さ、すべての `pageInfo`）です。終了コードは変わりません。

<a id="attach-files"></a>

### ファイルを添付する

呼び出しの引数にファイルのバイトデータを含めることはできません。ファイルをステージングしてから、その参照を引数に指定します。ゲートウェイがサーバー側でバイトデータを読み取り、リクエストに書き込みます。

```text
beeuni connectors call microsoft-graph.sendmail @mail.json \
  --attach /workspace/artifacts/report.pdf
```

`--attach` はファイルをステージングし、アクションの添付ファイル配列に参照を追加します。この配列はアクションの入力スキーマで確認できます: Email チャネルでは `attachments`、Microsoft Graph `sendMail` では `body.message.attachments` です。スキーマが特殊な場合は、`--attach-path body.message.attachments` で名前を指定してください。
大きな JSON 引数はファイル（`@mail.json`）または標準入力（`-`）で渡します。

ファイルを自分で配置する場合は、まずステージングします:

```text
beeuni connectors upload /workspace/artifacts/report.pdf --connector microsoft-graph
# → { "attachment_id": "…", "ref": { "$beeuni_attachment": "…" }, … }
```

引数内の任意の位置に `ref` を指定します。ゲートウェイは位置に応じて置き換えます:

| `ref` の位置 | 置き換え後 |
| --- | --- |
| 要素がオブジェクトの添付ファイル配列内 | プロバイダーの添付ファイル項目。項目のスキーマによって形式が決まります: Microsoft Graph `fileAttachment`（`name` + `contentBytes` または `@odata.type`）、Postmark（`Name` + `Content`）、Mailjet（`Filename` + `Base64Content`）、SendGrid と Resend（`filename` + `content`）、Brevo（`name` + `content`）。それ以外の項目形式は `attachment_item_shape_unknown` で拒否されます。 |
| 文字列フィールド（例: `contentBytes`、または GitHub ファイルの `content`） | ファイルの base64。 |
| Email チャネルの `attachments[]` | Email プロバイダー向けの署名付きダウンロード URL。 |

ルール:

- ファイルは `/workspace/output`、`/workspace/artifacts`、
  `/workspace/reports`、または `/workspace/deliverables` から取得します。シンボリックリンクとハードリンクは拒否されます。ファイルを先にそこへコピーしてください。
- 1 回の呼び出しで、最大 20 個のファイル、合計 25 MiB まで送信できます。上流 API の上限がこれより低い場合があります。Microsoft Graph では、1 つの `sendMail` リクエストに添付できるファイルの最大サイズを 3 MB としています。
- ステージングしたファイルは、ステージングしたセッション内でのみ使用でき、1 回限りで、24 時間後に削除されます。呼び出しが失敗した場合は、再試行できるように解放されます。
- 監査記録、承認プレビュー、モデルに表示されるのは参照のみで、バイトデータは表示されません。ファイルを含む上流エラーが返された場合は、base64 が削除されます。
- 管理対象のコネクタは、ステージングしたファイルを受け付けません
  （`connector_attachments_unsupported`）。

MCP サーバーでも同じフローを利用できます: `call` は `attachment_files`（および省略可能な `attachment_path`）を受け取り、`upload_attachment` は `ref` を返します。SDK では `connectors.uploadAttachment(bytes, { filename, contentType,
connector })`, which returns `ref` が相当します。

<a id="call-results"></a>

### 呼び出し結果

`POST /connectors/projects/{projectId}/call` は 1 つの JSON オブジェクトを返します。
以下のフィールドはすべてのバインディング（OpenAPI、HTTP、MCP、GraphQL、`composio`、`pipedream`、computers）で共通です:

| フィールド | 対象 | 値 |
| --- | --- | --- |
| `data` | 200 | 変更されていない上流の生の応答。 |
| `output` | 200 | バインディングのエンベロープを除いたペイロード: `composio` `data.result`、MCP `result.structuredContent ?? result.content`、GraphQL `data.data`。`data` と同じ場合（OpenAPI、HTTP、Postman、channel、`pipedream`、computer の呼び出し）は存在しないため、本文にはペイロードが 1 回だけ含まれます: `output ?? data` を読み取ってください。SDK がこの値を補完します。 |
| `binding` | 200、500、429、503 | 呼び出しを実行したバインディング: `openapi`、`http`、`mcp`、`graphql`、`composio`、`pipedream`、`pipedream_proxy`、`postman`、`tunnel`。アクションが解決する前にエラーが発生した場合は `null`。 |
| `upstream_status` | 200、500、429、503 | 上流の HTTP ステータス。上流から応答がなかった場合（タイムアウト、リクエスト拒否、computer）は `null`。`composio` と `pipedream` では、プロバイダーの失敗が 200 内で報告されるため、Beeuni はその場合に `502` を設定します（Linear クエリの拒否では `400`、レート制限では `429`）。 |
| `upstream_error` | 200 | 上流が 2xx 応答内で失敗を報告した場合に存在します: `isError: true` を含む MCP ツール結果または JSON-RPC エラー、あるいはデータのない GraphQL `errors`。呼び出しは実行済みとして扱われ、`ok` は `true` のままです。 |
| `retry_after_seconds` | 429、503 | 上流が送信した場合、その `Retry-After`（秒単位）。応答には `Retry-After` ヘッダーも含まれます。 |

呼び出しに失敗した場合の HTTP ステータス:

- 上流が `429` の場合は `429` を返します。上流が `503` の場合は `503` を返します。`retry_after_seconds`（またはバックオフ）してから、再度呼び出してください。
- その他の上流エラーは `500` を返し、`reason` に原因を含めます。

- 上流の応答が 64 MiB を超える場合は、`reason: "upstream_response_too_large: …"` とともに `500` を返します。Beeuni は上限に達した時点で読み取りを停止します。ページサイズを小さくするか、フィルターを指定してください。
- 上流が制限時間内に応答しない場合は、`reason: "upstream_timeout: …"` とともに `500` を返します。デフォルトの制限時間は 60 秒です。ゲートウェイが必ず先に応答するよう、クライアントのタイムアウトをこれより長く設定してください。

コネクタの呼び出しは冪等ではありません。Beeuni は同じ呼び出しを重複排除しません。`upstream_timeout` またはクライアント側の中断後は、上流で呼び出しが実行されている可能性があります。書き込みを繰り返す前（メールの送信、レコードの作成など）に、その結果を確認してください。

<a id="typed-calls-from-code"></a>

### コードから型付き呼び出しを行う

`beeuni connectors types` は、呼び出し可能なすべてのアクションについて TypeScript 宣言ファイルを書き出します。各アクションの引数型は入力スキーマから、結果型は出力スキーマから生成されます。結果型は、呼び出しの `output` フィールドを表します。

```sh
beeuni connectors types --out src/beeuni-connectors.d.ts
beeuni connectors types --connector linear,github --out src/beeuni-connectors.d.ts
```

ファイルを `tsconfig.json` に含めます。その後、`callAction` 経由で呼び出します:

```ts
import { createBeeuni } from '@beeuni/sdk';

const connectors = createBeeuni({ backendUrl, getToken }).project(projectId).connectors;
const result = await connectors.callAction('linear', 'list_issues', { team: 'CORE' });
if (result.ok) console.log(result.output?.issues.length);
```

コネクタハンドルは同じファイルを読み込み、`run` は型付き出力を返すか、型付きエラーをスローします（Connectors from code を参照）:

```ts
const issues = await createBeeuni({ backendUrl, getToken })
  .project(projectId)
  .connector('linear')
  .run('list_issues', { team: 'CORE' });
```

`callAction(slug, action, args, options)` は `call('<slug>.<action>', args, options)` と同じリクエストを送信し、同じ結果を返します。異なるのは型だけです。必須引数の欠落や未知の引数はコンパイルエラーになり、`output` には生成された型が適用されます。ファイルに含まれないアクションは、任意のオブジェクトを受け付け、`output: unknown` を返します。

- OpenAPI、HTTP、MCP、GraphQL コネクターは、ソースで定義されている場合、出力スキーマを公開します。GraphQL の結果はオブジェクト型です。
- 管理対象コネクターは出力スキーマを公開しません。その結果は `unknown` です。CLI はファイルを書き込んだ後に、これらの名前を表示します。
- 各 `$defs` エントリーは名前付き型（`BeeuniConnectorDef<n>_<name>`）1 つになります。そのため、再帰スキーマも有限です。コンパイルできないスキーマ（自身を含むユニオン）や、1 アクションあたりの型が 256 KB を超えるスキーマは `unknown` になります。
- コネクターを追加した後、または新しいバージョンが同期された後に、コマンドを再実行してください。
- カタログが出力スキーマを返すのは、要求された場合のみです。
  `GET /connectors/projects/{projectId}/catalog?include_output_schemas=true`
  を指定すると、各アクションに `outputSchema` が追加されます（保存されていない場合は `null`）。

<a id="when-a-call-is-denied"></a>

### 呼び出しが拒否された場合

拒否された呼び出しは `{ ok: false, status: "denied", reason, hint }` を返します。`reason` は安定したコードで、`hint` は対処方法を示します。

| `reason` | HTTP | 意味 | 本文に含まれる情報 |
| --- | --- | --- | --- |
| `connector_not_assigned` | 403 | 実行中のエージェントの `connectors:` 権限は、`beeuni.yaml` でこのコネクターを許可していません。 | `agent`、`granted`（一覧、または `"all"`）、`manifest_revision`、`manifest_commit`（権限の基になったマニフェスト）。 |
| `connector_not_connected` | 403 | この呼び出しに使用できるアカウントがありません。この呼び出し元のコネクターにアカウントがまったくない（保存済みの認証情報がない、またはアプリが未認証で、`beeuni connectors ls` では `needs_auth` と表示される）か、`--account` で指定されたアカウントを解決できませんでした。 | 接続がない場合、呼び出し元がリンクを作成できるときは、アカウント認証用のホストされたリンク `connect_url` が含まれます。`--account` でアカウントが指定されていた場合は、解決できなかった名前と解決できた名前 `requested_account` および `available_accounts` が含まれます。 |
| `connector_disabled` | 403 | コネクターは宣言されていますが、無効になっています。 | — |
| `connector_not_found` | 404 | このスラッグのコネクターは、プロジェクトに宣言されていません。 | — |
| `action_not_found` | 404 | このコネクターに該当するアクションはありません。 | — |

未接続のコネクターに対する対処方法は `connect_url` だけです。セッションの開始時に接続がないことを理由に拒否されることはありません（[エージェントにアクセス権を付与](#grant-an-agent-access) を参照）。そのため、拒否応答自体に解決方法が含まれます。エージェントはリンクをそのまま表示し、ウェブのトランスクリプトではワンクリックの「接続」ボタンとして表示されます。既定では、このリンクを開いた人のプライベートアカウントが認証されます。共有アカウントの接続は明示的な選択が必要です（`beeuni connectors connect stripe-read --owner project`、`project.connector.write` が条件）。

セッションを作成したチャネルコネクター（Slack、Teams、メール）は、エージェントの権限設定にかかわらず、常にそのセッションから呼び出せます。これにより、エージェントは依頼を受けたスレッドにいつでも返信できます。

セッションの権限は `beeuni.yaml` に従います。実行中のエージェントの `connectors:`（`beeuni connectors add --apply` を含む）に対する変更は、次の呼び出しから反映されます。権限には、その基になったマニフェストの blob とコミットが記録されます。同じ blob から置き換える読み込みでは、まず 2 回目の読み込みで確認され、古いコミットからの読み込みでは置き換えられません。

Slack と Microsoft Teams は、OAuth アプリと同じ方法でダッシュボードから接続できます。Slack を接続すると、あなたのために `channel` コネクターが `beeuni.yaml` に書き込まれます。[Slack とチャネル](/docs/ja/connect/slack) を参照してください。