Referencia do protocolo

Este documento fornece uma referencia completa dos metodos e eventos de streaming do ACP (Agent Client Protocol) expostos pelo servidor iac-code.

Visao geral do ciclo de vida

Uma sessao ACP tipica segue este fluxo:

initialize → new_session → prompt (loop) → close_session
                ↑                              │
                └── load_session / resume ──────┘

initialize — Handshake. Negocia a versao do protocolo e descobre as capacidades do servidor.
session/new — Cria uma nova sessao com um runtime de agente independente.
session/prompt — Envia entrada do utilizador; recebe eventos de streaming ate uma resposta final.
session/close — Libera a sessao e seus recursos.

As sessoes tambem podem ser carregadas do historico (session/load) ou retomadas (session/resume) em vez de criar novas.

Backups de sessão

Sessões ACP usam o mesmo comportamento de backup de sessão v2 das execuções interativas e headless. Quando IAC_CODE_CONFIG_BACKUP_DIR está definido, uma conclusão normal de prompt registra um backup não bloqueante normal_turn_end; se esse backup falhar, a falha é registrada como warning e gravada em .backup-state.json, enquanto a resposta final ainda conclui sem prometer um campo warning. O modo Pipeline tem seus próprios gates de backup crítico.

Metodos

initialize

Handshake do protocolo. Deve ser a primeira chamada em cada conexao.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`protocolVersion`	integer	Sim	Versao do protocolo solicitada (atualmente `1`)
`clientInfo`	object	Nao	Nome e versao do cliente
`clientCapabilities`	object	Nao	Capacidades suportadas pelo cliente

Campos da resposta

Campo	Tipo	Descricao
`protocolVersion`	integer	Versao do protocolo negociada
`agentCapabilities`	object	Capacidades do servidor (veja abaixo)
`agentInfo`	object	Nome e versao do servidor
`authMethods`	array	Metodos de autenticacao disponiveis (vazio se usar credenciais integradas)

Capacidades do agente

Capacidade	Valor	Significado
`loadSession`	`true`	Suporta restauracao de sessoes a partir do historico
`promptCapabilities.embeddedContext`	`true`	Aceita conteudo de recurso incorporado em prompts
`promptCapabilities.image`	`false`	Entrada de imagem nao suportada (degrada para marcador de texto)
`promptCapabilities.audio`	`false`	Entrada de audio nao suportada (degrada para marcador de texto)
`mcpCapabilities.http`	`true`	Aceita servidores MCP HTTP/streamable na criacao da sessao
`mcpCapabilities.sse`	`true`	Aceita servidores MCP SSE na criacao da sessao
`sessionCapabilities.list`	`{}`	Suporta listagem de sessoes
`sessionCapabilities.close`	`{}`	Suporta fechamento de sessoes

session/new

Cria uma nova sessao com um runtime de agente independente, registro de ferramentas e contexto de LLM.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`cwd`	string	Sim	Caminho absoluto para o diretorio de trabalho
`mcpServers`	array	Nao	Array de configuracao de servidores MCP injetado no runtime da sessao; servidores HTTP (streamable) e SSE sao conectados para a sessao

Campos da resposta

Campo	Tipo	Descricao
`sessionId`	string	Identificador unico da sessao para chamadas subsequentes
`modes`	object	Modos disponiveis e modo atual
`models`	object	Modelos disponiveis e modelo atual

Nota

Cada sessao cria um AgentLoop independente. Multiplas sessoes podem ser executadas simultaneamente, mas cada uma consome uma conexao LLM.

session/load

Carrega uma sessao previamente persistida do disco, restaurando seu historico de mensagens.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`cwd`	string	Sim	Caminho do diretorio de trabalho
`sessionId`	string	Sim	ID da sessao a carregar

Campos da resposta

Campo	Tipo	Descricao
`models`	object	Modelos disponiveis e estado do modelo atual
`modes`	object	Modos disponiveis e estado do modo atual

