O código deixou de ser o gargalo. A gestão tomou o lugar.

Parte I: Por que sistemas modulares de agentes dependem de contratos, responsabilidade e estado persistente

O que você vai encontrar neste artigo

Eu conseguia receber dos agentes mais código do que era capaz de revisar direito, e a parte difícil passou a ser manter visíveis as responsabilidades e as decisões anteriores. Explico isso com um microagente contábil de tarefa limitada, depois examino contratos de módulos, o custo de acrescentar agentes e o estado de que uma nova sessão precisa para continuar.

Artigo completo

O dia em que o código deixou de ser escasso

Você já viu um programa crescer mais rápido do que a sua capacidade de entender o que tinha crescido?

Isso aconteceu comigo enquanto eu trabalhava num sistema de contabilidade. No começo, o ritmo parecia quase perfeito. Eu descrevia um problema. Um agente investigava, outro escrevia um módulo, um terceiro ajudava nos testes. As alterações chegavam depressa. A documentação aumentava. Apareciam serviços, filas, regras de autorização, relatórios e tarefas em segundo plano.

Até que percebi uma coisa incômoda. Eu conseguia receber mais código num dia do que era capaz de revisar direito, conectar ao restante do sistema e manter na cabeça.

Escrever o código tinha virado a parte mais fácil. Eu precisava entender o que estávamos acrescentando, por que aquilo fazia parte do sistema e de qual decisão anterior dependia.

Uma parte daquele sistema deixa o problema mais concreto. Um pagamento de, digamos, US$ 10 mil pode incluir vários produtos que precisam ser registrados separadamente e acompanhados conforme são usados. Materiais consumidos na produção precisam entrar na contabilidade à medida que são consumidos. Um cliente ou a própria empresa também pode pagar um depósito para um mês e utilizá-lo aos poucos. No extrato bancário, há um pagamento. Nos documentos que o explicam, pode haver muitos lançamentos menores.

Esses detalhes nem sempre chegavam em linhas organizadas. Alguém podia enviá-los numa mensagem, num e-mail ou num documento mais formal. Um parser convencional podia transferir um valor de um campo conhecido para outro. Só esse mapeamento não dizia a que a quantia se referia. Muitas vezes, os contadores acabavam digitando os detalhes à mão, mesmo quando módulos de leitura automática tentavam ajudar e cometiam erros.

Para essa etapa específica, usamos um pequeno agente com Terra ou Luna. Não precisávamos treiná-lo para fazer contabilidade. O prompt lhe dava uma tarefa limitada: ler a entrada não estruturada, identificar os valores e a finalidade de cada pagamento, depois devolver esses campos ao parser para inclusão no banco de dados estruturado. Ele não podia reescrever, omitir nem combinar itens só para entregar um resultado com aparência de completo. Se não conseguisse resolver algo, precisava dizer isso.

A fronteira importante ficava entre extrair o sentido de um documento e aceitar um lançamento contábil. O agente fornecia campos estruturados; o restante do sistema ainda precisava decidir o que fazer com eles. Um único pagamento não podia virar silenciosamente um único item só porque esse era o formato mais fácil para o parser devolver.

Uma suposição vaga pode entrar num módulo, virar uma afirmação num teste, aparecer como fato na documentação e voltar na sessão seguinte como verdade estabelecida. Cada passo local pode parecer razoável enquanto a cadeia está errada.

Foi essa sequência que me fez prestar mais atenção à arquitetura ao redor dos agentes. Um agente de IA é um executor probabilístico dentro de um sistema. Ele pode ser capaz, rápido e surpreendentemente bom para recuperar uma intenção. Continua sendo um modelo de linguagem operando com contexto, ferramentas, permissões e um ciclo no qual escolhe a próxima ação. Às vezes escolhe bem. Às vezes erra com uma segurança admirável.

No projeto de contabilidade, eu precisava impedir que uma interpretação aparentemente razoável virasse, sem percebermos, a base do módulo seguinte. O pequeno agente de extração era útil porque tinha uma tarefa e limites específicos. A pergunta maior era como manter esses limites visíveis enquanto o sistema crescia.

Onde começa um módulo de verdade?

É fácil começar por um diagrama: um arquiteto, um desenvolvedor, um crítico, setas entre eles. Entendo por que isso parece uma equipe. Mas ainda faltam as perguntas de trabalho. Quem pode alterar o módulo? Quem verifica a regra que ele implementa? Qual resultado chega à próxima pessoa ou ao próximo agente?

Se dois agentes podem alterar o mesmo arquivo, ninguém é responsável pelo estado compartilhado, os resultados passam por longos resumos narrativos e o próprio executor decide se terminou, as responsabilidades continuam sobrepostas. Um agente pode produzir uma alteração que faz sentido isoladamente enquanto outro trabalha com uma premissa diferente sobre o mesmo arquivo.

