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

Este documento fornece uma arquitetura de referência para ajudar você a projetar um sistema de IA 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 Vertex AI Agent Engine ou no Google Kubernetes Engine (GKE). A arquitetura usa o Protocolo de Contexto de Modelo (MCP), que permite que o agente acesse e processe 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 conhecimento 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 de um único agente implantado no Cloud Run:

Uma arquitetura de agente único implantada no Cloud Run.

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 dele, seleciona as ferramentas adequadas e sintetiza informações para responder às consultas.
Ambiente de execução do agente O agente é criado usando o ADK e implantado como um serviço sem servidor do Cloud Run. Também é possível implantar o agente no Vertex AI Agent Engine ou como um app contêinerizado no GKE. Para informações sobre como escolher um ambiente de execução do agente, 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, você pode configurar o acesso e o uso de ferramentas integradas, como a Pesquisa Google.
Modelo de IA e tempo de execução do modelo Para veiculação de inferência, o agente nesta arquitetura de exemplo usa o modelo de IA do Gemini na Vertex AI.
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 a ferramentas padronizando a interação entre agentes e ferramentas. Para cada par agente-ferramenta, um cliente MCP envia solicitações a um servidor MCP pelo qual o agente acessa 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 com agentes

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

  1. Um usuário insere um comando em um front-end, como uma interface de chat, que é executada 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 ferramentas e adiciona a resposta ao contexto.
    • O agente realiza embasamento e validação intermediária.

Produtos usados

Esta arquitetura de referência usa os seguintes produtos e ferramentas Google Cloud 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

Você pode adaptar essa arquitetura de referência para automatizar a triagem de relatórios de bugs recebidos: entender o problema, pesquisar duplicados, reunir 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.
  • Melhor precisão e 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 transferir tarefas repetitivas de triagem das equipes de suporte de TI e engenharia, permitindo que elas se concentrem em trabalhos 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 agentes humanos 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 de pedidos e o agendamento. Para mais informações e opções de implantação, consulte Agente 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 em 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 as organizações em vários cenários, como os seguintes:

  • Gerenciamento de inventário: usando análises avançadas combinadas 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 prestadores de serviços e entregadores. Para isso, ele analisa padrões de tráfego em tempo real e históricos, além de eventos como obras ou interdições de vias.
  • Evitar 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 em constante 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érie temporal com o ADK e a MCP Toolbox do Google.

Recuperação de documentos

Você pode adaptar essa arquitetura de referência para usar o mecanismo de RAG da Vertex AI e criar um agente para gerenciar a recuperação de dados contextuais. 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ê pode 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, garantindo 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, recursos de produtos 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 em Google Cloud.

Ambiente de execução do agente

Na arquitetura descrita neste documento, o agente e as ferramentas dele são implantados no Cloud Run. Você também pode usar o GKE ou o Vertex AI Agent Engine como um ambiente de execução alternativo. Para informações sobre como escolher um ambiente de execução do agente, consulte Ambiente de execução do agente em "Escolha os componentes da arquitetura de IA de agente".

Tempo de execução do modelo de IA

Na arquitetura descrita neste documento, o ambiente de execução do modelo de IA é a Vertex AI. Você também pode 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 "Escolha 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 seus 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 regiões Google Cloud para sua implantação e selecionar os produtos e ferramentas Google Cloud adequados.

Seleção da região

Ao selecionar Google Cloud regiões 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 ideal do Google Cloud 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 oferece uma maneira programática de encontrar locais de implantação em Google Cloud, Google Distributed Cloud e outros provedores de nuvem.

Design do agente

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

Foco no design Recomendações
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 atenda melhor aos seus requisitos.
  • Use o ADK para criar, implantar e gerenciar com eficiência sua arquitetura de agente.
Interações com agentes
  • Projete os agentes voltados para 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 processar consultas ambíguas e interações sutis.
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 com clareza a finalidade, os argumentos e o uso das ferramentas que os agentes podem usar.
  • Garanta que as respostas dos agentes sejam baseadas em fontes de dados confiáveis para reduzir as alucinações.
  • Implemente uma lógica para lidar com situações de não correspondência, como quando um comando não tem relação com o tema.

Memória e armazenamento de sessões

