Agents Best Practices: projete o harness antes de ampliar autonomia

ANÁLISE EDITORIAL

Um agente de IA pode responder bem em uma demonstração e ainda ser perigoso em produção. O problema costuma estar fora do modelo: ferramenta ampla demais, aprovação tratada como texto, contexto que some após a compactação e ausência de um critério verificável de parada. A Agents Best Practices, mantida no repositório público DenisSergeevitch/agents-best-practices, organiza essas decisões como um projeto de harness, a camada que valida, autoriza, executa, registra e devolve observações ao modelo.

Esta curadoria fixou o commit 8ae085045bd6cddfab22c740c95dd2d764117ffc, observado em 7 de setembro de 2026. O pacote hospedado pelo Bastidores contém SKILL.md, 21 referências Markdown, a licença MIT e ORIGEM.md. Não inclui imagens, ícones, dependências, executáveis, credenciais, dados nem projetos gerados.

Ilustração editorial exclusiva do Bastidores da IA. A capa representa um ciclo abstrato de proposta, validação, permissão, execução e observação. Não é captura de tela, interface real, benchmark, selo, certificação nem material oficial do projeto.

O que esta Skill faz de verdade

O SKILL.md auditado trata o harness como o plano de controle ao redor do modelo. O modelo propõe. A aplicação valida o schema, verifica permissão, pausa para aprovação quando necessário, executa por uma ferramenta estreita, registra o resultado e decide se o loop continua dentro do orçamento.

A instrução começa por seis perguntas: domínio, autonomia, risco, duração do estado, superfície de ferramentas e evidência de conclusão. Quando o pedido é construir um agente, ela direciona para um blueprint de MVP com o menor loop confiável. Modos avançados, como ferramentas descobertas em tempo de execução, execução especulativa e agentes recursivos, só entram quando o caso realmente os exige.

As referências separam arquitetura, loop, permissões, memória, planejamento, orquestração, observabilidade, avaliações e APIs de provedores. Isso reduz a tentação de colocar todos os controles em um prompt enorme. A tese central é verificável: autoridade, credenciais, orçamento e políticas precisam permanecer em código ou configuração controlada pelo host.

Para quem serve

Serve a equipes que projetam agentes para suporte, pesquisa, operações, desenvolvimento, vendas, finanças, educação ou outros fluxos com ferramentas reais. Também ajuda quem já tem um protótipo e precisa explicar por que ele repete chamadas, esquece aprovações, custa mais do que deveria ou não deixa rastros suficientes para diagnosticar uma falha.

A finalidade é diferente de itens já publicados. Planning With Files preserva contexto de tarefas longas. Architecture Decision Records registra decisões técnicas. Agent Reach organiza pesquisa em plataformas externas. Agents Best Practices conecta essas preocupações ao runtime completo, com matriz de risco, contratos de ferramenta, memória, avaliações e critérios de lançamento.

Ela não entrega um framework pronto, servidor ou agente funcional. Também não decide sozinha qual ação deve ser autorizada. O valor está em transformar um pedido amplo em um desenho de MVP, um roteiro de auditoria ou uma lista de mudanças que possa ser implementada e testada.

Compatibilidade e pré-requisitos

O README fixado declara compatibilidade com Codex, Claude Code e outros runtimes que carreguem o padrão Agent Skills. A especificação do formato pode ser conferida em agentskills.io. A Skill é documental: não exige runtime Python, Node ou chave de API para ser lida.

Para produzir algo útil, o agente precisa receber um domínio concreto, limites de autonomia, sistemas que poderá acessar e uma definição de pronto. Projetos ligados a dados privados, comunicação externa, finanças, saúde, segurança ou ações destrutivas precisam de políticas executadas fora do modelo e revisão humana adequada ao risco.

As referências incluem padrões para OpenAI, Anthropic e APIs compatíveis, mas versões e recursos de cada provedor mudam. Use a lista de fontes da própria Skill como ponto de partida e confirme a documentação oficial antes da implementação.

Instalação recomendada

