ACP क्लाइंट या होस्ट बनाएँ

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

इंस्टॉल करें

[dependencies]
adk-acp = "2.1.0"

डिफ़ॉल्ट फीचर सेट क्लाइंट कार्यान्वयन है। server फीचर की आवश्यकता केवल तब होती है जब कोई ADK-Rust एजेंट उपलब्ध कराया जा रहा हो।

क्लाइंट का रूप चुनें

वन-शॉट प्रॉम्प्ट

use adk_acp::{
    AcpAgentConfig, PermissionPolicy, prompt_agent_with_policy,
};
use std::sync::Arc;

let config = AcpAgentConfig::new("my-coding-agent --acp")
    .working_dir("/absolute/path/to/project");

let answer = prompt_agent_with_policy(
    &config,
    "Inspect the failing test and explain the cause.",
    Arc::new(PermissionPolicy::DenyAll),
).await?;

DenyAll डिफ़ॉल्ट है, क्योंकि स्पॉन किया गया कोडिंग एजेंट वास्तविक प्रभाव वाले ऑपरेशनों का अनुरोध कर सकता है। AutoApprove का उपयोग केवल विश्वसनीय स्थानीय वर्कफ़्लो के भीतर करें।

समृद्ध प्रॉम्प्ट सामग्री भेजना

prompt_agent_content_with_policy पूर्ण adk_core::Content मान प्रसारित करता है — केवल स्ट्रिंग नहीं — इसलिए प्रॉम्प्ट में गैर-पाठ सामग्री भी शामिल हो सकती है। एम्बेडेड-रिसोर्स, इमेज और ऑडियो भाग हटाए जाने के बजाय साझा कंटेंट मॉड्यूल के माध्यम से संबंधित ACP कंटेंट ब्लॉक में मैप किए जाते हैं; टेक्स्ट हमेशा सुरक्षित रहता है। जिन भागों में प्रसारित करने योग्य ACP प्रतिनिधित्व नहीं होता, उन्हें छोड़ दिया जाता है, और ऐसा प्रॉम्प्ट जो किसी भी ब्लॉक में मैप नहीं होता, अस्वीकार कर दिया जाता है।

use adk_acp::{AcpAgentConfig, PermissionPolicy};
use adk_acp::connection::prompt_agent_content_with_policy;
use adk_core::{Content, Part};
use std::sync::Arc;

let mut content = Content::new("user");
content.parts.push(Part::Text { text: "What is in this image?".into() });
content.parts.push(Part::InlineData { mime_type: "image/png".into(), data: png_bytes });

let config = AcpAgentConfig::new("my-coding-agent --acp")
    .working_dir("/absolute/path/to/project");

let answer = prompt_agent_content_with_policy(
    &config,
    &content,
    Arc::new(PermissionPolicy::DenyAll),
).await?;

ADK एजेंट से डेलीगेट करना

use adk_acp::{AcpAgentTool, PermissionDecision, PermissionPolicy};
use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

let policy = PermissionPolicy::Custom(Box::new(|request| {
    if request.title.to_ascii_lowercase().contains("delete") {
        PermissionDecision::deny()
    } else {
        PermissionDecision::allow_once()
    }
}));

let coding_agent = AcpAgentTool::new("my-coding-agent --acp")
    .name("repository_specialist")
    .description("Inspect and improve the current Rust repository")
    .working_dir("/absolute/path/to/project")
    .permission_policy(policy);

let coordinator = LlmAgentBuilder::new("coordinator")
    .model(model)
    .instruction("Delegate repository changes to repository_specialist.")
    .tool(Arc::new(coding_agent))
    .build()?;

प्रत्येक AcpAgentTool कॉल एक नई प्रक्रिया और सेशन शुरू करती है। इस संरचना को तब चुनें जब डेलीगेट किया गया कार्य स्व-निहित हो और कोऑर्डिनेटर को अपने टूल परिणाम के रूप केवल अंतिम टेक्स्ट की आवश्यकता हो।

स्थायी सेशन और रद्दीकरण

use adk_acp::{AcpAgentConfig, AcpSession, PermissionPolicy};
use std::sync::Arc;

let config = AcpAgentConfig::new("my-coding-agent --acp")
    .working_dir("/absolute/path/to/project");
let mut session = AcpSession::start(
    config,
    Arc::new(PermissionPolicy::DenyAll),
).await?;

let first = session.prompt("Map the error-handling modules.").await?;
let second = session.prompt("Now inspect the most central one.").await?;

let cancel = session.cancellation_handle()?;
// Move `cancel` into a stop-button, timeout, or shutdown task while another
// task awaits `session.prompt(...)`.

session.close().await?;

रद्दीकरण हैंडल आधिकारिक session/cancel सूचना भेजता है। रद्द किए गए स्टॉप कारण के आने तक प्रॉम्प्ट को अवेट करते रहना चाहिए; इससे वही सेशन अपनी कतार में पुराने रिस्पॉन्स के बिना किसी अन्य प्रॉम्प्ट को स्वीकार कर सकता है।

किसी टर्न को UI में स्ट्रीम करना

stream_prompt एजेंट टेक्स्ट, विचारों, टूल प्रारंभ, अनुमति संबंधी निर्णयों, पूर्णता और त्रुटियों के लिए OutputChunk मान प्रदान करता है। इनके अतिरिक्त, यह External_Agent के टर्न के दो अधिक समृद्ध दृश्य प्रस्तुत करता है:

• OutputChunk::ToolUpdate — External_Agent का ToolCallUpdate, टूल-कॉल id द्वारा सहसंबद्ध, जिसमें रिपोर्ट की गई स्थिति, प्रकार, अद्यतन शीर्षक, निकाला गया सामग्री-पाठ और प्रभावित फ़ाइल स्थान शामिल हैं। इससे UI केवल अंतिम पाठ के बजाय टूल की प्रगति, अंतर और प्रभावित-फ़ाइल सूचियाँ प्रदर्शित कर सकता है।
• OutputChunk::Usage — External_Agent का UsageUpdate, जिसमें टोकन used और संदर्भ-विंडो size, साथ ही संचयी cost और currency शामिल हैं, जब agent उनकी रिपोर्ट करता है, ताकि UI संदर्भ-विंडो की खपत प्रदर्शित कर सके।

Agent संदेश का पाठ पहले की तरह ही सटीक रूप से उपलब्ध कराया जाता है, इसलिए ऐसा UI जो केवल पाठ के खंड पढ़ता है, प्रभावित नहीं होता। एप्लिकेशन thought chunks को छिपा सकता है, टूल गतिविधि को अलग-अलग प्रदर्शित कर सकता है और साझा StatusTracker को अपने इंटरफ़ेस में दिखा सकता है।

पूरे लूप के लिए चलने योग्य acp_client_host crate देखें।

Agent को फ़ाइलों का अनुरोध करने दें

AcpFileSystem लागू करें और इसे AcpAgentConfig::filesystem के साथ संलग्न करें। पढ़ने और लिखने की क्षमताओं की स्वतंत्र रूप से supports_read और supports_write के माध्यम से घोषणा की जाती है।

कॉलबैक को absolute paths प्राप्त होते हैं। Production host को:

1. स्वीकृत workspace और अनुरोधित path को canonicalize करना चाहिए;
2. symlink escapes सहित, स्वीकृत roots के बाहर के paths को अस्वीकार करना चाहिए;
3. यह तय करना चाहिए कि बिना सहेजे गए editor buffers, disk content को अधिलेखित करते हैं या नहीं;
4. file-size और line-range limits लागू करनी चाहिए;
5. writes की घोषणा केवल तभी करनी चाहिए जब एप्लिकेशन उन्हें लागू और अधिकृत करता हो।

Working directory संदर्भ है, sandbox नहीं। Filesystem validation और OS process boundary अलग-अलग समस्याओं का समाधान करते हैं।

Agent को commands चलाने दें

AcpTerminal लागू करें और इसे AcpAgentConfig::terminal के साथ संलग्न करें। ACP terminal को एक capability के रूप में घोषित करता है, इसलिए host को पूरे create, output, wait, kill और release lifecycle को लागू करना होगा।

होस्ट कमांड allowlists, कार्य-निर्देशिका नियम, पर्यावरण चर, आउटपुट सीमाएँ, प्रक्रिया पृथक्करण और सफ़ाई व्यवहार चुनता है। टर्मिनल कॉलबैक JSON-RPC डिस्पैच लूप के बाहर निष्पादित होते हैं, इसलिए लंबे समय तक प्रतीक्षा करने से अनुमति या रद्दीकरण ट्रैफ़िक रुकता नहीं है।

सत्र को MCP सर्वर प्रदान करें

use adk_acp::AcpAgentConfig;
use adk_acp::agent_client_protocol::schema::v1::{
    McpServer, McpServerStdio,
};

let tools = McpServer::Stdio(
    McpServerStdio::new("project-tools", "/absolute/path/to/mcp-server")
        .args(vec!["--read-only".into()]),
);

let config = AcpAgentConfig::new("my-coding-agent --acp")
    .working_dir("/absolute/path/to/project")
    .mcp_server(tools);

स्थिर ACP v1 के लिए आवश्यक है कि एजेंट stdio MCP कॉन्फ़िगरेशन स्वीकार करें। HTTP और SSE प्रविष्टियाँ केवल तभी भेजी जाती हैं जब बाहरी एजेंट उन वैकल्पिक ट्रांसपोर्ट का विज्ञापन करता है। AcpAgentConfig डिबग आउटपुट गुप्त मानों को प्रिंट किए बिना नाम और पर्यावरण कुंजियाँ सूचीबद्ध करता है।

अनुमति नीतियाँ

प्रत्येक अनुमति अनुरोध में सत्र ID, सटीक टूल-कॉल ID, टूल प्रकार, कच्चा इनपुट और एजेंट द्वारा प्रस्तावित सभी विकल्प शामिल होते हैं। विकल्प ID अपारदर्शी होते हैं। ADK-Rust अनुमति और अस्वीकृति के अर्थों से मेल खाता है, फिर मूल ID लौटाता है; गढ़ा गया चयन रद्दीकरण बन जाता है।

PermissionPolicy::async_custom डेस्कटॉप संवाद, वेब अनुमोदन UI या संगठन नीति सेवा की प्रतीक्षा कर सकता है। इस API के माध्यम से मानवीय सहभागिता की प्रतीक्षा करके डिस्पैच लूप को प्रतिक्रियाशील बनाए रखें, न कि किसी थ्रेड को अवरुद्ध करके।

अगला

• एक ADK-Rust ACP एजेंट प्रदर्शित करें
• परीक्षण और समर्थन मैट्रिक्स