التطبيق الذي يتفاعل معه الأشخاص
عادةً ما يكون محررًا أو تطبيق سطح مكتب أو CLI أو منسق ADK-Rust. فهو يبدأ تشغيل وكيل الترميز، ويفتح جلسة المشروع، ويعرض التقدم، ويقرر كيفية وصول أسئلة الإذن إلى المستخدم.
يوفر ACP واجهة تشفير ووكيل تشفير طريقة مشتركة لفتح مشروع وتبادل المطالبات ودفق التقدم وطلب الموافقة وإلغاء العمل ومواصلة نفس الجلسة. ينفذ ADK-Rust كلا الجانبين من تلك العلاقة.
العمارة ADK-Rust ACP
البرنامج ذو الواجهة هو عميل ACP. البرنامج الذي يقوم بأعمال الترميز هو وكيل ACP. يمكن لـ ADK-Rust الجلوس على جانبي تلك العلاقة.
01 · ADK-Rust هو العميل/المضيف ACP
يقرر أن مهمة المستودع تحتاج إلى متخصص في الترميز.
يبدأ العملية ويختار مساحة العمل ويحتفظ بالسياق ويطبق سياسة الأذونات.
يفحص التعليمات البرمجية، ويقترح التعديلات، ويستدعي الأدوات، ويتابع تقدمها.
The shared ACP v1 contract
Both directions use the same message vocabulary.
initializesession/newsession/promptsession/updaterequest_permissioncancelclose · list · resume · delete02 · ADK-Rust هو وكيل/خادم ACP
يمتلك واجهة مستخدم المحادثة ويبدأ الثنائي ADK-Rust.
يتفاوض بشأن القدرات، ويتحقق من صحة الجلسات، ويبث التحديثات، ويتعامل مع الإلغاء.
يستخدم النماذج وأدوات Rust وسير العمل والجلسات والذاكرة والمصنوعات اليدوية لإكمال الدور.
يتم تعيين جلسة ACP واحدة إلى جلسة ADK-Rust واحدة مستمرة.
يختار العميل خيارًا عرضه الوكيل بالفعل.
النص والأفكار وبدء تشغيل الأداة ودفق إكمال الأداة كـ session/update.
يستخدم ACP v1 المستقر عملية فرعية محلية وJSON-RPC عبر stdio.
ابدأ بالعلاقة
يمكن لوكيل الترميز التفكير في المستودع واستخدام الأدوات، لكن لا يزال الأشخاص بحاجة إلى واجهة يمكنهم من خلالها وصف المهمة، ورؤية ما يفعله الوكيل، والإجابة على الأسئلة، والموافقة على الإجراءات الحساسة، وإيقاف الدور. بدون معيار، يحتاج كل محرر وكل وكيل ترميز إلى تكامل مخصص لتلك الأساسيات.
يحدد ACP تلك المحادثة المفقودة. يمتلك العميل الواجهة وبيئة العمل التي يختار توفيرها. الوكيل يمتلك ذكاء الترميز. وهم يوافقون على الجلسات والمطالبات والمحتوى والتحديثات المباشرة واستدعاءات الأدوات واختيارات الأذونات والإلغاء والإكمال دون الحاجة إلى مشاركة رمز التنفيذ.
يدعم ADK-Rust كلا الاتجاهين العمليين. يمكن لوكيل ADK تفويض العمل إلى وكيل ترميز ACP خارجي كأداة. باستخدام ميزة الخادم، يمكن للمحرر بدء ثنائي ADK-Rust واستخدام Runner والنماذج والأدوات والجلسات والذاكرة وسير العمل من خلال نفس عقد ACP v1.
عادةً ما يكون محررًا أو تطبيق سطح مكتب أو CLI أو منسق ADK-Rust. فهو يبدأ تشغيل وكيل الترميز، ويفتح جلسة المشروع، ويعرض التقدم، ويقرر كيفية وصول أسئلة الإذن إلى المستخدم.
يتلقى المطالبات والأسباب المتعلقة بالمستودع ويبلغ عن نشاط الأداة ويسأل قبل الإجراءات الحساسة ويعيد سبب التوقف عند انتهاء الدور.
تحتوي الجلسة على معرف ودليل عمل مطلق وجذور مساحة عمل اختيارية والعديد من المطالبات والتحديثات المتدفقة ودورة حياة إغلاق أو استئناف واضحة.
يصف الوكيل استدعاء الأداة الدقيق ويقدم الخيارات. يقوم العميل بإرجاع أحد هذه الاختيارات، وبالتالي فإن التطبيق - وليس الوكيل - هو الذي يتحكم في استمرار الإجراء.
One ACP turn
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.
Editor or ADK-Rust
Coding process or ADK-Rust
initializeprotocolVersion: 1
capabilitiesWhat this agent really supports
session/newAbsolute cwd + workspace roots
session/promptTyped content blocks
session/updateText · thought · tool call
session/request_permissionChoose from offered options
permission responseAllow once · always · reject
PromptResponseend_turn · cancelled
session/cancel into the Runner cancellation token and returns a typed cancelled stop reason.الاتجاه الأول · ADK-Rust هو العميل
تظهر عملية ACP الخارجية داخل ADK-Rust كأداة مسماة. يمكن لمنسقك أن يقرر متى يستخدمه، واختيار دليل المشروع، والحفاظ على السياق عندما يمتد العمل لعدة دورات، وتدفق التقدم إلى الواجهة الخاصة بك، والحفاظ على سياسة الموافقة خارج وكيل الترميز.
AcpAgentToolالأفضل عندما يقوم وكيل ADK أحيانًا بتفويض مهمة مستودع قائمة بذاتها. يبدأ كل استدعاء عملية ACP ويعيد النص الخاص به كمخرج عادي للأداة.
AcpToolsetقم بإعطاء منسق اسمه وكلاء المراجعة أو الاختبار أو الترحيل أو التوثيق. تساعد أوصاف الأدوات الخاصة بهم النموذج في توجيه كل مهمة إلى العملية الصحيحة.
AcpSessionأبقِ العملية وجلسة ACP حية عبر المطالبات. يتذكر الوكيل ما قام بفحصه بالفعل، ويمكن لمقبض الإلغاء أن يوقف الانعطاف على متن الطائرة.
stream_promptاحصل على أجزاء النص والفكر واستدعاء الأدوات والإذن والإكمال والخطأ فور حدوثها بدلاً من انتظار سلسلة واحدة مدمجة.
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()?;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 التي يوفرها العميل إلى إنشاء الجلسة. لا يتم تمكين أي شيء بشكل افتراضي. يمكن لكل من أداة التوثيق للقراءة فقط، ومحرر سطح المكتب الذي يحتوي على مخازن مؤقتة غير محفوظة، وعامل بناء معزول نشر مجموعة قدرات مختلفة ودقيقة.
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.
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.
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 بإرجاع معرف الخيار المعتم الدقيق الذي يوفره الوكيل؛ لا يخترع أبدًا قيمة موافقة.
يحمل الطلب معرف الجلسة، ومعرف استدعاء الأداة، والعنوان، ونوع الأداة، والإدخال الأولي، وكل خيار استجابة يدعمه الوكيل.
قم بالرفض بشكل افتراضي، أو استخدم قاعدة متزامنة، أو انتظر حوارًا بشريًا أو خدمة سياسة عن بعد من خلال async_custom.
تتم مطابقة اختيارات السماح والرفض بالمعنى ACP، ثم يتم إرجاع معرف الخيار غير الشفاف الأصلي. تصبح الهوية الملفقة بمثابة إلغاء.
يتلقى وكيل الترميز القرار في نفس الجلسة ويمكنه مواصلة استدعاء الأداة أو اختيار مسار آخر أو إنهاء الدور.
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
يبدأ المحرر ملف Rust الثنائي كعملية فرعية ACP. يمتلك SDK الرسمي إطار JSON-RPC ومعرفات الطلب وفك التشفير المكتوب وstdio. يقوم معالج الجلسة بتعيين جلسة ACP واحدة إلى جلسة ADK-Rust واحدة، ثم يقوم Runner ببث أحداث النموذج والأداة مرة أخرى كإشعارات session/update المباشرة.
يكون هذا الاتجاه مفيدًا عندما يكون لدى الوكيل الخاص بك تعليمات خاصة بالمجال، أو أدوات Rust، أو وكلاء سير العمل، أو الذاكرة، أو الخدمات الداخلية التي يجب أن تكون متاحة من واجهة الترميز. لا يحتاج المحرر إلى فهم تلك الأمور الداخلية؛ فهو يرى القدرات ودورة الحياة التي ينشرها الثنائي بأمانة.
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?;{
"name": "repository-guide",
"command": "/absolute/path/to/repository-guide",
"args": [],
"env": {
"MODEL_API_KEY": "from-the-editor-secret-store"
}
}{
"jsonrpc": "2.0",
"id": 3,
"method": "session/prompt",
"params": {
"sessionId": "session-7f2a",
"prompt": [{
"type": "text",
"text": "Explain error handling in src/main.rs"
}]
}
}{"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 القابل للتشغيل البيني عن الميزات التي لا تزال بحاجة إلى التنفيذ، لذلك لا يكتشف المحرر أو المنتج القدرة المفقودة بعد بدء عمل التكامل.
ACP protocol v1 · official Rust SDK 1.2 · JSON-RPC over local stdio
ImplementedInitialize, new session, prompt, live updates, tool permissions, one-shot, persistent, streaming
ImplementedCloneable handle sends session/cancel while another task awaits the prompt
ImplementedInitialize, new, prompt, update, cancel, close, list, resume, delete
ImplementedText and resource links; unsupported media types are rejected and not advertised
Implemented scopeOpt-in host traits advertise only the file and terminal operations the application implements
Implemented APITyped session configuration, required stdio server support, per-session ADK toolsets, bounded startup and cleanup
Implemented · stdioThe 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 limitationHTTP or WebSocket ACP between machines
Protocol work is evolving; stdio onlyبوابة التشغيل البيني
يتصل عميل SDK الرسمي بوكيل ADK-Rust SDK من خلال النقل في الذاكرة ويكمل التهيئة ← جديد ← موجه ← تحديث ← إغلاق ← قائمة ← استئناف ← إغلاق ← حذف. تغطي اختبارات الإلغاء كلا من جلسة/إلغاء ACP وإلغاء طلب JSON-RPC، ثم تثبت أن الجلسة يمكنها قبول مطالبة أخرى بعد التنظيف. تغطي اختبارات الأذونات قوائم الرفض أولاً، والمعرفات غير الشفافة، والاختيارات الملفقة، والقرار البشري المنتظر. تبدأ البوابة المباشرة المنفصلة إنشاء طفل حقيقي لـ MCP من stdio وتكتشف كتالوج الأدوات الخاص به من خلال نفس McpToolset الذي تستخدمه جلسات ACP.
اختر الحدود
ابدأ بالسؤال عما يجلس على الجانب الآخر. يحتاج وكيل الترميز إلى جلسة مشروع ومضيف تفاعلي. يحتاج وكيل الأعمال عن بعد إلى عقد مهمة على الشبكة. تحتاج الأداة أو خدمة البيانات إلى عقد قدرة قابل للاستدعاء.
استخدم ACP بين واجهة الترميز والوكيل الذي يعمل داخل جلسة المشروع.
Explore ACP A2Aاستخدم A2A لاكتشاف وكيل بعيد وإرسال العمل ومتابعة حالة المهمة وتلقي العناصر عبر الشبكة.
Explore A2A MCPاستخدم MCP لتزويد الوكيل بأدوات ومطالبات وموارد قابلة للاستدعاء دون تحويل هذا الخادم إلى الوكيل نفسه.
Explore MCPقم بالبناء مع الدور الذي تحتاجه
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.