Como criar agentes personalizados com ADK, MCP e Memory Bank

1. Introdução

A pilha de agentes modernos

Criar um agente de IA de nível de produção exige mais do que um modelo de linguagem grande (LLM). Embora um LLM ofereça recursos de raciocínio, um agente robusto precisa interagir com o mundo externo, gerenciar o estado da conversa e lembrar as preferências do usuário ao longo do tempo.

Neste workshop, você vai aprender a arquitetar e criar um sistema de agentes abrangente usando três tecnologias fundamentais:

1. Conectividade (MCP): para dar ao seu agente acesso a ferramentas e dados locais.
2. Orquestração (ADK): para gerenciar o loop de raciocínio e o estado do agente.
3. Memória (banco de memória): para fornecer contexto personalizado de longo prazo.

Conceitos básicos

Componente	Função
Protocolo de Contexto de Modelo (MCP)	Um padrão universal que conecta modelos de IA a sistemas externos (bancos de dados, sistemas de arquivos, APIs) sem integrações personalizadas.
Kit de Desenvolvimento de Agente (ADK)	Um framework que fornece o ambiente de execução para agentes, gerenciando o loop de eventos, as transições de estado e a execução de ferramentas.
Serviço de sessão	Processa a memória de curto prazo. Ele preserva o contexto imediato da conversa (por exemplo, "O que o usuário acabou de perguntar?"), mas é limpo quando a sessão termina.
Vertex AI Memory Bank	Processa a memória de longo prazo. Ele persiste fatos e preferências específicos do usuário (por exemplo, "O usuário prefere Python") por tempo indeterminado, permitindo que o agente personalize interações futuras.
Vertex AI Agent Engine	O serviço de infraestrutura gerenciada que hospeda a lógica do agente e os componentes de memória em grande escala.

O que você vai criar

Para demonstrar esses conceitos, você vai criar um Assistente de design de fim de ano. Esse agente poderá receber solicitações de usuários de alto nível e orquestrar de forma autônoma ferramentas locais do Python para gerar código e imagens personalizados.

Você vai passar por três etapas:

1. Camada de ferramentas: crie um servidor MCP para expor funções locais do Python à IA.
2. Camada de agente: use o ADK para criar um agente que planeja e executa fluxos de trabalho de várias etapas.
3. Camada de memória: integra o banco de memória para permitir que o agente aprenda e se lembre das preferências de estilo do usuário.

2. Configurar

Para alimentar nossos agentes de IA, precisamos de duas coisas: um projeto do Google Cloud para fornecer a base.

Parte 1: ativar a conta de faturamento

• Reivindique sua conta de faturamento com um crédito de US$ 5, que será necessário para a implantação. Verifique sua conta do Gmail.

Não é preciso cartão de crédito nem pagamento: você vai receber US $5 em créditos sem custo financeiro. Leva menos de dois minutos. Basta inserir seu nome e aceitar os créditos.

Parte 2: ambiente aberto

1. 👉 Clique neste link para acessar diretamente o editor do Cloud Shell.
2. 👉 Se for preciso autorizar em algum momento hoje, clique em Autorizar para continuar.
3. 👉 Se o terminal não aparecer na parte de baixo da tela, abra-o:
   • Clique em Visualizar.
   • Clique em Terminal.
4. 👉💻 No terminal, verifique se você já está autenticado e se o projeto está definido como seu ID do projeto usando o seguinte comando:

   gcloud auth list
   

5. 👉💻 Clone o projeto de bootstrap do GitHub:

   git clone https://github.com/cuppibla/holiday_workshop
   

6. 👉💻 Execute o script de configuração no diretório do projeto.

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ Observação sobre o ID do projeto:o script vai sugerir um ID do projeto padrão gerado aleatoriamente. Pressione Enter para aceitar esse padrão.

   No entanto, se você preferir criar um novo projeto específico, digite o ID do projeto desejado quando o script solicitar.

   O script vai processar o restante da configuração automaticamente.
7. 👉💻 Defina o ID do projeto necessário:

   gcloud config set project $(cat ~/project_id.txt) --quiet
   

Parte 3: configurar permissões

1. 👉💻 Ative as APIs necessárias usando o comando a seguir. Isso pode levar alguns minutos.

   gcloud services enable \
       cloudresourcemanager.googleapis.com \
       servicenetworking.googleapis.com \
       run.googleapis.com \
       aiplatform.googleapis.com \
       compute.googleapis.com
   

