Como criar Agentes de IA em 2026 (Curso Completo)

aqui está a verdade que ninguém conta para os construtores de IA.

a maioria deles está construindo demos

tudo o que você precisa construir é

um agente de IA de nível de produção

TLDR; se você não quer ler, dê este link ao seu agente e faça perguntas: ➡️https://github.com/codejunkie99/agentic-harness

aqui está o tweet que começou tudo

o problema é que a maioria dos engenheiros de IA não tem ideia clara do que realmente construir quando decidem levar agentes a sério.

alguns recorrem ao LangChain porque as demos multi-agente parecem limpas no YouTube, e passam as próximas duas semanas lutando com interoperabilidade Python e incompatibilidades de runtime assíncrono antes de descartar tudo.

alguns tentam construir uma camada de orquestração personalizada do zero: um loop, um armazenamento de sessão, um montador de contexto — e nunca terminam o agente real porque a infraestrutura consumiu o cronograma.

outros copiam o exemplo de webhook hello-world, recebem uma resposta JSON de volta, assumem que entenderam o sistema, e entregam algo que quebra na primeira vez que uma sessão passa de dez minutos, um sandbox remoto cai no meio da tarefa, ou a janela de contexto enche sem compactação configurada.

o resultado geralmente é o mesmo: muita encanação, nenhum agente de produção, e nenhum modelo mental do que um runtime de agente de produção realmente parece.

se seu objetivo é construir e entregar agentes reais em 2026, você não precisa aprender seis frameworks.

você precisa entender um runtime profundamente o suficiente para dominar um agente de produção do handler ao deploy.

isso significa aprender como:

conectar a arquitetura de três camadas para que sua lógica de handler sobreviva a trocas de provedor e mudanças de destino sem tocar no código do agente
usar sessões e tarefas corretamente para que trabalhos longos não contaminem seu próprio contexto
escrever papéis e habilidades que moldam o comportamento do modelo sem recompilar nada
configurar compactação para que sessões rodando por duas horas não comecem a alucinar na primeira hora
apontar HttpSessionEnv para sandboxes remotos para que o binário rode localmente enquanto a execução roda no Linux
escolher o destino de build correto: nativo, node ou Cloudflare, sem reescrever nenhuma lógica do agente entre eles
gerar conectores em vez de escrever adaptadores manualmente, e entender por que essa distinção importa sob carga real

este guia é uma explicação técnica completa construída a partir do código real do agentic-harness, seis semanas construindo e quebrando agentes reais com ele, e os modos de falha que mais custaram tempo para depurar.

o texto tem MAIS DE 4.000 PALAVRAS e extrai diretamente do repositório e da documentação — não resumos de segunda mão ou exemplos de nível demo.

mas seu valor real é que cada seção tem um trecho de código funcional, uma explicação clara de por que a decisão foi tomada, e o modo de falha exato que você encontrará se pular a seção.

dessa forma, quando você terminar de ler, poderá dominar um agente de produção de ponta a ponta — do primeiro handler ao sandbox ao job de CI que o executa sem supervisão.

construir esse entendimento levou mais de 6 SEMANAS de trabalho diário com o código, a maior parte depurando coisas que pareciam corretas antes de quebrarem sob condições reais.

agora vamos nessa. ⬇️

A Forma do Projeto

duas crates. um binário. cada destino de execução é uma escolha de configuração, não uma reescrita.

o SDK é uma biblioteca que você puxa para qualquer projeto Rust. o CLI a envolve. seu agente é um binário Rust que começa com use agentic_harness::prelude::*.
cargo build é o pipeline inteiro. sem bundler. sem etapa de transpilação. sem runtime de linguagem na máquina de destino. um executável autocontido mais um manifest.json.

a restrição de design que impulsionou tudo: o mesmo binário do agente deve rodar no seu laptop em modo interativo, em um job do GitHub Actions clonando um repositório novo, contra um sandbox remoto E2B via HTTP, e em um limite do Cloudflare Worker sem alterar uma única linha de lógica do agente entre eles.

