Sistema de IA de agente único usando o ADK e o Cloud Run

Last reviewed 2025-12-09 UTC

Este documento apresenta uma arquitetura de referência para ajudar você a projetar um sistema de IA agêntica de agente único no Google Cloud. O sistema de agente único nesta arquitetura é criado usando o Kit de Desenvolvimento de Agente (ADK) e implantado no Cloud Run. Também é possível implantar o agente no Agent Runtime na Gemini Enterprise Agent Platform ou no Google Kubernetes Engine (GKE). A arquitetura usa o Protocolo de Contexto de Modelo (MCP), que permite ao agente acessar e processar informações de várias fontes para fornecer insights ricos em contexto.

Este documento é destinado a arquitetos, desenvolvedores e administradores de aplicativos de IA. Ele pressupõe que você tenha uma compreensão básica dos conceitos de IA, machine learning (ML) e modelo de linguagem grande (LLM). O documento também pressupõe que você tenha um entendimento básico de agentes e modelos de IA. Ele não fornece orientação específica para projetar e programar agentes de IA.

A seção Implantação deste documento lista exemplos de código que você pode usar para aprender a criar e implantar sistemas de IA de agente único.

Arquitetura

O diagrama a seguir mostra uma arquitetura para um sistema de IA agêntica de agente único implantado no Cloud Run:

Uma arquitetura de agente único implantada no Cloud Run. Arquitetura de um sistema de IA multiagente no Google Cloud.

Componentes de arquitetura

A arquitetura de exemplo consiste nos seguintes componentes:

Componente Descrição
Front-end Os usuários interagem com o agente por um front-end, como uma interface de chat, que é executada como um serviço sem servidor do Cloud Run.
Agente O agente recebe solicitações do usuário, interpreta a intenção do usuário, seleciona as ferramentas adequadas e sintetiza as informações para responder às consultas.
Agent Runtime O agente é criado usando o ADK e implantado como um serviço sem servidor do Cloud Run. Você também pode implantar o agente no Agent Runtime na Gemini Enterprise Agent Platform ou como um app em contêiner no GKE. Para informações sobre como escolher um Agent Runtime, consulte Escolher os componentes da arquitetura de IA agêntica.
ADK O ADK oferece ferramentas e um framework para desenvolver, testar e implantar agentes. O ADK abstrai a complexidade da criação de agentes e permite que os desenvolvedores de IA se concentrem na lógica e nos recursos do agente. Ao desenvolver agentes usando o ADK, é possível configurá-los para acessar e usar ferramentas integradas, como a Pesquisa Google.
Modelo de IA e ambiente de execução do modelo Para veiculação de inferência, o agente neste exemplo de arquitetura usa o modelo de IA do Gemini na Gemini Enterprise Agent Platform.
MCP Toolbox A MCP Toolbox for Databases oferece ferramentas específicas do banco de dados para o agente. Ele pode lidar com complexidades, como pooling de conexões e autenticação.
Clientes, servidores e ferramentas do MCP O MCP facilita o acesso às ferramentas padronizando a interação entre agentes e ferramentas. Para cada par de agente e ferramenta, um cliente do MCP envia solicitações a um servidor MCP, que o agente usa para acessar uma ferramenta, como um sistema de arquivos ou uma API. Por exemplo, ferramentas externas como a ferramenta LangChain do StackOverflow e a ferramenta Pesquisa Google podem fornecer dados e embasamento.
Observabilidade O agente é monitorado usando o Google Cloud Observability para geração de registros, monitoramento e rastreamento.

Fluxo agêntico

O sistema de agente único de exemplo na arquitetura anterior tem o seguinte fluxo:

  1. Um usuário insere um comando por um front-end, como uma interface de chat, que é executado como um serviço sem servidor do Cloud Run.
  2. O front-end encaminha o comando para o agente.
  3. O agente usa o modelo de IA para analisar o comando do usuário e sintetizar uma resposta:
    • O modelo de IA determina quais ferramentas usar para coletar informações contextuais ou realizar uma tarefa.
    • O agente faz chamadas de ferramenta e adiciona a resposta ao contexto.
    • O agente realiza o embasamento e a validação intermediária.

Produtos usados

Esta arquitetura de referência usa os seguintes produtos e ferramentas do Google Cloud e de código aberto:

Casos de uso

Esta seção descreve possíveis casos de uso para a arquitetura descrita neste documento.

Triagem automatizada de relatórios de bugs

É possível adaptar essa arquitetura de referência para automatizar a triagem de relatórios de bugs recebidos: entender o problema, pesquisar duplicatas, coletar contexto técnico relevante e criar um bug no sistema. Um agente com tecnologia de IA pode atuar como um assistente inteligente que realiza a investigação inicial, permitindo que especialistas humanos se concentrem em problemas mais complexos.

