Callback Agent - Intelligent Media Services

Panggilan balik agen memungkinkan aplikasi Anda secara otomatis memicu aksi atau tanggapan yang telah ditentukan sebelumnya ketika kejadian tertentu terjadi. Topik ini menjelaskan cara menggunakannya.

Ikhtisar

Saat agen AI sedang Berjalan dan suatu kejadian tertentu terjadi, Alibaba Cloud secara otomatis mengirimkan permintaan ke server Anda sehingga Anda dapat memproses kejadian tersebut menggunakan logika bisnis kustom Anda sendiri.

Konfigurasi panggilan balik agen

Buka halaman AI Agents di Konsol, temukan agen yang ingin dikonfigurasi, lalu klik Manage pada kolom Actions.
Pada tab Callback Configurations, klik Enable untuk mengonfigurasi panggilan balik agen. Pilih jenis event dan atur Callback URL serta Authentication Token opsional.
Catatan
Token ditempatkan dalam header Authorization untuk autentikasi. Server Anda harus memverifikasi token ini guna memastikan permintaan berasal dari sumber tepercaya.
Klik OK untuk menyimpan konfigurasi.

Bidang muatan callback

Nama	Tipe	Diperlukan	Deskripsi	Contoh
aiAgentId	String	Ya	ID agen.	xxxxx
instanceId	String	Ya	ID unik dari instans agen.	39f8e0bc005e4f309379701645f4****
event	String	Ya	Jenis event. Panggilan balik status agen: agent_start: Tugas agen dimulai. session_start: Sesi panggilan berhasil dibuat. agent_stop: Tugas agen berhenti. error: Terjadi kesalahan. Panggilan balik status alur kerja: intent_detected: Agen mulai mendeteksi maksud pengguna. intent_recognized: Maksud pengguna yang lengkap berhasil dikenali. llm_data_received: Paket pertama dari tanggapan streaming diterima dari model bahasa besar (LLM). tts_data_received: Paket pertama dari tanggapan streaming diterima dari layanan Text-to-Speech (TTS). Panggilan balik catatan obrolan real-time: chat_record: Catatan obrolan real-time. Panggilan balik rekaman audio: audio_record: Audio pengguna (role adalah user): Dikirim saat maksud pengguna yang lengkap berhasil dikenali. Kontennya mencakup data audio pengguna dan hasil STT yang sesuai. Audio agen (role adalah agent): Dikirim saat agen selesai berbicara atau terganggu oleh pengguna. Kontennya mencakup data audio agen dan teks yang sesuai. full_audio_record: Jika perekaman panggilan lengkap diaktifkan, seluruh audio panggilan akan digabung dan direkam menjadi satu file audio. Callback pesan proaktif sisi klien client_defined_data: Callback untuk pesan kustom yang dikirim oleh klien. Disarankan untuk menyertakan pengenal guna membedakan awal dan akhir pesan. Callback instruksi: instruction: Callback untuk instruksi aksi agen.	agent_start
data	Json	Tidak	Muatan data, seperti catatan obrolan.	chat_record Catatan obrolan pesan teks: { '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' } ] } Catatan obrolan audio/video: `{ '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	Ya	Kode status untuk event callback. Untuk detailnya, lihat Kode status event callback.	1001
message	String	Ya	Pesan callback.	Pengguna telah dikeluarkan dari ruangan
timestamp	String	Ya	Timestamp saat event panggilan balik terjadi.	2023-10-01T12:00:00Z
userData	String	Tidak	Informasi yang ditentukan pengguna.
extendData	Json	Tidak	Informasi tambahan kustom.

Contoh callback

Panggilan balik status alur kerja

Untuk event status alur kerja, bidang extendData adalah sebagai berikut:

Nama	Tipe	Deskripsi
channelId	String	ID saluran.
sentenceId	Int	ID unik untuk giliran percakapan. Catatan Beberapa respons agen terhadap satu pertanyaan pengguna memiliki sentenceId yang sama.
requestTimestamp	String	Saat event adalah llm_data_received atau tts_data_received, ini adalah timestamp saat permintaan dikirim ke layanan LLM atau TTS. Saat event adalah intent_recognized, ini adalah timestamp saat agen mendeteksi akhir ucapan pengguna. Nilai ini adalah `None` jika agen menentukan bahwa kondisi akhir ucapan belum terpenuhi.
responseTimestamp	String	Saat event adalah llm_data_received atau tts_data_received, ini adalah timestamp paket respons pertama dari layanan LLM atau TTS. Saat event adalah intent_recognized, ini adalah timestamp saat hasil ASR diperoleh setelah pengguna selesai berbicara.

Contoh server

Python

from aiohttp import web
import json
from loguru import logger

async def handle_post(request):
    """
    Menangani permintaan POST dan mencatat data yang diterima.
    """
    # Mendapatkan header Authorization dari permintaan.
    authorization_header = request.headers.get('Authorization')
    if authorization_header is None or not authorization_header.startswith('Bearer fixed-token'):
        logger.error("Permintaan tidak sah")
        return web.Response(status=401, text='Unauthorized')

    try:
        # Mendapatkan data dari badan permintaan.
        callback_data = await request.json()

        logger.info("Data JSON yang diurai:")
        logger.info(json.dumps(callback_data, indent=4))

        return web.Response(text='Callback received successfully', status=200)
    except json.JSONDecodeError:
        # Jika penguraian JSON gagal, mengembalikan respons kesalahan.
        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)

Kode status event panggilan balik

Kode status	Event panggilan balik	Pesan panggilan balik
1001	Agen dimulai	Agen AI dimulai.
1002	Agen dihentikan	Agen AI berakhir.
1003	Sesi dimulai	Sesi dimulai
4001	Rute agen bersamaan habis	Rute konkuren habis
4002	Agen dikeluarkan dari saluran	Pengguna telah dikeluarkan dari ruangan
4003	Token agen tidak valid	Token tidak valid untuk Agen AI
4004	Langganan aliran agen gagal	Gagal menarik aliran untuk Agen AI
4005	ASR pihak ketiga gagal	deskripsi kesalahan
4006	Layanan avatar tidak tersedia	Layanan avatar tidak tersedia
8001	Maksud dikenali	Peristiwa niat dikenali
8002	Data LLM diterima	Peristiwa data LLM diterima
8003	Data TTS diterima	Peristiwa data TTS diterima