Um módulo começa com um contrato e um responsável. Para cada módulo, quero oito perguntas respondidas:

Qual decisão ou transformação única ele controla?
O que está explicitamente proibido de fazer?
Quais entradas pode usar e de onde elas vieram?
Qual artefato observável deve produzir?
Quem assume a responsabilidade por esse artefato depois da entrega?
O que o módulo pode ler, alterar ou enviar para fora do sistema?
Qual verificação externa aceita o resultado?
Em que momento ele deve parar e pedir ajuda?

Depois de definir a responsabilidade, posso escolher como executá-la. Um módulo não precisa necessariamente ter um agente dentro dele.

Pode ser uma função, uma consulta SQL, um fluxo determinístico, uma decisão humana, uma chamada ao modelo ou um pequeno grupo de especialistas. O que importa é conseguir examinar a responsabilidade daquela parte do sistema de forma independente.

Isso muda a pergunta de projeto. Em vez de perguntar "qual agente deve fazer isso?", pergunte "qual resultado precisa existir, quem responde por ele e o que prova que foi aceito?"

Assim, se a regra errada chegar a um teste ou documento, tenho um lugar específico para investigar.

Por que uma arquitetura multiagente deve ser a exceção?

Quando as pessoas têm o primeiro contato com agentes, muitas querem construir uma pequena empresa digital. Eu entendo a atração. Também passei por isso.

Eu percorreria as opções nesta ordem:

Use código comum quando a regra for conhecida.
Use uma chamada ao modelo para uma operação semântica.
Use um fluxo quando a sequência de passos for conhecida.
Use um agente com ferramentas quando o próximo passo depender do que ele encontrar.
Adicione roteamento quando as classes de tarefa forem distintas e classificáveis.
Adicione um orquestrador e executores quando houver partes independentes.
Use um conselho limitado quando várias posições defensáveis exigirem uma arbitragem explícita.

A orientação da Anthropic chega à mesma conclusão básica: comece pela solução mais simples que funcione e só acrescente complexidade quando houver uma melhora mensurável. O sistema multiagente de pesquisa da empresa serve como exemplo positivo e aviso ao mesmo tempo. Numa avaliação interna de pesquisa ampla, ele superou uma configuração de agente único em 90,2%. Também usou cerca de 15 vezes mais tokens que uma conversa comum. A própria Anthropic observa que áreas com contexto fortemente compartilhado e muitas dependências combinam mal com esse desenho.

O ganho vem com um consumo considerável de tokens, mas as bases são diferentes: a qualidade foi comparada com um agente único, e os tokens com uma conversa comum. Não dá para transformar os dois números numa relação de custo por melhoria. Eu compararia os dois desenhos na mesma tarefa e contaria o custo completo de um resultado aceito.

Há pesquisa independente por trás dessa cautela. No artigo "Should We Be Going MAD?", apresentado na ICML em 2024, Smit e seus colegas observaram que o debate multiagente não superava de forma consistente estratégias mais simples sem ajuste cuidadoso. O resultado trata de protocolos de debate, não de todo sistema modular. Ainda assim, dá um motivo para exigir que a coordenação adicional justifique seu lugar.

Essa diferença importa.

Cinco agentes pesquisando cinco categorias independentes de fontes podem trabalhar em paralelo. Cinco agentes alterando a mesma arquitetura, os mesmos dados e arquivos vizinhos criam uma conta de coordenação. Alguém terá de resolver responsabilidade, trabalho duplicado, premissas conflitantes, resultados desatualizados e falhas parciais.

Quero saber se essas mensagens extras ajudaram a resolver a tarefa ou apenas aumentaram o trabalho de coordenação.

A arquitetura só paga pela própria complexidade depois que você conta o custo completo: tokens, tempo, falhas, revisão humana, depuração e o preço de gravar um artefato errado num estado persistente.

O que o agente principal deveria controlar?

Um agente principal é útil para planejar, decompor, encaminhar e reunir resultados. Torna-se perigoso quando também controla permissões, estado compartilhado, aceitação e o direito de continuar tentando para sempre.

Prefiro separar a camada probabilística de trabalho de um plano de controle determinístico.

A camada de trabalho pode pesquisar, interpretar, redigir, classificar, comparar e propor. O plano de controle mantém as regras que precisam continuar estáveis entre chamadas ao modelo:

estado da tarefa e versões dos artefatos
escopos de acesso e permissões das ferramentas
limites de tempo, custo e número de tentativas
transições permitidas entre etapas
regras para novas tentativas e detecção de falta de progresso
pontos de aprovação
estados finais e encerramento
registros de auditoria e pontos de recuperação

O modelo pode recomendar a próxima operação. O plano de controle decide se ela é permitida.