Para esse caso de uso, a arquitetura oferece os seguintes benefícios:

  • Tempos de resolução mais rápidos: o agente automatiza a pesquisa inicial e a coleta de contexto, o que pode reduzir significativamente o tempo necessário para atribuir e resolver tíquetes de bugs.
  • Melhoria na precisão e na consistência: o agente pode pesquisar sistematicamente em várias fontes de dados (bancos de dados internos, repositórios de código e a Web pública). Esse recurso oferece uma análise mais abrangente e consistente do que a triagem manual.
  • Redução da carga de trabalho manual: o agente pode assumir tarefas repetitivas de triagem das equipes de suporte de TI e engenharia, permitindo que elas se concentrem em atividades de maior valor.

Essa arquitetura é ideal para qualquer organização que desenvolva software e queira melhorar a eficiência e a eficácia do processo de resolução de bugs. Para mais informações e opções de implantação, consulte Assistente de bugs de software: agente de amostra do ADK Python e Ferramentas para criar um agente: do zero ao assistente com o ADK.

Atendimento ao cliente

Você pode adaptar essa arquitetura de referência para oferecer uma experiência de compra personalizada e integrada aos clientes. Um agente com tecnologia de IA pode oferecer atendimento ao cliente, recomendar produtos, gerenciar pedidos e agendar serviços, permitindo que os representantes humanos se concentrem em outras tarefas.

Para esse caso de uso, a arquitetura oferece os seguintes benefícios:

  • Upsell e promoções: o agente pode ajudar a aumentar as vendas sugerindo produtos, serviços e promoções. As sugestões do agente são baseadas no pedido atual do cliente e nas vendas relevantes, no histórico de pedidos do cliente e nos itens que estão no carrinho.

  • Gerenciamento e agendamento de pedidos: o agente pode aumentar a eficiência e reduzir o atrito com o cliente gerenciando o conteúdo do carrinho de compras e facilitando o autoagendamento de serviços.

  • Redução da carga de trabalho manual: o agente lida com consultas gerais, pedidos e agendamentos, o que permite que os representantes de atendimento ao cliente se concentrem em problemas mais complexos.

Essa arquitetura é ideal para qualquer organização de varejo que queira melhorar a experiência do cliente, aumentar as vendas e simplificar o gerenciamento e a programação de pedidos. Para mais informações e opções de implantação, consulte Representante de atendimento ao cliente da Cymbal Home & Garden.

Previsão de série temporal

Você pode adaptar essa arquitetura de referência para ajudar a prever resultados, como previsão de demanda, previsão de padrões de tráfego ou análise e previsão de falhas de máquinas. Um agente com tecnologia de IA pode analisar dados em tempo real, tendências históricas e eventos futuros. O agente pode usar essas análises para prever resultados para um período especificado. Essas previsões podem ajudar você a planejar e reduzir o tempo gasto por analistas de dados humanos.

Esse caso de uso pode beneficiar organizações em vários cenários, como os seguintes:

  • Gerenciamento de inventário: usando a análise avançada combinada com dados históricos de vendas e tendências de mercado, o agente pode ajudar você a planejar pedidos de reposição para se preparar para aumentos ou diminuições na demanda dos clientes.
  • Rotas de viagem: o agente pode ajudar a economizar tempo e reduzir os custos de viagem para provedores de serviços e entregas analisando padrões de tráfego históricos e em tempo real, além de eventos como obras ou vias interditadas.
  • Evite interrupções: o agente pode ajudar você a evitar possíveis interrupções de serviço identificando a causa raiz de interrupções históricas. Ele também pode ajudar a prever possíveis estados de falha futuros para que você possa mitigar um problema antes que ele se torne um problema.

Essa arquitetura é ideal para qualquer organização que precise se adaptar a padrões de mudança com base em tendências estabelecidas. Também é ideal para organizações cujos clientes podem se beneficiar de insights proativos que ajudam a planejar o futuro. Para mais informações e opções de implantação, consulte Agente de previsão de séries temporais com o ADK e o MCP Toolbox do Google.

Recuperação de documentos

É possível adaptar essa arquitetura de referência para usar o mecanismo RAG na Gemini Enterprise Agent Platform e criar um agente para gerenciar a recuperação de dados de contexto. Um agente de recuperação de documentos pode buscar dados relevantes de um conjunto selecionado de documentos para fornecer respostas factuais com citações do material de origem.

Com um agente de recuperação de documentos, você ajuda a garantir que os clientes e usuários internos recebam respostas informadas e contextualizadas para as consultas. Essa implementação pode ajudar a reduzir erros e imprecisões, ajudando a garantir que as respostas sejam baseadas nas informações que você validou.

