بدء الاستخدام مع A2A

أنشئ وشغّل وكيلاً لبروتوكول A2A (من وكيل إلى وكيل) في أقل من 5 دقائق.

المتطلبات الأساسية

• Rust 1.95.0 أو أحدث (rustup update stable)
• تثبيت cargo-adk (cargo install cargo-adk)
• مفتاح Google API (احصل على واحد من هنا)

إنشاء هيكل مشروع A2A

أسرع طريقة للبدء هي قالب a2a:

cargo adk new my-a2a-agent --template a2a
cd my-a2a-agent

ينشئ هذا مشروعًا كاملًا يتضمن:

• Cargo.toml — adk-rust مع features = ["standard"] (يتضمن دعم A2A)
• src/main.rs — خادم A2A باستخدام أداة الإنشاء API
• .env.example — عنصر نائب لمفتاح API

أضف مفتاح API الخاص بك:

cp .env.example .env
# Edit .env and set GOOGLE_API_KEY=your-key-here

شغّل:

cargo run

يعمل وكيل A2A الآن على http://localhost:8080.

موفرو الخدمات الآخرون

# OpenAI
cargo adk new my-agent --template a2a --provider openai

# Anthropic
cargo adk new my-agent --template a2a --provider anthropic

---

API الميسّرة

يوفر ADK-Rust الدالة A2aServer لإتاحة أي وكيل عبر بروتوكول A2A دون الحاجة إلى إعداد المسارات يدويًا.

دون إعداد: quick_start

النهج الأبسط — استدعاء دالة واحد وإعدادات افتراضية مناسبة:

use adk_rust::prelude::*;
use adk_rust::server::A2aServer;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("GOOGLE_API_KEY")?;

    let model = GeminiModel::new(api_key, "gemini-3.7-flash")?;

    let agent: Arc<dyn Agent> = Arc::new(
        LlmAgentBuilder::new("my-agent")
            .description("A helpful AI assistant")
            .instruction("You are a helpful assistant exposed via A2A.")
            .model(Arc::new(model))
            .build()?,
    );

    let app = A2aServer::quick_start(agent);
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

تُعدّ quick_start ما يلي:

• خدمة جلسات داخل الذاكرة
• بطاقة الوكيل في GET /.well-known/agent.json
• نقطة نهاية JSON-RPC في POST /a2a
• تفعيل البث

إعداد مخصص: أداة الإنشاء

استخدم أداة الإنشاء عندما تحتاج إلى التحكم في المنفذ أو البيانات الوصفية أو واجهة خلفية للجلسات:

use adk_rust::prelude::*;
use adk_rust::server::A2aServer;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(api_key, "gemini-3.7-flash")?;

    let agent: Arc<dyn Agent> = Arc::new(
        LlmAgentBuilder::new("my-agent")
            .description("Production A2A agent")
            .instruction("You are a helpful assistant.")
            .model(Arc::new(model))
            .build()?,
    );

    let server = A2aServer::builder()
        .agent(agent)
        .bind_addr("0.0.0.0:9090")
        .agent_card_name("My Production Agent")
        .agent_card_description("Handles customer queries via A2A")
        .agent_card_version("2.0.0")
        .streaming(true)
        .push_notifications(false)
        .build()?;

    server.serve().await?;
    Ok(())
}

---

الاختبار باستخدام curl

بعد تشغيل وكيلك، تحقّق منه باستخدام هذه الأوامر.

جلب بطاقة الوكيل

curl http://localhost:8080/.well-known/agent.json | jq .

الاستجابة المتوقعة:

{
  "name": "my-agent",
  "description": "A helpful AI assistant",
  "url": "http://localhost:8080",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "skills": []
}

إرسال رسالة (JSON-RPC)

curl -X POST http://localhost:8080/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "What is the A2A protocol?"}],
        "messageId": "msg-1"
      }
    },
    "id": "req-1"
  }'

الاستجابة المتوقعة:

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "result": {
    "id": "task-uuid",
    "status": {"state": "completed"},
    "artifacts": [
      {
        "parts": [{"kind": "text", "text": "The A2A protocol is..."}]
      }
    ]
  }
}

بث استجابة

curl -X POST http://localhost:8080/a2a/stream \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "message/stream",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Explain Rust in 3 sentences."}],
        "messageId": "msg-2"
      }
    },
    "id": "req-2"
  }'

يُرجع هذا أحداثًا مُرسلة من الخادم مع تحديثات تدريجية لحالة المهمة.

---

حافظ على تمييز حدود MCP وA2A

يربط MCP تطبيق وكيل بالأدوات والموارد والقدرات الأخرى المنشورة. ويربط A2A الوكلاء المنشورين بشكل مستقل، وينقل دورة حياة عملهم عن بُعد. يمكن لجسر ترجمة البروتوكولين، لكن هذا الجسر مكوّن منشور بشكل منفصل، وله هويته وتفويضه وربط مخططه وربط حالة مهمته وسلوك فشله الخاص.

لا يوفّر ADK-Rust ملفًا ثنائيًا باسم mcp-a2a-server. لا تضع ذلك الأمر في تهيئة MCP ما لم يوفّر النشر لديك جسرًا كهذا ويختبره بشكل منفصل. عندما يكون كلا الطرفين وكيلين، استخدم عميل A2A مباشرةً.

الاتصال من وكيل ADK-Rust آخر

استخدم RemoteA2aAgent لاستدعاء وكيل A2A من تطبيق ADK-Rust آخر:

use adk_rust::server::RemoteA2aAgent;

let remote = RemoteA2aAgent::new(
    "my-remote-agent",
    "http://localhost:8080",
);

ينشئ هذا وكيلًا يعيد توجيه الطلبات إلى خادم A2A عبر الشبكة.

---

مرجع نقاط النهاية

---

الخطوات التالية

• A2A مثال البدء السريع — مثال عملي بسيط
• تكامل الأدوات — إضافة أدوات مخصصة إلى وكيل A2A الخاص بك
• الجلسات — الاحتفاظ بحالة المحادثة عبر الطلبات
• النشر — نشر وكيل A2A الخاص بك في بيئة الإنتاج

---

السابق: البدء السريع | التالي: LlmAgent