بروتوكول Agent2Agent · A2A v1.0

دعونا نشر وكلاء بشكل مستقل العمل معا.

يمنح A2A وكيل الذكاء الاصطناعي طريقة قياسية لتقديم نفسه إلى وكيل آخر، وقبول وظيفة أو مهمة، والإبلاغ عن التقدم، وطلب المزيد من المعلومات، وإرجاع نتائج مفيدة - حتى عندما يعمل الوكيل الآخر في خدمة ذكاء اصطناعي مختلفة، أو يستخدم لغة برمجة مختلفة أو إطار عمل وكيل، أو يتم نشره في سحابة أخرى. لا يحتاج أي من الوكيلين إلى فهم كيفية بناء الآخر. يستخدمون معيار A2A للتواصل والعمل معًا.

شاهد الهندسة المعمارية بناء وكيل A2A

عمليات 11 ضد 1بطاقات الوكيلJSON-RPC + RESTتدفق SSEمهام متعددة المنعطفاتدفعة مصادق عليهاRemoteA2aAgent

ADK-Rust A2A البنية المرجعية

بنية الوكلاء البعيدين A2A

The network contract stays separate from the agent's model, tools, memory, and internal orchestration.

نظام الاتصال

الوكيل أو التطبيق يطلب من وكيل آخر القيام بالعمل.

وكيل منسق

يقرر أي متخصص عن بعد يجب أن يتلقى المهمة.

العميل A2A

يكتشف البطاقة ويختار البث ويرسل رسائل البروتوكول.

HTTPS

حدود الخدمة A2A

العقد العام الذي يمكن لكل عميل متوافق أن يفهمه.

بطاقة الوكيل

الاسم والمهارات ونقطة النهاية وإصدار البروتوكول والأمان والقدرات المعلنة.

طلب الشيكات

الإصدار ونوع المحتوى والمعرفات وأجزاء الرسالة وبيانات التعريف والهوية والحدود.

معالج الطلب

يرسل عمليات JSON-RPC أو REST من خلال تطبيق مشترك واحد.

مكالمة مكتوبة

وقت التشغيل ADK-Rust

ينفذ الإطار المهمة وينتج تقدمًا مكتوبًا.

Runner

إنشاء سياق الاستدعاء وتدفق أحداث الوكيل.

نظام الوكيل

LLM أو سير العمل أو الرسم البياني أو المنطق المخصص أو المنطق متعدد الوكلاء.

أدوات

أدوات Rust وMCP

الدولة

الجلسات والذاكرة

يتم تسجيل حالة المهمة والأحداث أثناء عمل الوكيل

دورة حياة المهمة

آلة الحالة التي تم التحقق من صحتها تجعل العمل طويل الأمد قابلاً للفحص.

مخزن المهام

الحالة والسياق والتاريخ والمصنوعات والبيانات الوصفية وتكوين الدفع.

آلة الدولة

يتم قبول التحولات الصالحة فقط؛ المهام النهائية تبقى طرفية.

تسليم التقدم

يختار المتصل الطريقة التي يريد بها تلقي التغيير.

الرد المباشر

قم بإرجاع المهمة كاملة وعناصرها.

تيار SSE

المهمة أولاً، ثم تحديثات الحالة والعناصر.

العمل بعد الطلب

يمكن الإبلاغ عن المهام الطويلة لاحقًا دون الاستمرار في فتح اتصال واحد.

الاشتراك

يستمع العميل إلى التحديثات الخاصة بمهمة موجودة.

ادفع خطاف الويب

تمت المصادقة على التسليم مع إعادة المحاولة وفحوصات SSRF.

يحتفظ ADK-Rust بالعقد السلكي A2A ودورة حياة المهمة وتنفيذ الوكيل وقنوات التسليم كأجزاء منفصلة بحيث يمكن تأمين كل منها واختبارها واستبدالها بشكل مستقل.

ابدأ بالفكرة

كيف يمكنني العمل مع وكيل الذكاء الاصطناعي المستضاف خارجيًا؟

داخل عملية ADK-Rust واحدة، يمكن للوكلاء مشاركة أنواع وجلسات وأدوات Rust واستدعاءات الوظائف المباشرة. بمجرد أن ينتمي الوكيل إلى خدمة أخرى - أو مؤسسة أخرى - فإن تفاصيل التنفيذ الخاصة هذه لم تعد عقدًا آمنًا.

يحدد A2A اللغة المشتركة عند تلك الحدود. يكتشف المتصل ما يقدمه الوكيل البعيد، ويرسل رسالة منظمة، ويتبع مهمة من خلال حالات معروفة، ويتلقى العناصر دون الحاجة إلى معرفة النموذج أو إطار العمل أو الأدوات التي تعمل خلف نقطة النهاية.