2. 👉💻 Conceda as permissões necessárias executando os seguintes comandos no terminal:

   . ~/holiday_workshop/set_env.sh
   

Um arquivo .env será criado para você. Isso mostra as informações do projeto.

3. Turbinando com o MCP

O momento "USB-C" da IA

Imagine se toda vez que você comprasse um mouse novo, precisasse soldá-lo à placa-mãe. Esse era o estado das ferramentas de IA até pouco tempo atrás. Os desenvolvedores precisavam escrever um "código de ligação" personalizado para conectar LLMs a bancos de dados, sistemas de arquivos ou APIs.

Insira o Protocolo de Contexto de Modelo (MCP). Pense no MCP como a porta USB-C para aplicativos de IA. Ele oferece uma maneira padronizada de conectar modelos de IA a fontes de dados e ferramentas.

Se você criar um servidor MCP para suas ferramentas uma vez, poderá conectá-lo à CLI do Gemini, a um ambiente de desenvolvimento integrado ou a qualquer outro cliente compatível com o MCP sem mudar uma única linha de código.

O que você vai criar

Neste codelab, você vai criar um Assistente de design de fim de ano que:

1. Conecta-se ao seu ambiente local (ferramentas do Studio) usando o MCP.
2. Gerencia o contexto da conversa de maneira confiável usando o Kit de Desenvolvimento de Agente (ADK).
3. Lembram suas preferências (por exemplo, "Prefiro código Python") em diferentes sessões usando o Vertex AI Memory Bank.

Aviso: confira se você autenticou a CLI do Google Cloud (gcloud auth login) antes de executar os exemplos de código.

Como criar a lógica do servidor

Preparamos o ambiente, mas a lógica do servidor está incompleta. Precisamos implementar as quatro ferramentas específicas que nosso agente vai usar para criar o cartão de fim de ano.

Parte 1: abrir o esqueleto do servidor

Vamos trabalhar no diretório 01-MCP-Files-Testing/01-starter.

1. No terminal do Cloud Shell, verifique se você está no diretório correto:

   cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
   

2. Abra o arquivo no editor do Cloud Shell executando:

   cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
   

Você vai notar que o código clichê (configuração do servidor MCP, tratamento de conexões e inicialização do cliente da Vertex AI) já foi feito. No entanto, as quatro funções principais são marcadores de posição vazios no momento.

Parte 2: implementar o gerador de cenas de fim de ano

Primeiro, precisamos de uma ferramenta que considere o interesse de um usuário (por exemplo, "pássaros") e o transforma em um comando detalhado e otimizado para geração de imagens.

Localize o comentário #REPLACE_GENERATE_HOLIDAY_SCENE dentro da função generate_holiday_scene.

Substitua toda essa linha pelo seguinte código:

    prompt = (
        f"""
        Create a cozy, high-fidelity 3D render of a winter holiday scene.
        The scene should be warm and inviting with soft cinematic lighting.
        
        Seamlessly integrate the following specific theme/interest into the 
        holiday decor or landscape: {interest}.
        
        The style should be whimsical but detailed.
        Aspect Ratio: 16:9 Landscape.
        """
    )
    generate_image(prompt, "16:9", "static/generated_scene.png")
    return "Done! Saved at generated_scene.png"

Parte 3: implementar o resultado final da foto

Por fim, queremos garantir que a iluminação e o estilo pareçam fotorrealistas e festivos.

Localize o comentário #REPLACE_GENERATE_FINAL_PHOTO.

Substitua toda essa linha pelo código a seguir para realizar a transferência e a renderização de estilo final:

    prompt = (
        """
        Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
        
        Lighting: Warm, glowing ambient light from a fire below (out of frame).
        Background: Softly blurred (bokeh) pine garland and twinkling lights.
        
        Foreground Composition:
        1. A wooden picture frame containing the [attached selfie image]. 
           The face in the photo must be clearly visible.
        2. A folded holiday greeting card standing upright next to the frame. 
           The front of the card displays the [attached holiday scene image] as a print.
           
        Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
        """
    )
    generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
    return "Done! Saved at generated_final_photo.png"

Configuração do ambiente

Agora que o código está no lugar, precisamos garantir que as dependências estejam instaladas. Vamos usar o uv, um gerenciador de projetos e pacotes Python rápido.

👉💻 No terminal, execute o seguinte comando para adicionar o FastMCP como uma dependência do projeto:

cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp

Uma nova dependência fastmcp>=2.13.3 será adicionada ao arquivo ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml.

4. Teste com a CLI do Gemini para o servidor MCP

Agora que o código do servidor está completo, como podemos testá-lo?

Normalmente, testar um servidor de back-end exige a criação de uma interface de front-end ou a gravação de solicitações curl complexas. No entanto, aqui podemos usar a CLI do Gemini.

O que é a CLI do Gemini?

A CLI do Gemini é uma ferramenta de linha de comando que permite conversar diretamente com um modelo do Gemini no seu terminal, mas com um superpoder: ela pode descobrir e usar automaticamente as ferramentas em execução no seu servidor MCP local.

Isso é muito útil para o desenvolvimento porque isola a lógica. É possível verificar se o modelo entende suas ferramentas e as chama corretamente antes de se preocupar em criar uma interface da Web ou uma estrutura de agente.

Conectar e executar

Vamos pedir à CLI do Gemini para gerenciar nosso servidor usando o comando mcp add.

No terminal, execute:

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

• add holidays: demos um apelido ao nosso servidor ("holidays").
• uv run ...: fornecemos o comando explícito para iniciar o servidor Python que acabamos de modificar.

Vamos fazer mágica!

Agora, inicie a sessão de chat:

gemini

Teste o seguinte comando para saber se o Gemini consegue "ver" suas novas ferramentas. Talvez seja necessário permitir que a CLI do Gemini use nossa ferramenta de feriados.

• 👉 Usuário:

  "I want to create a festive holiday photo. I like birds a lot."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_holiday_scene(interest='birds')*
  
  Done! Saved at generated_scene.png
  

• 👉 Usuário:

  "Great! Now generate a knitting pattern for a sweater with reindeer on it."
  

• Gemini:

  *Thinking...*
  *Calling tool: generate_sweater_pattern(motif='reindeer')*
  
  Done! Saved at generated_pattern.png
  

  Como você usou o MCP, a IA entendeu exatamente qual função Python chamar para atender à sua solicitação.

Analisar a imagem

• Encerre a CLI do Gemini pressionando Control+C.
• Confira a imagem gerada na pasta: ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static.

Confira sua foto aqui:

Conclusão e próximas etapas

Parabéns! Você criou um servidor MCP funcional. Agora você tem um conjunto funcional de "ferramentas de IA" que podem gerar padrões, imagens compostas e refinar cenas.

No entanto, você notou algo no teste acima? Você precisava conduzir o processo. Você precisava pedir a cena, depois pedir o padrão e depois pedir para combinar os dois.

Embora o Gemini seja inteligente, para um fluxo de trabalho de produção complexo, em que precisamos gerar um padrão antes de colocá-lo em um suéter e lidar com erros se a geração de imagens falhar, queremos mais controle. Queremos um sistema dedicado que possa planejar, criticar o próprio trabalho e gerenciar o estado do nosso cartão de fim de ano sem que precisemos ficar de olho em cada etapa.

Na próxima seção, vamos organizar esse caos criativo. Vamos implementar o Agent Development Kit (ADK) para criar um agente estruturado que orquestra essas ferramentas do MCP em um pipeline de produção perfeito.

5. Vibe coding para criar um agente do ADK

Temos um conjunto de ferramentas em funcionamento (nosso servidor MCP), mas, no momento, somos nós que fazemos todo o trabalho pesado, dizendo ao Gemini exatamente qual ferramenta chamar e quando.

Nesta seção, vamos criar um agente de IA: um sistema que pode raciocinar, planejar e executar tarefas de várias etapas de forma autônoma. Para isso, vamos usar o Kit de Desenvolvimento de Agente (ADK).

O que é um agente?

Se as ferramentas do MCP forem as "mãos" (fazendo o trabalho), o agente será o "cérebro". Um agente usa um LLM para entender a intenção de um usuário ("Faça um cartão de fim de ano para mim"), divide em etapas ("Primeiro preciso de uma cena, depois de um padrão...") e decide quais ferramentas usar para atingir a meta.

O que é o ADK?

O Kit de Desenvolvimento de Agente (ADK) é um framework do Google que facilita a criação desses agentes. Ele lida com a "infraestrutura" complexa, como gerenciar o histórico de chat, conectar-se a ferramentas e alternar entre diferentes modelos, para que você possa se concentrar na personalidade e na lógica do seu app.

