iCode Agent · Guia · Automação
Automatize em scripts e na CI.
O iCode Agent é um agente de terminal, mas não precisa de um terminal. As mesmas tarefas executadas interativamente rodam headless com -p, e o stream completo de eventos do runtime fica disponível como JSON.
Modo de impressão
Execute uma tarefa, imprima a resposta final e saia:
icode-agent -p "run the tests and report failures" /path/to/project
O espaço de trabalho pode ser passado como argumento ou definido com --cwd <dir>. O modo de impressão sai com 0 quando a execução chegou a uma resposta final e 1 caso contrário — assim você pode ramificar com base nisso em um script.
Modo de eventos JSON
Adicione --mode json para transmitir cada evento da execução como uma linha JSON, seguida por uma linha de resultado final. Este é o modo para ferramentas: você recebe o progresso do agente como dados, não como saída de terminal.
icode-agent --mode json -p "find all TODO comments" /path/to/project
O stream inclui eventos como:
run_start— a tarefa e a identidade do modelo.iteration_start,assistant_delta— progresso dentro de cada etapa.tool_calletool_result— cada ferramenta que o agente usou e o que ela retornou.model_response— uso de tokens da chamada, quando o provedor informa.compaction,projection_reduced— eventos de gerenciamento de contexto, para que o comportamento de custo fique visível no stream.run_end— o resumo da execução.
Cada linha é um objeto JSON completo, então ferramentas padrão — jq, um pipeline de logs, uma etapa de CI — podem consumi-lo diretamente.
Continuando uma sessão
As sessões do espaço de trabalho persistem automaticamente. Continue a mais recente ou retome uma específica pelo id:
# continue the most recent session in this workspace icode-agent -c -p "now fix the issue you found" /path/to/project # resume a specific session icode-agent --resume <id> -p "add tests for that fix" /path/to/project
Um exemplo de CI
Uma etapa que pede ao agente para fazer a suíte passar e faz o job falhar quando ele retorna diferente de zero:
icode-agent -p "run the full test suite and fix any failures" "$PWD" status=$? if [ "$status" -ne 0 ]; then echo "iCode Agent did not reach a passing state." >&2 exit 1 fi
Instruções e configurações do projeto
Execuções headless leem a mesma configuração que as interativas:
- O
AGENTS.md(ouCLAUDE.md) na raiz do repositório é carregado no prompt de sistema, para que as execuções de CI sigam as regras do seu projeto. - As configurações globais ficam em
~/.icode-agent/settings.jsone podem ser substituídas por projeto em.icode-agent/settings.json. - Modelos de prompt (
.icode-agent/prompts/*.md) e skills (.icode-agent/skills/<name>/SKILL.md) são carregados automaticamente.
Em um runner de CI sem ~/.icode-agent, aponte ICODE_AGENT_CONFIG_DIR para um diretório preparado, para que a configuração do modelo esteja disponível.