يقوم ADK-Rust بتنفيذ A2A v1 في adk-server ويربط البروتوكول مباشرة بـ Runner. يمكن أن يصبح نفس الوكيل الذي تختبره محليًا خدمة شبكة، بينما يتيح RemoteA2aAgent لنظام ADK-Rust آخر استهلاكه من خلال واجهة الوكيل العادية.

بطاقة الوكيل

ملف تعريف الخدمة للوكيل

يخبر مستند عام صغير المتصلين باسم الوكيل ونقطة النهاية والمهارات وإصدار البروتوكول ومتطلبات الأمان وما إذا كان يدعم البث أو الإشعارات.

رسالة

ما يقوله وكيل لآخر

تحمل الرسالة دورًا ومعرفًا فريدًا وجزءًا واحدًا أو أكثر مثل النص أو البيانات المنظمة. المعرف الفريد يجعل إعادة المحاولة الآمنة ممكنة.

المهمة

المهمة التي يمكن أن يتبعها كلا النظامين

تمنح المهمة العمل عن بعد معرفًا وسياق محادثة وحالة وسجل الرسائل وبيانات التعريف وأي عناصر تم إنتاجها على طول الطريق.

قطعة أثرية

المخرج المفيد للعمل

القطعة الأثرية هي نتيجة مسماة مرفقة بالمهمة: تقرير أو قرار أو خطة أو ملف تم إنشاؤه أو أي مخرجات منظمة أخرى يمكن لنظام آخر استخدامها.

اتبع وظيفة واحدة

يحمل البروتوكول كلاً من الطلب ومدة العمل.

يمكن للمتصل انتظار رد واحد، أو فتح بث حدث مباشر، أو الاشتراك في مهمة موجودة، أو تسجيل خطاف ويب للحصول على التحديثات اللاحقة. تعمل هوية المهمة وسياقها على إبقاء كل وضع تسليم مرتبطًا بنفس قطعة العمل.

آلة حالة المهمة

الوظيفة عن بعد لها حياة يمكنك متابعتها.

يقوم A2A بأكثر من مجرد إرجاع النص. إنه يمنح العمل هوية وسياق محادثة وحالة حالية وتاريخًا ومصنوعات يدوية. يقوم ADK-Rust بالتحقق من صحة كل انتقال قبل حفظه.

SUBMITTED

قبل الخادم المهمة.

WORKING

يقوم الوكيل بتنفيذه.

INPUT REQUIRED

الوكيل يحتاج إلى مزيد من المعلومات.

AUTH REQUIRED

يجب على المتصل تقديم إذن.

COMPLETED

العمل والتحف جاهزة.

FAILED

انتهى التنفيذ بوجود خطأ.

CANCELED

أدى الإلغاء المسموح به إلى إنهاء المهمة.

REJECTED

رفض الخادم المهمة.

عمل متعدد المنعطفات: عندما تصل المهمة INPUT_REQUIRED، يرسل المتصل رسالة أخرى بنفس الشيء contextId. يجد ADK-Rust المهمة ويعيدها إليها WORKING، يقوم بإلحاق الرسالة، ويستمر في نفس المهمة.

التدفق المنطقي في العالم الحقيقي

Case Study: Resolve a customer's damaged order across two distinct agent services.

A customer tells the company's support agent that an order arrived damaged. The support agent remains responsible for the conversation: it understands the request, keeps the customer informed, collects any missing evidence, and presents the final decision. It does not have direct access to warehouse stock, delivery records, or replacement policy.

تنتمي هذه المعلومات التشغيلية إلى وكيل تنفيذ تم نشره بشكل منفصل. من خلال A2A، يمكن لوكيل الدعم اكتشاف ما يفعله وكيل التنفيذ، وإرسال التحقيق إليه كمهمة، ومتابعة تقدمه، والإجابة على طلبات الحصول على مزيد من المعلومات، والحصول على قرار الاستبدال النهائي. تحتفظ كل خدمة بالرمز والبيانات والأدوات وموفر النموذج وعناصر التحكم الأمنية الخاصة بها؛ إنهم يشاركون فقط الرسائل وحالة المهمة والعناصر المحددة بواسطة عقد A2A.

اكتشف المتخصص

يقرأ منسق الدعم بطاقة وكيل التنفيذ ويؤكد أنه يتعامل مع التحقيق في الطلب ويتابع التقدم.

أرسل وظيفة واحدة واضحة

