Como criar agentes com estado e personalizados com o ADK

1. Introdução

O problema do peixinho-dourado

Imagine que você contrata um agente de viagens para planejar as férias dos sonhos em Tóquio. Use o agente de sessão para ver "O problema do peixinho dourado" em ação.

Você entra no escritório dela e diz:

"Olá! Quero planejar uma viagem de dois dias para Tóquio. Tenho interesse em locais históricos e sushi."

O agente responde com entusiasmo:

"Great! Planejei uma visita ao Palácio Imperial e um jantar de sushi no Sukiyabashi Jiro".

Você sorri e diz:

"Isso parece perfeito! Você pode me enviar o itinerário?"

O agente olha para você sem entender e pergunta:

"Olá! Como posso ajudar você a planejar uma viagem hoje?"

Esse é o "problema do peixinho dourado". Sem memória, cada interação é uma tela em branco. A inteligência está lá: o agente sabe como planejar viagens, mas falta continuidade. Para ser realmente útil, um agente de IA precisa se lembrar.

Sua missão hoje

Neste workshop, você vai resolver o problema do peixinho dourado criando um agente de viagens que se lembra, aprende e se adapta. Você vai passar por seis níveis de memória do agente, criando um sistema que se comporta menos como um chatbot e mais como um assistente pessoal dedicado.

Nível	Conceito	O "Superpoder"
Nível 1	Sessão e estado	Manter uma conversa sem esquecer
Nível 2	Estado multiagente	Compartilhar observações entre membros da equipe
Nível 3	Persistência	Lembrar de você mesmo após uma reinicialização do sistema
Nível 4	Callbacks	Atualização da memória de forma totalmente autônoma
Nível 5	Ferramentas personalizadas	Leitura e gravação de perfis de usuários estruturados
Nível 6	Memória multimodal	"Ver" e lembrar fotos e vídeos

A pilha de memória do ADK

Antes de escrever o código, vamos entender as ferramentas que estamos usando. O Kit de Desenvolvimento de Agente (ADK) do Google oferece uma maneira estruturada de lidar com a memória:

1. Sessão: o contêiner de uma conversa. Ele contém o histórico do que foi dito.
2. Estado: um "bloco de notas" de chave-valor anexado à sessão. Os agentes usam isso para armazenar fatos específicos (por exemplo, destination="Tokyo").
3. MemoryService: armazenamento de longo prazo. É aqui que mantemos as coisas para sempre, como preferências do usuário ou documentos analisados.

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

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

   cd ~/memory_agent_starter
   ./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:

   . ~/memory_agent_starter/set_env.sh
   

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

3. A base: sessão e estado

O conceito: o contexto é fundamental

A forma mais básica de memória é a memória de sessão. É isso que permite que um agente saiba que "ele" na frase "Quero comprar ele" se refere ao sapato de que você estava falando há 10 segundos.

No ADK, gerenciamos isso com o objeto Session.

• Abordagem sem estado: criar uma nova sessão para cada mensagem.
• Abordagem com estado: criar uma sessão e reutilizá-la durante toda a conversa.

Etapa 1: analisar o agente

👉💻 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/01_session_agent/agent.py

Abra ~/memory_agent_starter/01_session_agent/agent.py.

👉 Localize o comentário # TODO: Create a root agent dentro da função agent.py.

Substitua toda essa linha pelo seguinte código:

root_agent = LlmAgent(
    name="multi_day_trip_agent",
    model="gemini-2.5-flash",
    description="Agent that progressively plans a multi-day trip, remembering previous days and adapting to user feedback.",
    instruction="""
    You are the "Adaptive Trip Planner" 🗺️ - an AI assistant that builds multi-day travel itineraries step-by-step.

    Your Defining Feature:
    You have short-term memory. You MUST refer back to our conversation to understand the trip's context, what has already been planned, and the user's preferences. If the user asks for a change, you must adapt the plan while keeping the unchanged parts consistent.

    Your Mission:
    1.  **Initiate**: Start by asking for the destination, trip duration, and interests.
    2.  **Plan Progressively**: Plan ONLY ONE DAY at a time. After presenting a plan, ask for confirmation.
    3.  **Handle Feedback**: If a user dislikes a suggestion (e.g., "I don't like museums"), acknowledge their feedback, and provide a *new, alternative* suggestion for that time slot that still fits the overall theme.
    4.  **Maintain Context**: For each new day, ensure the activities are unique and build logically on the previous days. Do not suggest the same things repeatedly.
    5.  **Final Output**: Return each day's itinerary in MARKDOWN format.
    """,
    tools=[google_search]
)