Nota

Carregar uma sessao le o historico de ~/.iac-code/sessions/, repara automaticamente mensagens interrompidas e injeta o historico num novo AgentLoop.

session/fork

Bifurca uma sessao existente para criar uma ramificacao independente com o mesmo historico.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`cwd`	string	Sim	Caminho do diretorio de trabalho
`sessionId`	string	Sim	ID da sessao a bifurcar

Campos da resposta

Campo	Tipo	Descricao
`sessionId`	string	Novo ID de sessao para a ramificacao bifurcada
`models`	object	Modelos disponiveis e estado do modelo atual
`modes`	object	Modos disponiveis e estado do modo atual

session/resume

Retoma ou reconecta a uma sessao existente. Carrega automaticamente o historico se necessario.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`cwd`	string	Sim	Caminho do diretorio de trabalho
`sessionId`	string	Sim	ID da sessao a retomar

Campos da resposta

Campo	Tipo	Descricao
`models`	object	Modelos disponiveis e estado do modelo atual (opcional)
`modes`	object	Modos disponiveis e estado do modo atual (opcional)

Nota

Ao contrario de session/new, a resposta nao inclui um campo sessionId pois o cliente ja conhece o ID da sessao a partir da requisicao.

session/prompt

Envia entrada do utilizador e aciona respostas do agente em streaming.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`sessionId`	string	Sim	ID da sessao alvo
`prompt`	array	Sim	Array de blocos de conteudo (veja Tipos de blocos de conteudo abaixo)

Tipos de blocos de conteudo

Tipo	Descricao
`TextContentBlock`	Entrada de texto simples do utilizador
`EmbeddedResourceContentBlock`	Conteudo de arquivo incorporado inline
`ResourceContentBlock`	Referencia de link de recurso
`ImageContentBlock`	Imagem (degrada para marcador de texto `[image: mime/type]`)
`AudioContentBlock`	Audio (degrada para marcador de texto `[audio: mime/type]`)

Campos da resposta

Campo	Tipo	Descricao
`stopReason`	string	Por que o prompt foi concluido (veja Motivos de parada)
`_meta.usage`	object	Uso de tokens sob o objeto `_meta` da resposta: `input_tokens`, `output_tokens`, `total_tokens`

Motivos de parada

Valor	Significado
`end_turn`	Modelo concluiu normalmente
`max_turn_requests`	Atingiu o limite maximo de loop de chamadas de ferramentas
`max_tokens`	Limite de tokens de saida atingido
`cancelled`	Cliente cancelou o prompt
`refusal`	Modelo recusou responder

Nota

Durante a execucao, o servidor envia notificacoes session/update com eventos de streaming antes de retornar a resposta final.

session/cancel

Cancela uma tarefa de prompt em execucao.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`sessionId`	string	Sim	Sessao com o prompt em execucao

Comportamento

Para de consumir eventos do stream
Ferramentas em execucao nao sao terminadas forcosamente, mas os resultados sao descartados
A chamada prompt pendente retorna com stopReason: "cancelled"

session/close

Fecha uma sessao e libera seus recursos.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`sessionId`	string	Sim	Sessao a fechar

Comportamento

Sessao removida da memoria
O historico persistido permanece no disco
Chamadas prompt subsequentes a esta sessao retornam um erro

session/list

Lista todas as sessoes persistidas para um determinado diretorio de trabalho.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`cwd`	string	Sim	Diretorio de trabalho para delimitar a listagem

Campos da resposta

Campo	Tipo	Descricao
`sessions`	array	Lista de objetos de sessao com `sessionId` e metadados

session/set_config_option

Define dinamicamente uma opcao de configuracao para uma sessao.

Parametros da requisicao

Campo	Tipo	Obrigatorio	Descricao
`sessionId`	string	Sim	Sessao alvo
`configId`	string	Sim	Chave de configuracao a definir
`value`	any	Sim	Novo valor