يرسل رقم الطلب وطلب العميل ومعرف الرسالة الفريد وسياق المحادثة الجديد.

الطريق داخل الخدمة

يقوم وكيل ADK-Rust عن بعد بالتحقق من أدوات الطلب والمخزون وتاريخ التسليم وسياسة الشركة دون تعريض تلك العناصر الداخلية للمتصل.

اسأل عما هو مفقود

إذا كان إثبات الضرر مطلوبًا، تصبح المهمة INPUT_REQUIRED بدلاً من التخمين أو الفشل بصمت.

استئناف نفس المهمة

يقوم المنسق بتزويد الأدلة المعتمدة باستخدام نفس معرف السياق؛ يظل التاريخ وهوية المهمة سليمة.

إرجاع نتيجة قابلة للتدقيق

تكتمل المهمة بسجل الحالة وقطعة أثرية تحتوي على قرار الاستبدال والخطوات التالية.

Sequence diagram

The task pauses and resumes without losing its identity.

Read from top to bottom. The A2A service owns the network contract and task record. The fulfilment agent owns its reasoning and private tools.

Support coordinator

Calling agent

A2A service

Protocol boundary

Fulfilment agent

ADK-Rust Runner

Business systems

Orders · inventory · policy

المكالمات من خلال A2A

يرسل إلى Runner

يستخدم الأدوات المعتمدة

GET /.well-known/agent-card.json

Discover skills and streaming

Agent Card

Fulfilment capability published

SendStreamingMessage

ORD-1042 · messageId msg-order-1042

Runner invocation

Create task and execute agent

order.lookup + policy.check

Use private business tools

Evidence required

Damage photo is missing

INPUT_REQUIRED

Persist state and context

SSE status update

Ask support for evidence

SendMessage · same contextId

Approved photo reference

Resume task

INPUT_REQUIRED → WORKING

inventory.reserve

Reserve replacement stock

Artifact + COMPLETED

Replacement decision

Final SSE events

Auditable result returned

The support coordinator never receives database credentials or fulfilment code. It receives only the Agent Card, protocol events, task state, and final artifact.

استجابات الكود والأسلاك

انظر ما يرسله ويستقبله كل جانب.

تستخدم هذه الأمثلة نفس أسماء عمليات v1 وحقول الرسائل وحالات المهام وأشكال الاستجابة SSE مثل تطبيق ADK-Rust. تم إصلاح المعرفات وتفاصيل الطلب حتى يسهل متابعة المحادثة بأكملها.

fulfilment.rsخدمة الوفاء · الصدأ

let fulfilment = LlmAgentBuilder::new("fulfilment")
      .description("Investigates orders and delivery")
      .model(model)
      .instruction(
          "Use the approved order, inventory, and policy tools.            Ask for evidence when the replacement policy requires it."
      )
      .build()?;

  A2aServer::builder()
      .agent(Arc::new(fulfilment))
      .agent_card_name("Fulfilment Agent")
      .streaming(true)
      .build()?
      .serve()
      .await?;

support.rsمنسق الدعم · الصدأ

let fulfilment = RemoteA2aAgent::builder("fulfilment")
      .description("Investigates orders and delivery")
      .agent_url("https://agents.example.com/fulfilment")
      .streaming(true)
      .build()?;

  let support = LlmAgentBuilder::new("support")
      .model(model)
      .instruction("Own the customer conversation.")
      .sub_agent(Arc::new(fulfilment))
      .build()?;

SendStreamingMessage.json1 · أرسل الوظيفة

{
    "jsonrpc": "2.0",
    "id": "replace-1",
    "method": "SendStreamingMessage",
    "params": {
      "message": {
        "messageId": "msg-order-1042",
        "role": "ROLE_USER",
        "parts": [{
          "text": "Investigate damaged order ORD-1042 and prepare a replacement decision."
        }]
      }
    }
  }

text/event-stream2 · متابعة تقدم المهمة

data: {
    "jsonrpc":"2.0", "id":"replace-1",
    "result":{"task":{
      "id":"task-order-1042",
      "contextId":"ctx-order-1042",
      "status":{"state":"TASK_STATE_SUBMITTED"}
    }}
  }

  data: {
    "jsonrpc":"2.0", "id":"replace-1",
    "result":{"statusUpdate":{
      "taskId":"task-order-1042",
      "contextId":"ctx-order-1042",
      "status":{"state":"TASK_STATE_WORKING"}
    }}
  }

input-required.event.json3 · اطلب الأدلة المفقودة