cada decisão neste código existe para honrar essa restrição.

As 3 camadas e por que cada uma existe

o modelo mental são três anéis concêntricos. saber onde cada limite está economizará mais tempo de depuração do que qualquer outra coisa neste guia.

seu código Rust é o anel externo.

você escreve handlers. handlers recebem um AgentContext. eles chamam sessões. sessões chamam o modelo, leem arquivos, escrevem arquivos, executam comandos shell, geram tarefas, conectam-se a servidores MCP.
você nunca toca em um cliente HTTP diretamente. você nunca analisa uma resposta do modelo diretamente. o SDK cuida de ambos.

o harness é o anel do meio.

ele gerencia o registro de agentes, roteia identidade por caminho de URL, lida com persistência de sessão entre chamadas, compactação de contexto quando as sessões crescem, descoberta de papéis e habilidades, precedência de seleção de modelo, e o trait ModelClient neutro em relação ao provedor.
isso permite trocar Anthropic por OpenAI por uma instância local do Ollama sem tocar no código do handler.
o harness é o que torna sua lógica de agente reutilizável entre provedores e destinos.
também é onde todas as coisas que quebram em produção são tratadas — estado de sessão, estouro de contexto, falhas de provedor, ordenação de requisições concorrentes.

os destinos de execução são o anel interno.

sistema de arquivos local. checkout de CI. HttpSessionEnv apontado para Daytona ou E2B. limite do Cloudflare Worker.
o harness não se importa com qual você está usando. seus handlers também não. eles chamam session.shell() e session.write() e o harness traduz isso para o que o destino subjacente precisar.
essa separação é o ponto principal. quando o E2B lançar uma nova versão da API, você atualiza o conector, não sua lógica de agente.
quando a Anthropic lançar o claude-opus-4-7, você atualiza o runtime.json, não seus handlers. o anel externo permanece limpo porque o anel do meio absorve toda a rotatividade.

Configuração de runtime: o arquivo que controla a camada do modelo

antes de escrever um único handler, você precisa do runtime.json no seu workspace.

coloque isso em .agentic-harness/config.json ou na raiz do workspace como agentic-harness.json. load_workspace_context() pega automaticamente.

a seleção de modelo em tempo de execução segue esta precedência:

PromptOptions::model(...): substituição por chamada
os metadados do modelo do papel selecionado: padrão por papel
defaultModel da configuração de runtime: padrão do workspace

a coisa a entender: o ID do modelo deve estar registrado antes que você possa usá-lo. openaiCompatibleModels é a lista que o harness usa para configurar o cliente de chat-completions embutido. se seu modelo não estiver nessa lista, você recebe um erro claro na inicialização em vez de uma falha confusa no meio da sessão.

para gateways compatíveis com OpenAI, a configuração parece a mesma. aponte baseUrl para seu gateway:

nunca escreva uma chave de API literal no runtime.json. use apiKeyEnv e mantenha a chave real em seu ambiente.
o harness lê a variável de ambiente no momento da requisição, não na inicialização — o que significa que você pode rotacionar chaves sem reiniciar o servidor.

Identidade do agente é um caminho de URL, nunca uma consulta de registro

esta foi a primeira decisão de design que me surpreendeu. agora acho que é a certa.

não há sistema de ID de agente. nenhuma chave de registro. nenhum UUID que você gera. a identidade do seu agente é POST /agents/<nome>/<id>.

o harness lida com toda a contabilidade do estado da sessão por trás dessa URL.
a razão pela qual isso funciona: todo chamador em todo sistema já sabe como construir um ID significativo a partir do contexto. um número de PR. um ID de execução. um timestamp combinado com um nome de tarefa. um handle de usuário.
você não precisa de um endpoint de criação de sessão. você não precisa armazenar IDs de sessão separadamente. a URL é a sessão.

o handler do agente no lado Rust chama ctx.id() para obter o ID que o chamador forneceu:

Sessões: o contexto de execução com estado

uma sessão é mais do que um thread de conversa. é o contexto completo de execução para uma invocação de agente.

