ADK-Rust एजेंट को ACP के माध्यम से उपलब्ध कराएँ

सर्वर मार्ग का उपयोग तब करें जब कोई संपादक या अन्य ACP क्लाइंट आपके ADK-Rust बाइनरी को शुरू करके किसी कोडिंग इंटरफ़ेस के भीतर उसके एजेंट का उपयोग करना चाहता हो। आपकी Rust प्रक्रिया एजेंट, मॉडल, टूल, वर्कफ़्लो, सत्र, मेमोरी और संचालन नीति का स्वामित्व रखती है। क्लाइंट केवल ACP के माध्यम से प्रकाशित क्षमताओं और सत्र जीवनचक्र को देखता है।

सर्वर सुविधा इंस्टॉल करें

[dependencies]
adk-acp = { version = "2.1.0", features = ["server"] }

एजेंट बनाएँ और सर्व करें

use adk_acp::server::{AcpServer, AcpServerConfigBuilder};
use adk_session::InMemorySessionService;
use std::sync::Arc;

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

let handle = AcpServer::run(config).await?;
handle.wait().await?;

सर्वर आधिकारिक SDK Agent बिल्डर और stdio ट्रांसपोर्ट का उपयोग करता है। प्रोटोकॉल ट्रैफ़िक ही stdout पर लिखा जाने वाला एकमात्र डेटा है; ट्रेसिंग और डायग्नोस्टिक्स को stderr का उपयोग करने के लिए कॉन्फ़िगर करें।

रनटाइम मैपिंग

Rendering architecture…

हैंडलर एक पूर्ण cwd को मान्य करता है, सत्र क्षमता आरक्षित करता है, ADK सत्र बनाता या फिर से शुरू करता है, और कॉन्फ़िगर किए गए एजेंट को चलाता है। प्रॉम्प्ट सक्रिय होने के दौरान टाइप किए गए ADK इवेंट को ACP session/update सूचनाओं में अनुवादित किया जाता है।

कार्यान्वित जीवनचक्र

एक समय में केवल एक प्रॉम्प्ट ही किसी सत्र में चल सकता है। अलग-अलग सत्र max_sessions तक समवर्ती रूप से चल सकते हैं।

इवेंट मैपिंग

• मॉडल का टेक्स्ट agent_message_chunk बन जाता है;
• मॉडल की विचार-सामग्री agent_thought_chunk बन जाती है;
• एम्बेडेड-रिसोर्स की सामग्री एक ACP एम्बेडेड-रिसोर्स agent_message_chunk बन जाती है;
• ADK फ़ंक्शन कॉल, अनुमानित टूल kind के साथ ACP टूल-स्टार्ट अपडेट बन जाती हैं;
• फ़ंक्शन प्रतिक्रियाएँ, परिणाम की सामग्री और प्रभावित फ़ाइल स्थानों से समृद्ध टूल-कम्प्लीशन अपडेट बन जाती हैं, जिन्हें मूल टूल कॉल से संबद्ध किया जाता है;
• उपयोग मेटाडेटा वाले इवेंट UsageUpdate सूचनाएँ बन जाते हैं (टोकन गणना, और रिपोर्ट किए जाने पर USD में लागत सहित);
• एजेंट द्वारा घोषित कमांड, सत्र सक्रिय होने पर AvailableCommandsUpdate बन जाते हैं, और रिकॉर्ड किया गया सत्र शीर्षक SessionInfoUpdate बन जाता है;
• प्लान प्रविष्टियाँ Plan अपडेट बन जातीं — यह मैपिंग मौजूद है, लेकिन तब तक निष्क्रिय रहती है जब तक कोई ADK प्लान प्रिमिटिव प्लान प्रविष्टियों को सामने नहीं लाता;
• रद्दीकरण StopReason::Cancelled बन जाता है;
• सामान्य पूर्णता StopReason::EndTurn बन जाती है।

एक साझा सामग्री मॉड्यूल दोनों दिशाओं में ContentBlock ↔ adk_core::Part मैपिंग का स्वामी है। एम्बेडेड-संसाधन प्रॉम्प्ट सामग्री Part::EmbeddedResource से मैप होती है, जिसमें स्रोत URI, वैकल्पिक MIME प्रकार और सामग्री सुरक्षित रहती है; टेक्स्ट संसाधन यथावत सुरक्षित रहते हैं, जबकि बाइनरी संसाधनों को वायर पर base64-एन्कोड किया जाता है और आंतरिक रूप से कच्चे बाइट्स में डिकोड किया जाता है। इमेज और ऑडियो प्रॉम्प्ट सामग्री Part::InlineData से मैप होती है, जिसमें MIME प्रकार, डिकोड किए गए बाइट्स, एनोटेशन और इमेज का वैकल्पिक स्रोत URI सुरक्षित रहता है। ये फ़ील्ड session JSON में बने रहते हैं और session/load द्वारा पुनर्स्थापित किए जाते हैं। चूँकि प्रॉम्प्ट हैंडलर एम्बेडेड-संसाधन, इमेज और ऑडियो सामग्री स्वीकार करता है, सर्वर embedded_context, image और audio प्रॉम्प्ट क्षमताओं की घोषणा करता है। ऐसी सामग्री प्रकार वाला प्रॉम्प्ट, जिसकी सर्वर ने घोषणा नहीं की है, आंशिक रूप से संसाधित किए जाने के बजाय वर्णनात्मक त्रुटि के साथ अस्वीकार कर दिया जाता है।