{
    "statusUpdate": {
      "taskId": "task-order-1042",
      "contextId": "ctx-order-1042",
      "status": {
        "state": "TASK_STATE_INPUT_REQUIRED",
        "message": {
          "role": "ROLE_AGENT",
          "parts": [{
            "text": "Please provide a photo showing the damaged item."
          }]
        }
      }
    }
  }

SendMessage.follow-up.json4 · استئناف نفس المهمة

{
    "jsonrpc": "2.0",
    "id": "replace-2",
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "msg-order-1042-photo",
        "contextId": "ctx-order-1042",
        "role": "ROLE_USER",
        "parts": [{
          "text": "Evidence received and approved: damage-photo-8841.jpg"
        }]
      }
    }
  }

final-events.json5 · استلام القطعة الأثرية وإكمالها

{
    "artifactUpdate": {
      "taskId": "task-order-1042",
      "contextId": "ctx-order-1042",
      "artifact": {
        "artifactId": "replacement-decision-1042",
        "name": "Replacement decision",
        "parts": [{
          "text": "Approved. Reserve SKU-RED-42 and dispatch with priority shipping."
        }]
      }
    }
  }

  {
    "statusUpdate": {
      "taskId": "task-order-1042",
      "contextId": "ctx-order-1042",
      "status": { "state": "TASK_STATE_COMPLETED" }
    }
  }

A2A v1 API

كل ما يحتاجه العميل لبدء العمل ومتابعته وإنهائه على وكيل بعيد.

ينفذ ADK-Rust جميع العمليات الـ 11 في A2A v1. بالنسبة لمهمة قصيرة، اتصل بـ SendMessage وانتظر نتيجة المهمة. عندما يستغرق العمل وقتًا أطول، استخدم SendStreamingMessage لتلقي المهمة أولاً، متبوعة بالحالة المباشرة وأحداث المنتجات عبر SSE.

يتيح معرف المهمة الذي تم إرجاعه لعميلك إعادة الاتصال دون إرسال المهمة مرة أخرى. يمكنه جلب أحدث الحالة أو قائمة المهام ذات الصلة أو الاشتراك في مزيد من التحديثات أو طلب الإلغاء. إذا لم يتمكن العميل من إبقاء الاتصال مفتوحًا، فيمكنه تسجيل خطاف ويب مصادق عليه والسماح للوكيل البعيد بتقديم تغييرات لاحقة.

ابدأ العمل

أرسل رسالة واحصل على مهمة كاملة أو بث مباشر.

SendMessageSendStreamingMessage

التفتيش والسيطرة

اقرأ العمل الحالي، أو قم بإدراج المهام المطابقة، أو قم بإلغاء مهمة عندما تسمح حالتها بذلك.

GetTaskListTasksCancelTask

متابعة التقدم

افتح اشتراك SSE للحصول على التحديثات من مهمة موجودة بالفعل.

SubscribeToTask

تلقي التحديثات في وقت لاحق

قم بإنشاء وجهات خطاف الويب التي تمت مصادقتها لمهمة ما وقراءتها وإدراجها وإزالتها.

CreatePushConfigGetPushConfigListPushConfigsDeletePushConfig

اكتشف المزيد

اطلب النسخة الموسعة من ملف تعريف الخدمة المنشور للوكيل.

GetExtendedAgentCard

معالج واحد لاثنين من الارتباطات

يتم إرسال مسارات JSON-RPC وREST إلى نفس RequestHandler، لذلك لا ينجرف سلوك المهمة بين وسائل النقل.

التنفيذ المدعوم من Runner

تصبح رسائل A2A الواردة محتوى ADK-Rust. يقوم Runner بتنفيذ الوكيل المحدد وتحويل أحداثه إلى حالة المهمة والتحف.

إعادة المحاولة الآمنة

يقوم معرف الرسالة المتكرر بإرجاع المهمة الموجودة بدلاً من تشغيل نفس العمل مرتين. يجب أن تستمر عمليات نشر الإنتاج في هذا التعيين عبر عمليات إعادة التشغيل.

البث الذي يبدأ بالسياق

حدث SSE الأول هو المهمة الكاملة. تحمل الأحداث اللاحقة تحديثات الحالة والعناصر، لذلك يعرف العميل دائمًا ما ينتمي إليه الدفق.

يشعر الوكلاء البعيدون بأنهم محليون

يقوم RemoteA2aAgent بتنفيذ سمة الوكيل ADK-Rust. يمكن للمنسق تضمين خدمة شبكة في التسلسل الهرمي للوكيل الخاص به واستقبال أحداث إطار العمل العادية.

الحماية على الحدود

يمكن للتفاوض على الإصدار، والتحقق من صحة الرسالة، ومصادقة حاملها، وتحديد المعدل، واعتراضات التدقيق، ومصادقة خطاف الويب، وفحوصات SSRF حماية الخدمة.

