Se usó la API de Cloud Translation para traducir esta página.

Guía de inicio rápido con el kit de desarrollo de agentes

Después de configurar tu agente del Kit de desarrollo de agentes (ADK) para que use Memory Bank, el agente coordina las llamadas a Memory Bank para administrar recuerdos a largo plazo por ti.

En este instructivo, se muestra cómo puedes usar Memory Bank con el ADK para administrar recuerdos a largo plazo:

Crea tu agente y ejecutor del ADK local.
Interactúa con tu agente para generar de forma dinámica recuerdos a largo plazo a los que se puede acceder en todas las sesiones.
Realiza una limpieza.

Para realizar llamadas directamente a Memory Bank sin la organización del ADK, consulta la Guía de inicio rápido con el SDK de Agent Engine. Usar el SDK de Agent Engine es útil para comprender cómo Memory Bank genera recuerdos o para inspeccionar el contenido de Memory Bank.

Antes de comenzar

Para completar los pasos que se muestran en este instructivo, primero debes seguir los pasos que se indican en Configura Memory Bank.

Configure las variables de entorno

Para usar el ADK, configura tus variables de entorno:

import os

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

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones admitidas para Memory Bank.

Crea tu agente de ADK

Cuando desarrolles tu agente de ADK, incluye una herramienta Memory que controle cuándo el agente recupera recuerdos y cómo se incluyen en la instrucción. El agente de ejemplo usa PreloadMemoryTool, que siempre recupera recuerdos al comienzo de cada turno y los incluye en la instrucción del 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()]
)

Crea un servicio de memoria VertexAiMemoryBankService, que el ejecutor del ADK usa para recuperar recuerdos. Este paso es opcional si usas la plantilla del ADK de Agent Engine en lugar de definir tu propio entorno de ejecución del ADK.
```
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
)
```
VertexAiMemoryBankService es un wrapper del ADK alrededor de Memory Bank que se define con el BaseMemoryService del ADK y usa una interfaz diferente a la del SDK de Agent Engine. Puedes usar el SDK de Agent Engine para realizar llamadas directas a la API de Memory Bank. La interfaz VertexAiMemoryBankService incluye lo siguiente:
- memory_service.add_session_to_memory, que activa una solicitud GenerateMemories a Memory Bank con el adk.Session proporcionado como contenido fuente. El ejecutor del ADK no coordina las llamadas a este método. Si quieres automatizar la generación de recuerdos con el ADK, debes definir tus propias funciones de devolución de llamada.
- memory_service.search_memory, que activa una solicitud RetrieveMemories a Memory Bank para recuperar recuerdos relevantes para el user_id y el app_name actuales. El ejecutor del ADK coordina las llamadas a este método cuando proporcionas una herramienta de memoria a tu agente.
Crea un entorno de ejecución de ADK, que coordina la ejecución de tus agentes, herramientas y devoluciones de llamada. La configuración del ejecutor del ADK depende del entorno de implementación que uses:

`adk.Runner`

Por lo general, adk.Runner se usa en un entorno local, como Colab. La mayoría de las opciones de implementación, como Agent Engine Runtime, ofrecen su propio tiempo de ejecución para el ADK.

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)

Reemplaza lo siguiente:

APP_NAME: Es el nombre de tu app del ADK.

Plantilla del ADK de Agent Engine

La plantilla del ADK de Agent Engine (AdkApp) se puede usar de forma local y para implementar un agente del ADK en el entorno de ejecución de Agent Engine. Cuando se implementa en el entorno de ejecución de Agent Engine, la plantilla del ADK de Agent Engine usa VertexAiMemoryBankService como servicio de memoria predeterminado, con la misma instancia de Agent Engine para Memory Bank que el entorno de ejecución de Agent Engine. En este caso, no es necesario que proporciones un servicio de memoria de forma explícita.

Consulta Cómo configurar Agent Engine para obtener más detalles sobre cómo configurar tu entorno de ejecución de Agent Engine, incluido cómo personalizar el comportamiento de tu banco de memoria.

Usa el siguiente código para implementar tu agente del ADK en el entorno de ejecución de Agent Engine:

import vertexai
from vertexai.preview.reasoning_engines import AdkApp

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)

adk_app = AdkApp(agent=agent)

# Create a new Agent Engine with your agent deployed to Agent Engine Runtime.
# The Agent Engine instance will also include an empty Memory Bank.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

# Alternatively, update an existing Agent Engine to deploy your agent to Agent Engine Runtime.
# Your agent will have access to the Agent Engine instance's existing memories.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

async def call_agent(query, session_id, user_id):
    async for event in agent_engine.async_stream_query(
        user_id=user_id,
        session_id=session_id,
        message=query,
    ):
        print(event)

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones admitidas para Memory Bank.
AGENT_ENGINE_ID: Es el ID del motor de Agent que se usará para Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.
STAGING_BUCKET: Es tu bucket de Cloud Storage que se usará para la etapa intermedia de tu Agent Engine Runtime.