लोड और इतिहास पुनरावृत्ति

session/load किसी क्लाइंट के पुनः कनेक्ट होने पर स्थायी session के दृश्यमान इतिहास को पुनर्स्थापित करता है। हैंडलर session को उसी प्रकार पुनः सक्रिय करता है जैसे session/resume करता है — यह सत्यापित करते हुए कि कॉलर ने मूल cwd प्रदान किया है और किसी अज्ञात पहचानकर्ता के लिए session-not-found त्रुटि लौटाते हुए — और फिर पुनरावृत्ति चरण निष्पादित करता है। यह session service के माध्यम से स्थायी events को पढ़ता है और प्रत्येक संग्रहीत user, agent, thought और tool event को उसके संबंधित session/update notification में, मूल कालानुक्रमिक क्रम में, मैप करता है; यह प्रक्रिया load request पूरी होने से पहले पूरी हो जाती है। सर्वर load_session क्षमता की घोषणा करता है, ताकि client जान सके कि वह पुनः कनेक्ट होकर conversation view को पुनर्निर्मित कर सकता है।

session modes, configuration options, और fork

एक एजेंट AcpServerConfigBuilder::session_controls के माध्यम से SessionControls प्रदाता देकर इंटरैक्टिव सत्र नियंत्रणों का विकल्प चुनता है। प्रदाता उपलब्ध मोड (एक SessionModeState), कॉन्फ़िगरेशन विकल्प (चयन और टॉगल), और ACP स्लैश-कमांड घोषित करता है। सर्वर ठीक वही घोषित करता है जो प्रदाता घोषित करता है — बिना प्रदाता वाला एजेंट कोई मोड और कोई विकल्प घोषित नहीं करता — और उन्हें session/new, session/load, session/resume, और session/fork प्रतिक्रियाओं में उपलब्ध कराता है।

session/set_mode अनुरोधित मोड आईडी को घोषित सेट के विरुद्ध सत्यापित करता है, उसे रिकॉर्ड करता है, और CurrentModeUpdate उत्सर्जित करता है; अज्ञात आईडी अस्वीकार कर दी जाती है और वर्तमान मोड अपरिवर्तित रहता है। session/set_config_option मान को विकल्प के घोषित चयन के विरुद्ध सत्यापित करता है, उसे रिकॉर्ड करता है, और ConfigOptionUpdate उत्सर्जित करता है; अज्ञात विकल्प या अमान्य मान अस्वीकार कर दिया जाता है। दोनों चयन ADK सत्र स्थिति में acp:mode और acp:config:<id> के अंतर्गत स्थायी रहते हैं, इसलिए वे लोड, फिर से शुरू करने और फ़ोर्क करने के बाद भी बने रहते हैं।

session/fork एक स्थायी सत्र की शाखा बनाता है: यह स्रोत सत्र को पढ़ता है, एक नई सत्र आईडी बनाता है, संग्रहीत इवेंट और प्रासंगिक स्थिति (cwd, अतिरिक्त डायरेक्टरी, मोड और कॉन्फ़िगरेशन) को उसमें कॉपी करता है, और नई आईडी लौटाता है। स्रोत सत्र का स्थायी इतिहास बाइट-दर-बाइट अपरिवर्तित रहता है। अज्ञात सत्र पहचानकर्ता के लिए फ़ोर्क करने पर सत्र-नहीं-मिला त्रुटि लौटाई जाती है। हैंडलर के पंजीकृत होने के कारण सर्वर fork सत्र क्षमता घोषित करता है।

सत्र सक्रिय होने पर सर्वर प्रदाता द्वारा घोषित किसी भी कमांड के लिए AvailableCommandsUpdate भी उत्सर्जित करता है (और जब वह कोई कमांड घोषित नहीं करता तो कुछ भी नहीं), तथा acp:title के अंतर्गत रिकॉर्ड किए गए सत्र शीर्षक को लेकर SessionInfoUpdate उत्सर्जित करता है (जिसे set_session_title के माध्यम से सेट किया जाता है)। Plan अपडेट मैपिंग मौजूद है, लेकिन तब तक निष्क्रिय रहती है जब तक ADK प्लान प्रिमिटिव प्लान प्रविष्टियों को उपलब्ध नहीं कराता।

क्लाइंट-प्रदत्त MCP सर्वर

