بروتوكول عميل الوكيل · بروتوكول مستقر v1

قم بإحضار وكلاء الترميز إلى منتجك - أو أحضرهم وكيلك في المحرر.

يوفر ACP واجهة تشفير ووكيل تشفير طريقة مشتركة لفتح مشروع وتبادل المطالبات ودفق التقدم وطلب الموافقة وإلغاء العمل ومواصلة نفس الجلسة. ينفذ ADK-Rust كلا الجانبين من تلك العلاقة.

تنسيق رسائل SDK الرسميأدوار العميل + الوكيلجلسات مستمرةالتحديثات المكتوبة الحيةموافقة بشرية غير متزامنةالإلغاءاستمرارية دورة الحياة

العمارة ADK-Rust ACP

بروتوكول واحد، اتجاهان مفيدان.

البرنامج ذو الواجهة هو عميل ACP. البرنامج الذي يقوم بأعمال الترميز هو وكيل ACP. يمكن لـ ADK-Rust الجلوس على جانبي تلك العلاقة.

01 · ADK-Rust هو العميل/المضيف ACP

يستخدم ADK-Rust وكيل ترميز خارجي

اختر هذا الاتجاه

منسق أدك

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

استدعاء الأداة

AcpAgentTool · AcpSession

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

ACP v1 · stdio

وكيل ACP الخارجي

يفحص التعليمات البرمجية، ويقترح التعديلات، ويستدعي الأدوات، ويتابع تقدمها.

The shared ACP v1 contract

Both directions use the same message vocabulary.

initializesession/newsession/promptsession/updaterequest_permissioncancelclose · list · resume · delete

02 · ADK-Rust هو وكيل/خادم ACP

يستخدم المحرر وكيل ADK-Rust

اختر هذا الاتجاه

محرر أو عميل ACP

يمتلك واجهة مستخدم المحادثة ويبدأ الثنائي ADK-Rust.

ACP v1 · stdio

معالج الجلسة الرسمي SDK +

يتفاوض بشأن القدرات، ويتحقق من صحة الجلسات، ويبث التحديثات، ويتعامل مع الإلغاء.

استدعاء مكتوب

Runner + وكيل ADK

يستخدم النماذج وأدوات Rust وسير العمل والجلسات والذاكرة والمصنوعات اليدوية لإكمال الدور.

خدمة الجلسة

يتم تعيين جلسة ACP واحدة إلى جلسة ADK-Rust واحدة مستمرة.

حد الإذن

يختار العميل خيارًا عرضه الوكيل بالفعل.

التحديثات المكتوبة

النص والأفكار وبدء تشغيل الأداة ودفق إكمال الأداة كـ session/update.

حدود العملية

يستخدم ACP v1 المستقر عملية فرعية محلية وJSON-RPC عبر stdio.

لا يقوم ACP بدمج المحرر وعامل الترميز في تطبيق واحد. فهو يمنحهم عقد جلسة مشتركة بينما يحتفظ كل جانب بالواجهة الخاصة به ووقت التشغيل والأدوات ومسؤوليات الأمان الخاصة به.

ابدأ بالعلاقة

ما هي المشكلة التي يحلها ACP؟

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

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

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

العميل / المضيف

التطبيق الذي يتفاعل معه الأشخاص

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

وكيل ACP

العملية التي تؤدي أعمال الترميز

يتلقى المطالبات والأسباب المتعلقة بالمستودع ويبلغ عن نشاط الأداة ويسأل قبل الإجراءات الحساسة ويعيد سبب التوقف عند انتهاء الدور.

جلسة

محادثة العمل المشتركة

تحتوي الجلسة على معرف ودليل عمل مطلق وجذور مساحة عمل اختيارية والعديد من المطالبات والتحديثات المتدفقة ودورة حياة إغلاق أو استئناف واضحة.

إذن

القرار في نقطة العمل

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

One ACP turn

The interface stays responsive while the agent works.

Read from top to bottom. Initialization establishes the contract once. A session then carries several prompts, live updates, approval questions, cancellation, and a final stop reason.

Client / host

Editor or ADK-Rust

ACP agent

Coding process or ADK-Rust

initialize

protocolVersion: 1

capabilities

What this agent really supports

session/new

Absolute cwd + workspace roots

session/prompt

Typed content blocks

session/update

Text · thought · tool call

session/request_permission

Choose from offered options

permission response

Allow once · always · reject

PromptResponse

end_turn · cancelled

Cancellation is part of the conversation. ADK-Rust forwards session/cancel into the Runner cancellation token and returns a typed cancelled stop reason.

الاتجاه الأول · ADK-Rust هو العميل

اسمح لوكيل ADK بتفويض المستودع للعمل إلى وكيل الترميز.

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

AcpAgentTool

مهمة واحدة، عملية جديدة

الأفضل عندما يقوم وكيل ADK أحيانًا بتفويض مهمة مستودع قائمة بذاتها. يبدأ كل استدعاء عملية ACP ويعيد النص الخاص به كمخرج عادي للأداة.

AcpToolset