اختر الحدود الصحيحة

الوكيل الفرعي المحلي مقابل وكيل A2A البعيد

يقدم A2A الشبكة والعقد العام والمصادقة ومعالجة الفشل وحالة المهمة عن بعد. وهذه التكاليف تكون ذات قيمة عندما تخلق استقلالاً حقيقياً؛ فهي غير ضرورية عندما يعيش كل وكيل بالفعل في نفس العملية.

الوكيل الفرعي المحلي

وكيل A2A عن بعد

أفضل ملاءمة

وكلاء يملكها تطبيق واحد

الوكلاء منتشرون أو مملوكون بشكل مستقل

الاتصالات

مكالمات الوكيل قيد التشغيل وأحداث محددة الأنواع

HTTP، JSON-RPC أو REST، وSSE

الدولة المشتركة

يمكن استخدام نفس الجلسات والخدمات

يشارك فقط الرسائل والمهام والعناصر المعلنة

حد الفشل

وقت التشغيل والنشر واحد

فشل الشبكة والمهلة وإعادة المحاولة والخدمة عن بعد

إمكانية التشغيل البيني

مكونات ADK-Rust

أي لغة أو إطار عمل متوافق مع A2A

من وكيل Rust إلى خدمة الشبكة

فضح الوكيل، ثم استهلكه كوكيل.

يقوم الخادم المريح بإنشاء تطبيق Axum مع تمكين بطاقة الوكيل والجلسات ومسارات A2A والبث. يكتشف المحول البعيد تلك الخدمة ويحول تحديثات المهام الخاصة بها مرة أخرى إلى أحداث ADK-Rust.

serve.rsفضح وكيل

use adk_server::a2a::convenience::A2aServer;

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

  axum::serve(listener, app).await?;

coordinator.rsنسميها من وكيل آخر

use adk_server::a2a::RemoteA2aAgent;

  let fulfilment = RemoteA2aAgent::builder("fulfilment")
      .description("Investigates orders and delivery")
      .agent_url("https://agents.example.com/fulfilment")
      .build()?;

  let coordinator = LlmAgentBuilder::new("support")
      .model(model)
      .sub_agent(Arc::new(fulfilment))
      .build()?;

للحصول على خدمة v1 التي تم تكوينها بالكامل: استخدام الموثقة RequestHandler::with_runner المسار لاختيار مخزن المهام، ودفع المرسل، وبطاقة الوكيل، وخدمات Runner، ومسار JSON-RPC، وجهاز التوجيه REST، والبرامج الوسيطة للتفاوض على الإصدار بشكل صريح.

قبل الإنتاج

نشر وكلاء A2A

يوفر ADK-Rust أنواع v1، والمعالجات، ودورة الحياة، والعملاء، والتحقق من الصحة، وأوليات التسليم، والتكامل مع Runner. لا يزال جاهزية الإنتاج تعتمد على سياسات التخزين والهوية والشبكة وإمكانية المراقبة والتشغيل المحددة لخدمتك.

نشر بطاقة صادقة

قم بالإعلان فقط عن المهارات، والارتباطات، والبث، والتسليم الفوري، وأنظمة الأمان التي يدعمها النشر بالفعل.

اختر حالة دائمة

يعد InMemoryTaskStore المضمن وخريطة العجز في الذاكرة مفيدًا للتطوير. تحتاج أعمال الإنتاج طويلة الأمد إلى مساحة تخزين تدوم حتى عمليات إعادة تشغيل العملية.

تأمين كلا الاتجاهين

مصادقة المكالمات الواردة وحماية تسليم الدفع للخارج. يدعم مرسل الدفع HTTP بيانات اعتماد الحامل ورموز الإشعارات وإعادة المحاولة ورفض العنوان الخاص.

إلغاء التصميم والمهلات

العمل عن بعد يمكن أن يفوق الطلب. حدد مهلات العميل، وسياسة الإلغاء، وسلوك إعادة المحاولة، وما يحدث عندما تصبح أي من الخدمتين غير متاحة.

ربط نظام الوكيل

كشف وكيلك من خلال واجهة A2A القياسية.

ابدأ ببطاقة وكيل واحدة صادقة ومهمة واحدة مفيدة. أضف البث، والإدخال متعدد المنعطفات، واستمرارية المهمة، والاشتراكات، والدفع المصادق عليه، وعناصر التحكم في الحدود عندما يصبح العمل أطول وتصبح الخدمة أكثر أهمية.

اقرأ دليل A2A فحص الوكيل كاملا