emyann/criar-um-agente

Criar um agente no Nemia

Um agente é uma contratação: uma pessoa com um trabalho, padrões (suas habilidades) e equipamento (suas ferramentas). A etapa de um fluxo de trabalho é uma posição que ele ocupa; um agente pode ocupar posições em vários fluxos de trabalho. As fábricas de uma pessoa não recebem nenhum agente do Nemia: a equipe de um repositório está em workflows/, a de uma pessoa em ~/.agent-workflows/workflows/, e a página Agentes do quadro escreve a segunda. Leia o LEIAME do Nemia, Um agente é um anexo de um nó, para o formato completo; este é o procedimento e o que custou aprender.

Quem ele é

• Seu nome é o nome do seu arquivo, agents/<nome>.md, um primeiro nome de pessoa em minúsculas (nora), e uma etapa o nomeia por ele (agent: nora). O quadro mostra o nome como o de uma pessoa (Nora) ao lado de um rosto desenhado a partir dele (Blobatar), o mesmo onde quer que apareça.
• role: é o trabalho que ele ocupa, em poucas palavras (Engenheiro de produto); description: diz quando anexá-lo, uma linha. Ambos são linhas próprias do agente, com harnessPrompt:: uma etapa que define um é recusada. O skills: de uma etapa adiciona ao do seu agente (Suas habilidades).
• mcp: nomeia os servidores MCP que suas sessões carregam, pelos nomes que o checkout .mcp.json lhes dá (mcp: playwright). O mcp: de uma etapa adiciona ao do seu agente, assim como seu skills: faz: um servidor que apenas um repositório tem é nomeado pela etapa que precisa dele, para que o agente permaneça portátil. Uma sessão carrega os servidores que seu agente e sua etapa nomeiam e nenhum outro: sem nenhuma linha em nenhum dos dois, não carrega nenhum, e um nome que o checkout não declara recusa a sessão no seu início. Carregar um servidor não permite nenhuma de suas ferramentas: seu limite ainda decide. Um agente que nomeia um não pode ser testado, pois um teste não tem checkout.
• Uma linha name: deve ser igual ao nome do arquivo; card: está aposentado (o cartão é gerado a partir de suas habilidades: npx wf agents card <nome>).

O arquivo

Frontmatter, depois suas instruções. As outras chaves são como suas sessões são executadas — harness, model, effort, context, remote, output, e seu limite — e uma etapa que o nomeia assume cada uma a menos que defina a sua própria. A fiação é da etapa e recusada aqui: after, input, workspace, check, gate, loop, budget, background.

• O limite fica sob o bloco do seu harness: claude: { fence: { permissionMode, tools, allowedTools, disallowedTools } }, ou codex: { fence: { sandbox } }. O bloco contém apenas fence, e um bloco para outro harness que não o do arquivo é recusado. Uma chave de limite no nível superior é a grafia anterior, ainda lida; nemia frontmatter rewrite <pasta> a move para dentro do bloco.
• Diga o que uma etapa pode substituir: overridable: model, effort, fence, skills, cada palavra uma de OVERRIDABLE (model, effort, context, harness, remote, output, fence, skills, mcp). Uma etapa que define qualquer outra coisa é recusada ao carregar, nomeando a chave e o agente. Sem nenhuma linha, uma etapa pode substituir tudo, e nemia start diz para adicionar uma.

---
role: Revisor de código
harness: claude
model: opus
overridable: model, effort, fence
claude:
  fence:
    permissionMode: dontAsk
    tools: Read, Grep, Glob, Bash
    allowedTools: Bash(registro git log:*), Bash(registro git diff:*)
---

• O frontmatter é YAML, como o de uma etapa e o de uma habilidade são, todo valor lido como o texto escrito. Coloque entre aspas um valor que contenha : ou #, ou que abra com um sinal YAML ([, {, *, &, !, |, >, -, ?), como em description: "Revisa uma alteração: sua correção". Escreva um longo como um bloco literal, |- e o valor nas linhas abaixo dele, indentado. Uma chave de lista aceita Read, Grep ou [Read, Grep]; o quadro escreve o primeiro.
• Diga effort: e context: (200k): um trabalho não lê configurações de usuário, e uma sessão sem limite lê até um milhão de tokens em cada chamada.
• auto é recusado ao carregar nos modelos medidos para descartá-lo (haiku, claude-sonnet-4-5); nomeie dontAsk com regras lá.

Suas instruções

O corpo são suas instruções, anexadas ao prompt próprio do Claude Code (harnessPrompt: keep; no-coding remove a seção de codificação do harness, replace coloca as instruções em seu lugar). Mantenha-as genéricas e curtas: quem ele é, pelo que ele é responsável, o que ele nunca faz, como ele encerra um turno, o que seu encerramento contém. O procedimento pertence a uma habilidade, e uma regra que a maquinaria mantém (um limite, uma barreira) não precisa de uma frase. Uma sessão retomada mantém o corpo com o qual começou: uma edição atinge a próxima execução, nunca uma em andamento.