A arquitetura de exemplo mostrada neste documento não inclui memória ou armazenamento de sessão. Em um ambiente de produção, é possível 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 todas as chamadas de função 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 Banco de Memória. Para armazenar o estado da sessão, também é possível usar serviços como o Memorystore para Redis.

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

Segurança

Nesta seção, descrevemos 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.

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

Os agentes de IA apresentam riscos de segurança exclusivos e críticos que as práticas de segurança convencionais e deterministas talvez não consigam mitigar adequadamente. O Google recomenda uma abordagem que combine 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 fundamentais: supervisão humana, autonomia do agente cuidadosamente definida e capacidade de observação. Confira a seguir algumas recomendações específicas alinhadas a 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 essenciais para os negócios, incorpore um fluxo human-in-the-loop para permitir que supervisores humanos monitorem, substituam e pausem agentes. Por exemplo, os 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 assunto dos usuários humanos.

Controle de acesso para agentes: configure as permissões de agente usando os controles do Identity and Access Management (IAM). Conceda a cada agente apenas as permissões necessárias para realizar as tarefas e se comunicar com ferramentas e outros agentes. Essa abordagem ajuda a minimizar o possível impacto de uma violação de segurança, porque um agente comprometido teria acesso limitado a outras partes do sistema. Para mais informações, consulte Configurar a identidade e as permissões do seu agente e Gerenciar o acesso para agentes implantados.

Monitoramento: monitore o comportamento do agente usando recursos abrangentes de rastreamento que oferecem visibilidade sobre todas as ações que um agente realiza, 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 em um agente no Vertex AI Agent Engine e Como fazer login no ADK.

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

Responsabilidade compartilhada: a segurança é uma responsabilidade compartilhada. A Vertex AI protege a infraestrutura subjacente e fornece 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 Vertex AI.

Controles de segurança: a Vertex AI é compatível com controles de segurança do Google Cloud que podem ser usados para atender aos seus 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 mitigar o possível uso indevido do sistema de IA autônoma, configure filtros de conteúdo para agir 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 e respostas de inferência contra ameaças como injeção de comandos e conteúdo nocivo, use o Model Armor. 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 forma 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 nas solicitações 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.

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.
A2A

Segurança de transporte: o protocolo A2A exige HTTPS para toda a comunicação A2A em ambientes de produção e recomenda as 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 dele. Para mais informações, consulte Autenticação A2A.

Cloud Run

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 Cloud Run de front-end e configure um balanceador de carga de aplicativo externo regional. Além de balancear a carga do tráfego de entrada para o aplicativo, o balanceador de carga gerencia os certificados SSL. Para mais 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 Identity-Aware Proxy (IAP). Quando um usuário tenta acessar um recurso protegido pelo IAP, o IAP realiza 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 seu 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 Como autenticar usuários.

Segurança de imagens 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 reduzir os riscos de segurança nas imagens de contêiner, use o Artifact Analysis para executar automaticamente verificações de vulnerabilidade. 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. As funções do Cloud Run são executadas na região selecionada.

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

Todos os produtos na arquitetura

Criptografia de dados: por padrão,o Google Cloud criptografa dados em repouso usando o Google-owned and Google-managed encryption keys. Para proteger os dados dos seus agentes usando chaves de criptografia controladas por você, use CMEKs criadas e gerenciadas no Cloud KMS. Para informações sobre serviços Google Cloud compatíveis com o Cloud KMS, consulte Serviços compatíveis.

Reduza o risco de exfiltração de dados: para reduzir o risco de exfiltração de dados, crie um perímetro do VPC Service Controls em torno da infraestrutura. O VPC Service Controls é compatível com todos os serviços Google Cloud usados por essa arquitetura de referência.

Controle de acesso: ao configurar permissões para os recursos na sua topologia, siga o princípio do privilégio mínimo.

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 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

Simule falhas: antes de implantar o sistema de IA agente 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 de agente por trá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 runtimes de agente processam o balanceamento de carga automaticamente, como o escalonamento automático de instâncias nos serviços do Cloud Run.

Recuperação de interrupções: para garantir que o agente possa processar reinicializações normalmente e manter o contexto, desacople 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.

Vertex AI

Gerenciamento de cotas: a Vertex AI oferece suporte à cota compartilhada dinâmica (DSQ) para modelos do Gemini. O DSQ ajuda a gerenciar de maneira flexível as solicitações de pagamento conforme o uso e elimina a necessidade de gerenciar a cota manualmente ou solicitar aumentos. A DSQ aloca dinamicamente os recursos disponíveis para um determinado modelo e região entre os clientes ativos. Com o DSQ, não há limites de cota predefinidos para clientes individuais.