क्लाइंट MCP सर्वरों को session/new या session/resume में शामिल कर सकता है। सर्वर किसी प्रक्रिया को शुरू करने से पहले नामों, कमांड, आर्ग्युमेंट और पर्यावरण प्रविष्टियों का सत्यापन करता है। इसके बाद वह:

1. प्रत्येक चाइल्ड को सत्र कार्यक्षेत्र में शुरू करता है;
2. सीमित स्टार्टअप हैंडशेक लागू करता है;
3. कनेक्शन को ADK McpToolset के रूप में रैप करता है;
4. उस Runner invocation में टूलसेट इंजेक्ट करता है;
5. बंद होने, हटाए जाने, स्टार्टअप विफल होने या सर्वर शटडाउन पर MCP सेवाओं को रद्द करता है।

Invocation-स्कोप वाले टूलसेट वर्तमान में LlmAgent और CodeActAgent द्वारा रिज़ॉल्व किए जाते हैं। वैकल्पिक HTTP और SSE MCP ट्रांसपोर्ट सर्वर द्वारा विज्ञापित नहीं किए जाते।

स्थायित्व संबंधी निर्णय

InMemorySessionService स्थानीय एडिटर प्रक्रिया और परीक्षणों के लिए उपयुक्त है। जब सत्रों को प्रक्रिया के पुनः आरंभ होने के बाद भी जारी रहना हो, तो टिकाऊ सेवा का उपयोग करें। Resume यह सत्यापित करता है कि कॉलर मूल cwd प्रदान करता है; किसी सत्र को चुपचाप किसी अलग प्रोजेक्ट से दोबारा संलग्न नहीं किया जा सकता।

टूल अनुमोदन सीमा

सर्वर ADK टूल पुष्टिकरणों को मूल ACP अनुमति अनुरोधों से जोड़ता है। जब कॉन्फ़िगर किया गया एजेंट किसी प्रॉम्प्ट टर्न के दौरान ToolConfirmationRequest पर रुकता है — जिसे event.actions.tool_confirmation पर तब प्रदर्शित किया जाता है जब एजेंट किसी टूल कॉल के लिए मानव अनुमोदन की प्रतीक्षा करता है — सर्वर टूल और उसके आर्ग्युमेंट का वर्णन करने वाला session/request_permission अनुरोध भेजता है, क्लाइंट के परिणाम की प्रतीक्षा करता है, और मैप किए गए निर्णय के साथ निष्पादन फिर से शुरू करता है। अनुमोदन allow से मैप होता है, जबकि अस्वीकृति या रद्दीकरण दोनों deny से मैप होते हैं, इसलिए रद्द किया गया अनुरोध कभी भी टूल को निष्पादित नहीं करता। प्रत्येक परिणाम अपने function-call identifier के माध्यम से सटीक कॉल से संबद्ध किया जाता है और RunConfig::tool_confirmation_decisions के माध्यम से रनर को वापस भेजा जाता है।

नेस्टेड session/request_permission उस कार्य से जारी किया जाता है जो पहले से ही बाहरी session/prompt को संभाल रहा है और ConnectionTo::spawn के माध्यम से शुरू किया गया है, इसलिए यह कनेक्शन के dispatch loop को अवरुद्ध नहीं करता और बाहरी prompt response फिर भी पूरा हो जाता है। पहले यह चिंता थी कि आधिकारिक Rust SDK, नेस्टेड bidirectional request के बाद बाहरी prompt response खो देता है, लेकिन इस pause/resume प्रवाह में ऐसा दोबारा नहीं होता; इसे इन-मेमोरी interoperability परीक्षणों द्वारा कवर किया गया है।

Server-owned tool authorization, read-only tools, RBAC, guardrails और workflow interrupts उन स्थितियों में उपलब्ध रहते हैं जहाँ approval पूरी तरह ADK-Rust प्रक्रिया के भीतर होना आवश्यक है। बाहरी ACP agents के लिए client-side permission path भी पूरी तरह कार्यान्वित है।

सुरक्षित रूप से परिनियोजित करें

• बाइनरी को इच्छित project workspace के साथ शुरू करें।
• cwd और अतिरिक्त roots को context मानें, OS isolation नहीं।
• अविश्वसनीय prompts और commands के लिए adk-sandbox, container या किसी अन्य process boundary का उपयोग करें।
• model और MCP credentials को client secret store या process environment में रखें।
• protocol stdout में कभी भी banners, debug objects या logs न लिखें।
• जब resume को process restart के बाद भी बनाए रखना हो, तो durable SessionService का उपयोग करें।
• एक सीमित session limit निर्धारित करें और निष्क्रिय sessions बंद करें।

चलाने योग्य acp_server crate में Gemini-backed agent, workspace-bounded read tools, stderr tracing और editor process configuration शामिल हैं।

अगला

• ACP client या host बनाएँ
• परीक्षण और support matrix