Uma arquitetura de recuperação de documentos é ideal para bases de conhecimento sobre políticas e processos, infraestrutura técnica, experiência no produto e outras documentações baseadas em fatos. Para informações sobre como desenvolver um agente de recuperação de documentos com tecnologia de geração aumentada por recuperação (RAG), consulte Agente de recuperação de documentação.

Alternativas de design

Esta seção apresenta abordagens de design alternativas que você pode considerar para a implantação do seu agente de IA no Google Cloud.

Agent Runtime

Na arquitetura descrita neste documento, o agente e as ferramentas dele são implantados no Cloud Run. Também é possível usar o GKE ou o Agent Runtime como um ambiente de execução alternativo. Para informações sobre como escolher um Agent Runtime, consulte Agent Runtime em "Escolher os componentes da arquitetura de IA agêntica".

Ambiente de execução do modelo de IA

Na arquitetura descrita neste documento, o tempo de execução do modelo de IA é a plataforma de agente. Também é possível usar o Cloud Run ou o GKE como um ambiente de execução alternativo. Para informações sobre como escolher um ambiente de execução de modelo, consulte Ambiente de execução de modelo em "Escolher os componentes da arquitetura de IA agêntica".

Considerações sobre o design

Nesta seção, fornecemos orientações para ajudar você a usar essa arquitetura de referência para desenvolver uma arquitetura que atenda aos requisitos específicos de segurança, confiabilidade, custo, eficiência operacional e desempenho.

Design do sistema

Nesta seção, fornecemos orientações para ajudar você a escolher as regiões do Google Cloud para sua implantação e selecionar os produtos e as ferramentas adequados do Google Cloud .

Seleção da região

Ao selecionar as regiões do Google Cloud para seus aplicativos de IA, considere os seguintes fatores:

Para selecionar locais Google Cloud adequados para seus aplicativos, use as seguintes ferramentas:

  • Google Cloud Seletor de região: uma ferramenta interativa baseada na Web para selecionar a região Google Cloud ideal para seus aplicativos e dados com base em fatores como pegada de carbono, custo e latência.
  • API Cloud Location Finder: uma API pública que fornece uma maneira programática de encontrar locais de implantação no Google Cloud, no Google Distributed Cloud e em outros provedores de nuvem.

Design do agente

Nesta seção, fornecemos recomendações gerais para projetar agentes de IA. Orientações detalhadas sobre como escrever código e lógica de agente estão fora do escopo deste documento.

  • Definição e design do agente:
    • Defina claramente a meta de negócios do sistema de IA agêntica e a tarefa que cada agente realiza.
    • Escolha um padrão de design de agente que melhor atenda aos seus requisitos.
    • Use o ADK para criar, implantar e gerenciar sua arquitetura de agentes com eficiência.
  • Interações do agente:
    • Projete os agentes humanos na arquitetura para oferecer suporte a interações em linguagem natural.
    • Verifique se cada agente comunica claramente as ações e o status aos clientes dependentes.
    • Projete os agentes para detectar e lidar com consultas ambíguas e interações com nuances.
  • Contexto, ferramentas e dados:
    • Verifique se os agentes têm contexto suficiente para rastrear interações de várias rodadas e parâmetros de sessão.
    • Descreva claramente a finalidade, os argumentos e o uso das ferramentas que os agentes podem usar.
    • Verifique se as respostas dos agentes estão embasadas em fontes de dados confiáveis para reduzir as alucinações.
    • Implemente uma lógica para lidar com situações sem correspondência, como quando um comando está fora do assunto.

Memória e armazenamento de sessão

O exemplo de arquitetura mostrado neste documento não inclui armazenamento de memória ou de sessão. Em um ambiente de produção, você pode melhorar as respostas e adicionar personalização integrando estado e memória ao seu agente.

  • Sessão: uma sessão é a conversa entre um usuário e o agente, desde a interação inicial até o fim do diálogo.
  • Estado: o estado são os dados que o agente usa e coleta em uma sessão específica. Os dados de estado coletados incluem o histórico de mensagens trocadas entre o usuário e o agente, os resultados de chamadas de ferramentas e outras variáveis necessárias para que o agente entenda o contexto da conversa.

O ADK pode rastrear sessões na memória de curto prazo usando o objeto Session e os atributos state. O ADK também oferece suporte à memória de longo prazo em sessões com o mesmo usuário, inclusive pelo Memory Bank. Para armazenar o estado da sessão, também é possível usar serviços como o Memorystore para Redis.

Para informações sobre as opções de memória do agente, consulte Escolher os componentes da arquitetura de IA agêntica.

Segurança

Nesta seção, descrevemos as considerações e recomendações de design para criar uma topologia no Google Cloud que atenda aos requisitos de segurança da sua carga de trabalho.

Considerações sobre segurança para agentes

