A partir de 29 de abril de 2025, os modelos Gemini 1.5 Pro e Gemini 1.5 Flash não estarão disponíveis em projetos que não os usaram antes, incluindo novos projetos. Para mais detalhes, consulte Versões e ciclo de vida do modelo.

Esta página foi traduzida pela API Cloud Translation.

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

Depois de configurar o agente do kit de desenvolvimento (ADK, na sigla em inglês) para usar as sessões do mecanismo do agente da Vertex AI e o banco de memória, o agente lê e grava memórias e sessões automaticamente.

Para acessar o guia de início rápido sobre a API REST, consulte Guia de início rápido com a API REST.

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

Crie sua instância do Vertex AI Agent Engine para acessar as sessões do Vertex AI Agent Engine e o banco de memória.
Crie o agente e o executor locais do ADK.
Interaja com seu agente para gerar dinamicamente recordações de longo prazo que podem ser acessadas em todas as sessões.
Limpeza.

Antes de começar

Para concluir as etapas demonstradas neste tutorial, primeiro configure seu projeto e ambiente.

Criar o projeto

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

Se você selecionou um projeto, verifique se você tem o papel do IAM de Usuário da Vertex AI (roles/aiplatform.user) no projeto.

Autenticar na Vertex AI

Para usar os exemplos Python desta página em um ambiente de desenvolvimento local, instale e inicialize o gcloud CLI e e configure o Application Default Credentials com suas credenciais de usuário.

Install the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na documentação de Google Cloud autenticação.

Importar bibliotecas

Instale o Agent Development Kit:

pip install google-adk==1.2.0

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. Apenas us-central1 é compatível com o banco de memória e as sessões do Vertex AI Agent Engine.

Criar a instância do Vertex AI Agent Engine

Para acessar as sessões do Vertex AI Agent Engine e o banco de memória do Vertex AI Agent Engine, primeiro é necessário criar uma instância do Vertex AI Agent Engine. Não é necessário implantar nenhum código para começar a usar o Sessions e o Memory Bank. Sem a implantação de código, a criação de uma instância do Vertex AI Agent Engine leva alguns segundos.

Se você quiser que o Memory Bank do agente do mecanismo da Vertex AI gere memórias para você usando um modelo de linguagem grande (LLM), forneça memoryBankConfig.generationConfig e inclua o modelo que você quer que o Memory Bank use para gerar memórias. O Agente de serviço do Vertex AI Reasoning Engine do seu projeto precisa ter permissão aiplatform.endpoints.predict para usar o modelo.

import requests

import google.auth
import google.auth.transport.requests

credentials, _ = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)

url = "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines"

response = requests.post(
    url=url,
    json={
        "contextSpec": {
            "memoryBankConfig": {
                "generationConfig": {
                    "model": f"projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_NAME"
                },
                "similaritySearchConfig": {
                    "embeddingModel": f"projects/PROJECT_ID/locations/LOCATION/publishers/google/models/EMBEDDING_MODEL_NAME"
                }
            }
        }
    },
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {credentials.token}"
    }

)

split_name = response.json()["name"].split("/")
agent_engine_name = "/".join(split_name[:-2])

Substitua:

PROJECT_ID: o ID do projeto.
LOCATION: sua região. Apenas us-central1 é compatível com o banco de memória e as sessões do Vertex AI Agent Engine.
MODEL_NAME: o modelo LLM para gerar memórias. Você pode usar qualquer modelo do Gemini ou do Model Garden.
EMBEDDING_MODEL_NAME: (opcional) o modelo de embedding para encontrar memórias semelhantes em um escopo específico. É possível usar qualquer modelo compatível com a API Embeddings que aceite o comprimento do vetor 768 como a dimensão de saída.

Criar seu agente do ADK

Crie um serviço de memória baseado no Memory Bank do Vertex AI Agent Engine envolvendo o Memory Bank no BaseMemoryService do ADK. O executor chama add_session_to_memory para acionar a geração de memória e search_memory para recuperar memórias para o escopo atual.

from datetime import datetime
import json
import pprint
import requests

from google import adk
from google.adk.memory import BaseMemoryService
from google.adk.memory import base_memory_service
from google.adk.memory import memory_entry
import google.auth
import google.auth.transport.requests
from google.genai import types