Vibe coding baseado em contexto

É comum usar um único comando grande para gerar código. No entanto, ao criar aplicativos complexos, é melhor tratar a IA como um parceiro que mantém o contexto ao longo do tempo.

Vamos usar os recursos de Memória da CLI do Gemini para preparar o terreno antes de escrever uma única linha de código.

1. Prepare o ambiente

Abra o terminal e navegue até o diretório de inicialização:

cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter

Inicie a CLI do Gemini:

gemini

2. Gerenciar contexto e memória

Ao programar com base na vibe, a IA precisa saber quem ela é e o que ela sabe. A CLI do Gemini permite gerenciar isso de forma explícita.

• /memory show: digite isso para saber o que a IA sabe sobre seu projeto e sessão.
• /memory add: use isso para injetar conhecimento fundamental que a IA precisa lembrar durante toda a conversa.

Vamos começar definindo a persona do nosso parceiro de programação. Execute o seguinte comando na CLI do Gemini:

/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."

Agora o Gemini entende o papel dele. Esse contexto vai influenciar todas as respostas subsequentes, garantindo um código de alta qualidade compatível com o ADK.

3. Etapa 1: codificação de vibe do agente básico

Em vez de tentar gerar o sistema inteiro de uma só vez, vamos começar com o esqueleto. Queremos estabelecer a estrutura de arquivos e a personalidade básica do agente.

Insira o seguinte comando na CLI do Gemini:

Let's start by building the basic agent structure. 

Please create a file structure for a `root_agent`. 
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant". 
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.

O Gemini vai gerar a estrutura de arquivos e o código Python inicial. Revise para garantir que esteja tudo certo e aplique/aceite as mudanças.

4. Etapa 2: adicionar o servidor MCP (as ferramentas)

Agora que temos um agente básico, precisamos dar "mãos" a ele. Precisamos conectar o agente ao servidor MCP que criamos no laboratório anterior.

Insira o seguinte comando na CLI do Gemini:

Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.

O Gemini vai refatorar seu agent.py atual para incluir as definições de ferramentas e a lógica de conexão.

Observação:se você quiser verificar seu trabalho ou se o código gerado não estiver funcionando como esperado, compare seus arquivos com a solução de referência localizada em: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Executar a interface da Web do agente

O ADK vem com uma interface de teste integrada chamada adk web. Isso inicia uma interface de chat leve para que possamos conversar com nosso agente imediatamente.

1. Se você ainda tiver o GeminiCLI aberto, pressione control+C para fechar. Agora, no terminal(na pasta solution, acesse starter para testar o código executando uv run adk web na pasta starter):

   cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution
   uv run adk web --port 8000
   

2. O Cloud Shell vai alertar que um serviço está sendo executado na porta 8000. Clique em Visualização na Web -> Visualizar na porta 8000.

Testar o agente

Agora você vai ver uma interface de chat. Vamos ver se o agente segue as novas instruções e acessa corretamente as ferramentas do MCP.

Teste estes comandos:

• "Olá! Quem é você?"
  • (Espere uma resposta festiva e entusiasmada).
• "Preciso de um plano de fundo para meu cartão de fim de ano. Faça uma vila nevada."
  • O agente precisa ligar para generate_holiday_scene. Observe como ele aplica automaticamente o estilo "fofo/desenho animado" definido nas instruções do sistema.
• "Gere um padrão de suéter com pequenas fatias de pizza."
  • (O agente deve ligar para generate_sweater_pattern).

Confira a imagem gerada aqui:

Pressione Control+C para sair quando terminar o teste.

Conclusão e próximas etapas

Você codificou com sucesso a vibe de um agente do ADK do Google usando uma abordagem baseada no contexto.

• Estabelecemos o contexto:usamos /memory add para definir uma persona especialista.
• Criamos o Iteratively:primeiro criamos o esqueleto e depois adicionamos as conexões de ferramentas.

A prévia da Web do ADK integrada é ótima para testes, mas, para o produto final, queremos uma experiência personalizada e com marca. Na próxima seção, vamos integrar esse agente a um front-end da Web personalizado.

Se você encontrar Unexpected response from metadata server: service account info is missing 'email' field a qualquer momento durante o workshop, isso significa que é necessário atualizar o Cloud Shell e executar gcloud config set project $(cat ~/project_id.txt) --quiet novamente para definir project id antes de continuar.

7. Como conectar o ADK à interface