O mantenedor documenta instalação global pelo Skills CLI:

npx skills add DenisSergeevitch/agents-best-practices -g

O parâmetro -g torna a Skill disponível no nível do usuário. Para uma avaliação inicial, prefira instalação por projeto, quando o cliente permitir, ou examine primeiro a árvore fixada. Confira o pacote npx, o destino e o diff antes de aceitar alterações globais.

O ZIP local pode ser extraído diretamente na pasta de Skills reconhecida pelo agente. Preserve SKILL.md ao lado de references, pois o carregamento progressivo depende desses caminhos relativos. Compare o SHA-256 publicado nesta página e mantenha LICENSE e ORIGEM.md no pacote.

Configuração antes do primeiro uso

Descreva o trabalho em linguagem operacional. Informe quem usa o agente, quais fontes são autorizadas, o que ele pode apenas ler, o que pode rascunhar e quais ações precisam de aprovação. Defina limites de passos, tempo, custo, tentativas e volume acumulado. Um limite por chamada não impede que várias chamadas pequenas ultrapassem um teto de negócio.

Liste ferramentas com entradas estreitas e resultados estruturados. Evite nomes como execute_anything, write_database ou send_message. Prefira ações específicas, por exemplo ler um cliente autorizado, criar um rascunho rotulado ou solicitar aprovação com um resumo do efeito.

Separe estado durável de conversa. Plano ativo, aprovações, tarefas, artefatos e orçamento não devem existir somente no histórico do chat. A referência Context, Memory and Compaction mostra como compactar sem perder o estado operacional.

Primeiro uso seguro

Comece em modo de blueprint, sem conectar contas. Peça um agente pequeno, de leitura e rascunho, para um caso fictício. Exija uma matriz de ferramentas, risco, aprovação, resultado e evidência de conclusão. O primeiro artefato deve ser revisável antes de qualquer código ou credencial.

Depois faça um exercício com ferramentas simuladas. Cada proposta precisa passar por validação local de schema e permissão. Toda chamada deve receber um resultado, inclusive negação, timeout ou erro. Force cenários de orçamento esgotado, ferramenta indisponível, conteúdo malicioso em uma fonte e compactação no meio de uma aprovação.

Somente conecte um sistema real quando os testes demonstrarem que não há escrita externa sem registro de aprovação. O guia oficial da OpenAI sobre guardrails e aprovação humana e a orientação da Anthropic sobre agentes eficazes ajudam a confrontar o desenho com fontes primárias.

Como o fluxo deve funcionar

1. Limite do MVP: declare o menor resultado útil e os itens adiados.
2. Autonomia: escolha resposta, rascunho, ação aprovada ou autonomia limitada por política.
3. Contexto: reúna somente fontes necessárias e marque conteúdo externo como não confiável.
4. Proposta: o modelo retorna texto ou uma chamada tipada.
5. Validação: o host verifica schema, identidade, recurso, orçamento e política.
6. Aprovação: efeitos de maior risco pausam com um resumo claro do impacto.
7. Execução: uma ferramenta estreita atua apenas no escopo autorizado.
8. Observação: sucesso, erro, negação ou timeout voltam em formato estruturado.
9. Parada: o loop encerra por resultado, limite ou bloqueio explícito.
10. Avaliação: traces e casos de falha provam se o comportamento atende ao lançamento.

Esse desenho aparece na referência Agentic Loop. Para decomposição em pacotes duráveis de trabalho, consulte Workflow Orchestration. A própria Skill recomenda não adotar vários agentes antes que um loop único tenha falhado em avaliações mensuráveis.

Resultado esperado

Para um agente novo, a saída esperada é um blueprint específico ao domínio: objetivo, escopo do MVP, nível de autonomia, loop, hierarquia de instruções, registro de ferramentas, memória, planejamento, aprovações, observabilidade, avaliações e caminho mínimo de implementação. Cada ferramenta deve ter risco e contrato de resultado claros.