Planejamento de capacidade: se o número de solicitações para o modelo exceder a capacidade alocada, o código de erro 429 será retornado. Para cargas de trabalho essenciais para os negócios e que exigem alta capacidade de processamento consistente, é possível reservar a capacidade de processamento 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 automático do tráfego entre as zonas. 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 vai parar de ser executado até que o Google resolva essa interrupção.

Escalonamento horizontal: os serviços do Cloud Run processam 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 uso da CPU necessários para garantir a alta disponibilidade.

Todos os produtos na 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. Revise 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 framework bem arquitetado.

Operações

Nesta seção, descrevemos os fatores que você precisa considerar ao usar essa arquitetura de referência para projetar uma topologia de 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.

Vertex AI

Monitoramento usando registros: 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 Registrar um agente e 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 erros, 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 para bancos de dados. Ele oferece um local centralizado para armazenar e atualizar ferramentas de banco de dados. Você pode 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 Google Cloud , como o AlloyDB para PostgreSQL e 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 do 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 Google Security Operations, Google Threat Intelligence e Security Command Center, use servidores MCP para produtos de segurança do Google.

Todos os produtos Google Cloud na arquitetura

Rastreamento: colete e analise continuamente dados de rastreamento usando o Trace. Com os dados de rastreamento, é possível identificar e diagnosticar rapidamente problemas de latência em fluxos de trabalho complexos do agente. É possível fazer uma análise detalhada usando as visualizações na página do explorador de traces do console 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 framework bem arquitetado.

Otimização de custos

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

Componente Considerações e recomendações de design
Vertex AI

Análise e gerenciamento de custos: para analisar e gerenciar os custos da Vertex AI, recomendamos que você crie métricas de base para consultas por segundo (QPS) e tokens por segundo (TPS). Em seguida, monitore essas métricas após a implantação. A referência também ajuda no planejamento da 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 selecionado 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) afeta diretamente o desempenho e o custo. Escreva comandos curtos, diretos e que 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 criação 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.
Cloud Run

Alocação de recursos: ao criar um serviço do Cloud Run, é possível especificar a quantidade de memória e CPU a serem alocadas. Comece com as alocações padrão de CPU e memória. Observe o uso de recursos e o custo ao longo do tempo e ajuste a alocação conforme necessário. Para mais informações, consulte a seguinte documentação:

Otimização de taxas: se você conseguir prever os requisitos de CPU e memória, poderá economizar dinheiro com descontos por compromisso de uso (CUDs).
Todos os produtos na arquitetura Otimização pós-implantação: depois de implantar o aplicativo em Google Cloud, receba recomendações para otimizar ainda mais o custo 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.

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 Framework bem arquitetado.

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.

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

Seleção de modelo: ao selecionar modelos para seu sistema de IA agêntica, considere as capacidades necessárias para as tarefas que os agentes precisam realizar.

Otimização de comandos: para melhorar e otimizar rapidamente o desempenho de comandos em grande escala e eliminar a necessidade de reescrita manual, use o otimizador de comandos da Vertex AI. O otimizador ajuda você a adaptar comandos de maneira eficiente em diferentes modelos.
Vertex AI

Seleção de modelo: o modelo selecionado 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.

Engenharia de comando: o tamanho dos comandos (entrada) e das respostas geradas (saída) afeta diretamente o desempenho e o custo. Escreva comandos curtos, diretos e que 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 criação 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.
Cloud Run

Alocação de recursos: dependendo dos 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 a seguinte documentação:

Para mais orientações sobre otimização de performance, consulte Dicas gerais de desenvolvimento do Cloud Run.
Todos os produtos na arquitetura Otimização pós-implantação: depois de implantar o aplicativo em Google Cloud, receba recomendações para otimizar ainda mais a performance 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.

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

Implantação

A implantação automatizada para essa 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 exemplos de código a seguir. 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 o código com base nos 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 especificadas de pedidos.
  • Engenharia de dados: desenvolva pipelines do Dataform, solucione problemas de pipeline e gerencie 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 por upload para o mecanismo de RAG da Vertex AI e receba respostas com citações de documentação e código.

A seguir

Colaboradores