एजेंट क्लाइंट प्रोटोकॉल आर्किटेक्चर

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

दो भूमिकाएँ

ADK-Rust किसी भी भूमिका में हो सकता है। ये दो परिनियोजन दिशाएँ हैं, दो अलग प्रोटोकॉल नहीं।

Rendering architecture…

जब ADK-Rust किसी अन्य कोडिंग एजेंट को consume करता है, तो बाईं ओर ADK-Rust होती है और दाईं ओर बाहरी प्रक्रिया होती है। जब कोई editor एक ADK-Rust एजेंट को consume करता है, तो editor बाईं ओर का स्वामी होता है और AcpServer दाईं ओर का स्वामी होता है।

एक ACP turn

Rendering architecture…

कनेक्शन bidirectional है। prompt चल रहा हो तब client को पढ़ना जारी रखना चाहिए, क्योंकि अंतिम prompt response से पहले agent notifications या permission requests भेज सकता है।

Session identity और state

एक ACP session एक ही project के बारे में चल रही बातचीत की पहचान करता है। इसमें एक absolute cwd, वैकल्पिक अतिरिक्त directories, multiple prompts, streamed updates, और एक lifecycle शामिल होता है। ADK-Rust server में, एक ACP session एक ADK-Rust session से map होता है ताकि model history और session state उसी बातचीत से जुड़े रहें।

एक active connection को बंद करना persisted history को delete करने से अलग है:

• session/close active session और उसके processes को release करता है;
• session/resume persisted ADK session state से attach करता है;
• session/load एक persisted session को reactivate करता है और उसकी stored conversation को client को ordered session/update notifications के रूप में replay करता है, इससे पहले कि request complete हो;
• session/fork एक persisted session को एक नए session id में branch करता है, जिसकी stored history source की copy होती है, और source को अपरिवर्तित छोड़ देता है;
• session/delete persisted session को remove करता है;
• session/list configured SessionService के माध्यम से visible sessions लौटाता है।

session/load supplied cwd को session की stored working directory के खिलाफ उसी तरह validate करता है जैसे session/resume करता है, और unknown session identifier के लिए session-not-found error लौटाता है। Replay प्रत्येक stored user, agent, thought, और tool event को original chronological order में उसके corresponding SessionUpdate variant से map करता है, इसलिए reconnecting editor visible history को उसी क्रम में restore करता है जिस क्रम में वह हुई थी।

Interactive session controls

एक agent SessionControls provider देकर client को interactive controls expose कर सकता है। जब वह ऐसा करता है, तो server उन्हें session/new, session/load, session/resume, और session/fork responses में advertise करता है:

• Modes — named modes का एक set (उदाहरण के लिए "ask" versus "code") current selection के साथ। session/set_mode requested mode को advertised set के खिलाफ validate करता है, उसे record करता है, और एक CurrentModeUpdate emit करता है; unknown mode reject हो जाता है और current mode अपरिवर्तित रहता है।
• Configuration options — selects और toggles जिन्हें client पढ़ और बदल सकता है। session/set_config_option value को option की declared choices के खिलाफ validate करता है, उसे record करता है, और एक ConfigOptionUpdate emit करता है; unknown option या invalid value reject हो जाता है।
• Available commands — session active होने पर ACP slash-commands को एक AvailableCommandsUpdate के रूप में surface किया जाता है।

Mode और configuration selections ADK session state (acp:mode, acp:config:<id>) में persist होती हैं, इसलिए वे load, resume, और fork के बाद भी बनी रहती हैं। दर्ज किया गया session title activation पर और जब भी वह बदलता है, एक SessionInfoUpdate के रूप में surface होता है। एक Plan update mapping मौजूद है, लेकिन तब तक dormant रहता है जब तक कोई ADK plan primitive plan entries को surface नहीं करता। जो agent कोई SessionControls प्रदान नहीं करता, वह कोई modes और कोई options advertise नहीं करता, जिससे advertised capabilities server द्वारा implement की गई चीज़ों के साथ बिल्कुल aligned रहती हैं।

Content एक mapping के माध्यम से boundary पार करता है

client से आने वाले prompts और वापस streaming updates, दोनों एक ही content module से pass होते हैं, जो ACP ContentBlock values को adk_core::Part values में और वापस map करता है। दोनों दिशाओं में एक mapping रखने से server prompt parser, server streamer, और client इस बात पर सहमत रहते हैं कि हर content type कैसे represent होती है।

यह mapping payloads को faithfully preserve करती है। Text blocks Part::Text में string को ज्यों का त्यों map करते हैं। Embedded-resource blocks Part::EmbeddedResource में map होते हैं, जिसमें source URI, वैकल्पिक MIME type, और contents बने रहते हैं। Text resource दोनों दिशाओं में verbatim travel करती है और कभी base64-encoded नहीं होती; binary resource wire पर base64-encoded होती है और boundary के ADK side पर raw bytes में decode होती है। Image और audio blocks Part::InlineData में map होते हैं, MIME type और decoded bytes को preserve करते हुए; server उन prompt media को advertise और accept करता है, और client non-text ADK content (embedded resource, image, audio) को matching ACP block के रूप में transmit करता है, उसे drop नहीं करता।

Streaming updates text से अधिक वहन करते हैं

