エージェントコールバック - Intelligent Media Services - Alibaba Cloud ドキュメントセンター

エージェントコールバックを使用すると、特定のイベントが発生したときに、アプリケーションで事前に設定されたアクションや応答を自動的にトリガーできます。

概要

AI エージェントが特定のランタイムイベントをトリガーすると、Alibaba Cloud はご利用のサーバーにコールバックリクエストを送信します。その後、ビジネスロジックを追加してリクエストを処理できます。

エージェントコールバックの設定

Intelligent Media Service コンソールにログインします。設定するエージェントを選択し、[操作] 列の [管理] をクリックします。
[コールバック設定] タブで、エージェントコールバックを有効にし、コールバックタイプを選択して、[コールバック URL] とオプションの [認証トークン] を入力します。

説明
このトークンは、リクエストヘッダーの Authorization フィールドで送信されます。リクエストのセキュリティを確保するために、ご利用のサーバーでこのトークンを検証する必要があります。

利用可能なコールバックタイプは次のとおりです：エージェントステータスコールバック、ワークフローステータスコールバック、リアルタイムチャット履歴コールバック、切断意図検出コールバック、アウトバウンドコールステータスコールバック、インバウンドコールステータスコールバック、カスタムクライアントメッセージコールバック、命令コールバック。コールバック URL が HTTP と HTTPS の両方をサポートしている場合は、セキュリティを強化するために HTTPS を強く推奨します。
[OK] をクリックして、コールバック設定を完了します。

コールバックペイロードのフィールド

パラメーター	タイプ	必須	説明	例
aiAgentId	String	はい	エージェント ID。	xxxxx
instanceId	String	はい	エージェントインスタンスの一意の ID。	39f8e0bc005e4f309379701645f4****
event	String	はい	イベントタイプ。エージェントステータスコールバック： agent_start：エージェントタスクが開始されるとトリガーされます。 session_start：通話セッションが確立されるとトリガーされます。 agent_stop：エージェントタスクが停止するとトリガーされます。 error：エラーが発生するとトリガーされます。ワークフローステータスコールバック： intent_detected：エージェントがユーザーの意図の検出を開始するとトリガーされます。 intent_recognized：エージェントがより完全なユーザーの意図を認識するとトリガーされます。 llm_data_received：大規模言語モデル (LLM) から応答データが受信されるとトリガーされます。ストリーム応答の場合、このイベントは最初のデータパケットを受信したときにトリガーされます。 tts_data_received：Text-to-Speech (TTS) サービスから応答データが受信されるとトリガーされます。ストリーム応答の場合、このイベントは最初のデータパケットを受信したときにトリガーされます。リアルタイムチャットレコードコールバック： chat_record：会話のリアルタイムトランスクリプトを提供します。音声録音コールバック： audio_record：ユーザー音声 (role="user")：エージェントがより完全なユーザーの意図を認識したときにトリガーされます。ペイロードには、ユーザーの音声データと対応する音声テキスト変換 (STT) の結果が含まれます。エージェント音声 (role="agent")：エージェントが音声の再生を終了したとき、またはユーザーがそれを中断したときにトリガーされます。ペイロードには、エージェントの音声データと対応するテキストが含まれます。 full_audio_record：通話全体の録音が有効になっている場合、通話終了後にトリガーされます。ペイロードには、完全なミックスチャンネル音声ファイルへのリンクが含まれます。通話ステータスコールバック： outbound_call：アウトバウンドコールのステータス変更または切断イベントに対してトリガーされます。 inbound_call：インバウンドコールのステータス変更または切断イベントに対してトリガーされます。クライアントからのカスタムメッセージのコールバック： client_defined_data：クライアントから送信されたカスタムメッセージのコールバック。メッセージの開始と終了を区別するための識別子を含めることを推奨します。エージェントアクション命令コールバック： instruction：エージェントが実行するアクション命令が含まれます。	agent_start
data	Json	いいえ	データペイロード。このフィールドの構造はイベントタイプによって異なります。	chat_record テキストメッセージチャットレコード： { 'requestId': 'abcd', 'code': 'Success', 'message': 'Success', 'dialogues': [ { 'roundId': 'xxxxxxx', 'producer': 'agent', 'text': '1+1=2', 'reasoningText': 'The user is asking what 1+1 is. It seems simple, but I need to think carefully.', 'time': 1739445458025, 'source': 'chat', 'dialogueId': 'xxxxxxxxxx', 'type': 'normal' }, { 'roundId': 'xxxxxxxxxxx', 'producer': 'user', 'text': 'Just answer, what is 1+1?', 'time': 1739445436218, 'source': 'chat', 'dialogueId': 'xxxxxxxxxxx', 'type': 'normal' } ] } `{ 'role': 'user', 'type': 'normal', 'text': 'Tell me a long story.', 'sentence_id': 1 }` audio_record `{ 'role': 'user', 'sentence_id': 1, 'start_timestamp': 1743151532.33012, 'text': 'Tell me a long story.', 'audio_url': '<file oss address>' }` full_audio_record `{ 'audio_url': '<file oss address>', 'start_timestamp': '2025-11-06T09:33:48.776253+00:00', 'end_timestamp': '2025-11-06T09:34:34.550809+00:00' }`
code	String	はい	コールバックイベントのステータスコード。	1001
message	String	はい	コールバックメッセージ。	User has been kicked from the room
timestamp	String	はい	イベントが発生した時刻。ISO 8601 形式の文字列 (協定世界時 (UTC)) です。	2023-10-01T12:00:00Z
userData	String	いいえ	ユーザー定義情報。
extendData	Json	いいえ	カスタム拡張データ。

