الوكلاء متعددو الوسائط وفي الوقت الفعلي

أنشئ وكلاء يتحدثون، يستمعون، يرون، ويتصرفون في الوقت الفعلي — عبر اتصال مباشر، منخفض الكمون بخدمة Realtime API الخاصة بـ OpenAI أو Gemini Live API من Google.

الوكيل في الوقت الفعلي ليس روبوت دردشة يعتمد على الطلب/الاستجابة. إنه يحتفظ بجلسة مفتوحة: ميكروفون المستخدم يبث باستمرار، والنموذج يبث صوتًا + نصًا مباشرًا مكتوبًا مرة أخرى، ويكتشف متى يبدأ المستخدم ويتوقف عن الكلام، ويمكن مقاطعته في منتصف الجملة (barge-in)، ويمكنه رؤية إطارات من الكاميرا، و يمكنه استدعاء أدواتك والتحدث بالنتيجة — كل ذلك دون إنهاء "المكالمة" أبدًا.

هل أنت جديد على ADK-Rust؟ اقرأ المقدمة و البدء السريع أولاً. يفترض هذا القسم أنك تعرف ما هو الـ agent، والـ tool، والـ session.

ما يمكنك بناؤه

ثم انظر إلى تطبيقات الأمثلة الأربعة القابلة للتشغيل.

النموذج الذهني

هناك طبقتان، وتستخدم معظم التطبيقات الطبقة العليا:

  IntegratedRealtimeRunner          ← sessions, memory, tools, plugins (use this)
        │ wraps
  RealtimeRunner                    ← event loop + tool dispatch
        │ drives
  RealtimeSession  (a transport)    ← the live WebSocket to the provider
        │ created by
  RealtimeModel    (OpenAI | Gemini)

• RealtimeModel (على سبيل المثال OpenAIRealtimeModel، GeminiRealtimeModel) يعرف كيف connect() وينتج RealtimeSession — النقل المباشر.
• RealtimeRunner يمتلك تلك الجلسة: يضخ الأحداث، وعندما يطلب النموذج أداة، فإنه ينفذ المعالج ويرسل النتيجة مرة أخرى.
• IntegratedRealtimeRunner يغلف الـ Runner ويربطه ببقية ADK — SessionService (استمرارية النسخ)، MemoryService (استدعاء + تخزين)، EnhancedPluginManager (خطافات)، وجسر يسمح لأي adk-core Tool بالتشغيل في جلسة في الوقت الفعلي. هذا ما تستخدمه الأمثلة.

(يوجد أيضًا مستوى أعلى RealtimeAgent للوكلائين الصوتيين البسيطين فقط، ووسائل نقل مباشرة — WebRTC، LiveKit، Vertex AI Live — موثقة هناك.)

التثبيت

# Voice + tools + the integration layer (recommended)
adk-realtime = { version = "2.0.0", features = ["openai", "gemini", "integration"] }

بدء سريع في 60 ثانية

دورة صوتية بدون واجهة: اتصل، اسأل بالنص، واضخ الرد المتدفق.

use adk_realtime::config::{RealtimeConfig, VadConfig};
use adk_realtime::events::ServerEvent;
use adk_realtime::integration::{IntegratedRealtimeRunner, IntegrationConfig};
use adk_realtime::model::BoxedModel;
use adk_realtime::openai::OpenAIRealtimeModel;
use adk_session::{CreateRequest, InMemorySessionService, SessionService};
use std::sync::Arc;

# async fn run() -> anyhow::Result<()> {
let model: BoxedModel = Arc::new(OpenAIRealtimeModel::new(
    std::env::var("OPENAI_API_KEY")?,
    "gpt-realtime",
));

let config = RealtimeConfig::default()
    .with_instruction("You are a friendly assistant. Keep replies short.")
    .with_voice("marin")
    .with_audio_only()
    .with_vad(VadConfig::server_vad())   // model decides turn boundaries
    .with_transcription();               // emit a text transcript too

let sessions = Arc::new(InMemorySessionService::new());
sessions.create(CreateRequest {
    app_name: "demo".into(), user_id: "u1".into(),
    session_id: Some("s1".into()), state: Default::default(),
}).await?;

let runner = IntegratedRealtimeRunner::builder()
    .model(model)
    .config(config)
    .identity("demo", "u1", "s1")
    .session_service(sessions)
    .integration_config(IntegrationConfig::default())
    .build()?;

runner.connect().await?;
runner.send_text("Say hello in one short sentence.").await?;
runner.create_response().await?;       // text input needs an explicit trigger

while let Some(event) = runner.next_event().await {
    match event? {
        ServerEvent::TranscriptDelta { delta, .. } => print!("{delta}"),
        ServerEvent::AudioDelta { .. } => { /* PCM16 to play */ }
        ServerEvent::ResponseDone { .. } => break,
        _ => {}
    }
}
runner.close().await?;
# Ok(()) }

في تطبيق حقيقي، تقوم ببث صوت الميكروفون باستخدام runner.send_audio(base64_pcm16) بدلاً من send_text، وتقوم VAD الخادم بتشغيل الاستجابات تلقائيًا — لا حاجة إلى create_response(). انظر بناء تطبيقات الويب.

أين تذهب بعد ذلك

1. البنية — كيف تتلاءم الأجزاء، حلقة الأحداث، مسار الصوت.
2. الموفرون — OpenAI مقابل Gemini models، الأصوات، نقاط النهاية، المصادقة.
3. الأدوات — استدعاء الوظائف من جانب الخادم.
4. متعدد الوسائط — إرسال إطارات الفيديو.
5. الحوار العاطفي — الاستجابات الواعية بالعواطف.
6. الذاكرة — الذاكرة طويلة المدى القائمة على الرسم البياني المعرفي.
7. بناء تطبيقات الويب — جسر المتصفح.
8. أمثلة — أربعة تطبيقات قابلة للتشغيل.