जब prompt चलता है, server typed ADK events को ACP session/update notifications में translate करता है। Model text और thoughts message और thought chunks बन जाते हैं, और embedded-resource content embedded-resource message chunk बन जाता है। इस surface से आगे, दो तरह के updates client को turn का अधिक समृद्ध दृश्य देते हैं:

• Usage updates. जब कोई ADK event usage metadata carry करता है, तो server एक UsageUpdate भेजता है जो reported token counts को reflect करता है, और runtime report करे तो USD में cost भी शामिल करता है। usage metadata के बिना events कोई update produce नहीं करते, और server कभी counts fabricate नहीं करता।
• Rich tool-call updates. एक tool call ToolCall के रूप में शुरू होता है, जिसमें tool का एक kind होता है जो tool के declared behavior से inferred होता है। उसका बाद का ToolCallUpdate tool result content और वे file locations carry करता है जिन्हें tool ने प्रभावित बताया है, ताकि editor diffs और affected-file lists render कर सके। update वही identifier रखता है जो originating ToolCall का था, जिससे पूरे turn में correlation बनी रहती है।

क्लाइंट की दिशा का मिलान समान निष्ठा के साथ होता है। जब कोई ADK-Rust अनुप्रयोग एक External_Agent का उपभोग करता है, तो उसका स्ट्रीमिंग सतह (OutputChunk) न केवल एजेंट टेक्स्ट और विचारों को, बल्कि External_Agent के ToolCallUpdate को भी उजागर करता है (एक id-संबद्ध टूल-अपडेट के रूप में, जिसमें स्थिति, प्रकार, शीर्षक, सामग्री टेक्स्ट, और प्रभावित फ़ाइल स्थान शामिल होते हैं) तथा उसके UsageUpdate को भी (उपयोग किए गए टोकन और आकार, साथ ही रिपोर्ट किए जाने पर लागत और मुद्रा)। एजेंट संदेश टेक्स्ट ठीक पहले की तरह ही प्रस्तुत किया जाता है, इसलिए मौजूदा टेक्स्ट उपभोक्ताओं पर कोई प्रभाव नहीं पड़ता।

अनुमति अनुरोध टूल पुष्टिकरणों के लिए सेतु बनाते हैं

एक ADK-Rust एजेंट टूल कॉल की मानव स्वीकृति लंबित होने पर एक टर्न को रोक सकता है (ToolConfirmationRequest)। सर्वर पक्ष पर, वह विराम टूल और उसके तर्कों का वर्णन करने वाले एक मूल ACP session/request_permission अनुरोध बन जाता है। क्लाइंट का परिणाम टर्न को पुनः प्रारंभ करता है: स्वीकृति का मान allow से मैप होता है, और अस्वीकृति या रद्दीकरण दोनों deny से मैप होते हैं, इसलिए रद्द किया गया अनुरोध कभी टूल को निष्पादित नहीं करता। प्रत्येक परिणाम अपनी function-call पहचानकर्ता द्वारा ठीक उसी कॉल से संबद्ध होता है और टूल-पुष्टिकरण निर्णयों के माध्यम से runner को वापस भेजा जाता है। नेस्टेड अनुमति अनुरोध spawned prompt task से जारी किया जाता है, इसलिए बाहरी session/prompt प्रतिक्रिया फिर भी सामान्य रूप से पूरी होती है।

क्षमताएँ एक अनुबंध हैं

आरंभिककरण कोई सजावटी हैंडशेक नहीं है। प्रत्येक पक्ष केवल वही संचालन और सामग्री घोषित करता है जिसे वह समर्थित करता है। ADK-Rust उन क्षमताओं का उपयोग stdio केवल स्वीकार करने वाले agent को वैकल्पिक HTTP या SSE MCP कॉन्फ़िगरेशन भेजने से बचने के लिए करता है, और यह filesystem या terminal host संचालन तभी घोषित करता है जब अनुप्रयोग संबंधित implementation प्रदान करता है।

सर्वर ठीक वही सामग्री प्रकार घोषित करता है जिन्हें उसका prompt handler स्वीकार करता है। यह embedded_context, image, और audio prompt क्षमताओं को घोषित करता है क्योंकि embedded-resource content adk_core::Part::EmbeddedResource से मैप होता है और image तथा audio content adk_core::Part::InlineData से मैप होते हैं। यह load_session घोषित करता है क्योंकि यह एक session/load handler पंजीकृत करता है, और fork session क्षमता क्योंकि यह एक session/fork handler पंजीकृत करता है। session modes और configuration options केवल तभी घोषित किए जाते हैं जब agent एक SessionControls provider प्रदान करता है, इसलिए जिसके पास वह नहीं है ऐसा agent इनमें से कोई भी घोषित नहीं करता। Remote transports, model selectors, और experimental protocol additions अघोषित रहते हैं। ऐसा prompt जो किसी ऐसे content type को लेकर आता है जिसे server ने घोषित नहीं किया है, उसे आंशिक रूप से संभालने के बजाय एक वर्णनात्मक त्रुटि के साथ अस्वीकार कर दिया जाता है। callers को यह मानने के बजाय कि हर ACP implementation का सतह क्षेत्र समान है, negotiated capability object के अनुसार डिज़ाइन करना चाहिए।

अगला

• एक ACP क्लाइंट या host बनाएं
• एक ADK-Rust ACP agent को expose करें
• परीक्षण और support matrix