A instrução diz ao LLM para lembrar, mas o código precisa fornecer a capacidade de lembrar.

Etapa 2: os dois cenários

Abra ~/memory_agent_starter/01_session_agent/main.py.

👉 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/01_session_agent/main.py

Abra ~/memory_agent_starter/01_session_agent/main.py e localize o comentário # TODO: Create a runner with in memorysession service dentro da função main.py.

Substitua toda essa linha pelo seguinte código:

    runner = Runner(
        agent=agent,
        session_service=session_service,
        app_name=agent.name
    )

👉 Localize o comentário # TODO: create a different session to test dentro da função main.py.

Substitua toda essa linha pelo seguinte código:

    tokyo_session_2 = await session_service.create_session(
        app_name=multi_day_agent.name,
        user_id=user_id
    )

Realizar o teste

Temos duas funções que demonstram a diferença entre a memória de "peixe dourado" e de "elefante".

Cenário 1: com estado (sessão compartilhada)

async def run_trip_same_session_scenario(session_service, user_id):
    # 1. Create ONE session
    trip_session = await session_service.create_session(...)

    # 2. Turn 1
    await run_agent_query(..., trip_session, ...)

    # 3. Turn 2 - REUSING the same session!
    # The agent can "see" Turn 1 because it's in the session history.
    await run_agent_query(..., trip_session, ...)

Cenário 2: sem estado (nova sessão a cada vez)

async def run_trip_different_session_scenario(session_service, user_id):
    # Turn 1
    tokyo_session = await session_service.create_session(...)
    await run_agent_query(..., tokyo_session, ...)

    # Turn 2 - Creating a FREASH session
    # The agent has NO IDEA what happened in Turn 1.
    tokyo_session_2 = await session_service.create_session(...)
    await run_agent_query(..., tokyo_session_2, ...)

Etapa 3: executar o agente

Vamos conferir a diferença na prática. Execute o script:

👉💻 Na linha de comando, execute o seguinte:

cd ~/memory_agent_starter
uv run python ~/memory_agent_starter/01_session_agent/main.py

Observe o cenário 1: o agente se lembra das suas preferências da primeira mensagem e adapta o plano na segunda.

Observe o cenário 2: na segunda vez ("você lembra do que eu gostei na comida?"), o agente falha completamente porque é uma nova sessão. É como dizer: "Não sei do que você está falando".

Principal vantagem

Regra nº 1 da memória:sempre reutilize o session.id para manter o contexto da conversa. O objeto Session é o buffer de memória de curto prazo do seu agente.

4. A equipe: estado multiagente

O conceito: "O jogo do telefone"

Quando vários agentes trabalham juntos, eles são como colegas passando uma pasta de arquivos um para o outro. Se um agente escrever uma observação na pasta, o próximo poderá lê-la.

No ADK, essa "pasta" é o Estado.

• O estado é um dicionário ({"key": "value"}) que fica dentro da sessão.
• Qualquer agente na sessão pode ler ou gravar nela.

Etapa 1: analisar o fluxo de trabalho

👉💻 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/02_multi_agent/agent.py

👉No arquivo ~/memory_agent_starter/02_multi_agent/agent.py, localize o comentário # TODO: foodie agent.

Substitua toda essa linha pelo seguinte código:

foodie_agent = LlmAgent(
    name="foodie_agent",
    model="gemini-2.5-flash",
    tools=[google_search],
    instruction="""You are an expert food critic. Your goal is to find the best restaurant based on a user's request.

    When you recommend a place, you must output *only* the name of the establishment and nothing else.
    For example, if the best sushi is at 'Jin Sho', you should output only: Jin Sho
    """,
    output_key="destination"  # ADK will save the agent's final response to state['destination']
)

👉 Localize o comentário # TODO: transportation agent dentro da função agent.py.

Substitua toda essa linha pelo seguinte código:

transportation_agent = LlmAgent(
    name="transportation_agent",
    model="gemini-2.5-flash",
    tools=[google_search],
    instruction="""You are a navigation assistant. Given a destination, provide clear directions.
    The user wants to go to: {destination}.

    Analyze the user's full original query to find their starting point.
    Then, provide clear directions from that starting point to {destination}.
    """,
)

👉 Localize o comentário # TODO: root_agent dentro da função agent.py.

Substitua toda essa linha pelo seguinte código:

root_agent = SequentialAgent(
    name="find_and_navigate_agent",
    sub_agents=[foodie_agent, transportation_agent],
    description="A workflow that first finds a location and then provides directions to it."
)

Agora temos dois agentes trabalhando em sequência:

1. Agente Foodie: encontra um restaurante.
2. Agente de transporte: dá instruções para chegar ao restaurante.

A transferência mágica: observe como foodie_agent passa o bastão para transportation_agent.

foodie_agent = LlmAgent(
    # ...
    # CRITICAL: This tells ADK to save the agent's output to state['destination']
    output_key="destination"
)

transportation_agent = LlmAgent(
    # ...
    # CRITICAL: This injects state['destination'] into the prompt
    instruction="""
    The user wants to go to: {destination}.
    Provide clear directions...
    """,
)

1. output_key="destination": a resposta do Foodie Agent é salva com eficiência.
2. {destination}: o agente de transporte lê essa resposta automaticamente.

(Nenhuma ação necessária) Etapa 2: o Orchestrator

Abra 02_multi_agent/main.py.

Usamos uma SequentialAgent para executá-las em ordem.

# 1. Create a single session for the sequential agent
session = await session_service.create_session(...)

# 2. Run the query
# The SequentialAgent manages the state flow:
# Query -> Foodie -> state['destination'] -> Transportation -> Final Answer
await run_agent_query(root_agent, query, ...)

O usuário envia um comando:

"Find best sushi in Palo Alto and then tell me how to get there."

Os agentes trabalham juntos para responder.

Etapa 3: executar a equipe

👉💻 No terminal do Cloud Shell, execute o fluxo de trabalho multiagente:

cd ~/memory_agent_starter
uv run python ~/memory_agent_starter/02_multi_agent/main.py

O que acontece?

1. Agente Foodie: encontra "Jin Sho" (ou similar).
2. ADK: salva "Jin Sho" em state['destination'].
3. Agente de transporte: recebe "Jin Sho" na instrução.
4. Resultado: "Para chegar ao Jin Sho da estação Caltrain, caminhe pela University Ave..."

Principal vantagem

Regra nº 2 da memória:use o estado para transmitir informações estruturadas entre agentes. Use output_key para gravar e {placeholders} para ler.

5. The Reboot - Persistence

O conceito: "O problema da reinicialização"

Até agora, nossa memória foi InMemory. Se você interromper e reiniciar o script, o agente vai esquecer tudo. É como um computador que apaga o disco rígido toda vez que você o desliga.

Para corrigir isso, precisamos de persistência. Vamos trocar InMemorySessionService por DatabaseSessionService.

Etapa 1: a troca de banco de dados

👉💻 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/03_persistent_agent/main.py

👉 No arquivo ~/memory_agent_starter/03_persistent_agent/main.py, localize o comentário # TODO: Configuration for Persistent Sessions.

Substitua toda essa linha pelo seguinte código:

SESSIONS_DIR = Path(os.path.expanduser("~")) / ".adk_codelab" / "sessions"
os.makedirs(SESSIONS_DIR, exist_ok=True)
SESSION_DB_FILE = SESSIONS_DIR / "trip_planner.db"
SESSION_URL = f"sqlite:///{SESSION_DB_FILE}"

Agora, cada sessão e evento é salvo em um arquivo SQLite.

Etapa 2: recuperação entre sessões

A persistência permite não apenas retomar uma conversa, mas também aprender com as anteriores.

No mesmo arquivo~/memory_agent_starter/03_persistent_agent/main.py, confira o Caso de teste 3: recuperação entre sessões.

👉 Localize o comentário # TODO: retrieve the previous session manually

Substitua toda essa linha pelo seguinte código:

    old_session = await session_service.get_session(
        app_name=root_agent.name, user_id="user_01", session_id=session_id
    )

👉 Localize o comentário # TODO: Extract content from the OLD session dentro da função main.py.

Substitua toda essa linha pelo seguinte código:

                    previous_context += f"- {role}: {text}\n"

