# エージェント API

> そのエージェント専用のキーで、HTTP 経由でエージェントを呼び出します。単発のリクエストでも、呼び出しをまたいでコンテキストを保つセッションでも使えます。

**API** セクションでは、endue の外部からこのエージェントを呼び出すためのキーを発行します。[会話](/ja/docs/work/conversations/)、[チャンネル](/ja/docs/automate/channels/)に続く3つ目の入り口で、こちらはプログラム向けです。

## 使いどころ

呼び出す側がコードのときです。毎日の要約を記録するスクリプト、エージェントに分類を任せるバックエンド、CI で動くジョブなどが該当します。呼び出す側が人なら、チャンネルのほうが適しています。スレッド、質問、承認がそろっているからです。

## キーを発行する

<Steps>

1. [エージェントビルダー](/ja/docs/build/agent-builder/)で **API セクションを開き**、キーを作成します。

2. **すぐにコピーします**。キーは一度しか表示されません。紛失した場合は、そのキーを無効化して新しいキーを発行します。

3. **プログラムからは読めて、人からは読めない場所に保管します**。環境変数やシークレットストアを使い、リポジトリには決して置かないでください。

</Steps>

ここで作成したキーは**このエージェント専用**で、ほかのエージェントの呼び出しには使えません。ほかのエージェントも呼び出せるアカウント全体のキーは、**設定 → アカウント**で発行します。なるべく範囲の狭いキーを使いましょう。

<Screenshot
  name="studio-api"
  alt="API セクション。発行済みのキーがプレフィックスと最終使用日時とともに表示され、その下にそのままコピーできるリクエスト例があります。"
/>

## エージェントを呼び出す

キーを `Authorization: Bearer sk_…`（または `X-API-Key`）で送り、エージェントにしてほしいことを POST します。

```http
POST /api/public/v1/agents/{agent_id}/invoke
Authorization: Bearer sk_...
Content-Type: application/json

{ "input": "Summarize yesterday's support tickets" }
```

レスポンスには、エージェントの回答とともに**セッション ID** が含まれます。次の呼び出しでその ID を送り返すと、エージェントは最初からやり直さずに、同じコンテキスト（履歴を含む同じ会話）で続きを処理します。

```json
{ "input": "Now group them by product area", "session_id": "..." }
```

`"stream": true` を指定すると、実行全体の完了を待たずに、生成されたそばから回答を受け取れます。

<Aside type="note" title="セッションは会話です">
  セッションは、別に管理するものではありません。どのセッションも endue で開ける会話で、サイドバーにあるエージェントの API グループから、エージェントが何を頼まれ、何と答えたかを確認できます。
</Aside>

## API 呼び出しでは使えないもの

API の呼び出し元は会話の画面の前にいるわけではないため、[無人の実行](/ja/docs/automate/routines/#承認する人は誰もいない)として扱われます。

- 外部への送信や削除を伴う操作は、誰かの承認を待つのではなく**拒否**されます。
- エージェントが答えを必要とする[質問](/ja/docs/work/questions/)にも、答える人がいません。

エージェントが判断を求めずに済むよう、リクエストは正確に書きましょう。また、結果は送信済みのものではなく下書きになると考えておきます。

## 制限事項

- 実行は1つのセッションにつき同時に1つまでです。そのセッションで実行が進行中にもう一度呼び出すと、順番待ちにはならずに拒否されます。
- キーは一度しか表示されず、復元できません。無効化してから再発行してください。
- エージェント専用のキーは、そのエージェントにしか使えません。ほかのエージェントに対しては、エンドポイントが「見つからない」と応答します。
- キーの無効化はすぐに反映されます。

## 関連項目

<CardGrid>
  <LinkCard
    title="チャンネル"
    href="/ja/docs/automate/channels/"
    description="プログラムではなく、人のための入り口。"
  />
  <LinkCard
    title="承認"
    href="/ja/docs/work/approvals/"
    description="API 呼び出しが単独でメールを送れない理由。"
  />
  <LinkCard
    title="セキュリティと権限"
    href="/ja/docs/account/security/"
    description="キーでアクセスできる範囲と、キーを無効化する方法。"
  />
</CardGrid>