Guia de início rápido do Kit de desenvolvimento de agentes

Depois de configurar o agente do Agent Development Kit (ADK) para usar as sessões e o Memory Bank do Vertex AI Agent Engine, o agente lê e grava memórias e sessões automaticamente para você.

Para o guia de início rápido usando a API REST, consulte Início rápido com a API REST.

Neste tutorial, mostramos como usar as sessões e o banco de memória do mecanismo de agente da Vertex AI com o ADK para criar e usar sessões e memórias de longo prazo:

  1. Crie seu agente e executor do ADK local.

  2. Interaja com seu agente para gerar dinamicamente recordações de longo prazo acessíveis em todas as sessões.

  3. Limpeza.

Antes de começar

Para concluir as etapas demonstradas neste tutorial, primeiro siga as etapas em Configurar o Memory Bank.

Defina as variáveis de ambiente

Para usar o ADK, defina as variáveis de ambiente:

import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

Substitua:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: sua região. Somente us-central1 é compatível com o Memory Bank do Vertex AI Agent Engine.

Criar seu agente do ADK

  1. Ao desenvolver seu agente do ADK, inclua uma ferramenta Memory, que controla quando o serviço de memória é usado e como as memórias são incluídas no comando. O agente de exemplo usa o PreloadMemoryTool, que sempre recupera memórias no início de cada turno e as inclui na instrução do sistema:

    from google import adk

agent = adk.Agent(
    model="gemini-2.0-flash",
    name='stateful_agent',
    instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
4.  **Brevity:** Limit responses to under 30 words.
""",
    tools=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
)

  2. Crie um serviço de memória VertexAiMemoryBankService, que o executor do ADK usa para recuperar memórias.

    from google.adk.memory import VertexAiMemoryBankService

agent_engine_id = agent_engine.api_resource.name.split("/")[-1]

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

  3. Crie um executor do ADK, que orquestra a execução de agentes, ferramentas e callbacks.

    from google.adk.sessions import VertexAiSessionService
from google.genai import types

# You can use any ADK session service.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

app_name="APP_NAME"
runner = adk.Runner(
    agent=agent,
    app_name=app_name,
    session_service=session_service,
    memory_service=memory_service
)

def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run(user_id=user_id, session_id=session, new_message=content)

  for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

    Substitua:

    • APP_NAME: o nome do seu app do ADK.

Interaja com seu agente

Depois de definir o agente e configurar as sessões e o banco de memória, você pode interagir com ele.

  1. Crie sua primeira sessão. Como não há memórias disponíveis durante a primeira sessão com um usuário, o agente não conhece as preferências dele, como a temperatura preferida:

    session = await session_service.create_session(
    app_name=app_name,
    user_id="USER_ID"
)

call_agent(
    "Can you update the temperature to my preferred temperature?",
    session.id,
    "USER_ID"
)

# Agent response: "What is your preferred temperature?"
call_agent("I like it at 71 degrees", session.id, "USER_ID")
# Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
# Temperature successfully changed.

    Substitua:

    • USER_ID: um identificador do usuário. As recordações geradas nessa sessão são identificadas por esse identificador opaco. O escopo das recordações geradas é armazenado como {"user_id": "USER_ID"}.

  2. Gerar lembranças para sua sessão atual. Se o Memory Bank extrair recordações da conversa, elas serão armazenadas no escopo {"user_id": USER_ID, "app_name": APP_NAME}.

    session = await session_service.get_session(
    app_name=app_name,
    user_id="USER_ID",
    session_id=session.id
)
await memory_service.add_session_to_memory(session)

  3. Crie a segunda sessão. Se você usou o PreloadMemoryTool, o agente vai recuperar memórias no início de cada turno para acessar as preferências que o usuário comunicou anteriormente.

    session = await session_service.create_session(
    app_name=app_name,
    user_id="USER_ID"
)

call_agent("Fix the temperature!", session.id, "USER_ID")
# Agent Response:  Setting temperature to 71 degrees.  Is that correct?

Limpar

Para limpar todos os recursos usados neste projeto, é possível excluir o projeto Google Cloud usado no guia de início rápido.

Caso contrário, exclua os recursos individuais criados neste tutorial da seguinte maneira:

  1. Use o exemplo de código a seguir para excluir a instância do Vertex AI Agent Engine, o que também exclui todas as sessões ou memórias pertencentes a esse Vertex AI Agent Engine.

    agent_engine.delete(force=True)

  2. Exclua todos os arquivos criados localmente.

A seguir