Para mim, é uma forma prática de deixar a responsabilidade visível. Não pedimos a uma consulta de banco de dados que redefina as próprias permissões. Também não deveríamos pedir a um modelo que interprete o pedido, execute a tarefa, mantenha o estado e julgue sozinho se tudo correu bem.

O Model Context Protocol facilita a padronização das fronteiras entre ferramentas, e SDKs de agentes tornam as transferências mais fáceis de expressar. Isso ajuda. Mas um protocolo limpo não define responsabilidade. Uma chamada tipada prova que os argumentos obedecem a um schema. Não prova que a chamada é sensata, autorizada ou baseada no fato correto.

Por exemplo, a chamada pode obedecer perfeitamente ao schema e ainda tratar um depósito mensal como uma compra concluída porque ninguém verificou essa interpretação.

Por que a conversa é um registro ruim do sistema?

Uma janela de contexto maior parece uma resposta natural: entregar todos os documentos e o histórico para o agente entender o que aconteceu. Isso ajuda se ele conseguir distinguir a decisão atual da antiga. Ele pode encontrar o fato correto e dar pouco peso a ele, ou seguir uma instrução de um documento recuperado que nunca veio do responsável pelo sistema.

Naquele sistema de contabilidade, eu precisava saber qual decisão ainda valia. Guardar mais conversa, por si só, não resolvia essa questão.

Num trabalho longo, quero o estado importante fora da conversa:

o objetivo atual e sua versão aceita
decisões, premissas e seus responsáveis
fatos verificados com referências às fontes
artefatos com versão e procedência
verificações já concluídas
riscos e divergências ainda abertos
a próxima operação permitida
as condições que encerram a execução

Esse estado pode ficar num banco de dados, num registro de tarefas, em arquivos ou num log de eventos. A escolha depende do projeto. O princípio não muda: uma nova sessão deve continuar a partir de um estado explícito, não reconstruir a realidade com uma história sobre uma conversa antiga.

Naquele sistema de contabilidade, a documentação parecia trabalho extra no início. Depois virou a memória de produção. Quando o código chega depressa, decisões escritas, contratos de módulos, definições de dados e logs de alteração deixam de ser burocracia. Eles impedem que o projeto se dissolva em versões plausíveis daquilo que alguém acha que aconteceu.

Antes, o código era o principal ativo escasso. No trabalho com agentes, o ativo mais raro costuma ser uma cadeia explicável de decisões ao redor do código.

Como é uma boa transferência de trabalho?

Uma boa entrega é pequena o bastante para ser inspecionada e completa o bastante para permitir a continuação.

Ela deve conter o artefato solicitado, as evidências usadas para criá-lo, as verificações realizadas, as premissas ainda abertas e a próxima ação exata. Não pode depender de o agente seguinte ler mil mensagens e adivinhar qual frase ainda importa.

Resumos narrativos ajudam pessoas. São fracos como único contrato de máquina porque misturam afirmações, evidências, decisões e incerteza num parágrafo fluente. Campos estruturados ajudam a separar essas categorias, mas também não resolvem a verdade sozinhos. O sistema precisa dos dois: um registro legível por máquina e uma explicação legível por gente.

A entrega também precisa permitir que o módulo diga que o resultado ainda não pode ser aceito.

Se um módulo só puder retornar sucesso ou falha, muitas vezes vai esticar a incerteza até transformá-la numa resposta. Dê estados explícitos como needs_evidence, conflict, out_of_scope ou human_decision_required. Agora o sistema pode parar sem fingir.

Assim, a etapa seguinte consegue ver que uma regra continua em aberto, em vez de tomar uma explicação fluente como autorização para construir em cima dela.

Aplicações práticas

Defina módulos por um resultado sob responsabilidade, não por uma persona ou cargo.
Mantenha permissões, orçamento, transições de estado, novas tentativas e encerramento num plano de controle determinístico.
Comece com código, uma chamada ao modelo ou um fluxo. Adicione agentes apenas quando a tarefa exigir ação adaptativa.
Use vários agentes para partes independentes com um ponto claro de síntese. Compare o ganho com uma alternativa mais simples.
Guarde decisões, evidências, artefatos, verificações e riscos fora da conversa.
Trate recusa e escalonamento como estados normais de saída.
Exija que toda transferência leve um artefato, sua procedência, a evidência de aceitação e uma única próxima ação permitida.

Em poucas palavras

Consigo examinar um módulo quando o resultado, o responsável e a verificação de aceitação estão claros. Agentes adicionais são úteis quando a divisão do trabalho e o ganho medido justificam a coordenação. Um sistema modular bem organizado ainda pode levar um erro convincente por várias etapas. A Parte II trata da verificação e dos pontos em que o sistema precisa parar.