Para um agente existente, a saída deve localizar falhas no harness e ordenar correções por impacto. Um bom relatório liga cada problema a um comportamento observado, como chamada sem resultado, aprovação perdida, retry ilimitado ou exposição de dado em trace. Recomendações sem evidência devem ser rotuladas como hipótese.

O documento não é prova de segurança nem substitui testes. O critério final depende de avaliações reproduzíveis, revisão de traces e confirmação de que políticas críticas são aplicadas pelo runtime, não por boa vontade do modelo.

Permissões, privacidade e riscos

O pacote é somente texto, mas seu uso pode levar o agente a ler código, arquitetura, tickets, traces e documentação interna. Delimite pastas, conectores, contas e período. Remova segredos antes de anexar exemplos. Logs devem registrar eventos operacionais sem expor raciocínio oculto, tokens, cookies ou dados pessoais desnecessários.

Ferramentas externas e MCP ampliam a superfície de ataque. Descrições descobertas, páginas, e-mails e documentos são dados não confiáveis, não instruções de maior autoridade. A especificação MCP define o protocolo, mas o host ainda precisa verificar permissão, identidade, recurso e versão em cada chamada.

Execução especulativa e agentes recursivos são perfis avançados. Não os ative para reduzir latência ou aumentar autonomia sem baseline, orçamento separado, isolamento, cancelamento comprovado e rollback. A referência Security and Observability deve acompanhar qualquer implantação real.

Erros comuns

• Prompt como política: mova autorização crítica para o runtime.
• Ferramenta genérica: divida o efeito em contratos estreitos.
• Sem resultado de ferramenta: devolva negação, erro e timeout ao loop.
• Orçamento só por chamada: aplique também limites acumulados do negócio.
• Memória sem ciclo de vida: defina fonte, escopo, expiração e exclusão.
• Compactação de prosa: preserve estado ativo e reidrate-o de forma explícita.
• Vários agentes cedo demais: prove primeiro o limite do loop simples.
• Trace com segredo: reduza e masque dados antes de armazenar.
• Teste só do caminho feliz: cubra injeção, negação, timeout e limite.
• Blueprint genérico: associe ferramentas, riscos e evidências ao domínio real.

Versão, licença e origem verificadas

Em 7 de setembro de 2026, a API pública do GitHub registrou 2.276 estrelas, repositório público, não arquivado, branch padrão main e HEAD 8ae085045bd6cddfab22c740c95dd2d764117ffc. O repositório não tinha release e o SKILL.md não declara versão semântica. A curadoria usa commit e blob f706d695a40c1432ad08e771b5a880ba513d0395 como identificadores.

A licença MIT permite redistribuição com preservação do aviso. O ZIP tem 117.499 bytes e SHA-256 0aca959b4c87c1002e208b7b1dad495218c178656d14dd937ffcce29e5ad4f5c. Ele contém exatamente 24 arquivos: SKILL.md, 21 referências Markdown, LICENSE e ORIGEM.md.

O commit auditado, o arquivo principal e a auditoria de cobertura são as referências para futuras atualizações.

Checklist antes de automatizar

• Fixar repositório, commit, blob e hash do pacote.
• Definir domínio, usuário, autonomia, risco e estado.
• Começar pelo menor loop único que entregue valor.
• Manter autoridade, credenciais e políticas fora do modelo.
• Usar ferramentas estreitas, tipadas e auditáveis.
• Separar leitura, rascunho, escrita externa e ação destrutiva.
• Preservar aprovações, plano, tarefas e orçamento na compactação.
• Registrar resultados sem segredos ou raciocínio oculto.
• Testar erro, negação, timeout, injeção e esgotamento de limite.
• Liberar autonomia somente quando as avaliações justificarem.

Fontes primárias

• Repositório oficial Agents Best Practices
• Árvore fixada no commit
• SKILL.md fixado
• README com instalação e casos de uso
• Licença MIT
• MVP Agent Blueprint
• Tools and Permissions
• Evals
• Agent Skills specification
• OpenAI function calling
• OpenAI agents
• OpenAI guardrails and approvals
• Anthropic, Building effective agents
• MCP Specification 2026-07-28