すべてのプロダクト
Search

このプロダクト

    Intelligent Media Services:エージェントコールバック

    ドキュメントセンター

    Intelligent Media Services:エージェントコールバック

    最終更新日:Dec 10, 2025

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

    概要

    AI エージェントが実行中で特定のイベントが発生すると、Alibaba Cloud は自動的にサーバーにリクエストを送信し、カスタムビジネスロジックを使用してイベントを処理できるようにします。

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

    1. コンソールで AI エージェントページに移動し、構成するエージェントを見つけて、操作列の [管理] をクリックします。

    2. [コールバック構成] タブで、[有効化] をクリックしてエージェントコールバックを構成します。イベントタイプを選択し、[コールバック URL] とオプションの [認証トークン] を設定します。

      説明

      トークンは、認証のために Authorization ヘッダーに配置されます。サーバーは、このトークンを検証して、リクエストが信頼できるソースからのものであることを確認する必要があります。

      image

    3. [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:

        • ユーザー音声 (ロールは user): 完全なユーザーの意図が認識されたときに送信されます。コンテンツには、ユーザーの音声データと対応する STT 結果が含まれます。

        • エージェント音声 (ロールは agent): エージェントが話し終えたとき、またはユーザーによって中断されたときに送信されます。コンテンツには、エージェントの音声データと対応するテキストが含まれます。

      • full_audio_record: 完全な通話録音が有効になっている場合、通話全体の音声がミックスされ、単一の音声ファイルに録音されます。

    • クライアントサイドのプロアクティブメッセージコールバック

      • 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': 'Okay, the user is asking what 1 plus 1 equals. It seems simple, but I need to think about it carefully.',
      'time': 1739445458025,
      'source': 'chat',
      'dialogueId': 'xxxxxxxxxx',
      'type': 'normal'
    },
    {
      'roundId': 'xxxxxxxxxxx',
      'producer': 'user',
      'text': 'Just answer 1+1=?',
      'time': 1739445436218,
      'source': 'chat',
      'dialogueId': 'xxxxxxxxxxx',
      'type': 'normal'
    }
  ]
}

    • 音声/ビデオチャットレコード:

    {
  'role': 'user',
  'type': 'normal',
  'text': 'Tell a longer story',
  'sentence_id': 1
}

    audio_record

    {
  'role': 'user',
  'sentence_id': 1,
  'start_timestamp': 1743151532.33012,
  'text': 'Tell a longer 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'
}

    video_frame

    {
  'sentence_id': 1,
  'start_timestamp': 1743151532.33012,
  'text': 'What am I holding in my hand?',
  'url_list': [<file oss address>, <file oss address>]
}

    code

    String

    はい

    コールバックイベントのステータスコード。詳細については、「コールバックイベントのステータスコード」をご参照ください。

    1001

    message

    String

    はい

    コールバックメッセージ。

    ユーザーはルームから退出させられました

    timestamp

    String

    はい

    コールバックイベントが発生したときのタイムスタンプ。

    2023-10-01T12:00:00Z

    userData

    String

    いいえ

    ユーザー定義情報。

    extendData

    Json

    いいえ

    カスタム拡張情報。

    コールバックの例

    ワークフローステータスコールバック

    ワークフローステータスイベントの場合、extendData フィールドは次のとおりです:

    名前

    タイプ

    説明

    channelId

    String

    チャネル ID。

    sentenceId

    Int

    会話のターンの一意の ID。

    説明

    1 つのユーザーの質問に対する複数のエージェントの応答は、同じ sentenceId を共有します。

    requestTimestamp

    String

    • event が llm_data_received または tts_data_received の場合、これはリクエストが LLM または TTS サービスに送信されたときのタイムスタンプです。

    • event が intent_recognized の場合、これはエージェントがユーザーの発話の終了を検出したときのタイムスタンプです。エージェントが発話終了条件が満たされていないと判断した場合、この値は None になります。

    responseTimestamp

    String

    • event が llm_data_received または tts_data_received の場合、これは LLM または TTS サービスからの最初の応答パケットのタイムスタンプです。

    • event が intent_recognized の場合、これはユーザーが話し終えた後に ASR 結果が取得されたときのタイムスタンプです。

    サーバーの例

    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:
        # リクエストボディからデータを取得します。
        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

    エージェントが開始

    AI エージェントが開始されます。

    1002

    エージェントが停止

    AI エージェントが終了します。

    1003

    セッションが開始

    セッションが開始されます

    4001

    同時エージェントルートが枯渇

    同時ルートが使い果たされました

    4002

    エージェントがチャネルからキックされた

    ユーザーはルームから退出させられました

    4003

    無効なエージェントトークン

    AI エージェントのトークンが無効です

    4004

    エージェントストリームのサブスクリプションに失敗

    AI エージェントのストリームをプルできませんでした

    4005

    サードパーティの ASR が失敗

    エラーの説明

    4006

    アバターサービスが利用不可

    アバターサービスは利用できません

    8001

    意図を認識

    インテント認識イベント

    8002

    LLM データを受信

    LLM データ受信イベント

    8003

    TTS データを受信

    TTS データ受信イベント