Eventos de streaming

Durante a execucao de session/prompt, o servidor envia notificacoes session/update contendo dados de eventos de streaming.

Formato do evento

Cada notificacao session/update carrega um objeto de atualizacao com um tipo especifico:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "abc123",
    "update": { "type": "agent_message_chunk", "text": "..." }
  }
}

Mapeamento de tipos de evento

Evento interno	Tipo de atualizacao ACP	Descricao
`TextDeltaEvent`	`AgentMessageChunk`	Saida de texto incremental do agente
`ThinkingDeltaEvent`	`AgentThoughtChunk`	Conteudo de raciocinio/pensamento do modelo
`ToolUseStartEvent`	`ToolCallStart`	Inicio da invocacao de ferramenta
`ToolResultEvent`	`ToolCallProgress`	Resultado da ferramenta (concluido ou falhou)
`CompactionEvent`	`AgentMessageChunk`	Notificacao de compactacao de contexto
`ErrorEvent`	`AgentMessageChunk`	Informacao de erro

Status e avisos MCP

ACP expoe o estado runtime MCP no caminho wire session/update.params.update._meta.iac_code:

Chave de metadados	Tipo de atualizacao ACP	Descricao
`mcpStatus`	`session_info_update`	Estado atual dos servidores MCP, enviado apos a criacao da sessao e quando o estado de MCP auth, connection ou capability muda.
`mcpWarning`	`agent_message_chunk`	Um aviso de inicializacao ou configuracao com uma mensagem curta visivel ao usuario.

mcpStatus contem servers e warnings. As entradas de server incluem serverName, state, authState, toolsCount, resourcesCount e promptsCount. Valores de authState incluem configured, needs-auth e not-configured.

Os server states comuns sao connected, failed, pending, needs-auth, pending-approval e disabled.

Status frames grandes podem incluir truncated, truncationReason com valor acp-frame-size-limit, serversOmittedCount, warningsOmittedCount ou contadores de omissao de capability list como toolsOmittedCount.

As entradas de tool em servers[].tools[] incluem publicName, originalServerName, originalToolName e podem incluir annotations. MCP annotations podem carregar hints como readOnlyHint e destructiveHint.

Registros permission audit operation podem incluir isReadOnly e isDestructive quando as annotations MCP fornecem hints read-only ou destructive.

As entradas mcpWarning incluem serverName, code, message, severity, source e opcionalmente sourcePath ou scope. Os warning codes comuns sao duplicate_config, invalid_name, invalid_config, missing_env, pending_approval, needs_auth, connection_failed, command_conflict, skill_read_failed, skill_truncated, alias_conflict e warnings dinamicos como <capability>_failed.

Ciclo de vida da chamada de ferramenta

ToolCallStart (status=in_progress)
    │
    ├── ToolCallProgress (status=in_progress, resumo de entrada / entrada segura de prompt)
    │
    ├── ToolCallProgress (status=completed, raw_output=result)   ← sucesso
    │
    └── ToolCallProgress (status=failed, raw_output=error)       ← falha

Mapeamento de tipo de ferramenta

Ferramenta	ACP ToolKind
`read_file`, `list_files`	`read`
`glob`, `grep`	`search`
`write_file`, `edit_file`	`edit`
`bash`, `agent`	`execute`
`web_fetch`	`fetch`
Outros	`other`

Solicitacoes de permissao

Antes de executar ferramentas de alto risco, o iac-code envia um callback request_permission ao cliente.

Categorias de permissao de ferramentas

Categoria	Ferramentas	Auto-aprovada
Somente leitura	`read_file`, `list_files`, `glob`, `grep`, `web_fetch`	Sim
API de nuvem somente leitura	Ações `aliyun_api` classificadas como somente leitura	Sim
Escrita	`write_file`, `edit_file`	Nao — requer aprovacao
Execucao	`bash`, `agent`	Nao — requer aprovacao
API de escrita de nuvem	Chamadas `aliyun_api` que não são somente leitura	Não — requer aprovação por API

