Diagrama de arquitetura de agente de IA: modelo, ferramentas, memória e guardrails

A maioria dos diagramas de agentes de IA mostra um ícone de robô ao lado do logo de um LLM, com uma seta escrita "ferramentas". Essa imagem esconde as perguntas que decidem se um agente é seguro de rodar: quem escolhe o próximo passo, no que o agente pode mexer, por onde entra texto não confiável e o que para uma execução que não está chegando a lugar nenhum.

Este artigo divide um agente em partes, percorre o loop que o move, cobre ferramentas e o Model Context Protocol, memória, guardrails, limites e tracing, e desenha um agente de suporte ao cliente que consegue consultar pedidos e emitir reembolsos.

Workflow ou agente?

O guia da Anthropic para construir agentes eficazes traça uma linha útil. Num workflow, LLMs e ferramentas são orquestrados por caminhos de código escritos de antemão. Num agente, o modelo dirige o próprio processo e decide, passo a passo, quais ferramentas usar até a tarefa terminar.

O mesmo guia recomenda a solução mais simples que funcione. Se uma tarefa sempre segue os mesmos três passos, escreva esses passos em código e chame o modelo dentro deles. Recorra a um agente quando o caminho depender do que o agente encontrar pelo caminho: um caso de suporte em que a próxima consulta depende da última resposta, ou uma tarefa de programação que precisa de várias rodadas de edição e teste.

As partes de um agente

O modelo é só uma caixa. A maior parte da engenharia, e a maior parte do controle de risco, mora no código em volta dele.

O loop

Reduzido ao essencial, o runtime é um loop:

def run(task, user):
    messages = [system_prompt(user), task]
    for step in range(MAX_STEPS):
        reply = llm.generate(messages, tools=allowed_tools(user))
        if not reply.tool_calls:
            return check_output(reply.text)
        for call in reply.tool_calls:
            result = execute(call, user)   # permission check, approval, timeout
            messages.append(tool_result(call, result))
    return stop("step limit reached", messages)

O modelo nunca executa nada sozinho. Ele devolve ou uma resposta ou um pedido para chamar uma ferramenta com certos argumentos, e o runtime decide se e como executar. É aí que mora o controle: checagens de permissão, aprovações, timeouts e limites ficam todos em execute e no loop, não no prompt.

Ferramentas, e onde o MCP entra

Uma ferramenta é uma função que o modelo pode pedir: um nome, uma descrição e um JSON schema para os argumentos. As descrições importam tanto quanto o código, porque são tudo o que o modelo sabe sobre quando usar uma ferramenta.

O Model Context Protocol é um padrão aberto para conectar aplicações de IA a sistemas externos. Um servidor MCP expõe ferramentas, dados e prompts; o runtime do agente atua como cliente. Em vez de amarrar cada integração no código do agente, cada sistema publica um servidor, e qualquer runtime compatível com MCP pode usá-lo.

Boas ferramentas têm algumas coisas em comum:

• Poucas e específicas. refund_order(order_id, amount, reason) é melhor do que um call_api(url, body) genérico.
• Leitura e escrita separadas, para que um papel possa ter ferramentas de leitura sem as de escrita.
• Erros claros com que o modelo consiga agir, como "valor excede o total do pedido".
• Chaves de idempotência nas escritas, para que um passo repetido não reembolse duas vezes.

Memória

Agentes têm dois tipos de memória, e os diagramas costumam misturá-los:

• A memória de trabalho é o contexto enviado ao modelo a cada passo: instruções, a conversa e os resultados de ferramentas até ali. Ela é limitada pela janela de contexto do modelo e pelo custo, então execuções longas resumem passos antigos ou descartam a saída bruta das ferramentas depois de usada.
• O conhecimento de longo prazo fica fora do modelo: documentos, políticas, tickets antigos. O agente recupera as partes relevantes, muitas vezes de um índice vetorial, e as adiciona à memória de trabalho. O diagrama de arquitetura RAG cobre o pipeline de recuperação em detalhe.

O estado da tarefa que precisa sobreviver a uma queda, como quais passos já rodaram e qual aprovação está pendente, pertence a um banco de dados comum, não ao contexto do modelo.

Guardrails e permissões

O OWASP Top 10 para aplicações LLM coloca prompt injection em primeiro lugar. Outro item, a agência excessiva, cobre ações danosas que um sistema LLM pode tomar porque tem mais funcionalidade, permissões ou autonomia do que precisa. Agentes estão expostos aos dois: leem texto não confiável (entrada do usuário, páginas web, documentos recuperados, resultados de ferramentas) e podem agir.

Regras que se sustentam na prática:

• Trate todo resultado de ferramenta e todo documento recuperado como dados. Um texto numa página web não pode conceder permissões nem mudar a tarefa.
• Aja com as permissões do usuário, não com uma conta de serviço que enxerga todos os clientes.
• Controle as escritas. Leituras rodam livremente; escritas acima de um limite, ou qualquer ação irreversível, esperam por uma pessoa.
• Rode código num sandbox: sem credenciais e sem rede por padrão.
• Cheque as saídas antes que cheguem aos usuários ou a outros sistemas, procurando vazamento de dados internos ou conteúdo inseguro.

O diagrama de fluxo de dados para modelagem de ameaças é uma boa forma de achar onde o texto não confiável entra num componente que pode agir.

Limites e custo

Um agente que fica girando sem progresso queima dinheiro e paciência. Coloque os limites no runtime, não no prompt:

• Passos: um número máximo de chamadas ao modelo por tarefa.
• Tempo: um limite de tempo real por tarefa e um timeout por chamada de ferramenta.
• Dinheiro: um orçamento em tokens ou dólares por tarefa e por usuário por dia.
• Taxa: limites de requisições por usuário na API, como no design de um rate limiter.

Quando um limite for atingido, pare de forma limpa: devolva o que foi encontrado até ali, diga qual limite parou a execução e guarde o trace para revisão.

Tracing e evals

Registre cada passo: o contexto enviado, o modelo e suas configurações, cada chamada de ferramenta com argumentos e resultados, tokens, latência e custo. O OpenTelemetry tem convenções semânticas para IA generativa, então esses traces podem ir para os mesmos backends que o resto do seu sistema; o diagrama de arquitetura de observabilidade mostra esse pipeline.

Traces respondem "o que aconteceu nesta execução?". Evals respondem "o agente está melhorando ou piorando?": um conjunto fixo de tarefas realistas, pontuadas automaticamente, rodadas a cada mudança de prompts, ferramentas ou modelos.

O diagrama de arquitetura

Como ler:

• Esquerda: o usuário envia uma tarefa pelo app de chat, que cuida do login e das sessões e repassa a tarefa, com a identidade do usuário, aos guardrails.
• Centro: o loop do agente envia o contexto e a lista de ferramentas ao LLM (linha cheia) e recebe uma resposta ou uma chamada de ferramenta (tracejado). Ele lê e escreve a memória de trabalho; o bloco Markdown lista os limites.
• Direita: as chamadas de ferramenta vão para a busca na web, um sandbox de código e a API de pedidos. Um reembolso espera o aprovador (tracejado).
• Embaixo: o índice de conhecimento alimenta a memória de trabalho com documentos recuperados, e cada passo é registrado em traces e evals (pontilhado).

Um exemplo completo: um reembolso

Um cliente escreve: "O pedido 4411 chegou quebrado, quero meu dinheiro de volta."

1. Os guardrails checam a mensagem e anexam a identidade do cliente.
2. O modelo pede get_order(4411). O runtime confere se o pedido é desse cliente e devolve: entregue há três dias, 180 dólares.
3. O runtime recupera a política de reembolso no índice de conhecimento e a adiciona à memória de trabalho: itens danificados podem ser reembolsados em até 30 dias.
4. O modelo pede refund_order(4411, 180, "damaged"). O valor passa do limite de 100 dólares, então o runtime pausa a execução e envia um pedido de aprovação para uma líder de suporte.
5. A líder aprova. O runtime executa o reembolso com uma chave de idempotência e devolve a confirmação.
6. O modelo escreve a resposta, as checagens de saída passam e o cliente recebe a resposta.

Três chamadas ao modelo, duas chamadas de ferramenta, uma recuperação, uma aprovação e um trace que mostra cada passo.

O que colocar num diagrama de agente

• Quem decide o próximo passo: o modelo ou o código que você escreveu.
• Cada ferramenta, com acesso de leitura ou escrita e com as permissões de quem ela roda.
• Os pontos de aprovação para ações arriscadas.
• Os limites: passos, tempo e orçamento.
• Por onde entra texto não confiável: entrada do usuário, páginas web, documentos, resultados de ferramentas.
• O tracing, para que quem revisa saiba que as execuções podem ser inspecionadas.

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. Adicione dois nós Pessoa do pack Modelo C4 para o usuário e o aprovador, e um Contêiner para o app de chat.
3. Adicione uma Moldura do pack Básico para o runtime do agente, com um Contêiner para o loop do agente e dois nós Componente para os guardrails e a memória de trabalho.
4. Adicione um Modelo e um Índice vetorial do pack ML, uma segunda Moldura com três nós Cartão de serviço do pack Stack para as ferramentas, e Rastreamentos do pack DevOps.
5. Desenhe as respostas do modelo tracejadas e a aresta de tracing pontilhada, e adicione um bloco Markdown do pack Básico com os limites. Para deixar um agente desenhar isso por você, veja criar diagramas com agentes de IA via MCP.

O exemplo usa 15 nós de diagrama e fica dentro do plano Free.

Perguntas frequentes

Qual a diferença entre um agente de IA e um workflow? Num workflow, o seu código decide a sequência de passos e chama o modelo dentro deles. Num agente, o modelo decide o próximo passo e quais ferramentas usar, dentro de um loop que o seu código controla.

O que é MCP numa arquitetura de agentes? O Model Context Protocol é um padrão aberto para conectar aplicações de IA a ferramentas e dados. Os sistemas expõem servidores MCP, e o runtime do agente se conecta a eles como cliente.

Como impeço um agente de tomar ações danosas? Dê a ele só as ferramentas de que precisa, rode-as com as permissões do usuário, exija aprovação humana para escritas acima de um limite e trate todos os resultados de ferramentas e documentos como dados não confiáveis.

Como os agentes se lembram das coisas? Dentro de uma execução, pelo contexto enviado ao modelo a cada passo. Entre execuções, por conhecimento armazenado que é recuperado quando necessário e pelo estado da tarefa guardado num banco de dados.

Como mantenho os custos de um agente sob controle? Defina no runtime limites de passos, tempo e tokens por tarefa, adicione orçamentos por usuário e rastreie cada execução para que padrões caros apareçam nas revisões.

Comece grátis — um assento, sem cartão de crédito.