العديد من المتخصصين في الترميز

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

AcpSession

محادثة واحدة مستمرة

أبقِ العملية وجلسة ACP حية عبر المطالبات. يتذكر الوكيل ما قام بفحصه بالفعل، ويمكن لمقبض الإلغاء أن يوقف الانعطاف على متن الطائرة.

stream_prompt

واجهة المستخدم الحية للمنتج

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

orchestrator.rsتفويض لمرة واحدة
use adk_acp::{AcpAgentTool, PermissionPolicy};

  let coder = AcpAgentTool::new("my-coding-agent --acp")
      .name("repository_coder")
      .description("Inspect and improve this Rust project")
      .working_dir("/absolute/path/to/project")
      .permission_policy(PermissionPolicy::DenyAll);

  let coordinator = LlmAgentBuilder::new("coordinator")
      .model(model)
      .tool(Arc::new(coder))
      .build()?;
session.rsمستمر + قابل للإلغاء
let mut session = AcpSession::start(
      AcpAgentConfig::new("my-coding-agent --acp")
          .working_dir("/absolute/path/to/project"),
      Arc::new(permission_policy),
  ).await?;

  let cancel = session.cancellation_handle()?;
  tokio::spawn(async move {
      shutdown.cancelled().await;
      cancel.cancel().await
  });

  let result = session
      .prompt("Trace the failing test and propose a fix")
      .await?;

يمكن للعميل توفير بيئة العمل

اختر ما يمكن أن يصل إليه وكيل الترميز.

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

يعرض ADK-Rust الآن الملفات المكتوبة وواجهات المضيف الطرفية ويمرر خوادم MCP التي يوفرها العميل إلى إنشاء الجلسة. لا يتم تمكين أي شيء بشكل افتراضي. يمكن لكل من أداة التوثيق للقراءة فقط، ومحرر سطح المكتب الذي يحتوي على مخازن مؤقتة غير محفوظة، وعامل بناء معزول نشر مجموعة قدرات مختلفة ودقيقة.

AcpFileSystem

Files from the real workspace

Your editor or application decides how reads and writes work. It can return an unsaved buffer, enforce approved roots, reject a symlink escape, or make the session read-only.

AcpTerminal

Managed command execution

The coding agent can start a command, collect output, wait, stop it, and release it through the client. Terminal support stays disabled until the host implements the complete lifecycle.

MCP over stdio

Tools supplied for this session

Attach an MCP server when the ACP session opens. ADK-Rust starts it inside the selected project, exposes its tools only to that session, and cancels it when the session closes.

لماذا يظهر MCP في إعداد جلسة ACP

يمكن للعميل إعارة خادم الأدوات لجلسة برمجة واحدة.

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

الموافقة تعود للمضيف

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

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

بالنسبة لسير عمل محلي موثوق به، يمكن للقاعدة الموافقة على العمليات المعروفة. بالنسبة للمنتج التفاعلي، يمكن لـ PermissionPolicy::async_custom انتظار مربع حوار سطح المكتب أو شاشة موافقة الويب أو خدمة سياسة المؤسسة. تقوم ADK-Rust بإرجاع معرف الخيار المعتم الدقيق الذي يوفره الوكيل؛ لا يخترع أبدًا قيمة موافقة.

01

يصف الوكيل العملية

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

02

تطبيقك يطبق السياسة

قم بالرفض بشكل افتراضي، أو استخدم قاعدة متزامنة، أو انتظر حوارًا بشريًا أو خدمة سياسة عن بعد من خلال async_custom.

03

يختار ADK-Rust خيارًا حقيقيًا

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

04

يستمر الوكيل أو يتوقف

يتلقى وكيل الترميز القرار في نفس الجلسة ويمكنه مواصلة استدعاء الأداة أو اختيار مسار آخر أو إنهاء الدور.

permissions.rsموافقة بشرية غير متزامنة
let policy = PermissionPolicy::async_custom(|request| async move {
      let choice = approval_ui.ask(ApprovalPrompt {
          title: request.title,
          kind: request.kind,
          input: request.raw_input,
          options: request.options,
      }).await;

      match choice {
          Approval::Once => PermissionDecision::AllowOnce,
          Approval::Always => PermissionDecision::AllowAlways,
          Approval::Reject => PermissionDecision::Deny,
      }
  });

دليل المشروع هو السياق، وليس رمل.

يخبر ACP كلا الجانبين بالمشروع والجذور الإضافية التي تنتمي إلى الجلسة. ولا يقوم بإنشاء حدود أمان لنظام التشغيل. إذا كان من الضروري عزل عملية الترميز عن بقية الجهاز، فقم بتشغيلها adk-sandboxأو حاوية أو سياسة عملية أخرى.

Keep credentials in the process environment or the client's secret store. Protocol stdout must contain only ACP JSON-RPC messages.

الاتجاه الثاني · ADK-Rust هو وكيل ACP

كشف وقت تشغيل ADK-Rust الكامل للمحرر.