Cuando se ejecuta de forma local, la plantilla del ADK usa InMemoryMemoryService como el servicio de memoria predeterminado. Sin embargo, puedes anular el servicio de memoria predeterminado para usar VertexAiMemoryBankService:

def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )

adk_app = AdkApp(
      agent=adk_agent,
      # Override the default memory service.
      memory_service_builder=memory_bank_service_builder
)

async def call_agent(query, session_id, user_id):
  # adk_app is a local agent. If you want to deploy it to Agent Engine Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Engine instance instead.
  async for event in adk_app.async_stream_query(
      user_id=user_id,
      session_id=session_id,
      message=query,
  ):
      print(event)

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones admitidas para Memory Bank.
AGENT_ENGINE_ID: Es el ID del motor de Agent que se usará para Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.

Interactúa con el agente

Después de definir tu agente y configurar Memory Bank, puedes interactuar con él.

Crea tu primera sesión. Como no hay recuerdos disponibles durante la primera sesión con un usuario, el agente no conoce ninguna preferencia del usuario, como su temperatura preferida:

Nota: Es posible que haya algunas variaciones en las respuestas del agente y del Banco de memoria según los modelos que se utilicen.
adk.Runner
Cuando usas adk.Runner, puedes llamar directamente a los servicios de memoria y sesión del ADK.
```
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.
```
Reemplaza lo siguiente:
- APP_NAME: Es el nombre de la app para tu runner.
- USER_ID: Es un identificador para tu usuario. Las memorias generadas a partir de esta sesión se indexan con este identificador opaco. El alcance de los recuerdos generados se almacena como {"user_id": "USER_ID"}.
Plantilla del ADK de Agent Engine
Cuando usas la plantilla del ADK de Agent Engine, puedes llamar a tu entorno de ejecución de Agent Engine para interactuar con la memoria y las sesiones.
```
session = await agent_engine.async_create_session(user_id="USER_ID")

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

# Agent response: "What is your preferred temperature?"
await call_agent("I like it at 71 degrees", session.get("id"), "USER_ID")
# Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
# Temperature successfully changed.
```
Reemplaza lo siguiente:
- USER_ID: Es un identificador para tu usuario. Las memorias generadas a partir de esta sesión se indexan con este identificador opaco. El alcance de los recuerdos generados se almacena como {"user_id": "USER_ID"}.
Genera recuerdos para tu sesión actual. Si Memory Bank extrae recuerdos de la conversación, se almacenan en el alcance {"user_id": USER_ID, "app_name": APP_NAME}.
adk.Runner
```
session = await session_service.get_session(
    app_name=app_name,
    user_id="USER_ID",
    session_id=session.id
)
memory_service.add_session_to_memory(session)
```
Plantilla del ADK de Agent Engine
Nota: Para usar async_add_session_to_memory, tu AdkApp debe haberse creado con la versión 1.110.0 o posterior de google-cloud-aiplatform. De lo contrario, puedes activar la generación de memoria haciendo llamadas directas a Memory Bank.
```
await agent_engine.async_add_session_to_memory(session=session)
```

Crea tu segunda sesión. Si usaste PreloadMemoryTool, el agente recupera recuerdos al comienzo de cada turno para acceder a las preferencias que el usuario le comunicó anteriormente.

`adk.Runner`

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?

También puedes usar memory_service.search_memory para recuperar recuerdos directamente:

await memory_service.search_memory(
    app_name="APP_NAME",
    user_id="USER_ID",
    query="Fix the temperature!",
)

Plantilla del ADK de Agent Engine

session = await agent_engine.async_create_session(user_id="USER_ID")

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

También puedes usar agent_engine.async_search_memory para recuperar recuerdos directamente: Nota: Para usar async_search_memory, tu AdkApp debe haberse creado con la versión 1.110.0 o posterior de google-cloud-aiplatform. De lo contrario, puedes recuperar recuerdos haciendo llamadas directas a Memory Bank.

await agent_engine.async_search_memory(
    user_id="USER_ID",
    query="Fix the temperature!",
)

Limpia

Para limpiar todos los recursos que se usaron en este proyecto, puedes borrar el proyecto Google Cloud que usaste para la guía de inicio rápido.

De lo contrario, puedes borrar los recursos individuales que creaste en este instructivo de la siguiente manera:

Usa el siguiente muestra de código para borrar la instancia de Vertex AI Agent Engine, lo que también borrará cualquier sesión o memoria que pertenezca a ese Vertex AI Agent Engine.
```
agent_engine.delete(force=True)
```
Borra los archivos creados de forma local.

¿Qué sigue?

Guía de inicio rápido con el SDK de Agent Engine

Guía de inicio rápido con el kit de desarrollo de agentes Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Configure las variables de entorno

Crea tu agente de ADK

adk.Runner

Plantilla del ADK de Agent Engine

Interactúa con el agente

adk.Runner

Plantilla del ADK de Agent Engine

adk.Runner

Plantilla del ADK de Agent Engine

adk.Runner

Plantilla del ADK de Agent Engine

Limpia

¿Qué sigue?

Guía de inicio rápido con el kit de desarrollo de agentes

`adk.Runner`

`adk.Runner`

`adk.Runner`

`adk.Runner`