Agentforce Agent API でヘッドレスエージェント・マルチエージェントを構築しよう

2025年3月、Agentforceの新しいAPI **「Agent API」** が一般公開されました。このAPIは、Salesforceプラットフォーム上で構築したAIエージェントを、あらゆるインターフェース、画面、アプリ、ワークフローへ展開可能にします。本記事では、Agent APIの概要とその活用方法について解説します。


## Agent APIとは？

Agent APIは、Salesforceプラットフォーム上にAgentforceで構築したAIエージェントを外部システムから呼び出せるAPIです。UIを持たないヘッドレスエージェントを様々な業務システムに組み込み、自動化や効率化を実現できます。


### MIAW API と何が違う？
Agentforceのエージェントを外部から呼び出す方法は、他にも Messaging for In-App and Web (MIAW) API があります。MIAWは会話UIでの利用が前提となります。Agent APIは、会話UIを持たないヘッドレスな使い方もできるため、様々なシーンでの活用が期待できます。


|          | MIAW API                               | Agent API                                    |
|--------------|----------------------------------------|----------------------------------------------|
| **主な目的**     | 人間との会話（会話UI）                             | 人間との会話、UIなしのシステム連携             |
| **設定のしやすさ**         | やや複雑                 | シンプル                                     |
| **対応形式**     | テキスト、フォーム、ファイル添付など       | テキストのみ          |
| **フィードバック機能**     | なし       | あり (Data Cloudへ保存される)         |


### Agent API でできること

Agent APIが提供する主な機能です。

#### REST API
Agent APIは標準的なREST APIで提供されます。開発者は使い慣れたHTTPリクエスト・レスポンスのパターンでAgentforceエージェントと会話できます。

#### セッションベースの対話モデル

Agent APIはセッションベースの対話モデルです。まずセッションを開始し、そのセッション内でメッセージをやり取りし、最後にセッションを終了するという流れで操作します。各セッションには一意のセッションIDが割り当てられ、後続のメッセージ送受信で使用します。


#### 同期・非同期両方のメッセージング対応

Agent APIは、同期メッセージング（一度のリクエストに対し一度の応答）と、ストリーミングベースの非同期メッセージング（Server-Sent Events:SSEプロトコル）の両方をサポートしています。特に複雑な質問に対してはストリーミングモードが有用で、応答が形成される過程をリアルタイムに表示できます。

#### コンテキスト変数とカスタム変数のサポート
セッション開始時や各メッセージ送信時に、コンテキスト変数やカスタム変数を渡すことができます。例えば、顧客IDをコンテキスト変数として渡すことで、エージェントは顧客固有の情報に基づいて応答できるようになります。不確実な要素であるプロンプトだけでなく、確定的な処理をエージェントの動作に取り入れることも可能にします。

#### フィードバックメカニズム

エージェントの応答に対するフィードバックを送信する機能も提供されています。このフィードバックは Data Cloud に保存され、エージェントの学習や改善に役立てることができます。

## Agent APIの使い方