ela contém:

histórico de mensagens com o modelo
acesso ao sistema de arquivos do workspace (ler, escrever, editar, grep, glob, stat, readdir)
execução de shell com controle de cwd e env
registros de ferramentas (servidores MCP, ferramentas personalizadas)
o papel atribuído e sua sobreposição de prompt de sistema
o orçamento de compactação e o watermark do histórico

você obtém uma sessão chamando ctx.session_with_id() com qualquer ID que faça sentido:

as sessões persistem entre chamadas HTTP quando você usa o mesmo ID. chame o mesmo endpoint de agente três vezes com o mesmo ID de sessão, o modelo vê todas as três trocas como uma conversa contínua.
o histórico se acumula automaticamente. você não o gerencia.
isso é o que torna fluxos de trabalho de várias etapas possíveis sem gerenciar estado você mesmo. você continua chamando session.prompt() e o harness cuida de todo o resto.

quando você precisa passar grandes quantidades de contexto junto com um prompt, leia o arquivo e formate inline:

a sessão gerencia a contagem de tokens para que você não estoure acidentalmente a janela de contexto no meio da conversa. quando você está perto do orçamento, a compactação é acionada. mais sobre isso em uma seção posterior.

Tarefas: sessões filhas focadas que mantêm o pai limpo

este é o primitivo que eu gostaria de ter entendido no primeiro dia. é a diferença entre agentes que permanecem coerentes em trabalhos longos e agentes que começam a alucinar no meio do caminho.
uma tarefa é uma sessão filha única. histórico novo. workspace compartilhado. retorna um resultado para o pai. o histórico do pai nunca vê nenhum raciocínio intermediário da tarefa.

a tarefa de pesquisa é executada em isolamento. toda a sua cadeia de raciocínio.
cada observação intermediária que o modelo fez sobre o código, cada "espera, deixe-me verificar este arquivo também", fica dentro da tarefa.
a sessão pai recebe um resumo limpo. isso é tudo que ela vê.

por que isso importa na prática: quando você executa análise exploratória diretamente dentro de uma sessão de longa duração, o histórico enche com chamadas de ferramentas intermediárias, respostas parciais e raciocínio do modelo sobre coisas que não são mais relevantes.

o modelo ancora nesse ruído quando não deveria. a compactação eventualmente dispara e perde contexto que você realmente precisava. tarefas são a correção cirúrgica.

a regra: se o subproblema tem uma entrega clara e não precisa do histórico de conversa do pai para ser concluído, transforme-o em uma tarefa. o limite para "transformar em tarefa" é mais baixo do que você pensa.

para análise paralela em uma base de código: o padrão cartógrafo, distribui tarefas e coleta resultados:

cada tarefa é limpa. cada tarefa é focada em exatamente um diretório. a sessão pai coleta os resultados e escreve o documento final.

se você tem 12 módulos, você executa 12 tarefas focadas, cada uma começando com zero bagagem das outras.

Papéis e habilidades: moldando comportamento sem recompilar

papéis vivem em .agentic-harness/roles/. habilidades vivem em .agents/skills/. ambos são descobertos automaticamente quando o harness inicia.
papéis são sobreposições de prompt de sistema com escopo para uma chamada. aplicados no momento da chamada e descartados depois. eles não persistem no histórico de mensagens. não se acumulam entre chamadas.

a cadeia de precedência: papel da chamada > papel da sessão > papel do agente > nenhum papel.

o frontmatter do modelo é opcional, mas útil. permite rotear papéis específicos para modelos específicos.
seu papel de explicador roda no claude-sonnet-4-6 para velocidade e custo. seu auditor de segurança roda no claude-opus-4-7 para profundidade. você configura isso uma vez no arquivo de papel e nunca mais pensa nisso.
habilidades são arquivos descritores de comportamento que o modelo lê no início de uma sessão.
são arquivos markdown em .agents/skills/. o harness os encontra automaticamente. você não os registra em lugar nenhum.

