Harness na prática — Como preparar Agentes de IA para operarem seu sistema (abrimos o código)

skail · 2026-09-01 · 5 min

Quase todo projeto de agente de IA que trava por meses trava sempre no mesmo lugar...

A equipe escolhe o modelo, ajusta o prompt, consegue uma demo que funciona e, aí, descobre que colocar aquilo dentro do ERP, do CRM ou do sistema de gestão que já está em produção é um problema de engenharia inteiro que ninguém tinha dimensionado.

O nome dessa parte é harness, e é nessa camada que o projeto realmente acontece.

O harness de um agente de IA é tudo o que fica em volta do modelo: o contexto que você monta, as ferramentas que você expõe, o loop que executa as decisões, a orquestração que define quem atende o quê, o estado que sobrevive a uma queda de infraestrutura, os guardrails e a observabilidade.

Nada disso mora na LLM. Tudo isso mora no seu sistema.

A boa notícia é que, se o seu software já conversa com alguma IA hoje, você já escreveu um harness. Mas ele, provavelmente, ainda não está preparado para lidar com tudo o que uma LLM tem a oferecer — seja bom ou ruim.\

Neste vídeo, mostramos na prática o que acontece quando um agente de IA precisa deixar de ser uma demo e começar a funcionar como parte de um sistema real — incluindo execução durável, ferramentas, orquestração e observabilidade.

O modelo sozinho só lida com texto

A LLM recebe texto, processa texto e devolve texto. É o limite dela, e vale repetir porque quase toda confusão de arquitetura em projetos de agentes nasce de esquecer isso.

Os modelos estão ficando melhores e, ao mesmo tempo, estão virando commodity. O que eles não estão fazendo é executar.

A LLM decide; o seu sistema executa.

Quando um anexo precisa entrar na conversa, quem transforma o PDF em texto é o seu código. Quando o agente precisa consultar um lead, quem chama a API é o seu código. O modelo só vê a versão em texto de tudo isso.

Essa fronteira é o que define o desenho do harness. Toda peça que descrevo abaixo existe porque a LLM não pode fazer aquilo sozinha.

Contexto, ferramentas e loop: o mínimo que todo harness tem

O contexto é a soma de três coisas: as instruções do prompt, os dados que você busca (RAG) e a memória da conversa. Você monta isso em texto e envia para o modelo. É a parte que a maioria das equipes já faz.

As ferramentas são o catálogo do que a IA pode pedir. Cada uma precisa de três elementos: o nome, uma descrição em linguagem natural explicando quando usar e o contrato dos argumentos com seus tipos. Tudo isso vai para o modelo como texto.

Uma ferramenta de atualização, por exemplo, pode ter em sua própria descrição a instrução para consultar os dados existentes antes de fazer uma alteração e preservar as informações que já estão cadastradas. O encadeamento de ferramentas pode ser resolvido na descrição, em texto, e não necessariamente em código de orquestração.

O método Executar de cada ferramenta é uma chamada para a própria API do sistema, com os argumentos que o modelo pediu. Autenticação, validação de injeção e controle de acesso ficam nessa camada, onde já estavam antes de existir agente nenhum.

O loop amarra as duas coisas. O modelo decide qual ferramenta usar, o sistema executa, registra o resultado e devolve para o modelo, que decide se já tem o suficiente ou se precisa de mais uma rodada.

Orquestração: a IA decide a intenção, seu código decide a ação

Aqui está a parte que mais muda o resultado em sistemas de gestão e a que menos aparece em tutorial de agente.

Você não precisa confiar cegamente no modelo. O desenho que uso separa as duas decisões.

Eu mando para a IA o texto do usuário, o contexto e as configurações da sessão, e ela me devolve qual intenção aquele texto representa. A partir daí, quem decide o que fazer com essa intenção é o meu código determinístico.

Cada intenção pode estar vinculada a um fluxo específico. Uma intenção de encerramento, por exemplo, dispara o fluxo correspondente, que carrega o motivo, aplica a política de encerramento configurada para aquela sessão e, se a política permitir, encerra a sessão e sai do loop.

O ganho é ficar com o melhor dos dois lados.

A IA faz o que faz bem: interpretar linguagem ambígua e classificar. O código faz o que já fazia bem há anos: executar regras de negócio de forma previsível e testável.

As configurações da sessão são carregadas de forma determinística logo no começo do atendimento, antes de qualquer chamada ao modelo.

Estado durável: o que acontece quando o pod cai no meio do atendimento

Um atendimento em andamento é uma execução que pode durar minutos ou semanas.

A conexão com o provedor do modelo pode cair. O provedor pode ficar indisponível. A rede pode falhar, a máquina pode reiniciar, o pod pode morrer.

Se o harness não tem estado durável, cada uma dessas situações pode transformar um atendimento em uma execução perdida no meio do caminho.

No código do agente, o estado durável entra pela execução persistida. Ao usar primitivas de execução durável, a execução ganha estado persistido automaticamente. Se ela parar por um problema de infraestrutura, o skail retoma exatamente de onde parou.

E quando a execução precisa esperar por uma interação humana que pode levar dias, ela hiberna. O host é liberado, as threads são liberadas e nada fica ocupando container ou instância só para segurar um await.

Dá para montar isso sem o skail. Você pode usar o SDK da OpenAI ou da Anthropic para o function calling e combinar isso com alguma plataforma de execução durável, como Azure Durable Functions ou workers duráveis na Cloudflare.

São duas dependências, dois modelos mentais e dois lugares para depurar quando algo trava.

Guardrails e observabilidade: saber o que o agente fez e o que ele não pode fazer

Guardrail responde a uma pergunta simples: o que a IA nunca pode executar?

Isso se traduz em validação de entrada, validação de saída, limite de tamanho de texto e proteção contra prompt injection e SSRF. No template de agente do skail, esses controles já vêm no projeto gerado.

Observabilidade responde à pergunta seguinte: o que o agente decidiu, o que ele chamou, o que voltou, quanto custou e quanto demorou?

Sem isso, você tem um sistema que toma decisões em produção e ninguém consegue reconstruir o porquê.

No monitor do skail, cada etapa do agente é registrada sem código adicional. Em um agente de emissão de nota fiscal, por exemplo, o rastro pode mostrar a chamada que iniciou o atendimento, a resposta do modelo, qual ferramenta foi acionada e o que ela retornou, o XML gerado, o tempo aguardando o retorno do gateway e o encerramento do fluxo.

Falta ainda a última pergunta, que é a mais difícil:

Como você sabe que a mudança de ontem melhorou e não piorou?

É para isso que servem as evals: medir o comportamento do agente antes que uma mudança chegue ao usuário.

Você provavelmente já tem um harness

Se o seu sistema pega um prompt, envia para a LLM e usa o retorno para conversar com o usuário, isso já é um harness.

Simples, com uma peça só, mas é.

O caminho para produção é ir preenchendo as outras peças na ordem em que a sua dor aparece.

Quase sempre, orquestração vem primeiro, porque é o que tira decisões críticas das mãos do modelo. Estado durável vem logo em seguida, porque é o que faz o agente sobreviver ao primeiro incidente de infraestrutura.

Depois entram guardrails, observabilidade, evals e todas as outras camadas necessárias para transformar uma demonstração em software de produção.

O código fica simples porque o skail entrega loop, ferramentas, execução durável, guardrails e observabilidade no mesmo lugar.

Se você quer entender como essas primitivas funcionam por baixo dos panos, consulte a documentação completa em docs.skail.dev