يبدأ المحرر ملف Rust الثنائي كعملية فرعية ACP. يمتلك SDK الرسمي إطار JSON-RPC ومعرفات الطلب وفك التشفير المكتوب وstdio. يقوم معالج الجلسة بتعيين جلسة ACP واحدة إلى جلسة ADK-Rust واحدة، ثم يقوم Runner ببث أحداث النموذج والأداة مرة أخرى كإشعارات session/update المباشرة.

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

main.rsفضح الوكيل
use adk_acp::server::{
      AcpServer, AcpServerConfigBuilder
  };

  let config = AcpServerConfigBuilder::new()
      .agent(Arc::new(repository_agent))
      .session_service(Arc::new(session_service))
      .agent_name("repository-guide")
      .agent_description("Explains and improves this workspace")
      .max_sessions(16)
      .build()?;

  let server = AcpServer::run(config).await?;
  server.wait().await?;
acp-agent.jsonتكوين عملية المحرر
{
    "name": "repository-guide",
    "command": "/absolute/path/to/repository-guide",
    "args": [],
    "env": {
      "MODEL_API_KEY": "from-the-editor-secret-store"
    }
  }
session-prompt.jsonطلب
{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "session/prompt",
    "params": {
      "sessionId": "session-7f2a",
      "prompt": [{
        "type": "text",
        "text": "Explain error handling in src/main.rs"
      }]
    }
  }
stdout.jsonlتحديث مباشر + الرد النهائي
{"jsonrpc":"2.0","method":"session/update","params":{
    "sessionId":"session-7f2a",
    "update":{"sessionUpdate":"agent_message_chunk","content":{
      "type":"text","text":"The entry point uses..."
    }}
  }}
  {"jsonrpc":"2.0","id":3,"result":{
    "stopReason":"end_turn"
  }}

النطاق الذي تم التحقق منه

تعرف بالضبط على ما هو جاهز قبل تصميم التكامل.

يستخدم ADK-Rust الآن صندوق agent-client-protocol الرسمي لكلا الدورين. يفصل الجدول سطح الإصدار 1 القابل للتشغيل البيني عن الميزات التي لا تزال بحاجة إلى التنفيذ، لذلك لا يكتشف المحرر أو المنتج القدرة المفقودة بعد بدء عمل التكامل.

Protocol and transport

ACP protocol v1 · official Rust SDK 1.2 · JSON-RPC over local stdio

Implemented

ADK-Rust as client

Initialize, new session, prompt, live updates, tool permissions, one-shot, persistent, streaming

Implemented

Client cancellation

Cloneable handle sends session/cancel while another task awaits the prompt

Implemented

ADK-Rust as agent

Initialize, new, prompt, update, cancel, close, list, resume, delete

Implemented

Prompt content

Text and resource links; unsupported media types are rejected and not advertised

Implemented scope

Client filesystem / terminal callbacks

Opt-in host traits advertise only the file and terminal operations the application implements

Implemented API

Client-supplied MCP servers

Typed session configuration, required stdio server support, per-session ADK toolsets, bounded startup and cleanup

Implemented · stdio

ADK tool approval → ACP

The runtime can await an exact-call decision; the server bridge is held back because the official SDK currently loses the outer prompt response in the nested-request test

SDK limitation

Remote transport

HTTP or WebSocket ACP between machines

Protocol work is evolving; stdio only

بوابة التشغيل البيني

تم اختباره كمحادثة، وليس كما تم قطع الاتصال JSON.

يتصل عميل SDK الرسمي بوكيل ADK-Rust SDK من خلال النقل في الذاكرة ويكمل التهيئة ← جديد ← موجه ← تحديث ← إغلاق ← قائمة ← استئناف ← إغلاق ← حذف. تغطي اختبارات الإلغاء كلا من جلسة/إلغاء ACP وإلغاء طلب JSON-RPC، ثم تثبت أن الجلسة يمكنها قبول مطالبة أخرى بعد التنظيف. تغطي اختبارات الأذونات قوائم الرفض أولاً، والمعرفات غير الشفافة، والاختيارات الملفقة، والقرار البشري المنتظر. تبدأ البوابة المباشرة المنفصلة إنشاء طفل حقيقي لـ MCP من stdio وتكتشف كتالوج الأدوات الخاص به من خلال نفس McpToolset الذي تستخدمه جلسات ACP.

اختر الحدود

تعمل ACP وA2A وMCP على حل مشكلات التكامل المختلفة.

ابدأ بالسؤال عما يجلس على الجانب الآخر. يحتاج وكيل الترميز إلى جلسة مشروع ومضيف تفاعلي. يحتاج وكيل الأعمال عن بعد إلى عقد مهمة على الشبكة. تحتاج الأداة أو خدمة البيانات إلى عقد قدرة قابل للاستدعاء.

قم بالبناء مع الدور الذي تحتاجه

أضف متخصصًا في البرمجة — أو اجعل وكيل ADK الخاص بك متاحًا حيث يعمل المطورون بالفعل.

Start with stdio, one absolute workspace, and DenyAll. Add a custom approval experience, persistent sessions, and stronger process isolation as the product's trust boundary becomes clear.