o uso prático: uma biblioteca de habilidades junto com sua base de código descreve como você trabalha. formato de mensagem de commit, bibliotecas preferidas, convenções de nomenclatura de migração, padrões de design de API, requisitos de teste.

o modelo lê isso antes de cada sessão. você edita o markdown. o comportamento é atualizado na próxima execução. sem recompilação.

o modelo lê isso. ele escreve commits que correspondem à sua convenção. você não precisa lembrá-lo a cada sessão. você mantém um arquivo.

O loop do agente de codificação em detalhes completos

o loop do agente de codificação é o caso de uso principal para o qual o CLI foi construído. também é onde mais coisas podem dar errado se você configurá-lo incorretamente.

o comando completo com todas as opções que importam:

o que cada flag faz e por que importa:

--workspace . define a raiz. todas as operações de arquivo são isoladas aqui. o agente não pode ler ou escrever fora deste caminho, aplicado no nível do harness — não confiando no modelo para se auto-restringir.
--llm auto seleciona o modelo a partir de defaultModel na sua configuração de runtime. use --llm anthropic/claude-opus-4-7 para tarefas complexas que precisam de raciocínio profundo, ou --llm anthropic/claude-sonnet-4-6 para iteração mais rápida.
--deny-path é um bloqueio duro. corresponde ao estilo de prefixo, então --deny-path config/ cobre tudo abaixo de config/. audite seu workspace antes da primeira execução e enumere cada caminho que contém segredos ou configuração de produção — não apenas .env.
--approve-dependencies permite modificações no Cargo.toml sem uma etapa de aprovação humana. deixe isso de fora se quiser revisar cada nova crate antes de ser adicionada.
--commit auto-adiciona todas as alterações e as commita no final de uma execução bem-sucedida com a mensagem que você fornecer. sem essa flag, as alterações chegam como modificações não preparadas para você revisar.
--pr abre um pull request a partir do commit. requer um estado git limpo antes da execução e um branch real, não um HEAD destacado.

o loop em si: Inspecionar → Brief → LLM + Ferramentas → Editar + Testar → Commit · PR.

inspecionar: lê a estrutura do workspace, carrega habilidades e papéis, identifica os arquivos mais provavelmente relevantes para o prompt.
escreve seu entendimento em coding-brief.md antes de tocar em qualquer código.
brief: o modelo se compromete com um plano. você pode ler .agentic-harness/runs/<id>/coding-brief.md no meio da execução para ver o que ele decidiu.
se o brief parecer errado, mate a execução. é mais barato reiniciar com um prompt mais claro do que deixar o agente executar um plano ruim.
LLM + ferramentas: o loop de editar-testar. o modelo faz alterações, executa a suíte de testes, lê a saída, faz mais alterações. itera até que os testes passem, o limite de iteração seja atingido, ou ele decida que a tarefa está completa.

commit · PR: adiciona, commita, envia, abre o PR com o diff anexado.

cada execução escreve seis artefatos em .agentic-harness/runs/<id>/:

coding-brief.md: o plano ao qual o agente se comprometeu antes de escrever qualquer código
summary.md: relato legível por humanos do que foi feito, o que foi tentado e por quê
run.json: metadados estruturados: modelo usado, duração total, contagens de tokens de entrada/saída, contagem de iterações, status de saída final
events.jsonl: cada chamada de ferramenta individual em ordem com entradas e saídas completas, para depurar o que deu errado
diff.patch: o diff completo de todas as alterações de arquivo
checks.json: resultados finais de teste e lint que determinaram sucesso ou falha

Dicas para Lembrar

trate estes como logs estruturados, não saída efêmera. eu commito artefatos de execução no repositório para qualquer tarefa que eu precise ser capaz de reproduzir.
o run.json sozinho — 2KB — diz o modelo, os custos de token e se foi bem-sucedido. o events.jsonl diz exatamente o que o agente fez e em que ordem quando você precisa depurar uma execução ruim.

para CI, o padrão é:

HttpSessionEnv: executando o binário localmente, executando remotamente