Agent APIを使用するには、クライアント認証フローをサポートする接続アプリケーションを呼び出したいエージェントに設定します。詳細は [公式ドキュメント](https://developer.salesforce.com/docs/einstein/genai/guide/agent-api.html) を参照してください。

:::note warn
2025/4/13現在、Agent APIは「Agentforce Service Agent(ASA)」タイプのエージェントのみサポートしています
:::

### 1. トークンの作成

接続アプリケーションを作成して取得した `コンシューマーキー`、`コンシューマーシークレット`を使用して、`アクセストークン`を取得します。

```bash
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=<CONSUMER_KEY>&client_secret=<CONSUMER_SECRET>" \
"https://<MY_DOMAIN_URL>/services/oauth2/token"
```

### 2. エージェントセッションの開始

`エージェントID` を渡してセッションを開始します。

```bash
curl -X POST "https://<MY_DOMAIN_URL>/services/data/v63.0/copilot/agents/<AGENT_ID>/sessions" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "externalSessionKey": "<ユニークなID>",
    "instanceConfig": {
        endpoint: "https://<MY_DOMAIN_URL>/"
    },
    "bypassUser": true
}'
```

成功すると、`セッションID` が含まれたレスポンスが返されます。


### 3. メッセージの送信

メッセージの送信には、同期メッセージングとストリーミングメッセージングの2つの方法があります。

#### 同期メッセージング
会話UIを伴わないサーバー間の連携に適しています。

```bash
curl -X POST "https://MY_DOMAIN_URL/services/data/v63.0/copilot/agents/sessions/<SESSION_ID>/messages" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "message": {
        "type": "Text",
        "sequenceId": 1,
        "text": "注文した商品の配送状況を教えて"
    }
}'
```

#### ストリーミングメッセージング
Server-Sent Events（SSE）プロトコルを介して応答が返されます。会話UIで使用することで、ユーザーフレンドリーなUXを提供できます。

```bash
curl -X POST "https://MY_DOMAIN_URL/services/data/v63.0/copilot/agents/sessions/SESSION_ID/messages/stream" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
    "message": {
        "type": "Text",
        "sequenceId": 1,
        "text": "注文した商品の配送状況を教えて"
    }
}'

```

チャンクごとに応答が段階的に返されます。

```bash:SSEレスポンス例
event: ProgressIndicator
data: {"type":"ProgressIndicator","data":{"status":"IN_PROGRESS"}}

event: TextChunk
data: {"type":"TextChunk","data":{"text":"注文データを調べるため、"}}

event: TextChunk
data: {"type":"TextChunk","data":{"text":"あなたのメールアドレスを"}}

event: TextChunk
data: {"type":"TextChunk","data":{"text":"教えてもらえますか？"}}

event: Inform
data: {"type":"Inform","data":{"content":"注文データを調べるため、あなたのメールアドレスを教えてもらえますか？","sequenceId":1}}

event: EndOfTurn
data: {"type":"EndOfTurn","data":{}}
```


### 4. セッションの終了
会話終了後、セッションを終了します。

```bash
curl -X DELETE "https://MY_DOMAIN_URL/services/data/v63.0/copilot/agents/sessions/<SESSION_ID>" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
```

### 5.フィードバックの送信
必要に応じて、会話セッションに対するフィードバックを送信することもできます。

```bash
curl -X POST "https://<MY_DOMAIN_URL>/services/data/v63.0/copilot/agents/sessions/<SESSION_ID>/feedback" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
    "feedbackId": "<ユニークなID>",
    "feedback": "GOOD",
    "text": "期待通り！"
}'
```


## 活用例と応用シナリオ
Agent APIを活用することで、外部Webサイト・アプリケーション・モバイルアプリ等での会話UI実装から、会話UIを持たないヘッドレスエージェントとしての利用。さらには複数のエージェントが協力して一つのタスクを遂行するマルチエージェントシステムなど、多様な分野での活用が考えられます。

#### ウェブサイトへの統合
自社のウェブサイトにAgentforceエージェントを統合することで、訪問者は **Salesforce や Data Cloud に統合されたデータに基づいたQ&A** を受けることができます。例えば、製品カタログの検索、価格確認、注文状況の確認などをウェブサイト上で直接実行できるようになります。また、Eコマースサイトでの商品リコメンデーションを、ヘッドレスエージェントの返答をもとに行うことで、よりパーソナライズされた提案が期待できます。

#### サードパーティアプリケーションとの連携
外部コラボレーションツールにAgentforceエージェントを統合し、チーム内でのデータアクセスや業務自動化を実現できます。従業員は普段使用しているプラットフォーム上で、Salesforceデータへのアクセスや定型的なタスクの実行が可能になります。

#### 自動化されたワークフローの強化
既存のロジックベースの自動化プロセスにAIのインテリジェンスを追加できます。Flow内からエージェントを呼び出して自然言語処理や複雑な判断を行い、ワークフローをさらに強化することができます。例えば、解約リスクの上昇を察知した離反防止エージェントが、解約を阻止するためのアクションを提示したり、関連する自動化プロセスをプロアクティブに実行します。

#### マルチエージェントシステムの構築
異なる専門分野を持つ複数のエージェントを構築し、それらをAPI経由で連携させることで、より高度で複雑なタスクを処理するマルチエージェントシステムを構築できます。例えば、ローン申請システムでは、顧客と対話するオーケストレーターエージェントが、ドキュメント検証エージェント、信用スコア計算エージェント、リスク分析エージェント、融資判断エージェントなどの複数エージェントとバックグラウンドで連携します。顧客は複数のエージェントに聞く必要はなく、単一のエージェントと対話するだけでシームレスにローン申請手続きを完了できます。

## おわりに
Agent APIは、Salesforce上に構築したAIエージェントの能力を、社内外の様々なアプリケーションやシステムに拡張するための強力なツールです。このAPIを活用することで、顧客体験の向上、業務プロセスの効率化、そしてこれまでにない新しいAI活用ソリューションの実現が期待できます。

何か思いつくアイデアがあれば、Agent API で試してみませんか？

## ご参考

***[開発者ガイド] Agent API Developer Guide***

https://developer.salesforce.com/docs/einstein/genai/guide/agent-api.html


***[TDXセッション録画] Build Headless Agents with the Agentforce API***

https://www.salesforce.com/plus/experience/tdx_2025/series/developers_at_tdx_2025/episode/episode-s1e3