الوكلاء الآنيون ومتعددو الوسائط

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

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

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

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

ثم راجع تطبيقات الأمثلة الأربعة القابلة للتشغيل.

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

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

  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 المشغّل ويربطه ببقية ADK — SessionService (استمرارية السجل)، وMemoryService (الاسترجاع والتخزين)، وEnhancedPluginManager (الخطافات)، وجسر يتيح لأي adk-core Tool العمل في جلسة آنية. هذا ما تستخدمه الأمثلة.

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

التثبيت

# Voice + tools + the integration layer (recommended)
adk-realtime = { version = "2.1.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-2.1",
));

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، والأصوات، ونقاط النهاية، والمصادقة.
3. الأدوات — استدعاء الدوال من جهة الخادم.
4. متعدد الوسائط — إرسال إطارات الفيديو.
5. الحوار العاطفي — استجابات واعية بالعواطف.
6. الذاكرة — ذاكرة طويلة الأمد قائمة على الرسم البياني للمعرفة.
7. إنشاء تطبيقات الويب — الجسر الخاص بالمتصفح.
8. الأمثلة — أربعة تطبيقات قابلة للتشغيل.