ACP fornece a uma interface de codificação e a um agente de codificação uma maneira compartilhada de abrir um projeto, trocar prompts, transmitir o progresso, solicitar aprovação, cancelar o trabalho e continuar a mesma sessão. ADK-Rust implementa ambos os lados desse relacionamento.
Arquitetura ADK-Rust ACP
O programa com interface é o cliente ACP. O programa que faz o trabalho de codificação é o agente ACP. ADK-Rust pode estar em qualquer um dos lados desse relacionamento.
01 · ADK-Rust é o cliente/host ACP
Decide que uma tarefa de repositório precisa de um especialista em codificação.
Inicia o processo, escolhe o espaço de trabalho, mantém o contexto e aplica a política de permissão.
Inspeciona o código, propõe edições, invoca ferramentas e transmite seu progresso.
The shared ACP v1 contract
Both directions use the same message vocabulary.
initializesession/newsession/promptsession/updaterequest_permissioncancelclose · list · resume · delete02 · ADK-Rust é o agente/servidor ACP
Possui a IU de conversação e inicia o binário ADK-Rust.
Negocia recursos, valida sessões, transmite atualizações e lida com cancelamentos.
Usa modelos, ferramentas Rust, fluxos de trabalho, sessões, memória e artefatos para concluir o turno.
Uma sessão ACP é mapeada para uma sessão ADK-Rust persistente.
O cliente seleciona uma opção que o agente realmente ofereceu.
Texto, pensamentos, início de ferramenta e fluxo de conclusão de ferramenta como session/update.
O ACP v1 estável usa um subprocesso local e JSON-RPC sobre stdio.
Comece com o relacionamento
Um agente de codificação pode raciocinar sobre um repositório e usar ferramentas, mas as pessoas ainda precisam de uma interface onde possam descrever o trabalho, ver o que o agente está fazendo, responder perguntas, aprovar ações confidenciais e interromper uma curva. Sem um padrão, todo editor e todo agente de codificação precisam de uma integração personalizada para esses princípios básicos.
ACP define aquela conversa perdida. O cliente é proprietário da interface e do ambiente de trabalho que escolhe fornecer. O agente possui a inteligência de codificação. Eles concordam com sessões, prompts, conteúdo, atualizações ao vivo, chamadas de ferramentas, opções de permissão, cancelamento e conclusão sem a necessidade de compartilhar o código de implementação.
ADK-Rust suporta ambas as direções práticas. Um agente ADK pode delegar trabalho a um agente de codificação ACP externo como uma ferramenta. Com o recurso de servidor, um editor pode iniciar um binário ADK-Rust e usar seu Runner, modelos, ferramentas, sessões, memória e fluxos de trabalho por meio do mesmo contrato ACP v1.
Geralmente um editor, aplicativo de desktop, coordenador CLI ou ADK-Rust. Ele inicia o agente de codificação, abre uma sessão do projeto, mostra o progresso e decide como as perguntas de permissão chegam ao usuário.
Ele recebe prompts, motivos sobre o repositório, relata a atividade da ferramenta, pergunta antes de ações confidenciais e retorna um motivo de parada quando o turno termina.
Uma sessão possui um ID, um diretório de trabalho absoluto, raízes de espaço de trabalho opcionais, vários prompts, atualizações transmitidas e um ciclo de vida claro de fechamento ou retomada.
O agente descreve a chamada exata da ferramenta e oferece opções. O cliente retorna uma dessas opções, então o aplicativo – e não o agente – controla se a ação prossegue.
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.Direção um · ADK-Rust é o cliente
O processo ACP externo aparece dentro de ADK-Rust como uma ferramenta nomeada. Seu coordenador pode decidir quando usá-lo, escolher o diretório do projeto, preservar o contexto quando o trabalho se estende por vários turnos, transmitir o progresso em sua interface e manter a política de aprovação fora do agente de codificação.
AcpAgentToolMelhor quando um agente ADK ocasionalmente delega uma tarefa de repositório independente. Cada chamada inicia um processo ACP e retorna seu texto como saída normal da ferramenta.
AcpToolsetDê a um coordenador nomeado agentes de revisão, teste, migração ou documentação. As descrições de suas ferramentas ajudam o modelo a encaminhar cada tarefa para o processo certo.
AcpSessionMantenha o processo e a sessão ACP ativos em todos os prompts. O agente lembra o que já inspecionou e um identificador de cancelamento pode interromper uma curva durante o voo.
stream_promptReceba texto, pensamento, chamada de ferramenta, permissão, conclusão e pedaços de erro conforme eles acontecem, em vez de esperar por uma string combinada.
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?;O cliente pode fornecer o ambiente de trabalho
ACP não pressupõe que um agente de codificação possa ler seu disco ou executar comandos diretamente. O cliente declara os serviços que está preparado para prestar, trata cada solicitação e mantém as regras de segurança próximas do produto e do usuário.
ADK-Rust agora expõe interfaces de arquivo tipado e host de terminal e passa servidores MCP fornecidos pelo cliente para a criação de sessão. Nada está habilitado por padrão. Uma ferramenta de documentação somente leitura, um editor de desktop com buffers não salvos e um trabalhador de construção isolado podem publicar, cada um, um conjunto de recursos diferente e preciso.
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.
Por que MCP aparece na configuração da sessão ACP
Por exemplo, um editor pode anexar seu rastreador de problemas ou servidor MCP de pesquisa de repositório ao abrir a sessão. O agente de codificação recebe essas ferramentas sem possuir suas credenciais ou configuração. ADK-Rust suporta o transporte stdio exigido pelo ACP v1 estável, inicia cada servidor com um handshake limitado e o remove com a sessão. Os transportes opcionais HTTP e SSE são aceitos pelo cliente somente quando o agente externo os anuncia.
A aprovação pertence ao anfitrião
Um agente de codificação pode precisar editar um arquivo, executar um comando, instalar uma dependência ou excluir a saída gerada. ACP envia a operação proposta de volta ao cliente com um menu de opções válidas. ADK-Rust preserva os detalhes relevantes para a segurança e nega solicitações por padrão.
Para um fluxo de trabalho local confiável, uma regra pode aprovar operações conhecidas. Para um produto interativo, PermissionPolicy::async_custom pode aguardar uma caixa de diálogo na área de trabalho, uma tela de aprovação na web ou um serviço de política da organização. ADK-Rust retorna o ID exato da opção opaca fornecido pelo agente; nunca inventa um valor de aprovação.
A solicitação carrega o ID da sessão, o ID da chamada da ferramenta, o título, o tipo de ferramenta, a entrada bruta e todas as opções de resposta suportadas pelo agente.
Negar por padrão, usar uma regra síncrona ou aguardar um diálogo humano ou serviço de política remota por meio de async_custom.
As opções de permissão e rejeição são correspondidas pelo significado de ACP e, em seguida, o ID da opção opaca original é retornado. Um ID fabricado torna-se um cancelamento.
O agente codificador recebe a decisão na mesma sessão e pode continuar a chamada da ferramenta, escolher outro caminho ou finalizar o turno.
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 informa a ambos os lados qual projeto e raízes adicionais pertencem à sessão. Ele não cria um limite de segurança do sistema operacional. Se o processo de codificação precisar ser isolado do resto da máquina, execute-o adk-sandbox, um contêiner ou outra política de processo.
Keep credentials in the process environment or the client's secret store. Protocol stdout must contain only ACP JSON-RPC messages.
Direção dois · ADK-Rust é o agente ACP
O editor inicia seu binário Rust como um subprocesso ACP. O SDK oficial possui enquadramento JSON-RPC, IDs de solicitação, decodificação tipada e stdio. O manipulador de sessão mapeia uma sessão ACP para uma sessão ADK-Rust e, em seguida, o Runner transmite eventos de modelo e ferramenta de volta como notificações session/update ao vivo.
Essa direção é útil quando seu agente possui instruções específicas de domínio, ferramentas Rust, agentes de fluxo de trabalho, memória ou serviços internos que devem estar disponíveis em uma interface de codificação. O editor não precisa entender esses aspectos internos; ele vê os recursos e o ciclo de vida que o binário publica honestamente.
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"
}}Escopo verificado
ADK-Rust agora usa a caixa oficial agent-client-protocol para ambas as funções. A tabela separa a superfície interoperável v1 dos recursos que ainda precisam de implementação, para que um editor ou produto não descubra um recurso ausente após o início do trabalho de integração.
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 onlyPortão de interoperabilidade
Um cliente SDK oficial se conecta ao agente ADK-Rust SDK por meio de um transporte na memória e conclui inicialização → novo → prompt → atualização → fechar → lista → retomar → fechar → excluir. Os testes de cancelamento cobrem a sessão/cancelamento ACP e o cancelamento da solicitação JSON-RPC e, em seguida, provam que a sessão pode aceitar outro prompt após a limpeza. Os testes de permissão abrangem menus rejeitados primeiro, IDs opacos, seleções fabricadas e uma decisão humana aguardada. Um portão ativo separado inicia um filho stdio MCP real e descobre seu catálogo de ferramentas por meio do mesmo McpToolset usado pelas sessões ACP.
Escolha o limite
Comece perguntando o que está do outro lado. Um agente de codificação precisa de uma sessão de projeto e de um host interativo. Um agente comercial remoto precisa de um contrato de tarefa de rede. Uma ferramenta ou serviço de dados precisa de um contrato de capacidade exigível.
Use ACP entre uma interface de codificação e o agente trabalhando dentro de uma sessão de projeto.
Explore ACP A2AUse A2A para descobrir um agente remoto, enviar trabalho, acompanhar o estado da tarefa e receber artefatos em uma rede.
Explore A2A MCPUse MCP para fornecer a um agente ferramentas, prompts e recursos que podem ser chamados, sem transformar esse servidor no próprio agente.
Explore MCPConstrua com a função que você precisa
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.