👉 Localize o comentário # TODO: Manually inject the context to the query dentro da função main.py.

Substitua toda essa linha pelo seguinte código:

    query_3 = f"""
    {previous_context}

    I'm planning a new trip to Osaka this time. 
    Based on my previous preferences (above), what should I eat?
    """

Isso simula um usuário voltando meses depois. Só com um banco de dados é possível recuperar esse histórico antigo.

Etapa 3: sobreviver à reinicialização

👉💻 No terminal, execute o script:

cd ~/memory_agent_starter
uv run python ~/memory_agent_starter/03_persistent_agent/main.py

Ele cria um arquivo ~/memory_agent_starter/trip_planner.db. Tente isto:execute o script duas vezes.

• Na segunda execução, procure "Resumed existing session".
• O agente vai lembrar o contexto da primeira execução porque ele é carregado do arquivo de banco de dados.

Principal vantagem

Regra nº 3 de memória:use DatabaseSessionService para produção. Isso garante que as conversas dos usuários sobrevivam às reinicializações do servidor e permite a análise do histórico de longo prazo.

6. The Spy - Callbacks

Às vezes, é necessário atualizar a memória automaticamente com base no que o agente faz, não apenas no que ele diz. Você quer um "espião" que observe o agente e faça anotações.

No ADK, esse espião é o Callback.

• after_tool_callback: uma função que é executada sempre que o agente funciona.
• ToolContext: uma maneira de gravar no estado de dentro dessa função.

Etapa 1: a lógica

👉💻 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/04_stateful_agent/agent.py

👉 No arquivo ~/memory_agent_starter/04_stateful_agent/agent.py, localize o comentário # TODO: Implement call back logic.

Substitua toda essa linha pelo seguinte código:

def save_activity_type_callback(
    tool,
    args: Dict[str, Any],
    tool_context: ToolContext,
    tool_response: Dict[str, Any],
) -> Optional[Dict[str, Any]]:
    """
    Callback to save the TYPE of activity just planned into the session state.
    """
    # 1. Get the actual agent name.
    if tool.name == "transfer_to_agent":
         agent_name = args.get("agent_name")
    else:
         agent_name = tool.name

    activity_type = "unknown"

    # 2. Determine the type based on which agent was actually used
    if agent_name == "museum_expert":
        activity_type = "CULTURAL"
    elif agent_name == "restaurant_expert":
        activity_type = "FOOD"
    elif agent_name == "outdoor_expert":
        activity_type = "OUTDOOR"

    print(f"\n🔔 [CALLBACK] The planner transferred to '{agent_name}'.")

    # 3. Update the state directly
    tool_context.state["last_activity_type"] = activity_type
    print(f"💾 [STATE UPDATE] 'last_activity_type' is now set to: {activity_type}\n")

    return tool_response

👉 No mesmo arquivo, localize o comentário # TODO: add callback to root agent na função 04_stateful_agent/agent.py.

Substitua toda essa linha pelo seguinte código:

    after_tool_callback=save_activity_type_callback,

A instrução dinâmica:agora a instrução do agente é uma função, não uma string. Ele muda com base no estado.

def get_planner_instruction(context):
    last_activity = context.state.get("last_activity_type", "None")
    
    return f"""
    The last activity was: {last_activity}
    
    If last_activity is 'CULTURAL' -> `museum_expert` is BANNED.
    """

Etapa 3: testar o Spy

👉💻 No terminal, copie e cole o comando abaixo para executar o script:

cd ~/memory_agent_starter
uv run python ~/memory_agent_starter/04_stateful_agent/main.py

Ao executar esse agente, você vai ver um loop.

1. Turno 1: você pede um museu. O espião define last_activity="CULTURAL".
2. Turno 2: você pede outro museu.
3. Atualizações nas instruções do agente: "CULTURAL is BANNED".
4. O agente diz: "Não posso fazer outro museu. Que tal um parque?"

Confira os registros do console para [CALLBACK] e [STATE UPDATE]. Você pode ver a memória mudando em tempo real enquanto o agente trabalha.

Principal vantagem

Regra nº 4 da memória:use callbacks para automatizar o gerenciamento de estado. O agente cria o próprio contexto apenas fazendo o trabalho dele.

7. O arquivo: ferramentas personalizadas

O conceito: "Memória estruturada"