esta é a capacidade que demorei mais para entender completamente. agora uso em quase todas as tarefas que tocam infraestrutura.
o binário do agente roda em sua máquina ou no CI. as operações de sistema de arquivos e shell executam dentro de um sandbox remoto.
o agente não sabe nem se importa em qual ambiente está.

use agentic_harness::HttpSessionEnv;

o protocolo de fio é JSON sobre HTTP. toda operação:

exec
read
write
edit
grep
glob
stat
readdir
mkdir
rm

tem uma forma de requisição/resposta definida.

qualquer sandbox que implemente este protocolo funciona como um destino HttpSessionEnv.

para conectar um sandbox nomeado:

os conectores embutidos lidam com autenticação e boilerplate de ciclo de vida para Vercel Sandbox, Daytona e E2B:

o caso de uso concreto para o qual uso isso com mais frequência: reproduzir falhas de CI em um ambiente Linux limpo.
o agente clona o repositório no hash de commit exato que falhou, executa o comando de teste exato que falhou, lê a saída completa, diagnostica a falha e escreve um relatório.
eu leio o relatório. nunca toquei em minha máquina local. o sandbox é descartado quando a sessão termina.

a questão de desempenho que ninguém avisa: cada chamada de shell via HttpSessionEnv é uma viagem de ida e volta de rede. loops apertados: editar, testar, verificar saída, editar — acumulam latência rapidamente.

um loop de 40 iterações que leva 5 segundos localmente leva vários minutos contra um sandbox remoto se cada iteração fizer três chamadas de shell separadas.

a correção: agrupar trabalho de shell em scripts.

uma chamada por iteração em vez de três. escreva o script uma vez, execute-o repetidamente. a diferença de latência em um loop de 40 iterações é real.

Destinos de build: mesma base de código, três formas de deploy

nativo é o padrão. um binário. um manifesto. nada mais na máquina de destino. roda em qualquer lugar que possa executar um binário Linux nativo.

node é para plataformas de hospedagem que exigem um ponto de entrada Node. o build gera server.mjs que inicia o binário Rust nativo como um processo filho e faz proxy HTTP para ele. a lógica do agente ainda roda como Rust. a camada Node é um shim HTTP de 30 linhas.

Cloudflare é para deploy de borda.

o build gera um arquivo de limite de Worker e vincula um adaptador de aplicativo compatível com Worker.
handlers compilam para WASM via o WASM JSON ABI.
bindings de Durable Object lidam com persistência de sessão via Cloudflare KV.

a restrição importante sobre Cloudflare: Workers não suportam comandos shell de longa duração. eles não têm um sistema de arquivos real.

eles não suportam cargo ou qualquer ferramenta de build. --target cloudflare é para manipulação de webhook, metadados de rota, pequenos endpoints de controle e roteamento de Durable Object — não para trabalho de codificação.

para qualquer coisa que precise executar cargo test, delegue a um processo nativo ou sandbox remoto.

a matriz de decisão prática:

entregar um agente como uma API que outros serviços chamam → nativo atrás de nginx ou uma plataforma gerenciada
hospedar em Railway, Render ou uma plataforma que espera Node → node
ingestão de webhook, roteamento leve, gerenciamento de estado de Durable Object → cloudflare
todo o resto → nativo

Saída guiada por esquema: structs Rust tipadas a partir de respostas do modelo

pedir ao modelo para retornar JSON e esperar que ele faça é metade da solução.

ter o harness extraindo, validando e desserializando em sua struct Rust é a solução completa.

o modelo pode retornar prosa de raciocínio junto com a carga tipada na mesma resposta. o harness extrai o bloco de resultado entre

marcadores ---RESULT_START--- e ---RESULT_END---. você obtém uma struct Rust. segurança de tipo em tempo de compilação da saída do modelo para sua lógica de handler.
o esquema faz duas coisas: diz ao modelo qual forma produzir, e dá ao harness algo para validar antes da desserialização.
se o modelo retornar algo que não corresponde ao esquema, você obtém PromptError::SchemaValidationFailed em vez de um pânico três locais de chamada depois, quando você acessa um campo ausente.