As cinco camadas

As instruções são uma das cinco camadas que moldam um agente além de sua tarefa, cada uma escrita por quem a possui:

1. Instruções — o corpo do agente: quem ele é, onde quer que seja contratado.
2. Instruções personalizadas — o que uma pessoa adiciona a um agente que usa sem reescrevê-lo, mantidas em seu armazenamento, um arquivo por nome de agente (wf agents custom <nome>), nunca na pasta do agente. Apenas palavras: não definem nenhuma chave, então nunca ampliam o limite ou fornecem uma ferramenta. Uma execução as congela quando começa, para que uma edição atinja apenas as execuções posteriores.
3. Os arquivos da pasta — os arquivos que o harness lê da pasta em que o agente trabalha (hoje CLAUDE.md, AGENTS.md): o que está lá para cada agente trabalhando nela. O Nemia não compõe nada deles. Eles estão acima das próprias instruções do agente e abaixo das regras da fábrica e da política da etapa, embora um harness os apresente como substituindo tudo: esse enquadramento é do harness.
4. As regras da fábrica — as regras e políticas de uma fábrica, informadas a cada agente contratado nela: um arquivo por fábrica, mantido no armazenamento (nemia factory rules <nome>), nunca em um repositório. Apenas palavras, e congeladas por uma execução quando começa, como as instruções personalizadas são. Uma etapa em um agente remoto não recebe nenhuma.
5. A política da etapa — as próprias palavras e chaves da etapa: o que esta posição deste processo pede de uma função. Uma camada normal, não uma solução alternativa: diga lá o que um fluxo de trabalho espera e mantenha-o fora das instruções. Uma etapa pode adicionar habilidades, nunca remover nenhuma.

O número é a precedência: onde duas camadas dizem coisas diferentes, o número mais alto vence, e a tarefa está acima de todas elas. A ordem em que as palavras chegam é uma coisa separada — instruções, instruções personalizadas, as regras da fábrica, a política da etapa, depois a tarefa, com os arquivos da pasta lidos pelo harness onde quer que o agente trabalhe. Qual camada possui uma nova instrução é a própria regra de roteamento do Nemia, Para onde vai uma nova instrução, dita uma vez no trecho Cinco camadas enviado: pergunte-a em vez de adivinhar. Limites apenas apertam: uma etapa pode estreitar o limite do seu agente e nunca ampliá-lo — o disallowedTools: de uma etapa adiciona ao do seu agente, e o carregador recusa um tools:, allowedTools:, permissionMode: ou sandbox: de uma etapa que daria ao agente o que seu arquivo não tem. Portanto, as instruções dizem o que vale para a função em todos os lugares, e nada sobre um fluxo de trabalho ou um espaço de trabalho.

Seu encerramento

output: <nome>.schema.json, um JSON Schema ao lado do agente: o que a etapa entrega, decodificado estritamente. Estilo da casa: todo campo described, required, additionalProperties: false.

• Reservados: outcome, summary, artifacts, needs são próprios da execução em cada encerramento; o carregador recusa um esquema que declare um. (A intenção da Iris diz proposedOutcome por esse motivo.)
• Mantenha um esquema igual nas tentativas de uma sessão: uma sessão continuada recebendo um esquema alterado reconstrói todo o cache de prompt.
• Uma etapa lê um encerramento com input: <etapa> de qualquer etapa em que espera, através das etapas intermediárias também; uma etapa que faz loop (loop:) pode esperar em apenas uma etapa, então lê o que veio antes do loop dessa forma (uma etapa de revisão lê a especificação assim).

Suas habilidades

skills: <a>, <b> nomeia pastas contendo um SKILL.md, procuradas em skills/ ao lado da pasta de agentes, depois em .claude/skills/ do repositório, depois no armazenamento, depois nas próprias habilidades do Nemia, por último. tools: deve permitir Skill. O .claude/skills/ do repositório é encontrado apenas quando o repositório é o lugar da etapa, como um início o dá: um teste que carrega uma pasta também passa o lugar. Uma etapa com um agente pode adicionar habilidades com seu próprio skills:: a sessão recebe as do agente, depois as da etapa, cada uma uma vez. O limite do agente já deve carregá-las; uma etapa nunca o amplia.