コールバックの例

アウトバウンドコールのステータス

event が outbound_call の場合、このコールバックはアウトバウンドコールのステータスを報告します。次の表に、このイベントの extendData オブジェクトのフィールドについて説明します。

パラメーター	タイプ	説明
aiAgentId	String	AI エージェント ID。
channelId	String	チャネル ID。
instanceId	String	AI エージェントインスタンスの一意の ID。
callerNumber	String	発信者 (AI エージェント) の電話番号。
calleeNumber	String	着信者の電話番号。
failReason	Int	失敗理由。このフィールドは、アウトバウンドコールが失敗した場合にのみ返されます。
status	Int	AI エージェントの現在の通話ステータス。指定できる値は次のとおりです。 `2`：アウトバウンドコールまたは通話転送が失敗しました。 `3`：アウトバウンドコールまたは通話転送が正常に接続されました。 `4`：通話が切断されました。
callStartTime	String	通話が接続された時刻。このフィールドは切断時にのみ返されます。
callEndTime	String	通話が切断された時刻。このフィールドは切断時にのみ返されます。
hangupRole	Int	通話を切断した当事者。このフィールドは切断時にのみ返されます。指定できる値は次のとおりです。 `0`：発信者 (AI エージェント)。 `1`：着信者。 `2`：転送された通話を受信した当事者。
forwardInfo	JSON	通話転送に関する情報。このフィールドは、通話転送関連のコールバックに対してのみ返されます。次のサブフィールドが含まれます。 `callerNumber`：転送を開始した当事者の電話番号。データ型：String。 `calleeNumber`：転送を受信する当事者の電話番号。データ型：String。 `callStartTime`：転送された通話が接続された時刻。データ型：String。このフィールドは、転送が成功した場合または切断が発生した場合にのみ返されます。

アウトバウンドコールの失敗

このコールバックは、着信者の番号が無効である、通話が拒否された、または着信者が到達不能であったためにアウトバウンドコールが失敗したことを示します。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10002,
  "message":"Dial status failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": -6,
      "status": 2
  }
}

アウトバウンドコールの接続

このコールバックは、被呼者がアウトバウンド呼び出しに応答したときに送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10003,
  "message":"Dial status connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3
  }
}

着信側切断

このコールバックは、アウトバウンドコールが接続された後に着信者が切断した場合に送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 1
  }
}

エージェントの切断

このコールバックは、アウトバウンドコールが接続された後に AI エージェントが切断した場合に送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 0
  }
}

通話転送の成功

このコールバックは、通話転送が正常に接続されたときに送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10006,
  "message":"Forward call connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

通話転送の失敗

このコールバックは、通話転送が失敗したときに送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10005,
  "message":"Forward call failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": 480,
      "status": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX"
      }
  }
}

通話転送後の切断

このコールバックは、転送を受信した当事者が切断した場合に送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

インバウンドコールのステータス

event が inbound_call の場合、このコールバックはインバウンドコールのステータスを報告します。次の表に、このイベントの extendData オブジェクトのフィールドについて説明します。

パラメーター	タイプ	説明
aiAgentId	String	この値は、コールバックのトップレベルの `aiAgentId` フィールドと同じです。
channelId	String	チャネル ID。
instanceId	String	この値は、コールバックのトップレベルの `instanceId` フィールドと同じです。
callerNumber	String	発信者 (インバウンドコールを発信している当事者) の電話番号。
calleeNumber	String	被呼者 (AI エージェント) の電話番号
failReason	Int	失敗理由。このフィールドは、インバウンドコールが失敗した場合にのみ返されます。
status	Int	AI エージェントの現在の通話ステータス。指定できる値は次のとおりです。 `2`：インバウンドコールまたは通話転送が失敗しました。 `3`：インバウンドコールまたは通話転送が正常に接続されました。 `4`：通話が切断されました。
callStartTime	String	通話が接続された時刻。このフィールドは切断時にのみ返されます。
callEndTime	String	通話が切断された時刻。このフィールドは切断時にのみ返されます。
hangupRole	Int	通話を切断した当事者。このフィールドは切断時にのみ返されます。指定できる値は次のとおりです。 `0`：着信者 (AI エージェント)。 `1`：発信者 (インバウンドコールを発信している当事者)。 `2`：転送された通話を受信した当事者。
forwardInfo	JSON	通話転送に関する情報。このフィールドは、通話転送関連のコールバックに対してのみ返されます。次のサブフィールドが含まれます。 `callerNumber`：転送を開始した当事者の電話番号。データ型：String。 `calleeNumber`：転送を受信する当事者の電話番号。データ型：String。 `callStartTime`：転送された通話が接続された時刻。データ型：String。このフィールドは、転送が成功した場合または切断が発生した場合にのみ返されます。