class AgentEngineMemoryBankService(BaseMemoryService):
  """Memory service for Agent Engine Memory Bank."""

  def __init__(self, agent_engine_name):
    self.agent_engine_name = agent_engine_name
    self.url = f"https://us-central1-aiplatform.googleapis.com/v1beta1/{self.agent_engine_name}"
    self.credentials, _ = google.auth.default()

  async def add_session_to_memory(self, session: adk.sessions.Session):
    """Adds a session to Agent Engine Memory Bank.

    A session can be added multiple times during its lifetime.

    Args:
        session: The session to add.
    """
    auth_req = google.auth.transport.requests.Request()
    self.credentials.refresh(auth_req)

    response = requests.post(
        url=f"{self.url}/memories:generate",
        headers={
            "Content-Type": "application/json; charset=utf-8",
            "Authorization": f"Bearer {self.credentials.token}",
        },
        json={
            "vertex_session_source": {
                "session": f"{self.agent_engine_name}/sessions/{session.id}"
            }
        }
    )
    return response.json()

  async def search_memory(
      self, app_name: str, user_id: str, query: str
  ) -> adk.memory.base_memory_service.SearchMemoryResponse:
    """Searches for memories that match the query."""
    auth_req = google.auth.transport.requests.Request()
    self.credentials.refresh(auth_req)

    filter = json.dumps(json.dumps({"user_id": user_id}))

    response = requests.get(
        url=f"{self.url}/memories?filter=scope={filter}",
        headers={
            "Content-Type": "application/json; charset=utf-8",
            "Authorization": f"Bearer {self.credentials.token}",
        },
    )

    memory_events = []
    for memory in response.json().get("memories", []):
        memory_events.append(
            memory_entry.MemoryEntry(
                author="user",
                content=types.Content(
                  parts=[types.Part(text=memory.get("fact"))],
                  role="user"),
                timestamp=memory.get("updateTime")
            )
        )

    return base_memory_service.SearchMemoryResponse(memories=memory_events)

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 inclui as memórias 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()]
)

Crie um executor do ADK, que orquestra a execução de agentes, ferramentas e callbacks. Ao usar VertexAiSessionService com a classe AgentEngineMemoryBankService, o executor orquestra chamadas para ler e gravar sessões e memórias.

from google.adk.sessions import VertexAiSessionService

session_service = VertexAiSessionService(
  "PROJECT_ID", "LOCATION")

memory_service = AgentEngineMemoryBankService(
  agent_engine_name="AGENT_ENGINE_NAME")

runner = adk.Runner(
    agent=agent,
    app_name="AGENT_ENGINE_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:

AGENT_ENGINE_NAME: o nome da instância do Vertex AI Agent Engine que você criou ou de uma instância do Vertex AI Agent Engine. O nome precisa estar no seguinte formato: projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID.

Interaja com seu agente

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

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:

Observação: pode haver alguma variação nas respostas do agente e do Memory Bank, dependendo dos modelos usados.
```
session = await session_service.create_session(
  app_name="AGENT_ENGINE_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 a partir dessa sessão são codificadas por esse identificador opaco. O escopo das recordações geradas é armazenado como {"user_id": "USER_ID"}.
Para gerar recordações usando a sessão, chame add_session_to_memory:
```
await memory_service.add_session_to_memory(session)
```
Observação: para inspecionar manualmente as recordações geradas, consulte Acessar as recordações geradas.

Crie a segunda sessão. Se você usou o PreloadMemoryTool, o agente recupera memórias no início de cada turno para acessar as preferências que o usuário já havia comunicado.

session = await session_service.create_session(
  app_name="AGENT_ENGINE_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, exclua 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:

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

credentials, _ = google.auth.default()
auth_req = google.auth.transport.requests.Request()
credentials.refresh(auth_req)

url = "https://LOCATION-aiplatform.googleapis.com/v1beta1/AGENT_ENGINE_NAME"

response = requests.delete(
    url=url,
    json={"force": True},
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {credentials.token}"
    }

)

Exclua todos os arquivos criados localmente.

A seguir

Guia de início rápido da API REST.

Guia de início rápido do Kit de desenvolvimento de agentes Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Criar o projeto

Autenticar na Vertex AI

Importar bibliotecas

Defina as variáveis de ambiente

Criar a instância do Vertex AI Agent Engine

Criar seu agente do ADK

Interaja com seu agente

Limpar

A seguir

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