Os agentes de IA apresentam riscos de segurança específicos e críticos que as práticas de segurança convencionais e determinísticas podem não ser capazes de mitigar adequadamente. O Google recomenda uma abordagem que combina os pontos fortes dos controles de segurança determinísticos com defesas dinâmicas baseadas em raciocínio. Essa abordagem se baseia em três princípios básicos: supervisão humana, autonomia do agente cuidadosamente definida e capacidade de observação. Veja a seguir recomendações específicas que estão alinhadas com esses princípios básicos.

  • Supervisão humana: um sistema de IA agêntica pode falhar ou não funcionar como esperado. Por exemplo, o modelo pode gerar conteúdo impreciso ou um agente pode selecionar ferramentas inadequadas. Em sistemas de IA agêntica críticos para os negócios, incorpore um fluxo human-in-the-loop para permitir que supervisores humanos monitorem, substituam e pausem os agentes. Por exemplo, usuários humanos podem revisar a saída dos agentes, aprovar ou rejeitar as saídas e fornecer mais orientações para corrigir erros ou tomar decisões estratégicas. Essa abordagem combina a eficiência dos sistemas de IA agêntica com o pensamento crítico e a experiência no domínio dos usuários humanos.
  • Identidade do agente e acesso de privilégio mínimo:
  • Governança do tráfego de entrada e saída: roteie o tráfego do agente pelo Gateway de Agente para aplicar políticas de segurança de tempo de execução nos limites de entrada e saída. Para informações sobre os Agent Runtimes que oferecem suporte ao Gateway de Agente, consulte Agent Runtimes compatíveis.
    • Cliente para agente (entrada): implante o Gateway de Agente na frente do Agent Runtime. O gateway ajuda a autenticar chamadores e inspecionar comandos de entrada em tempo real usando o Model Armor.
    • Agente para qualquer lugar (saída):
      • Encaminhe solicitações de saída de agente para agente (A2A) e de agente para ferramenta (MCP) pelo Gateway de Agente no modo de saída.
      • Aplique políticas de acesso de negação padrão usando políticas de acesso do IAM e o Identity-Aware Proxy (IAP).
      • Verifique se os agentes e as ferramentas de destino estão registrados no Agent Registry.
      • Inspecione invocações e respostas de ferramentas de saída com o Model Armor para ajudar a evitar a exfiltração de dados, a injeção indireta de comandos e o uso indevido de ferramentas.
  • Monitoramento: monitore o comportamento do agente usando recursos abrangentes de rastreamento que oferecem visibilidade sobre todas as ações de um agente, incluindo o processo de raciocínio, a seleção de ferramentas e os caminhos de execução. Para mais informações, consulte Como fazer login de um agente no Agent Runtime e Como fazer login no ADK.

Para mais informações sobre como proteger agentes de IA, consulte Segurança para agentes de IA.

Considerações de segurança da Agent Platform

Para garantir que as configurações e o uso da Agent Platform atendam aos seus requisitos de segurança, considere as seguintes recomendações:

  • Responsabilidade compartilhada: a segurança é uma responsabilidade compartilhada. A Agent Platform protege a infraestrutura subjacente e oferece ferramentas e controles de segurança para ajudar você a proteger seus dados, códigos e modelos. Você é responsável por configurar corretamente seus serviços, gerenciar controles de acesso e proteger seus aplicativos. Para mais informações, consulte Responsabilidade compartilhada da Agent Platform.
  • Controles de segurança: a Agent Platform oferece suporte a Google Cloud controles de segurança que você pode usar para atender aos requisitos de residência de dados, chaves de criptografia gerenciadas pelo cliente (CMEK), segurança de rede usando VPC Service Controls e Transparência no acesso. Para mais informações, consulte a seguinte documentação:
  • Segurança: os modelos de IA podem produzir respostas nocivas, às vezes em resposta a comandos maliciosos.
    • Para aumentar a segurança e reduzir o possível uso indevido do sistema de IA agêntica, configure filtros de conteúdo para atuar como barreiras contra entradas e respostas nocivas. Para mais informações, consulte Filtros de segurança e conteúdo.
    • Para inspecionar e higienizar solicitações de inferência, comandos do agente, chamadas de ferramentas e respostas a ameaças como injeção de comandos e conteúdo prejudicial, use o Model Armor para chamadas diretas da API do modelo e para solicitações roteadas pelo Agent Gateway. O Model Armor ajuda a evitar entradas maliciosas, verificar a segurança do conteúdo, proteger dados sensíveis, manter a conformidade e aplicar políticas de segurança de maneira consistente.
  • Acesso ao modelo: é possível configurar políticas da organização para limitar o tipo e as versões de modelos de IA que podem ser usados em um projeto Google Cloud . Para mais informações, consulte Controlar o acesso aos modelos do Model Garden.
  • Proteção de dados: para descobrir e desidentificar dados sensíveis nos comandos e respostas e nos dados de registro, use a API Cloud Data Loss Prevention. Para mais informações, assista este vídeo: Proteção de dados sensíveis em apps de IA.

