O agent.yaml
Todas as chaves do
agent.yaml, as variáveis${NOME}que ele aceita e as ações desteps, com o schema que valida o arquivo.
Todas as chaves do agent.yaml (padrão 1), as variáveis ${NOME} que ele aceita e as ações de steps. Um exemplo completo e o passo a passo estão em Escrevendo um agente; o schema é packages/domain/src/agent/schemes/v1/agent.schema.json.
| Chave | Obrigatória | Padrão | O que é |
|---|---|---|---|
version | sim | — | Versão do padrão: 1. |
agent | sim | — | id (igual à pasta, é o nome do comando), name, version (semver do agente), description e, opcional, color (cor do rótulo [agente]; CHOL_COLORS ganha dela). |
providers | sim | — | Os providers com que o agente roda e, em cada um, os modelos que ele pode usar (veja Providers e modelos). |
role, input, flow, output | sim | — | O texto do agente (veja O texto do agente). |
context, notes | não | nenhum | Listas de textos que completam o texto do agente. |
skills | não | [] | Pastas em .choliba/skills/, com a instrução de uso de cada uma (veja Skills e MCPs). |
mcps | não | nenhum | Servidores em .choliba/mcps/<nome>.json, com as tools liberadas e a instrução de uso de cada um. Usar outro MCP interrompe a execução. |
permissions.allow/.deny | não | nada liberado | read, write e delete: caminhos (sem glob = o item e tudo abaixo). permissions.exception tira caminhos de um deny (veja Exceções no deny). execute: diretório → comandos. tools: ferramenta da run → subcomandos (['*'] = todos; em deny, ['*'] tira a ferramenta). Veja Ferramentas da run. |
modes.allow / .default | não | os três / execute | Modos aceitos (execute, plan, ask) e o usado quando a linha de comando não diz. |
task.required / .default | não | true / — | Se a tarefa é obrigatória e, quando não é, qual usar (default passa a ser obrigatório). |
ticket_types | não | agente sem ticket | Tipos de ticket aceitos (story, bug, improvement, task); a execução pede --type ou --ticket, a não ser com allow_without_ticket. |
allow_without_ticket | não | false | true deixa a execução seguir sem --type/--ticket: com ticket_types, o ticket fica opcional; sem, deixa explícito que o agente não usa ticket. |
steps.<modo>.before / .after | não | nenhum | Ações do choliba antes e depois do agente, em cada modo (veja Steps). |
Regras de permissão: veja Segurança. Em toda execução o choliba acrescenta deny.write e deny.delete das pastas de agentes, skills e MCPs; uma exceção dentro delas é recusada. No fim, compara o sha256 de cada arquivo dessas pastas: se algum foi criado, alterado ou apagado, a execução termina com código 1 e lista os caminhos, sem desfazer. Delegar a um subagente não é uma permissão: é negado a todo agente, sem chave no agent.yaml.
Exceções no deny
permissions.exception, ao lado de allow e deny, tem read, write e delete. Cada caminho ali sai de um deny da mesma ação, como no .gitignore. A exceção não libera nada sozinha: o que está nela ainda precisa estar em allow.
permissions:
allow:
read: ['/home/jackson/dev/teste/', '${CHOL_ROOT}/docs/publico/']
deny:
read: ['${CHOL_ROOT}/']
exception:
read: ['${CHOL_ROOT}/docs/publico/']O agente lê o app em /home/jackson/dev/teste/ e, da pasta de trabalho, só docs/publico/. A pasta de cada skill que o agente declara já é uma exceção sozinha: ela não precisa estar em exception. Uma exceção que não está dentro de nenhum deny da mesma ação (ou que fica dentro de um glob) para a execução antes do provider, porque não tira nada. Uma exceção de write ou delete dentro das pastas de agentes, skills ou MCPs também para: o choliba nega escrita e exclusão nelas em toda execução, e nenhuma exceção reabre.
A forma antiga continua aceita: um caminho que começa com ! dentro de deny.read, deny.write ou deny.delete é o mesmo que pô-lo em exception da mesma ação (deny: { read: ['${CHOL_ROOT}/', '!${CHOL_ROOT}/docs/publico/'] }).
Providers e modelos
providers diz com que providers o agente roda e, em cada um, com que modelos. Cada modelo vai pelo nome que aquele provider usa.
providers:
claude:
models: [claude-sonnet-5]
cursor:
models: [Composer 2.5 Fast, Auto]
claude-ollama:
models: [qwen3.5:4b]- Pelo menos um provider, entre os que o choliba conhece:
claude,claude-ollama,codexecursor. Outro nome é recusado ao carregar. - Cada provider tem pelo menos um modelo, sem repetir.
- A ordem conta: em
auto, roda o primeiro provider declarado que estiver instalado, e sem--modelroda o primeiro modelo declarado para ele (o padrão do próprio provider ficaria de fora dos modelos declarados, e a execução o recusaria).
Como uma execução escolhe:
| A linha de comando diz | Provider | Modelo |
|---|---|---|
--provider X e --model Y | X, que o agente precisa declarar | Y, que precisa estar nos modelos de X |
só --provider X | X, que o agente precisa declarar | o primeiro modelo declarado para X |
só --model Y | o provider que declara Y; se dois declaram, a execução pede --provider | Y |
| nenhum dos dois | CHOL_AGENTS_PROVIDER, que o agente precisa declarar; em auto, o primeiro declarado instalado | como na linha "só --provider X" |
Um provider ou um modelo que o agente não declara é recusado antes de rodar, com a mensagem dizendo o que ele declara. O modelo que o provider informa ao começar também é conferido contra os modelos declarados para ele. No painel, o /agents oferece para cada agente só os modelos que ele declara, e o /model os modelos do provider da sessão, além do padrão (cada agente no primeiro modelo que declara).
Ollama
Os modelos de claude-ollama rodam no Ollama: é o Claude Code, com as mesmas permissões e as mesmas paradas, falando com o Ollama em vez da API do Claude. O modelo vai pelo nome do Ollama, como o ollama list mostra (qwen3.5:4b).
choliba run agent test-writer --claude-ollama --project loja --ticket loja-1- O endereço é
CHOL_OLLAMA_URL(padrãohttp://localhost:11434). O choliba põe esse endereço e o token do Ollama na sessão e deixa vazias as credenciais do Claude, para nenhuma delas ir ao Ollama. No docker, veja Ollama. - O modelo precisa saber chamar ferramentas (no
ollama list, a capacidadetools), e o Ollama precisa de contexto para o texto do agente: suba o servidor comOLLAMA_CONTEXT_LENGTH=65536ou mais. Um modelo pequeno roda, mas segue pior o fluxo e as permissões. - Um modelo que não chama a ferramenta e escreve a chamada como resposta (um JSON com
nameearguments, ou<tool_call>…</tool_call>) termina a sessão sem rodar nada. O choliba falha a execução e diz qual modelo e qual ferramenta: troque por um modelo que faça tool calling.
Ferramentas da run
O que só os agentes usam não é comando do choliba: é uma ferramenta da run. Em cada execução, o choliba cria o script de cada ferramenta ao lado da pasta da run (.cache/runs/<execução>.<ferramenta>), libera só esse caminho para o agente, impede que ele seja reescrito e o apaga no fim. O prompt traz o caminho completo de cada uma.
| Ferramenta | Vem de | O que faz |
|---|---|---|
delete | permissions.allow.delete | Apaga arquivos e pastas sob esses caminhos; recusa links para fora, a própria raiz e o que deny.delete nega. Não existe em plan/ask. |
playwright-cli | permissions.allow.tools | O navegador (playwright cli), na versão do choliba, na raiz da pasta de trabalho; grava em CHOL_PLAYWRIGHT_MCP_OUTPUT_DIR. |
playwright-trace | permissions.allow.tools | Lê o trace.zip de um teste que falhou (playwright trace), na versão do choliba; roda em CHOL_PLAYWRIGHT_MCP_OUTPUT_DIR, com os caminhos relativos à raiz. |
ask | permissions.allow.tools | Pergunta algo a quem roda o agente e devolve a resposta: escolha única (--options a,b, também aceito como lista JSON ou --option repetido), várias (--multi) ou texto. O agente segue na mesma sessão com a resposta. Sem resposta (a pessoa pulou, não há terminal ou passaram 25 minutos), sai com 2 e o agente segue com uma premissa explícita. |
permissions:
allow:
delete: ['${APP_DIR}/']
tools:
playwright-cli: ['*']
playwright-trace: [open, actions, close]
deny:
tools:
playwright-cli: [eval, run-code, route, unroute]Variáveis
${NOME} num texto do agent.yaml é substituído pelo choliba antes de qualquer coisa rodar. O catálogo é fechado: um nome fora da lista abaixo, ou usado onde não vale, impede o agente de carregar, com o campo onde está.
Onde valem: no texto do agente (role, context, input, flow, output, notes), nas instructions de skills e MCPs, em permissions (caminhos, diretórios de execute e comandos) e nos argumentos das ações de steps. Onde não valem: agent, providers, task e as tools de um MCP, que são valores fixos da declaração.
${CHOL_ROOT}
A pasta de trabalho (a pasta cujo package.json depende do choliba). Existe sempre; o choliba a descobre sozinho, e defini-la no .env ou no ambiente é erro.
permissions:
allow:
execute:
'${CHOL_ROOT}/': [bun choliba run tests] # os comandos rodam a partir da raiz${CHOL_AGENTS_DIR}
A pasta dos agentes. Existe sempre: CHOL_AGENTS_DIR do .env, ou .choliba/agents.
permissions:
deny:
read: ['${CHOL_AGENTS_DIR}/'] # o agente não lê a definição de outros agentes${CHOL_SKILLS_DIR}
A pasta das skills. Existe sempre: CHOL_SKILLS_DIR do .env, ou .choliba/skills.
permissions:
allow:
read: ['${CHOL_SKILLS_DIR}/playwright-cli/']${CHOL_MCPS_DIR}
A pasta dos MCPs. Existe sempre: CHOL_MCPS_DIR do .env, ou .choliba/mcps.
permissions:
deny:
write: ['${CHOL_MCPS_DIR}/'] # o agente não altera a configuração dos MCPs${CHOL_GLOBAL_DIR}
A pasta global, dos artefatos das execuções. Existe com CHOL_GLOBAL_DIR no .env.
permissions:
allow:
read: ['${CHOL_GLOBAL_DIR}/shared/']${CHOL_PROJECTS_DIR}
A pasta de todos os projetos. Existe com CHOL_GLOBAL_DIR no .env: CHOL_PROJECTS_DIR do .env, ou <CHOL_GLOBAL_DIR>/projects.
permissions:
deny:
read: ['${CHOL_PROJECTS_DIR}/'] # nenhum projeto além do liberado por PROJECT_DIR${CHOL_TICKET_RUNS}
A pasta das execuções por ticket. Existe com CHOL_GLOBAL_DIR no .env, quando CHOL_TICKET_RUNS está configurada.
permissions:
allow:
read: ['${CHOL_TICKET_RUNS}/${TICKET}/']${PROJECT}
O nome do projeto da execução. Existe com --project.
role: |
Você é o Test Writer do projeto `${PROJECT}`.${PROJECT_DIR}
A pasta do projeto. Existe com --project.
permissions:
allow:
read: ['${PROJECT_DIR}/config.json', '${PROJECT_DIR}/tests/']${APP_DIR}
O código da aplicação do ambiente ativo do projeto (appDir do config.json). Existe com --project.
permissions:
allow:
write: ['${APP_DIR}/'] # o implementer só muda a aplicação${TICKET}
A chave do ticket da execução (ex.: TT-12). Existe com --type ou --ticket, que exigem ticket_types.
permissions:
allow:
write: ['${PROJECT_DIR}/tests/${TICKET}.spec.ts']${TICKET_FILE}
O arquivo JSON do ticket da execução. Existe com --type ou --ticket, que exigem ticket_types.
permissions:
allow:
write: ['${TICKET_FILE}'] # o product-owner só grava o ticket${AGENT_EXIT_CODE}
O código de saída do agente. Existe só nas ações de steps.<modo>.after, que rodam depois dele.
steps:
execute:
after:
failure:
- run: [bun, scripts/report-failure.ts, '${TICKET}', '${AGENT_EXIT_CODE}']Consequências de usar uma variável:
${PROJECT},${PROJECT_DIR},${APP_DIR},${TICKET}ou${TICKET_FILE}(ou declararticket_types) tornam--projectobrigatório;${TICKET}ou${TICKET_FILE}semticket_typesimpedem o agente de carregar;${CHOL_GLOBAL_DIR},${CHOL_PROJECTS_DIR}e${CHOL_TICKET_RUNS}só exigem o.envconfigurado se o agente usar uma delas.
Não confundir com as variáveis dos .json de MCP. Um .choliba/mcps/<nome>.json também usa ${NOME}, mas preenchido com qualquer variável do .env, sem catálogo:
{
"command": "node",
"args": ["${SERVER_DIR}/dist/main.js"],
"env": { "LOG_DIR": "${LOG_DIR}" }
}SERVER_DIR e LOG_DIR vêm do .env; não fazem parte do catálogo do agent.yaml.
Steps
steps são ações que o choliba executa, nunca o agente, declaradas por modo (execute, plan, ask). Cada modo tem o seu before e o seu after; um modo sem steps não roda nada.
steps:
execute:
before: # guarda: uma ação falhou → para tudo, o agente não roda
- run: [bun, choliba, run, tests, '${PROJECT}:${TICKET}', --expect, red]
after:
success: # o agente saiu com 0
- run: [bun, choliba, run, tests, '${PROJECT}:${TICKET}', --expect, green]
failure: # o agente falhou: erro, limite, Ctrl+C
- run: [bun, scripts/report-failure.ts, '${AGENT_EXIT_CODE}']
always: # sempre, depois de success ou failure
- run: [rm, -f, .cache/tmp.patch]
plan:
after: # uma lista simples é o mesmo que always
- run: [rm, -f, .cache/tmp.patch]| Ação | Onde | O que faz |
|---|---|---|
run | os dois | Roda um comando, sem shell, a partir da pasta de trabalho. |
git_diff | before | Grava o diff do working tree e põe o caminho e o índice no prompt. |
search_files | before | Põe no prompt um resumo de pastas: subpastas e arquivos por extensão. |
read_files | before | Põe o conteúdo de arquivos no prompt, dentro de uma tag (<tag>). |
record_git_head | after | Grava o commit atual, base do próximo --since pending. |
write_files | after | Grava a resposta final do agente em cada arquivo dado. |
write_config | after | Grava a resposta final do agente, um JSON, numa chave do config.json do projeto. |
As ações de arquivo (search_files, read_files, write_files e write_config) usam campos com nome; as outras, uma lista de argumentos.
| Campo | Em | O que é |
|---|---|---|
tag | search_files, read_files | O nome do bloco no prompt (<tag>…</tag>), que o texto do agente cita. |
dirs | search_files, read_files | Pastas onde procurar, relativas à pasta de trabalho ou absolutas. |
pattern | search_files, read_files | O que achar, em padrões de caminho: /package.json só na raiz da pasta, *.php em todo nível. |
ignore | search_files, read_files | O que pular, no mesmo formato, somado ao de sempre: node_modules, vendor, dist, build, .git, .cache. |
max_depth | search_files | Quantos níveis descer em cada pasta (1: só o que ela tem); sem ele, todos. O resumo avisa quando cortou. |
files | read_files, write_files | Caminhos de arquivos, relativos à pasta de trabalho ou absolutos. |
max_size | search_files, read_files | O tamanho máximo do que o step põe no prompt (40KB, 2MB, 512); padrão 100KB. |
- O
search_filespõe, por pasta dedirs, as subpastas até 2 níveis (no máximo 200) e quantos arquivos há de cada extensão (as 30 mais comuns), dos quepatternacha (todos, sem ele). Serve para dar ao agente a forma de um app grande sem pôr a lista de cada arquivo. - O
read_fileslêfiles, ou os arquivos quepatternacha emdirs(um dos dois;dirssempre compattern, para não ler pastas inteiras por engano). - Passando de
max_size, o step falha antes do agente, dizendo o tamanho, o limite, quantos arquivos achou e o que fazer. Ele não corta o conteúdo: um prompt cortado perderia o texto do agente sem aviso. Oread_filessoma o tamanho dos arquivos antes de lê-los, então umpatternlargo demais para logo.
steps:
execute:
before:
- search_files: { tag: estrutura, dirs: ['${APP_DIR}'], ignore: [assets, volumes], max_size: 8KB }
- read_files:
tag: manifestos
dirs: ['${APP_DIR}']
pattern: [/package.json, /composer.json, '/Dockerfile*']
max_size: 40KB
- read_files: { tag: ticket, files: ['${TICKET_FILE}'] }O write_files é o choliba gravando, não o agente: o arquivo sai mesmo de um modelo que não chamaria a ferramenta de escrita, e o agente não precisa de permissão para ele. Os caminhos são relativos à pasta de trabalho ou absolutos (com as variáveis do agente, como ${PROJECT_DIR}); as pastas que faltarem são criadas e o que houver é substituído. Um bloco de código que envolva a resposta inteira (```markdown … ```) sai. Sem resposta (o agente falhou ou não escreveu texto), a ação falha; por isso ela costuma ficar em after.success:
steps:
execute:
after:
success:
- write_files: { files: ['${PROJECT_DIR}/relatorio.md'] }O write_config também é o choliba gravando, no config.json do projeto da execução (--project); o agente não diz o arquivo. A resposta do agente tem de ser um JSON, sem nada em volta além de um bloco de código. Quem confere e grava é o choliba: o valor segue a regra da chave, as outras chaves do arquivo ficam como estão, e uma resposta que não é JSON ou não segue a regra falha sem tocar no arquivo. Hoje a única chave é stack (veja config.json).
steps:
execute:
after:
success:
- write_config: { key: stack }Gravar nas pastas de agentes, skills e MCPs termina a execução com código 1, como qualquer mudança nelas (veja acima).
O que o before produz entra na tarefa que o agente recebe; cada arquivo do read_files e o índice do git_diff vão como dado, dentro de <untrusted_input> (veja Segurança). O after é um try/catch/finally sobre o agente:
| Bloco | Roda quando |
|---|---|
before | antes do agente |
after.success | depois do agente, se ele saiu com 0 |
after.failure | depois do agente, se ele falhou |
after.always | depois de success ou failure, sempre |
Quando uma ação falha:
- no
before, nada mais roda, nem o agente. O choliba termina com o código de saída do comando que falhou (1 para uma ação que não é comando); - no
after, as ações seguintes rodam do mesmo jeito. O choliba termina com o código do agente, se ele falhou; senão, com o da primeira ação que falhou.
Nos dois casos a falha sai tratada no terminal: qual ação, o que ela rodou, o código e as últimas linhas da saída do comando. A saída inteira, stdout e stderr na ordem em que o comando escreveu, fica num log em .cache/steps/, e a falha diz qual (saída completa: .cache/steps/….log); um step que dá certo não deixa log.
✗ execute.before 1/2 falhou — run: bun choliba run tests tt:TT-1 --expect red (código 2)
<as últimas linhas da saída do comando>
O agente não foi executado.A mesma lista em vários modos. O YAML tem âncoras: &nome dá um nome à lista que vem logo depois, e *nome a repete em outro lugar. O implementer usa isso para que plan e ask preparem o mesmo contexto de execute:
steps:
execute:
before: &before # a lista do before de execute ganha o nome "before"
- run: [bun, choliba, run, tests, '${PROJECT}:${TICKET}', --expect, red, --failures, '.cache/test-writer/${TICKET}/red.md']
- read_files: { tag: falhas_red, files: ['.cache/test-writer/${TICKET}/red.md'] }
after:
success:
- run: [bun, choliba, run, tests, '${PROJECT}:${TICKET}', --expect, green]
plan:
before: *before # a mesma lista do before de execute
ask:
before: *before