Agora que temos uma definição de agente, precisamos executá-la. É aqui que entram o Runner e o Session Service.

Implementação

1. 👉 Digite o seguinte no comando:

   cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py
   

   Isso abre ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py no editor.
2. Substitua # TODO: Create Session Service pelo seguinte:

   from google.adk.sessions import InMemorySessionService
   from google.adk.memory import InMemoryMemoryService
   session_service = InMemorySessionService()
   memory_service = InMemoryMemoryService()
   

   O serviço de sessão é a "memória de trabalho" do seu agente.

   • Função: armazena o histórico confuso e imediato da conversa atual (por exemplo, "O que eu acabei de perguntar?").
   • Duas variações:
   • InMemorySessionService: rápido, fácil, mas amnésico. Se você reiniciar o servidor, o agente vai esquecer tudo. Ótimo para testes.
   • VertexAiSessionService: robusto, com suporte a banco de dados. Ele salva o estado no Google Cloud para que a conversa possa continuar semanas depois ou após reinicializações do servidor.
3. Substitua # TODO: Initialize Runner pelo seguinte:

   runner = Runner(
       app_name="agents",
       agent=christmas_agent,
       session_service=session_service,
       memory_service=memory_service,
   )
   

O Runner: se o agente é o "cérebro", o Runner é o "coração". Ela mantém o sangue circulando. O Runner é responsável por:

• Vinculação do agente a um usuário e uma sessão.
• Executar o loop de eventos.
• Gerenciar transições de estado.

4. Revise a linha 158 neste ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py(nenhuma ação necessária): se você quiser saber como o aplicativo recebe a resposta final. Confira abaixo o loop de eventos com tecnologia do runner:

   async for event in runner.run_async(
       user_id=user_id,
       session_id=session_id,
       new_message=content
   )
   

Os agentes do ADK Event Loop não apenas "respondem". Eles pensam em um loop. Quando você liga para runner.run_async():

1. Entrada do usuário entra no loop.
2. Planejar: o agente considera as ferramentas e as metas.
3. Ação: se for o caso, ela chama uma ferramenta (por exemplo, list_files).
4. Observar: lê a saída da ferramenta.
5. Refletir: decide se precisa de mais informações ou se pode responder.
6. Loop: repete as etapas de 2 a 5 até ficar satisfeito.
7. Responder: entrega a resposta final ao usuário.

Análise detalhada: arquitetura e implantação

Estamos usando o FastAPI para veicular esse agente.

• Por que o FastAPI?: Os agentes geralmente são limitados por E/S (esperando LLMs). A natureza assíncrona do FastAPI lida com isso perfeitamente.
• Ausência de estado: observe que nosso endpoint de API é sem estado. Não salvamos variáveis no escopo global. Usamos session_id e SessionService para reconstruir o estado de cada solicitação. Isso significa que você pode implantar no Cloud Run (sem servidor) e escalonar para zero.

8. Testar o aplicativo com a mágica do agente

1. 👉💻 Digite o seguinte comando:

   cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter
   ./start_app.sh
   

   Isso abre ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py no editor.
2. O resultado vai aparecer assim:👉👉 Clique em http://localhost:5173/ ou abra uma nova janela e digite http://localhost:5173/.

   Observe que NÃO é o link do servidor de back-end: Uvicorn running on http://0.0.0.0:8000

3. Em seguida, você vai acessar o site com a interface de chat:
4. Teste fazendo upload de uma imagem(pode ser você ou seu animal de estimação)
5. 👉 Depois, pergunte

   Can you generate a picture my cat wearing snowflake pattern sweater?
   

   A imagem gerada vai aparecer aqui:
6. 👉💻 Depois de terminar o teste, pressione control+C no terminal para encerrar o processo.

Se as coisas não funcionarem como esperado, acesse ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution, execute ./start_app.sh e siga as mesmas etapas acima.

9. Memory Bank do Vertex AI

Memória de curto prazo x memória de longo prazo

• Contexto de curto prazo: "O que eu acabei de dizer?" (Histórico da sessão). Essas informações são perdidas quando a janela de chat é fechada.
• Memória de longo prazo: "Qual é minha linguagem de programação favorita?" (Preferências do usuário). Isso deve persistir para sempre.

O Vertex AI Memory Bank oferece esse armazenamento de longo prazo. Ele permite que o agente armazene e recupere informações personalizadas sobre o usuário.

Sessões x Memory Bank