Considerações de segurança do MCP

Para garantir que sua implementação do MCP atenda aos requisitos de segurança, considere as seguintes recomendações:

  • Registro e descoberta de ferramentas: registre servidores e ferramentas MCP no Agent Registry para que os agentes se conectem apenas a endpoints MCP inventariados e aprovados pelo administrador.
  • Controle de acesso e inspeção de tráfego: encaminhe o tráfego do agente para o MCP pelo Gateway de Agente no modo Agente para qualquer lugar (saída) e proteja os servidores MCP (como os hospedados no Cloud Run) usando IAP e políticas de acesso do IAM. Configure o Model Armor ou as políticas de governança semântica no Gateway de Agente para inspecionar as entradas e saídas da ferramenta MCP em busca de exposição de dados sensíveis e injeção de comandos indireta.
  • Segurança geral do MCP: ao configurar seus agentes para usar o MCP, verifique se o acesso a dados e ferramentas externos está autorizado, implemente controles de privacidade, como criptografia, aplique filtros para proteger dados sensíveis e monitore as interações dos agentes. Para mais informações, consulte MCP e segurança.

Considerações sobre segurança do A2A

Para garantir que sua implementação de A2A atenda aos requisitos de segurança, considere as seguintes recomendações:

  • Segurança de transporte: o protocolo A2A exige HTTPS para toda a comunicação A2A em ambientes de produção e recomenda o uso de versões 1.2 ou mais recentes do Transport Layer Security (TLS).
  • Autenticação: o protocolo A2A delega a autenticação a mecanismos da Web padrão, como cabeçalhos HTTP, e a padrões como OAuth2 e OpenID Connect. Cada agente anuncia os requisitos de autenticação no card de agente. Para mais informações, consulte Autenticação A2A.
  • Governança entre agentes: registre agentes A2A no Agent Registry e encaminhe solicitações entre agentes pelo Gateway de Agente. Ao combinar o Gateway de Agente com a Identidade do Agente, o IAP e as políticas de acesso do IAM, é possível verificar criptograficamente a identidade do agente de chamada, aplicar autorização granular entre agentes coordenadores e subagentes e inspecionar payloads entre agentes com o Model Armor.

Considerações de segurança do Cloud Run

Para garantir que a implementação do Cloud Run atenda aos seus requisitos de segurança, considere as seguintes recomendações:

  • Segurança de entrada (para o serviço de front-end): para controlar o acesso ao aplicativo, desative o URL run.app padrão do serviço de front-end do Cloud Run e configure um balanceador de carga de aplicativo externo regional. Além de fazer o balanceamento de carga do tráfego de entrada para o aplicativo, o balanceador de carga gerencia os certificados SSL. Para maior proteção, use as políticas de segurança do Google Cloud Armor para fornecer filtragem de solicitações, proteção contra DDoS e limitação de taxa para o serviço.

  • Autenticação de usuário:

    • Usuários na sua organização: para autenticar o acesso de usuários internos ao serviço de front-end do Cloud Run, use o IAP. Quando um usuário tenta acessar um recurso protegido pelo IAP, o IAP executa verificações de autenticação e autorização.
    • Usuários fora da sua organização: para autenticar o acesso de usuários externos ao serviço de front-end, use o Identity Platform ou o Firebase Authentication. Para gerenciar o acesso de usuários externos, configure o aplicativo para processar um fluxo de login e fazer chamadas de API autenticadas para o serviço do Cloud Run.

    Para mais informações, consulte Autenticar usuários.

  • Segurança do agente e do servidor MCP: ao hospedar agentes ou servidores MCP no Cloud Run, configure os recursos da Agent Platform para o Cloud Run para atribuir uma identidade de agente gerenciada ao serviço e use o IAP com o Gateway de Agente para autenticar e autorizar solicitações de entrada de agentes e ferramentas.

  • Segurança da imagem de contêiner: para garantir que apenas imagens de contêiner autorizadas sejam implantadas no Cloud Run, use a autorização binária. Para identificar e mitigar riscos de segurança nas imagens de contêiner, use o Artifact Analysis para executar verificações de vulnerabilidades automaticamente. Para mais informações, consulte Visão geral da verificação de contêineres.

  • Residência de dados: o Cloud Run ajuda você a atender aos requisitos de residência de dados. Os serviços do Cloud Run são executados na região selecionada.

Para mais orientações sobre segurança de contêineres, consulte Dicas gerais de desenvolvimento do Cloud Run.

Considerações de segurança para todos os Google Cloud produtos na arquitetura