Evento request_permission

O servidor envia um callback request_permission com:

Campo	Tipo	Descricao
`options`	array	Opcoes de permissao disponiveis
`sessionId`	string	Sessao solicitando permissao
`toolCall`	object	Detalhes da chamada de ferramenta (titulo, tipo, entrada)

Para prompts de permissao MCP, o title do ACP ToolCallUpdate usa o rotulo publico da operacao e o conteudo leva um resumo de entrada redigido. Pelo campo de extensibilidade ACP _meta, o objeto toolCall._meta.iac_code.permission inclui permissionId, toolName, toolUseId, scope, inputSummary e, quando disponiveis, publicName, originalServerName, originalToolName, isReadOnly e isDestructive. inputSummary e metadata de forma e redacao, nao entrada sensivel bruta.

Opcoes de permissao

ID da opcao	Significado
`allow_once`	Permitir esta invocacao especifica
`allow_always`	Permitir todas as futuras chamadas desta ferramenta nesta sessao quando a ferramenta oferece permissao global; nao e oferecido para `bash` nem `aliyun_api` por padrao
`allow_rule:<rules>`	Permitir futuras chamadas que correspondam as regras sugeridas nesta sessao
`deny_rule:<rules>`	Negar futuras chamadas que correspondam as regras sugeridas nesta sessao
`reject_once`	Negar esta invocacao especifica
`reject_always`	Negar todas as futuras chamadas desta ferramenta nesta sessao

Para aliyun_api, ações somente leitura são permitidas automaticamente. Ações RPC e ROA que não são somente leitura podem oferecer uma regra exata como aliyun_api(ros:CreateStack) ou aliyun_api(cs:CreateCluster). Regras allow com wildcards continuam não aprovando chamadas que não são somente leitura.

Formato de resposta

{
  "outcome": "selected",
  "optionId": "allow_once"
}

Ou para negar:

{
  "outcome": "cancelled"
}

Resposta do cliente	Comportamento da ferramenta
`AllowedOutcome`	Ferramenta executa normalmente
`DeniedOutcome`	Ferramenta ignorada; modelo recebe erro "Permission denied."

Tratamento de erros

Formato RequestError

Os erros seguem o formato de erro JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {"session_id": "Session not found"}
  }
}

Codigos de erro comuns

Codigo	Nome	Descricao
`-32700`	Erro de analise	JSON invalido
`-32600`	Requisicao invalida	JSON-RPC malformado
`-32601`	Metodo nao encontrado	Metodo desconhecido
`-32602`	Parametros invalidos	Parametros ausentes ou invalidos (ex.: ID de sessao desconhecido)
`-32603`	Erro interno	Falha no lado do servidor

Visao geral do ciclo de vida​

Backups de sessão​

Metodos​

initialize​

session/new​

session/load​

session/fork​

session/resume​

session/prompt​

session/cancel​

session/close​

session/list​

session/set_config_option​

Eventos de streaming​

Formato do evento​

Mapeamento de tipos de evento​

Status e avisos MCP​

Ciclo de vida da chamada de ferramenta​

Solicitacoes de permissao​

Categorias de permissao de ferramentas​

Evento request_permission​

Opcoes de permissao​

Formato de resposta​

Tratamento de erros​

Formato RequestError​

Codigos de erro comuns​

Visao geral do ciclo de vida

Backups de sessão

Metodos

initialize

session/new

session/load

session/fork

session/resume

session/prompt

session/cancel

session/close

session/list

session/set_config_option

Eventos de streaming

Formato do evento

Mapeamento de tipos de evento

Status e avisos MCP

Ciclo de vida da chamada de ferramenta

Solicitacoes de permissao

Categorias de permissao de ferramentas

Evento request_permission

Opcoes de permissao

Formato de resposta

Tratamento de erros

Formato RequestError

Codigos de erro comuns