O que compõe um agente de IA que funciona em produção é diferente do que aparece na demo. A demo mostra o caminho feliz. Produção é a soma de todos os caminhos infelizes, e a arquitetura é o que decide se o sistema sobrevive a eles.
Este post descreve os componentes centrais, como se conectam, os modos de falha de cada um, e como a arquitetura real fica depois que um time aprende com volume real.
O loop central
Todo agente de IA, independente de framework ou implementação, executa um loop: receber input, decidir o que fazer a seguir, tomar uma ação, observar o resultado, e repetir até que a tarefa seja concluída ou uma condição de parada seja atingida. A complexidade de um agente de produção está quase inteiramente em como esse loop lida com os casos em que cada passo produz algo inesperado.
O caminho feliz é fácil. Produção é a soma de todos os caminhos infelizes. Um agente que não tem arquitetura para lidar com falhas de ferramenta, contexto inesperado ou objetivos ambíguos vai falhar de formas que o conjunto de testes nunca antecipou.
O orquestrador
O orquestrador é o componente que executa o loop. Ele mantém o estado atual da tarefa, decide quando chamar o modelo, passa o contexto montado, analisa o output do modelo, e roteia a próxima ação. A maioria dos frameworks de agentes fornece um orquestrador. Construir o seu próprio é apropriado para casos de uso onde as abstrações do framework produzem mais fricção do que valor.
O orquestrador é onde a maioria dos bugs de produção vive. Quando um agente toma uma ação errada, o log do orquestrador é o que você precisa para reconstruir o que aconteceu. Sem instrumentação no orquestrador, depurar uma falha de produção é trabalho de arqueologia.
Um modo de falha comum: o orquestrador não tem estado explícito sobre o que já foi tentado. O agente entra em loop, chamando a mesma ferramenta com os mesmos argumentos após cada falha, sem nunca escalar ou parar. Isso custa tokens, custa latência, e em casos graves gera efeitos colaterais repetidos no mundo real.
Ferramentas e ações
Agentes tomam ações chamando ferramentas, funções com inputs e outputs definidos que o modelo aprende a invocar. Ferramentas podem chamar uma API, executar uma consulta de banco de dados, ler um arquivo, enviar um email, ou invocar outro modelo. Cada ferramenta é um ponto de falha potencial: pode expirar, retornar um erro, retornar dados inesperados, ou ser chamada com argumentos incorretos.
A arquitetura de agente de produção define o que acontece quando qualquer ferramenta falha: tentar novamente, escalar, parar, ou prosseguir com informação parcial. Essa política precisa ser explícita, não implícita. Um agente que tenta indefinidamente é perigoso. Um agente que para no primeiro erro é inútil. O ponto certo depende da criticidade da ação e do custo de cada tentativa adicional.
O schema de cada ferramenta é igualmente importante. Um schema vago produz argumentos errados com frequência. Um schema preciso, com exemplos e tipos definidos, reduz erros de invocação sem nenhuma mudança no modelo. É a versão de ferramenta do que a engenharia de contexto faz pelo prompt.
Memória e estado
Agentes precisam de memória para completar tarefas em múltiplos passos. Memória de curto prazo é o contexto da conversa dentro de uma única execução. Memória de longo prazo é informação que persiste entre execuções, armazenada em banco de dados e recuperada quando relevante. Memória de trabalho é o estado estruturado que o agente constrói durante uma tarefa, os resultados intermediários que informam ações subsequentes.
Quais tipos de memória um sistema precisa depende da tarefa. Um agente que processa um documento único em uma execução isolada não precisa de memória de longo prazo. Um agente que mantém contexto de um cliente ao longo de semanas precisa de persistência estruturada, com estratégia de recuperação que traga o histórico relevante sem encher a janela de contexto com tudo que já aconteceu.
O modo de falha clássico: o agente acumula estado na janela de contexto ao longo de uma execução longa, o contexto cresce além do útil, e a qualidade da resposta cai sem nenhuma mensagem de erro. A solução é gerenciar o estado explicitamente, compactar o histórico quando necessário, e separar o que precisa sobreviver à compactação do que pode ser descartado.
O problema do planejamento
Para tarefas complexas, agentes precisam planejar antes de agir. Planejamento significa decompor um objetivo em passos, identificar dependências e ordenar ações. Um agente que age sem planejar tende a tomar ações irreversíveis cedo, antes de ter informação suficiente para saber se aquela ação estava correta.
Planejamento ruim produz agentes que descobrem que precisavam de informações que não coletaram, ou que seguem uma sequência de passos que não pode atingir o objetivo declarado. A tarefa parece concluída pelo log, mas o resultado no mundo real está errado ou incompleto.
Bom planejamento inclui checkpoints onde o agente valida resultados intermediários antes de prosseguir. Um agente que extrai dados de um documento e depois os grava em um sistema externo deve validar a extração antes de gravar, não depois. O custo de refazer uma gravação errada é sempre maior que o custo de um passo de validação adicional.
Avaliação e monitoramento
Um agente que funciona em testes falha em produção por razões que não estavam no conjunto de testes. A solução é instrumentação: registrar toda chamada de modelo, toda invocação de ferramenta e seu resultado, todo ponto de decisão e o resultado final. Esse log é o que você precisa para diagnosticar falhas. Sem ele, depurar uma falha de agente de produção é arqueologia.
Além do log de execução, agentes de produção precisam de evals contínuos que rodem contra amostras reais. O conjunto de testes inicial captura os casos que o time imaginou antes do lançamento. Os casos que aparecem depois do lançamento são diferentes, e muitas vezes mais difíceis. Evals que não atualizam com o tráfego real ficam obsoletos rápido.
Cobrimos o lado do monitoramento em observabilidade de IA.
Guardrails e condições de parada
Agentes que podem tomar ações no mundo real precisam de guardrails que limitem o que podem fazer sem aprovação explícita. Um agente que pode enviar emails não deve poder enviar para endereços externos arbitrários. Um agente que pode modificar registros de banco de dados deve ter limites de escopo sobre quais tabelas pode tocar. Sem guardrails definidos, o limite do que o agente pode fazer é o limite do que as ferramentas permitem, que normalmente é muito mais amplo do que o necessário.
Condições de parada são igualmente importantes: defina quando o agente deve parar e entregar a um humano, não apenas quando deve completar. Um agente sem condição de parada clara vai tentar completar qualquer tarefa, incluindo aquelas onde a ação correta é escalar. Cobrimos o tema mais amplo em guardrails de IA.
Como fica a arquitetura na prática
Um agente de produção em uma empresa com que trabalhamos processa documentos de onboarding de clientes. O orquestrador recebe um evento de upload de documento e monta o contexto: conteúdo do documento, registro do cliente no CRM e regras de política relevantes recuperadas via RAG.
O modelo produz uma extração estruturada dos campos principais e uma lista de ações de acompanhamento necessárias. Para cada ação, o orquestrador chama a ferramenta apropriada, lida com falhas registrando e roteando para uma fila de revisão humana, e acompanha o estado de conclusão. O agente roda de forma autônoma para cerca de 70% dos casos. Os outros 30% vão para revisão humana com o output do agente como rascunho pré-preenchido.
Essa divisão não foi planejada. Foi o resultado de três semanas de tráfego real mostrando quais casos o agente consistentemente acertava e quais ele consistentemente errava. A arquitetura que funciona é sempre a que se ajustou ao que o volume real ensinou, não a que foi desenhada antes do primeiro deploy.
Publicado originalmente em studiolabsai.com. A Studio Labs constroi IA de producao para times enterprise. Agende uma call.
Top comments (0)