Para garantir que sua arquitetura atenda aos requisitos de segurança, considere as seguintes recomendações gerais:

  • Criptografia de dados: por padrão,o Google Cloud criptografa dados em repouso usando Google-owned and Google-managed encryption keys. Para proteger os dados dos agentes usando chaves de criptografia que você controla, use as CMEKs que você cria e gerencia no Cloud KMS. Para informações sobre serviços Google Cloud compatíveis com o Cloud KMS, consulte Serviços compatíveis.
  • Reduzir o risco de exfiltração de dados: para reduzir o risco de exfiltração de dados, crie um perímetro do VPC Service Controls ao redor da infraestrutura. O VPC Service Controls é compatível com todos os Google Cloud serviços usados por essa arquitetura de referência.
  • Controle de acesso: ao configurar permissões para os recursos na sua topologia, siga o princípio de menor privilégio.
  • Segurança do ambiente de nuvem: use as ferramentas do Security Command Center para detectar vulnerabilidades, identificar e reduzir ameaças, definir e implantar uma postura de segurança e exportar dados para análise mais detalhada.
  • Otimização pós-implantação: depois de implantar o aplicativo no Google Cloud, receba recomendações para otimizar ainda mais a segurança usando o Active Assist. Revise as recomendações e aplique-as conforme apropriado para seu ambiente. Para mais informações, consulte Encontrar recomendações no Active Assist.

Mais recomendações de segurança

Confiabilidade

Nesta seção, descrevemos as considerações e recomendações de design para criar e operar uma infraestrutura confiável para sua implantação no Google Cloud.

Componente Considerações e recomendações de design
Agente

Simular falhas: antes de implantar o sistema de IA agêntica na produção, valide-o simulando um ambiente de produção. Identifique e corrija problemas e comportamentos inesperados.

Escalonar horizontalmente: para garantir alta disponibilidade e tolerância a falhas, execute várias instâncias do aplicativo do agente atrás de um balanceador de carga. Essa abordagem também pode ajudar a reduzir a latência e os tempos limite distribuindo solicitações entre instâncias. Alguns ambientes de execução de agente lidam com o balanceamento de carga automaticamente, como com o escalonamento automático de instâncias nos serviços do Cloud Run.

Recuperação de interrupções: para garantir que o agente possa lidar com reinicializações e manter o contexto, separe o estado do ambiente de execução. Para implementar um aplicativo de agente sem estado, use um repositório de dados externo, como um banco de dados ou um cache distribuído. Por exemplo, é possível usar o Memory Bank, o Memorystore para Redis ou um serviço de banco de dados como o Cloud SQL.

Tratar erros: para permitir o diagnóstico e a solução de problemas, implemente mecanismos de registro, tratamento de exceções e repetição.

Agent Platform

Planejamento de capacidade: se o número de solicitações exceder a capacidade alocada, o código de erro 429 será retornado. Para cargas de trabalho essenciais para os negócios e que exigem constantemente uma alta capacidade de processamento, é possível reservar capacidade usando a Capacidade de Processamento Provisionada.

Disponibilidade do endpoint do modelo: se os dados puderem ser compartilhados em várias regiões ou países, use um endpoint global para o modelo.

Cloud Run

Robustez contra interrupções de infraestrutura: o Cloud Run é um serviço regional. Ele armazena dados de forma síncrona em várias zonas dentro de uma região e faz o balanceamento de carga do tráfego entre as zonas automaticamente. Em caso de interrupção do serviço na zona, o Cloud Run continua em execução e os dados não são perdidos. Se ocorrer uma interrupção do serviço na região, o serviço deixará de ser executado até que o Google resolva essa interrupção.

Escalonamento horizontal: os serviços do Cloud Run lidam com o escalonamento automático de instâncias para você. O escalonamento automático ajuda a garantir que as instâncias possam processar todas as solicitações, eventos e utilização da CPU necessários para garantir a alta disponibilidade.

Todos os produtos da arquitetura

Otimização pós-implantação: depois de implantar o aplicativo no Google Cloud, receba recomendações para otimizar ainda mais a segurança usando o Active Assist. Analise as recomendações e aplique-as conforme apropriado para seu ambiente. Para mais informações, consulte Encontrar recomendações no Active Assist.

Para princípios e recomendações de confiabilidade específicos para cargas de trabalho de IA e ML, consulte Perspectiva de IA e ML: confiabilidade no Well-Architected Framework.

Operações

Nesta seção, descrevemos os fatores que você precisa considerar ao usar essa arquitetura de referência para projetar uma topologia do Google Cloud que possa ser operada de maneira eficiente.

Componente Considerações e recomendações de design
Agente

Depuração e análise: implemente a geração de registros estruturados no aplicativo do agente. O registro e o rastreamento permitem capturar informações importantes em um formato estruturado, como quais ferramentas foram chamadas, as entradas e saídas do agente e a latência de cada etapa.

Agent Platform