Ferramentas MCP: alcançando fora do sandbox

quando o agente precisa de capacidades além de arquivo e shell, connect_mcp é a escotilha de escape.

o agente obtém o conjunto completo de ferramentas do servidor MCP. nenhuma definição de ferramenta para escrever. as descrições vêm do servidor. o modelo decide quando chamar qual ferramenta com base nessas descrições.

você pode conectar vários servidores MCP a uma sessão:

o modelo chama ferramentas com base em suas descrições. uma descrição vaga como "pesquisar sentry" é chamada inconsistentemente.
uma descrição que diz "chame isso antes de responder a qualquer pergunta sobre erros, incidentes ou problemas de produção" é chamada de forma confiável.
se você controla o servidor MCP, escreva descrições prescritivas: diga ao modelo quando chamar, não apenas o que ele retorna.

Conectores: gerando adaptadores em vez de escrevê-los

em vez de escrever código de adaptador manualmente contra uma API desconhecida, passe uma receita de conector para seu agente de codificação:

a receita do conector é uma descrição estruturada da API do sandbox e do contrato SessionEnv que ela precisa satisfazer.
o agente de codificação a lê, escreve o módulo adaptador Rust, lida com autenticação, envolve o ciclo de vida do provedor e o expõe como um HttpSessionEnv.
você revisa o diff. você o mescla. o adaptador vive em seu projeto. agora é seu código.

eu conectei Daytona usando isso em cerca de 20 minutos, incluindo o ciclo de revisão completo. o agente acertou o formato do cabeçalho de autenticação na primeira tentativa.

escrever o adaptador do zero contra a documentação do Daytona teria levado a maior parte de uma tarde e pelo menos duas suposições erradas sobre o fluxo de refresh token.

uma vez que o conector é gerado:

Compactação automática: lidando com sessões longas sem perder contexto

sessões de longa duração acumulam histórico.

eventualmente elas estouram a janela de contexto do modelo.

o harness lida com isso automaticamente, mas você precisa configurá-lo corretamente ou perderá contexto exatamente no momento errado.

context_window_tokens é o orçamento total para a sessão.

reserve_tokens é o que você reserva para a resposta do modelo. o limite efetivo para o histórico é context_window_tokens - reserve_tokens.
keep_recent_messages é o número de mensagens no final que são sempre preservadas literalmente, independentemente da compactação.

quando o histórico excede o orçamento, o harness pede ao modelo para resumir tudo entre o prompt de sistema e a cauda mantida.

esse resumo substitui a seção do meio. as mensagens da cauda permanecem intactas. a sessão compactada é menor e a próxima chamada cabe dentro do orçamento.

a troca é real: resumos perdem precisão. uma decisão específica tomada 50 mensagens atrás — "escolhemos authlib porque é a única biblioteca com suporte a PKCE que funciona com o modelo de middleware do axum" — pode sobreviver como "escolhemos authlib para autenticação" no resumo.

se essa precisão é crítica para decisões posteriores na sessão, armazene-a explicitamente:

escreva decisões em arquivos. arquivos sobrevivem à compactação. o modelo pode lê-los sob demanda. o histórico não precisa carregar tudo se o workspace o fizer.
execute agentic-harness doctor para ver a janela de contexto real relatada do seu modelo. defina context_window_tokens para 80-90% desse valor.
o contador de tokens não é perfeitamente preciso no lado do modelo, e uma única leitura de arquivo grande pode empurrá-lo além se você estiver sentado em 99%.

O que observar

Contaminação do histórico da sessão

problema: análise exploratória dentro de uma sessão longa envenena prompts posteriores com ruído da fase de exploração
correção: use tarefas. o histórico da tarefa nunca toca o pai. o limite para "transformar em tarefa" é mais baixo do que você pensa

Surpresas de precedência de papéis

problema: um papel no nível da chamada sombreia o papel da sessão. o modelo se comporta de forma diferente do esperado e você não sabe por quê
correção: o papel da sessão define identidade. o papel da chamada foca o escopo. eles se sobrepõem — o papel da chamada adiciona, não deve cancelar