• Sessões (VertexAiSessionService): este é o registro. Ele armazena a sequência bruta e cronológica de cada mensagem, chamada de função e evento (AppendEvent, ListEvents). Ele fornece a verdade fundamental sobre o que aconteceu.
• Banco de memória (VertexAiMemoryBankService): é o Conhecimento. Ele armazena fatos sintetizados de longo prazo (GenerateMemories, RetrieveMemories) e é limitado a um user_id específico, garantindo privacidade e isolamento.

1. 👉💻 Digite o seguinte comando:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py
   

   Isso abre ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py no editor.
2. Encontre # TODO: Create Vertex AI Session Service & Memory Bank Service e substitua a linha inteira pelo seguinte:

       session_service = VertexAiSessionService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
       memory_service = VertexAiMemoryBankService(
           project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
       )
   
   

3. 👉💻 Digite o seguinte comando:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py
   

   Isso abre ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py no editor.
4. Substitua # TODO: Set Up Configuration pelo seguinte:

   # Basic configuration types
   MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig
   SimilaritySearchConfig = (
       types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig
   )
   GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig
   
   # Advanced configuration types
   CustomizationConfig = types.MemoryBankCustomizationConfig
   MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic
   CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic
   GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample
   ConversationSource = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource
   )
   ConversationSourceEvent = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent
   )
   ExampleGeneratedMemory = (
       types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory
   )
   

Principais recursos

O Vertex AI Memory Bank não é apenas um banco de dados, mas um serviço cognitivo ativo.

• Extração de memória: o sistema usa um LLM para ler a conversa e extrair fatos significativos com base nos esquemas CustomMemoryTopic definidos (por exemplo, "Preferências de suéteres"). Ele ignora conversas informais e salva o indicador.
• Consolidação de memória: mescla automaticamente fatos novos com antigos. Se um usuário disser "Gosto de vermelho" e depois "Na verdade, prefiro azul", o Memory Bank vai evoluir o registro de memória em vez de criar duplicados conflitantes.
• Geração assíncrona: as recordações são geradas em segundo plano. O agente não fica parado enquanto o banco de memória "pensa" na conversa.