Monitoramento usando registros agênticos: por padrão, os registros do agente gravados nos streams stdout e stderr são encaminhados para o Cloud Logging. Para geração de registros avançada, é possível integrar o logger do Python ao Logging. Se você precisar de controle total sobre o registro e os registros estruturados, use o cliente do Logging. Para mais informações, consulte Como registrar um agente e Como fazer login no ADK.

Avaliação contínua: faça regularmente uma avaliação qualitativa da saída dos agentes e da trajetória ou das etapas seguidas por eles para produzir a saída. Para implementar a avaliação de agentes, use o serviço de avaliação de IA generativa ou os métodos de avaliação compatíveis com o ADK.

Cloud Run

Integridade e desempenho: monitore seus serviços do Cloud Run usando a Google Cloud Observability. Configure alertas no Cloud Monitoring para notificar você sobre possíveis problemas, como um aumento nas taxas de erro, alta latência ou utilização anormal de recursos.

Bancos de dados

Integridade e desempenho: monitore seu banco de dados usando o Google Cloud Observability. Configure alertas no Monitoring para notificar você sobre possíveis problemas, como um aumento nas taxas de erro, alta latência ou utilização anormal de recursos.

MCP

Ferramentas de banco de dados: para gerenciar com eficiência as ferramentas de banco de dados dos seus agentes de IA e garantir que eles lidem com segurança com complexidades como pool de conexões e autenticação, use a MCP Toolbox for Databases. Ele oferece um local centralizado para armazenar e atualizar ferramentas de banco de dados. É possível compartilhar as ferramentas entre agentes e atualizá-las sem reimplantar os agentes. A caixa de ferramentas inclui uma ampla variedade de ferramentas para bancos de dados do Google Cloud , como o AlloyDB para PostgreSQL, e para bancos de dados de terceiros, como o MongoDB.

Modelos de IA generativa: para permitir que os agentes de IA usem modelos de IA generativa do Google, como o Imagen e o Veo, use os servidores MCP para APIs de mídia generativa Google Cloud .

Produtos e ferramentas de segurança do Google: para permitir que seus agentes de IA acessem produtos e ferramentas de segurança do Google, como o Google Security Operations, o Google Threat Intelligence e o Security Command Center, use servidores MCP para produtos de segurança do Google.

Todos os produtos do Google Cloud na arquitetura

Rastreamento: colete e analise continuamente dados de trace usando o Trace. Com os dados de trace, você identifica e diagnostica rapidamente problemas de latência em Agentic Workflows complexos. É possível fazer análises detalhadas com as visualizações na página do Explorador de traces do console do Google Cloud . Para mais informações, consulte Rastrear um agente.

Para princípios e recomendações de excelência operacional específicos para cargas de trabalho de IA e ML, consulte Perspectiva de IA e ML: excelência operacional no Well-Architected Framework.

Otimização de custos

Nesta seção, você encontra orientações para otimizar o custo de configuração e operação de uma topologia do Google Cloud criada usando essa arquitetura de referência.

Considerações sobre custos da Agent Platform

Para garantir que as configurações e o uso da Agent Platform atendam aos seus requisitos de custo, considere as seguintes recomendações:

  • Análise e gerenciamento de custos: para analisar e gerenciar os custos da plataforma de agentes, recomendamos criar métricas de base para consultas por segundo (QPS) e tokens por segundo (TPS). Depois, monitore essas métricas após a implantação. A referência também ajuda no planejamento de capacidade. Por exemplo, o valor de referência ajuda a determinar quando a capacidade de processamento provisionada pode ser necessária.
  • Seleção de modelo: o modelo que você seleciona para seu aplicativo de IA afeta diretamente os custos e o desempenho. Para identificar o modelo que oferece um equilíbrio ideal entre desempenho e custo para seu caso de uso específico, teste os modelos de forma iterativa. Recomendamos começar com o modelo mais econômico e avançar gradualmente para opções mais potentes.
  • Comandos econômicos: o tamanho dos comandos (entrada) e das respostas geradas (saída) afetam diretamente o desempenho e o custo. Escreva comandos curtos, diretos e que ofereçam contexto suficiente. Crie comandos para receber respostas concisas do modelo. Por exemplo, inclua frases como "resuma em duas frases" ou "liste três pontos principais". Para mais informações, consulte as práticas recomendadas para design de comandos.
  • Armazenamento em cache de contexto: para reduzir o custo das solicitações que contêm conteúdo repetido com altas contagens de tokens de entrada, use o armazenamento em cache de contexto.
  • Solicitações em lote: quando relevante, considere a previsão em lote. As solicitações em lote têm um custo menor do que as solicitações padrão.

Considerações sobre custos do Cloud Run

Para garantir que a implementação do Cloud Run atenda aos seus requisitos de custo, considere as seguintes recomendações:

Considerações de custo para todos os produtos do Google Cloud na arquitetura

Depois de implantar o aplicativo em Google Cloud, receba recomendações para otimizar ainda mais o custo usando o Active Assist. Analise as recomendações e aplique-as conforme apropriado para seu ambiente. Para mais informações, consulte Encontrar recomendações no Active Assist.

Para estimar o custo dos seus recursos do Google Cloud , use a calculadora de preços doGoogle Cloud .

Para princípios e recomendações de otimização de custos específicos para cargas de trabalho de IA e ML, consulte Perspectiva de IA e ML: otimização de custos no Well-Architected Framework.

Otimização de desempenho

Nesta seção, descrevemos considerações e recomendações de design para criar uma topologia em Google Cloud que atenda aos requisitos de desempenho das suas cargas de trabalho.

Considerações de desempenho para agentes

Para garantir que as configurações do agente atendam aos requisitos de desempenho, considere as seguintes recomendações:

  • Seleção de modelos: ao selecionar modelos para seu sistema de IA agêntica, considere os recursos necessários para as tarefas que os agentes precisam realizar.
  • Otimização de comandos: para melhorar e otimizar rapidamente a performance de comandos em grande escala e eliminar a necessidade de reescrita manual, use o otimizador de comandos da plataforma do agente. O otimizador ajuda você a adaptar comandos de maneira eficiente em diferentes modelos.

Considerações sobre a performance da Agent Platform

Para garantir que as configurações e o uso da plataforma de agente atendam aos seus requisitos de performance, considere as seguintes recomendações:

  • Seleção de modelo: o modelo que você seleciona para seu aplicativo de IA afeta diretamente os custos e o desempenho. Para identificar o modelo que oferece um equilíbrio ideal entre desempenho e custo para seu caso de uso específico, teste os modelos de forma iterativa. Recomendamos que você comece com o modelo mais econômico e avance gradualmente para opções mais avançadas.
  • Engenharia de comando: o tamanho dos comandos (entrada) e das respostas geradas (saída) afeta diretamente o desempenho e o custo. Escreva comandos que sejam curtos, diretos e forneçam contexto suficiente. Crie comandos para receber respostas concisas do modelo. Por exemplo, inclua frases como "resuma em duas frases" ou "liste três pontos principais". Para mais informações, consulte as práticas recomendadas para design de comandos.
  • Armazenamento em cache de contexto: para reduzir a latência de solicitações que contêm conteúdo repetido com altas contagens de tokens de entrada, use o armazenamento em cache de contexto.

Considerações sobre o desempenho do Cloud Run

Dependendo dos seus requisitos de desempenho, configure a memória e a CPU a serem alocadas para o serviço do Cloud Run. Para mais informações, consulte Configurar limites de memória para serviços e Configurar limites de CPU para serviços

Para mais orientações sobre otimização de desempenho, consulte Dicas gerais de desenvolvimento do Cloud Run.

Considerações de desempenho para todos os produtos do Google Cloud na arquitetura

Depois de implantar o aplicativo no Google Cloud, receba recomendações para otimizar ainda mais o desempenho usando o Active Assist. Analise as recomendações e aplique-as conforme apropriado para seu ambiente. Para mais informações, consulte Encontrar recomendações no Active Assist.

Para princípios e recomendações de otimização de desempenho específicos para cargas de trabalho de IA e ML, consulte Perspectiva de IA e ML: otimização de desempenho no Well-Architected Framework.

Implantação

A implantação automatizada para esta arquitetura de referência não está disponível. Use os exemplos de código a seguir para criar uma arquitetura de agente único:

Para ver exemplos de código e começar a usar o ADK com servidores MCP, consulte Ferramentas do MCP.

Para exemplos de outros sistemas de IA de agente único, use os seguintes exemplos de código. Esses exemplos de código são pontos de partida totalmente funcionais para aprendizado e experimentação. Para uma operação ideal em ambientes de produção, personalize a base de código com base nos seus requisitos técnicos e de negócios específicos.

  • Compras personalizadas: ofereça recomendações de produtos personalizadas para uma marca, loja ou marketplace on-line específico.
  • Gerenciamento de incidentes: valide o token e a identidade do usuário final por solicitação usando a propagação dinâmica de identidade.
  • Processamento de pedidos: processe e armazene pedidos e organize a confirmação por e-mail com uma revisão humana condicional para quantidades de pedidos especificadas.
  • Engenharia de dados: desenvolver pipelines do Dataform, resolver problemas de pipeline e gerenciar a engenharia de dados, desde consultas SQL complexas até transformações e dependências de dados.
  • Recuperação de documentação: use a RAG para consultar documentos que você envia ao mecanismo de RAG na Gemini Enterprise Agent Platform e receba respostas com citações de documentação e código.

A seguir

Colaboradores