インバウンドコールの接続

このコールバックは、AI エージェントがインバウンドコールに正常に応答したときに送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10003,
  "message":"Dial status connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3
  }
}

インバウンドコールの失敗

このコールバックは、AI エージェントがインバウンドコールに応答できなかった場合に送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10002,
  "message":"Dial status failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": -6,
      "status": 2
  }
}

インバウンドコールの切断

このコールバックは、インバウンドコールが接続された後に AI エージェントが切断した場合に送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 0
  }
}

通話転送の成功

このコールバックは、インバウンドコールからの通話転送が正常に接続されたときに送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10006,
  "message":"Forward call connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

通話転送の失敗

このコールバックは、インバウンドコールからの通話転送が失敗したときに送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10005,
  "message":"Forward call failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": 480,
      "status": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX"
      }
  }
}

通話転送後の切断

このコールバックは、インバウンドコールからの転送後に転送を受信した当事者が切断した場合に送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

ワークフローのステータス

ワークフローステータスイベントの場合、extendData オブジェクトには次のフィールドが含まれます。

パラメーター	タイプ	説明
channelId	String	チャネル ID。
sentenceId	Int	会話のターンの一意の ID。説明単一のユーザークエリに対する AI エージェントの応答は、同じ `sentenceId` を共有します。
requestTimestamp	String	llm_data_received イベントの場合、これはリクエストが LLM に送信されたときのタイムスタンプです。 tts_data_received イベントの場合、これはリクエストが TTS サービスに送信されたときのタイムスタンプです。 intent_recognized イベントの場合、これは AI エージェントがユーザーの発話の終了を検出したときのタイムスタンプです。エージェントがまだ発話の終了を判断していない場合、この値は `None` です。
responseTimestamp	String	llm_data_received イベントの場合、これは LLM からの最初の応答のタイムスタンプです。 tts_data_received イベントの場合、これは TTS サービスからの最初の応答のタイムスタンプです。 intent_recognized イベントの場合、これはユーザーが話し終えた後に ASR 結果が返されたときのタイムスタンプです。

命令コールバック

event タイプが instruction の場合、コールバックは特定のアクション命令タグがトリガーされたことを示します。サポートされている命令コールバックは次のとおりです。

通話転送命令コールバック

このコールバックは、AI エージェントが通話転送アクションタグをトリガーしたときに送信されます。

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"instruction",
  "code":11001,
  "message":"Forward call triggered",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "triggerTime": "2023-10-01T12:00:00Z"
  }
}

サーバーの例

Python

from aiohttp import web
import json
from loguru import logger
async def handle_post(request):
    """
    POST リクエストを処理し、受信したデータをログに記録します。
    """
    # リクエストから Authorization ヘッダーを取得します。
    authorization_header = request.headers.get('Authorization')
    if authorization_header is None or not authorization_header.startswith('Bearer fixed-token'):
        logger.error("Unauthorized request")
        return web.Response(status=401, text='Unauthorized')
    try:
        # リクエストボディを JSON として解析します。
        callback_data = await request.json()
        logger.info("Parsed JSON data:")
        logger.info(json.dumps(callback_data, indent=4))
        return web.Response(text='Callback received successfully', status=200)
    except json.JSONDecodeError:
        # JSON の解析に失敗した場合はエラーを返します。
        return web.Response(text='Invalid JSON', status=400)
app = web.Application()
app.add_routes([web.post('/', handle_post)])
if __name__ == '__main__':
    web.run_app(app, host='localhost', port=8081)

コールバックイベントのステータスコード

ステータスコード	コールバックイベント	説明
1001	エージェント開始	エージェントが開始します。
1002	エージェント停止	エージェントが停止します。
1003	セッション開始	セッションが開始します。
4001	同時エージェントルートの枯渇	同時エージェントルートの最大数に達しました。
4002	エージェントがチャネルからキックされた	システムがエージェントをチャネルからキックしました。
4003	無効なエージェントトークン	エージェントのトークンが無効です。
4004	エージェントのストリームサブスクリプションの失敗	エージェントがストリームをサブスクライブできませんでした。
4005	サードパーティ ASR の失敗	サードパーティの ASR サービスが失敗しました。
4006	アバターサービス利用不可	アバターサービスは利用できません。
8001	意図認識	意図が認識されました。
8002	LLM データ受信	LLM データが受信されました。
8003	TTS データ受信	TTS データが受信されました。
10002	ダイヤルステータス失敗	通話の接続に失敗しました。
10003	ダイヤルステータス接続	通話は正常に接続されました。
10004	切断	通話が切断されました。
10005	通話転送失敗	通話転送の試行が失敗しました。
10006	通話転送接続	転送された通話は正常に接続されました。
11001	通話転送トリガー	システムが通話転送をトリガーしました。