5. 👉 No mesmo arquivo: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Procure o # TODO: Set up topic e substitua toda a linha pelo seguinte:

       custom_topics = [
           # Topic 1: Sweater Preference
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="sweater_preference",
                   description="""Extract the user's preferences for sweater styles, patterns, and designs. Include:
                   - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.)
                   - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted)
                   - Color preferences (red, green, navy, pastel, etc.)
                   - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft)
                   - Themes (retro, modern, ugly christmas sweater, elegant)
   
                   Example: "User wants a retro style sweater with a pixelated reindeer pattern."
                   Example: "User prefers dark blue colors and hates itchy wool."
                   """,
               )
           ),
           # Topic 2: Personal Context
           MemoryTopic(
               custom_memory_topic=CustomMemoryTopic(
                   label="personal_context",
                   description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include:
                   - Hobbies and activities (skiing, reading, gaming, cooking, etc.)
                   - Pets (type, breed, name, color)
                   - Job or profession if relevant to their style
                   - General interests (sci-fi, nature, vintage, tech)
                   - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach)
   
                   Example: "User has a golden retriever named Max."
                   Example: "User loves skiing and wants a snowy mountain background."
                   Example: "User is a software engineer who likes cyberpunk aesthetics."
                   """,
               )
           )
       ]
   

6. 👉 No mesmo arquivo: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py. Procure # TODO: Create Agent Engine e substitua toda a linha pelo seguinte:

       agent_engine = client.agent_engines.create(
           config={
               "display_name": AGENT_DISPLAY_NAME,
               "context_spec": {
                   "memory_bank_config": {
                       "generation_config": {
                           "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
                       },
                       "customization_configs": [customization_config]
                   }
               },
           }
       )
   

Mecanismo do agente

O Agent Engine é o "hardware do cérebro" na nuvem. Ele gerencia:

• Banco de dados vetorial: para armazenar memórias.
• Indexação: para tornar as recordações pesquisáveis.
• API: para permitir que o agente faça consultas. Ao executar deploy_agent.py, você está provisionando esse hardware.

Por que não usar apenas o comando?

Você pode perguntar: "Por que não colamos o histórico do usuário no comando?"

• Limites de tamanho: as janelas de contexto são grandes, mas não infinitas. Não é possível incluir cinco anos de histórico.
• Custo: processar 1 milhão de tokens para cada "Olá" é muito caro.
• Foco: a Central de memória funciona como um mecanismo de pesquisa para seu agente. Ele recupera apenas os fatos relevantes.

7. 👉💻 Digite o seguinte comando:

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
   

   Isso abre ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py no editor.
8. No arquivo ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py, substitua # TODO: Add PreloadMemoryTool pelo seguinte:

   if USE_MEMORY_BANK:
       agent_tools.append(PreloadMemoryTool())
   

PreloadMemoryTool e add_session_to_memory

Em agent.py, você vai encontrar dois componentes principais:

• PreloadMemoryTool: é uma ferramenta que permite ao agente "se pesquisar no Google". Se o usuário pedir algo vago como "Me dê meu café de sempre", o agente poderá usar essa ferramenta para consultar o banco de memória sobre "preferências de café" antes de responder.
• add_session_to_memory: é um callback em segundo plano.
  • Por que usar Async? Salvar memória leva tempo (resumir o chat, extrair fatos). Não queremos que o usuário espere por isso. Executamos em segundo plano (add_session_to_memory) usando after_agent_callback.

10. Memory Bank In Action

1. 👉💻 Digite o seguinte comando:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./use_memory_bank.sh
   

   Você vai ver o resultado abaixo:

   Esse script use_memory_bank.sh primeiro usa o arquivo 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py para anexar o Agent Engine ao seu agente, para que ele possa usar o Memory Bank da Vertex AI. Em seguida, ele vai atualizar o arquivo .env para que o ID do mecanismo do agente seja salvo como um environmental variable.

   Verifique seu arquivo ~/holiday_workshop/.env. Você vai encontrar (nenhuma ação necessária)

   USE_MEMORY_BANK=TRUE
   AGENT_ENGINE_ID={agent_engine_id}
   

2. 👉💻 Teste a memória com a interface do aplicativo. Digite o seguinte no comando:

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./start_app.sh
   

   Clique em http://localhost:5173/ ou abra uma nova janela e digite http://localhost:5173/.Observe que Uvicorn running on http://0.0.0.0:8000 é apenas o servidor de back-end, não o link real em que queremos clicar.Agora, a interface de chat no site se tornou seu agente personalizado!
3. 👉Teste a memória. Se você digitar na interface:

   I want a sweater that matches my dog. He's a golden retriever.
   

   I'm a programmer, so I want something geeky. Maybe a matrix style?
   

   I like snowflake sweater pattern
   

O agente vai identificar isso como uma preferência e armazenar no banco de memória.

Na próxima semana(ou sempre que você reiniciar o aplicativo pressionando Control+C e ./start_app.sh), se você perguntar:

what is my preference on sweater pattern?

O agente vai consultar o Memory Bank, conferir sua preferência e gerar o padrão do suéter sem precisar de um comando.

Personalização: é essencial para criar agentes úteis. Ao lembrar as preferências do usuário (padrão de suéter, contexto pessoal), o agente se torna mais eficiente e útil com o tempo.

4. Verifique no Vertex AI Agent Engine acessando Console do Google Cloud Agent Engine
   • Selecione o projeto no seletor no canto superior esquerdo:
   • Verifique o mecanismo do agente que você acabou de implantar com o comando anterior use_memory_bank.sh. Clique no mecanismo do agente que você acabou de criar.
5. Clique na guia Memories desse agente implantado para ver toda a memória.

Parabéns! Você acabou de anexar o banco de memória ao seu agente.

11. Conclusão

Resumo

Você arquitetou e criou um sistema de agentes completo.

• Conectividade: você usou o MCP para padronizar a forma como seu agente acessa ferramentas locais.
• Orquestração: você usou o ADK para gerenciar o loop de raciocínio complexo necessário para tarefas de várias etapas.
• Personalização: você usou o Memory Bank para criar uma camada de aprendizado persistente que lembra o contexto do usuário.

Próximas etapas

• Crie seu próprio servidor MCP: crie um servidor para sua API ou banco de dados interno.
• Conheça os padrões do ADK: saiba mais sobre "Reasoning Loops" e "Orchestration" na documentação do ADK.
• Implantação: leve seu agente de um script local para um serviço de produção no Cloud Run.

Continue criando: a combinação do MCP para conectividade e do Memory Bank para personalização cria a base para a próxima geração de aplicativos inteligentes.