Lacunas no --deny-path

problema: você nega .env. seus segredos também vivem em .env.local e config/staging.yaml. o agente lê um deles
correção: negue prefixos, não nomes de arquivo. --deny-path config/ cobre tudo abaixo dele

HEAD destacado no CI

problema: o agente edita, os testes passam, o commit falha — porque não há branch para commitar
correção: git checkout -b agent-run-$RUN_ID antes de invocar o harness

Latência do HttpSessionEnv em loops apertados

problema: 40 iterações com três chamadas de shell cada são minutos de latência de rede pura
correção: escreva agent-check.sh que faz tudo em uma invocação. uma chamada por iteração

Subestimação do orçamento de contexto

problema: a compactação dispara no meio da tarefa. o modelo perde seu plano e começa a improvisar a partir do resumo
correção: execute agentic-harness doctor para obter a janela real. defina o orçamento para 80-90% disso

Configuração de runtime carregada após o registro do handler

problema: um handler é executado antes de load_workspace_context(). Nenhum modelo registrado. O erro não parece um problema de configuração.
correção: sempre chame load_workspace_context() em app() antes de conectar qualquer agente.

--llm auto mudando entre execuções

problema: o defaultModel é atualizado. Duas execuções com seis meses de diferença não são comparáveis. Você não consegue reproduzir a primeira.
correção: fixe o modelo em runtime.json para qualquer coisa que precise de reprodutibilidade.

Exclusão de artefatos de execução

problema: você limpa a pasta runs/ com uma regra de .gitignore. Três semanas depois, precisa reproduzir uma regressão e tudo se foi.
correção: faça commit dos artefatos de execução para qualquer tarefa que precise ser reproduzida. run.json tem 2KB. Mantenha-o.

coisas que eu faria diferente

Ler o guia do agentic-harness antes de tocar em qualquer coisa.
Escrever testes no nível da sessão antes de escrever a lógica dos handlers.
Usar tasks para tudo que tem uma sub-entregável.
Fixar o modelo desde a primeira execução séria.
Armazenar decisões em arquivos, não no histórico da sessão.
Agrupar operações de shell desde o início ao usar sandboxes remotas.

a conclusão

A maioria dos frameworks de agentes são wrappers em torno de uma chamada de API. Isso aqui é um runtime.

Um wrapper resolve "fazer o modelo responder". Um runtime resolve "enviar um agente para produção e mantê-lo funcionando depois que o modelo muda, depois que o sandbox muda, depois que o código muda, depois que a sessão roda por duas horas e estoura a janela de contexto."

A arquitetura de 3 camadas

seu código
o harness
o alvo de execução

é o que torna isso possível. Você escreve handlers. O harness absorve toda a complexidade operacional. O alvo de execução é uma escolha de configuração.

As coisas que não mudam: lógica dos handlers, estrutura da sessão, padrões de tasks, definições de papéis, arquivos de skill. As coisas que mudam: modelos, provedores, fornecedores de sandbox, destinos de deploy.

A arquitetura é projetada para que as coisas que mudam nunca toquem nas coisas que não mudam.

Essa é a aposta. E é a aposta certa.

Espero que você tenha gostado de ler este artigo e explorado como construo para agentes e em geral ❣️

Avisos

Este artigo foi pesquisado e escrito pelo autor, editado por Minimax-M2.7. A miniatura foi retirada do Pinterest.

Harrison Chase "a memória deve ser aberta!" —

[https://x.com/hwchase17/status/2046308913939919232Harrison](https://x.com/hwchase17/status/2046308913939919232Harrison)

Chase: "Seu Harness, Sua Memória" —

[https://www.langchain.com/blog/your-harness-your-memory](https://www.langchain.com/blog/your-harness-your-memory)

Vivek Trivedi: "A Anatomia de um Harness de Agente" —

[https://www.langchain.com/blog/the-anatomy-of-an-agent-harness](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness)