エージェント API を使用してカスタム AI エージェントを作成する
学習の目的
- エージェント API を使い始める方法を説明する。
- エージェント API を使用して AI エージェントのセッションを開始し、セッションライフサイクルを管理する。
エージェント API を使ってみる
あなたはエンジニアで、Agentforce を Web サイトに組み込む業務を任されています。その目的は、お客様が Salesforce AI エージェントを利用して質問に対する有益な回答をすばやく得られるようにすることです。
これによってワークフローがシンプルになり、ユーザーインタラクションが強化されることはわかっていますが、どこから始めればよいのでしょうか? そこで役立つのエージェント API です。
エージェント API を使用して Agentforce の稼働を開始する手順の概要を見ていきましょう。
ステップ 1: Agentforce とエージェントを有効にする
まず、Salesforce 組織で Agentforce を有効にする必要があります。これは不可欠なステップで、これを行わなければ以降の設定は何も機能しません。Agentforce が有効になったら、1 つ以上のエージェントを有効にする必要があります。
エージェント API では [Agentforce (Default) (Agentforce (デフォルト))] 種別のエージェントはサポートされていません。
ステップ 2: 接続アプリケーションを作成し、OAuth 設定を有効にする
次に、Salesforce で接続アプリケーションを作成する必要があります。このアプリケーションは、安全な API コールに欠かせないクライアントログイン情報フローを処理します。API の OAuth 設定を有効にします。
ステップ 3: エージェントに接続アプリケーションを追加する
次に、接続アプリケーションをエージェントに追加する必要があります。これは Salesforce 組織の [Connections (接続)] タブで行います。このステップにより、接続アプリケーションがエージェントにリンクされ、API コールを実行できるようになります。
ステップ 4: コンシューマー鍵とコンシューマーの秘密を取得する
接続アプリケーションを設定したら、コンシューマー鍵とコンシューマーの秘密を取得する必要があります。このログイン情報は API コールを認証するために必須です。この情報は接続アプリケーションに表示されています。
ステップ 5: トークンを作成する
エージェント API へのすべてのコールにトークンが必要です。このトークンは API コールを認証するために使用されます。トークンはコンシューマー鍵、コンシューマーの秘密、ドメイン名を使用して作成できます。
実際に試してみる: 最初の API コールを実行する
ここからが楽しいところです。エージェント API へのコールを実行しましょう。
コールを実行する前に、組織からいくつかの情報を収集する必要があります。詳細は、『Agent API Developer Guide (Agent API 開発者ガイド)』の「Call the API (API のコール)」を参照してください。
コマンドラインインターフェースを使用して次の curl コマンドを実行し、エージェント API を使用した新しいエージェントセッションを作成します。
curl --location -X POST https://api.salesforce.com/einstein/ai-agent/v1/agents/{AGENT_ID}/sessions \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--data '{
"externalSessionKey": "{RANDOM_UUID}",
"instanceConfig": {
"endpoint": "https://{MY_DOMAIN_URL}"
},
"streamingCapabilities": {
"chunkTypes": ["Text"]
},
"bypassUser": true
}'
このコールが成功すると、セッション ID と追加情報が含まれた応答を受信します。次に応答のサンプルを示します。
{
"sessionId": "80ab2e16-392e-4c12-b80a-f028a58400b5",
"_links": {
"self": null,
"messages": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5/messages"
},
"messagesStream": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5/messages/stream"
},
"session": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/agents/0XxHr000000ysOSKAY/sessions"
},
"end": {
"href": "https://api.salesforce.com/einstein/ai-agent/v1/sessions/80ab2e16-392e-4c12-b80a-f028a58400b5"
}
},
"messages": [
{
"type": "Inform",
"id": "d27b7308-f1ab-47bd-949c-0225d5e21a8e",
"feedbackId": "",
"planId": "",
"isContentSafe": true,
"message": "Hi, I'm an AI service assistant. How can I help you?",
"result": [],
"citedReferences": []
}
]
}これで、AI エージェントへのメッセージの送信を開始できます。
エージェント API では、同期メッセージ処理とストリーミングメッセージ処理の両方がサポートされています。同期メッセージは 1 回のコールで完全な応答が必要なユースケースに最適で、ストリーミングメッセージはチャット会話のようなリアルタイムのやり取りに適しています。
完了したら、忘れずにセッションを閉じましょう。
考慮事項
-
データ使用量: エージェント API にコールを行うたびに Einstein 要求を消費します。使用される要求数は API コールのサイズと大規模言語モデル (LLM) の利用状況種別乗数によって異なります。
-
API タイムアウト: エージェント API には 120 秒のタイムアウトがあります。コールがタイムアウトすると、HTTP 500 応答を受信します。
まとめ
これで完了です。「Get Started with Agent API (エージェント API 入門)」ガイドとサンプルコードを使用して、Web サイトに Agentforce を組み込み、お客様のエクスペリエンスをより良いものにしましょう。