Até agora, a "Memória" era um registro de conversa ou um simples par de chave-valor. Mas e se você precisar se lembrar de um perfil de usuário complexo? Por exemplo: diet: vegan, budget: high, pets: [cat, dog].

Para isso, tratamos a memória como uma ferramenta. O agente decide explicitamente quando abrir o arquivo (leitura) e quando registrar um relatório (gravação).

Etapa 1: as ferramentas

👉💻 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/05_profile_agent/tools.py

👉 Neste arquivo: ~/memory_agent_starter/05_profile_agent/tools.py.

Precisamos implementar estas duas ferramentas específicas:

1. save_user_preferences: grava em um banco de dados.
2. recall_user_preferences: lê de um banco de dados.

Localize o comentário # TODO: implement save_user_preferences tools dentro da função ~/memory_agent_starter/05_profile_agent/tools.py.

Substitua toda essa linha pelo seguinte código:

def save_user_preferences(tool_context: ToolContext, new_preferences: Dict[str, Any]) -> str:
    user_id = tool_context.session.user_id
    with sqlite3.connect(USER_DB_FILE) as conn:
        for key, value in new_preferences.items():
            conn.execute("INSERT INTO user_preferences (user_id, pref_key, pref_value) VALUES (?, ?, ?) ON CONFLICT(user_id, pref_key) DO UPDATE SET pref_value = excluded.pref_value;",
                         (user_id, key, json.dumps(value)))
    return f"Preferences updated: {list(new_preferences.keys())}"

👉 Localize o comentário # TODO: implement recall_user_preferences tools dentro da função 05/tools.py.

Substitua toda essa linha pelo seguinte código:

def recall_user_preferences(tool_context: ToolContext) -> Dict[str, Any]:
    user_id = tool_context.session.user_id
    preferences = {}
    with sqlite3.connect(USER_DB_FILE) as conn:
        rows = conn.execute("SELECT pref_key, pref_value FROM user_preferences WHERE user_id = ?", (user_id,)).fetchall()
        if not rows: return {"message": "No preferences found."}
        for key, value_str in rows: preferences[key] = json.loads(value_str)
    return preferences

A instrução força um fluxo de trabalho:

instruction="""
1. RECALL FIRST: First action MUST be `recall_user_preferences`.
3. LEARN: If a user states a new preference, use `save_user_preferences`.
"""

Etapa 2: a execução

👉💻 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/05_profile_agent/main.py

Abra ~/memory_agent_starter/05_profile_agent/main.py.

Ao contrário dos módulos anteriores, em que o ADK processava o estado automaticamente, aqui o agente está no controle.

• Ele escolhe chamar recall_user_preferences no início.
• Ele escolhe chamar save_user_preferences quando você diz "Sou vegano".

Etapa 3: criar o perfil

👉💻 Execute o script:

cd ~/memory_agent_starter
uv run python ~/memory_agent_starter/05_profile_agent/main.py

Teste este fluxo de conversa:

1. "Olá, planeje um jantar." -> O agente verifica o banco de dados e não encontra nada. Pede preferências.
2. "Sou vegano." -> O agente salva "vegan" no banco de dados.
3. Reinicie o script.
4. "Olá, planeje um jantar." -> O agente verifica o banco de dados, vê "vegano" e sugere um restaurante vegano imediatamente.

Principal vantagem

Regra nº 5 da memória:para dados complexos e estruturados, dê ao seu agente as Ferramentas de leitura/gravação. Deixe o LLM gerenciar o próprio armazenamento de longo prazo.

8. O cérebro: memória multimodal

O conceito: "A experiência humana"

Os humanos se lembram de mais do que texto. Nós lembramos da vibe de uma foto, do som de uma voz, da sensação de um vídeo.

O Vertex AI Memory Bank permite que seu agente processe a memória multimodal. Ele pode ingerir imagens, vídeos e áudio, "entender" e recuperar esses itens mais tarde.

Etapa 1: a configuração

👉💻 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/06_multimodal_agent/main.py

👉 Abra 06_multimodal_agent/main.py. Localize o comentário # TODO: Configure Memory Bank Topic.

Substitua toda essa linha pelo seguinte código:

travel_topics = [
    MemoryTopic(
        managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES
        )
    ),
    MemoryTopic(
        managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
        )
    ),
    MemoryTopic(
        custom_memory_topic=CustomMemoryTopic(
            label="travel_experiences",
            description="""Memorable travel experiences including:
                - Places visited and impressions
                - Favorite restaurants, cafes, and food experiences
                - Preferred accommodation types and locations
                - Activities enjoyed (museums, hiking, beaches, etc.)
                - Travel companions and social preferences
                - Photos and videos from trips with location context""",
        )
    ),
    MemoryTopic(
        custom_memory_topic=CustomMemoryTopic(
            label="travel_preferences",
            description="""Travel style and preferences:
                - Budget preferences (luxury, mid-range, budget)
                - Transportation preferences (flying, trains, driving)
                - Trip duration preferences
                - Season and weather preferences
                - Cultural interests and language abilities
                - Dietary restrictions and food preferences""",
        )
    ),
    MemoryTopic(
        custom_memory_topic=CustomMemoryTopic(
            label="travel_logistics",
            description="""Practical travel information:
                - Passport and visa information
                - Frequent flyer numbers and hotel loyalty programs
                - Emergency contacts
                - Medical considerations and insurance
                - Packing preferences and essentials
                - Time zone preferences and jet lag strategies""",
        )
    ),
]

Localize o comentário # TODO: Configure Memory Bank Customization

Substitua toda essa linha pelo seguinte código:

memory_bank_config = {
    "customization_configs": [
        {
            "memory_topics": travel_topics,
        }
    ],
    "similarity_search_config": {
        "embedding_model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-embedding-001"
    },
    "generation_config": {
        "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
    },
}

Etapa 2: ingerir o mundo

Em test_trip_planner, enviamos:

1. Uma mensagem de texto ("Olá")
2. Uma imagem (ponto de referência)
3. Um vídeo (Mar Mediterrâneo)
4. Um clipe de áudio (nota de voz sobre Gaeta)

Localize o comentário # TODO create session service and memory service dentro da função 6_multimodal_agent/main.py.

Substitua toda essa linha pelo seguinte código:

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
)

👉 No mesmo arquivo 06_multimodal_agent/main.py, localize o comentário # TODO: create memory from session.

Substitua toda essa linha pelo seguinte código:

    await memory_service.add_session_to_memory(final_session_state)

Essa é a linha mágica. Ela envia toda essa mídia avançada para a Vertex AI, que a processa e indexa.

Etapa 3: a recuperação

👉💻 No terminal do Cloud Shell, abra o arquivo no editor do Cloud Shell executando:

cloudshell edit ~/memory_agent_starter/06_multimodal_agent/agent.py

O agente tem um PreloadMemoryTool.

tools=[PreloadMemoryTool(), budget_tool]

Quando uma nova sessão começa, essa ferramenta pesquisa automaticamente no Banco de Memória experiências passadas relevantes e as injeta no contexto.

Etapa 4: executar o cérebro

👉💻 No terminal do Cloud Shell, execute o script. Observação: isso exige um projeto do Google Cloud com a Vertex AI ativada:

cd ~/memory_agent_starter
uv run python ~/memory_agent_starter/06_multimodal_agent/main.py

Assista a etapa final de verificação:

"Com base na imagem, no vídeo E no áudio que compartilhei com você antes..."

O agente vai responder:

"Você precisa visitar Gaeta! Você me mostrou um vídeo do Mar Mediterrâneo e um clipe de áudio em que disse que amava Gaeta".

Ele conectou os pontos em diferentes tipos de mídia do passado.

Principal vantagem

Regra nº 6 da memória:use o Vertex AI Memory Bank para ter a melhor experiência de memória. Ele unifica texto, imagens e vídeo em um único cérebro pesquisável.

9. Conclusão

Você passou de um peixinho dourado esquecido para um elefante multimodal.

Você criou	O recurso
Agente de sessão	Memória de conversa de curto prazo
Multiagente	Memória compartilhada da equipe
Agente persistente	Histórico de longo prazo
Agente com estado	Memória dinâmica e autoatualizável
Agente de perfil	Memória de dados estruturados
Agente multimodal	Memória sensorial semelhante à humana

A confiança se baseia na memória. Ao implementar esses padrões, você cria agentes que respeitam o tempo e o histórico do usuário, levando a interações mais profundas e eficazes.

Comece a criar seus agentes personalizados hoje mesmo!