• Escreva uma habilidade com o método do criador de habilidades: uma description: que diga quando usá-la, um corpo curto, detalhes em arquivos ao lado dela.
• Use a de outra pessoa sem alterações: em um projeto temporário, DO_NOT_TRACK=1 npx skills add <proprietario>/<repo> --skill <nome> --agent claude-code --copy -y; copie a pasta para .claude/skills/, mescle sua entrada em skills-lock.json e adicione seu autor, fonte e licença a THIRD_PARTY_NOTICES.md (MIT pede o aviso em cada cópia). Nunca a edite — o bloqueio a fixa — e adapte-a no corpo do agente. Adquira a habilidade que um modelo pode invocar: uma que diz disable-model-invocation: true é um comando de barra de uma pessoa (grill-me chama apenas grilling).

Seu limite

• Uma função que não escreve nada executa dontAsk. Apenas leituras em seu espaço de trabalho, comandos somente leitura e o que uma regra de permissão nomeia executam; o resto é recusado sem perguntar. As configurações do repositório podem permitir comandos que outras funções precisam que escrevam no espaço de trabalho (uma compilação, por exemplo), então um agente que recebe Bash nega cada um pelo nome em disallowedTools:. Um sub-agente herda o modo e as regras; liste Agent em allowedTools: para que o próprio despacho nunca seja recusado. Permita pelo nome exato cada verificação que a função executa e que as configurações não permitem; sua habilidade escreve cada uma sem adornos, uma por chamada (uma envolvida, canalizada, redirecionada ou atrás de cd, git -C, VAR= ou for é recusada), e envia uma leitura ou pesquisa para Read, Grep ou Glob, não Bash.
• Uma função que edita executa auto, e nega pelo nome o que nunca deve fazer: Bash(git push), Bash(git push:*), Bash(git branch -D:*), Bash(git branch --delete --force:*), Bash(pkill:*), Bash(killall:*), mcp__playwright__browser_run_code_unsafe.
• Uma etapa apenas aperta, e apenas onde overridable: nomeia fence. Uma etapa que precisa de uma ferramenta, uma permissão ou um modo que o arquivo do seu agente não fornece precisa de outro agente; o disallowedTools: de uma etapa adiciona ao do seu agente: escreva apenas as negações que a etapa adiciona; ela nunca pode remover uma do agente.

Conversando com uma pessoa

Uma etapa é um trabalho no Agent SDK: ela não pode esperar dentro de uma conversa. Para perguntar, ela finaliza como blocked com suas perguntas; a pessoa responde no quadro ou com wf retry <execucao> <etapa> --message "…", e a mesma sessão continua com as respostas como seu próximo turno. Diga isso no corpo de um agente que entrevista, e coloque uma barreira na etapa cujo encerramento uma pessoa deve aceitar (gate: true). O último turno de um trabalho é sua finalização: um agente que executa comandos longos (o e2e) recebe a instrução de executá-los em primeiro plano ou esperar por eles, nunca finalizar com um em execução (a primeira compilação web de um engenheiro uma vez finalizou antes de seu e2e terminar). Um encerramento finalizado como blocked é lido por conta própria, então um agente que pergunta em rodadas carrega tudo decidido até agora em cada uma: a terceira rodada de um entrevistador uma vez deixou cair suas decisões anteriores. Declare as perguntas como um campo do esquema de saída, { "x-shape": "questions", "description": "…" }, que o carregador expande para uma forma estrita: o quadro as desenha como escolhas que uma pessoa responde clicando. Uma etapa com barreira que sabe o que as etapas seguintes custarão declara { "x-shape": "budgets", "description": "…" } ao lado delas: uma lista de { step, usd, why }, cada uma uma etapa após a barreira, uma vez, em dólares acima de zero, why os números pelos quais o valor foi calculado. A barreira os mostra ao lado do encerramento, e aprová-los os torna os limites dessas etapas, com qualquer valor que a pessoa alterou (nemia approve <execucao> <etapa> --budget <etapa>=<valor>); um limite acima do budget: próprio de uma etapa é dito lá, e nunca aprovado sem ser perguntado. Um encerramento cujos orçamentos nomeiam outra etapa, ou nenhum valor, é recusado de volta à sua sessão.

Verifique

1. npx wf agents card <nome> a partir do repositório: o carregador real lê o arquivo — suas chaves, os nomes reservados de seu esquema, cada habilidade encontrada — e imprime o cartão, ou recusa em palavras que nomeiam a correção.
2. As próprias verificações do repositório, onde suas proteções leem cada pasta que ele envia (os limites, as etapas congeladas, a ida e volta da renderização): execute-as passando por qualquer cache que não veja a pasta de fluxos de trabalho.
3. Execute-o: um fluxo de trabalho com barreira que o nomeia, em um pequeno cartão real, e leia seu encerramento antes de aprovar.
4. Nomeie o novo agente onde o repositório lista seus agentes.

Quando você aprende algo

Criar um agente é como esta habilidade é testada. Quando uma etapa aqui estava errada ou faltando — uma recusa que você encontrou, uma chave que o surpreendeu — corrija este arquivo na mesma alteração que o agente, em no máximo três linhas, com o arquivo que contém a regra.