Desarrollar un agente de Agent Development Kit

En esta página se explica cómo desarrollar un agente con la plantilla del kit de desarrollo de agentes (la clase AdkApp del SDK de Vertex AI para Python). El agente devuelve el tipo de cambio entre dos monedas en una fecha específica.

Sigue estos pasos:

1. Definir y configurar un modelo
2. (Opcional) Definir y usar una herramienta
3. (Opcional) Gestionar sesiones
4. (Opcional) Gestionar recuerdos

Antes de empezar

Para configurar tu entorno, sigue los pasos que se indican en el artículo Configurar el entorno.

Definir y configurar un modelo

Define la versión del modelo:

model = "gemini-2.0-flash"

(Opcional) Configura los ajustes de seguridad del modelo. Para obtener más información sobre las opciones disponibles para los ajustes de seguridad en Gemini, consulta Configurar atributos de seguridad. A continuación, se muestra un ejemplo de cómo puedes configurar los ajustes de seguridad:

from google.genai import types

safety_settings = [
    types.SafetySetting(
        category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
        threshold=types.HarmBlockThreshold.OFF,
    ),
]

(Opcional) Especifica los parámetros de generación de contenido:

from google.genai import types

generate_content_config = types.GenerateContentConfig(
   safety_settings=safety_settings,
   temperature=0.28,
   max_output_tokens=1000,
   top_p=0.95,
)

Crea un AdkApp con las configuraciones del modelo:

from google.adk.agents import Agent
from vertexai.agent_engines import AdkApp

agent = Agent(
   model=model,                                      # Required.
   name='currency_exchange_agent',                   # Required.
   generate_content_config=generate_content_config,  # Optional.
)
app = AdkApp(agent=agent)

Si estás en un entorno interactivo, como la terminal o un cuaderno de Colab, puedes ejecutar una consulta como paso de prueba intermedio:

async for event in app.async_stream_query(
   user_id="USER_ID",  # Required
   message="What is the exchange rate from US dollars to Swedish currency?",
):
   print(event)

• USER_ID: elige tu propio ID de usuario (128 caracteres como máximo). Por ejemplo, user-123.

La respuesta es un diccionario de Python similar al siguiente ejemplo:

{'actions': {'artifact_delta': {},
             'requested_auth_configs': {},
             'state_delta': {}},
 'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'To provide you with the most accurate '
                                'exchange rate, I need to know the specific '
                                'currencies you\'re asking about. "Swedish '
                                'currency" could refer to:\n'
                                '\n'
                                '*   **Swedish Krona (SEK):** This is the '
                                'official currency of Sweden.\n'
                                '\n'
                                "Please confirm if you're interested in the "
                                'exchange rate between USD and SEK. Once you '
                                'confirm, I can fetch the latest exchange rate '
                                'for you.\n'}],
             'role': 'model'},
 'id': 'LYg7wg8G',
 'invocation_id': 'e-113ca547-0f19-4d50-9dde-f76cbc001dce',
 'timestamp': 1744166956.925927}

(Opcional) Definir y usar una herramienta

Después de definir el modelo, define las herramientas que usará para razonar.

Cuando definas una función, es importante que incluyas comentarios que describan de forma completa y clara los parámetros de la función, lo que hace y lo que devuelve. El modelo usa esta información para determinar qué función debe usar. También debes probar la función localmente para confirmar que funciona.

Usa el siguiente código para definir una función que devuelva un tipo de cambio:

def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """Retrieves the exchange rate between two currencies on a specified date.

    Uses the Frankfurter API (https://api.frankfurter.app/) to obtain
    exchange rate data.

    Args:
        currency_from: The base currency (3-letter currency code).
            Defaults to "USD" (US Dollar).
        currency_to: The target currency (3-letter currency code).
            Defaults to "EUR" (Euro).
        currency_date: The date for which to retrieve the exchange rate.
            Defaults to "latest" for the most recent exchange rate data.
            Can be specified in YYYY-MM-DD format for historical rates.

    Returns:
        dict: A dictionary containing the exchange rate information.
            Example: {"amount": 1.0, "base": "USD", "date": "2023-11-24",
                "rates": {"EUR": 0.95534}}
    """
    import requests
    response = requests.get(
        f"https://api.frankfurter.app/{currency_date}",
        params={"from": currency_from, "to": currency_to},
    )
    return response.json()

Para probar la función antes de usarla en tu agente, ejecuta lo siguiente:

get_exchange_rate(currency_from="USD", currency_to="SEK")

La respuesta debería ser similar a la siguiente:

{'amount': 1.0, 'base': 'USD', 'date': '2025-04-03', 'rates': {'SEK': 9.6607}}

Para usar la herramienta en AdkApp, añádala a la lista de herramientas en el argumento tools=:

from google.adk.agents import Agent

agent = Agent(
    model=model,                     # Required.
    name='currency_exchange_agent',  # Required.
    tools=[get_exchange_rate],       # Optional.
)

Puedes probar el agente de forma local haciendo consultas de prueba. Ejecuta el siguiente comando para probar el agente de forma local con dólares estadounidenses y coronas suecas:

from vertexai.agent_engines import AdkApp

app = AdkApp(agent=agent)
async for event in app.async_stream_query(
    user_id="USER_ID",
    message="What is the exchange rate from US dollars to SEK on 2025-04-03?",
):
    print(event)

donde USER_ID es el ID de usuario que has definido. Por ejemplo, user-123.

La respuesta es una secuencia de diccionarios similar a la siguiente:

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_call': {'args': {'currency_date': '2025-04-03',
                                                   'currency_from': 'USD',
                                                   'currency_to': 'SEK'},
                                          'id': 'adk-e39f3ba2-fa8c-4169-a63a-8e4c62b89818',
                                          'name': 'get_exchange_rate'}}],
             'role': 'model'},
 'id': 'zFyIaaif',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_response': {'id': 'adk-e39f3ba2-fa8c-4169-a63a-8e4c62b89818',
                                              'name': 'get_exchange_rate',
                                              'response': {'amount': 1.0,
                                                           'base': 'USD',
                                                           'date': '2025-04-03',
                                                           'rates': {'SEK': 9.6607}}}}],
             'role': 'user'},
 'id': 'u2YR4Uom',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'The exchange rate from USD to SEK on '
                                '2025-04-03 is 9.6607.'}],
             'role': 'model'},
 'id': 'q3jWA3wl',
 # ...
}

(Opcional) Gestionar sesiones

AdkApp usa sesiones en memoria cuando se ejecuta de forma local y usa sesiones gestionadas basadas en la nube después de desplegar el agente en Vertex AI Agent Engine. En esta sección se describe cómo configurar el agente del ADK para que funcione con sesiones gestionadas.

(Opcional) Personalizar la base de datos de sesiones

Nota: Si usas un servicio de sesiones en memoria personalizado, es posible que las sesiones no se mantengan sincronizadas cuando despliegues el agente en Vertex AI Agent Engine. Solo te recomendamos que personalices tu base de datos si puedes sincronizar el estado entre sesiones en un entorno implementado.

Si quieres anular el servicio de sesión gestionado predeterminado con tu propia base de datos, puedes definir una función session_service_builder de la siguiente manera:

def session_service_builder():
  from google.adk.sessions import InMemorySessionService

  return InMemorySessionService()

Transfiere tu base de datos a AdkApp como session_service_builder=:

from vertexai.agent_engines import AdkApp

app = AdkApp(
   agent=agent,                                      # Required.
   session_service_builder=session_service_builder,  # Optional.
)

Usar el agente con sesiones

Cuando ejecutas AdkApp de forma local, las siguientes instrucciones usan sesiones en memoria:

Crea una sesión para tu agente:

session = await app.async_create_session(user_id="USER_ID")
print(session)

La sesión se crea como la representación de diccionario de un objeto de sesión del ADK.

Lista las sesiones asociadas a tu agente:

await app.async_list_sessions(user_id="USER_ID")

Obtener una sesión concreta:

session = await app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")

donde

• USER_ID es el ID de usuario que ha definido. Por ejemplo, user-123.

• SESSION_ID es el ID de la sesión concreta que quieres recuperar.

Consulta AdkApp mediante sesiones:

async for event in app.async_stream_query(
    user_id="USER_ID",
    session_id=SESSION_ID, # Optional. you can pass in the session_id when querying the agent
    message="What is the exchange rate from US dollars to Swedish currency on 2025-04-03?",
):
    print(event)

El agente puede responder con una solicitud de información como la siguiente:

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'I need to know the Swedish currency code to '
                                'provide you with the exchange rate.'}],
             'role': 'model'},
 'id': 'wIgZAtQ4',
 #...
}

Puedes enviar una respuesta (por ejemplo, "SEK") en nombre de USER_ID en la sesión correspondiente a session especificando lo siguiente:

async for event in app.async_stream_query(
    user_id="USER_ID",
    session_id=session.id, # Optional. you can pass in the session_id when querying the agent
    message="SEK",
):
    print(event)

Deberías recibir una continuación de la conversación como la siguiente secuencia de diccionarios:

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_call': {'args': {'currency_date': '2025-04-03',
                                                   'currency_from': 'USD',
                                                   'currency_to': 'SEK'},
                                          'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                          'name': 'get_exchange_rate'}}],
             'role': 'model'},
 'id': 'bOPHtzji',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_response': {'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                              'name': 'get_exchange_rate',
                                              'response': {'amount': 1.0,
                                                           'base': 'USD',
                                                           'date': '2025-04-03',
                                                           'rates': {'SEK': 9.6607}}}}],
             'role': 'user'},
 'id': '9AoDFmiL',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'The exchange rate from USD to SEK on '
                                '2025-04-03 is 1 USD to 9.6607 SEK.'}],
             'role': 'model'},
 'id': 'hmle7trT',
 # ...
}

(Opcional) Gestionar recuerdos

De forma predeterminada, AdkApp usa una implementación en memoria de la memoria del agente cuando se ejecuta de forma local y usa Vertex AI Agent Engine Memory Bank después de desplegar el agente en Vertex AI Agent Engine.

Cuando desarrolles tu agente de ADK, puedes incluir un PreloadMemoryTool que controle cuándo recupera el agente los recuerdos y cómo se incluyen en la petición. El siguiente agente de ejemplo siempre recupera recuerdos al inicio de cada turno e incluye los recuerdos en la instrucción del sistema:

from google import adk
from vertexai.agent_engines import AdkApp

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()],
)
app = AdkApp(agent=agent)

(Opcional) Personalizar el servicio de memoria

Nota: Si usas un servicio de memoria en memoria personalizado, es posible que las memorias no se sincronicen cuando implementes el agente en Vertex AI Agent Engine. Solo recomendamos personalizar el servicio de memoria si puedes sincronizar las memorias entre instancias en un entorno distribuido cuando se implemente el agente.

Si quieres anular el servicio de memoria predeterminado, puedes definir una función memory_service_builder que devuelva un BaseMemoryService de la siguiente manera:

def memory_service_builder():
  from google.adk.memory import InMemoryMemoryService

  return InMemoryMemoryService()

Transfiere tu base de datos a AdkApp como memory_service_builder=:

from vertexai.agent_engines import AdkApp

app = AdkApp(
   agent=agent,                                    # Required.
   memory_service_builder=memory_service_builder,  # Optional.
)

Usar el agente con recuerdos

Prueba tu agente de ADK con recuerdos:

1. Crea una sesión e interactúa con el agente:

   initial_session = await app.async_create_session(user_id="USER_ID")
   
   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="Can you update the temperature to my preferred temperature?",
   ):
       print(event)
   

   Como no hay recuerdos disponibles durante la primera sesión y el agente no conoce las preferencias del usuario, puede responder con una respuesta como "¿Cuál es tu temperatura preferida?". Puedes responder con el siguiente comando:

   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="I like it at 71 degrees",
   ):
       print(event)
   

   El agente puede responder algo como "Voy a poner la temperatura a 22 grados centígrados. La temperatura se ha cambiado correctamente". La respuesta del agente puede variar en función del modelo que hayas usado.

2. Generar recuerdos a partir de la sesión. Para almacenar información de la sesión y usarla en sesiones futuras, usa el método async_add_session_to_memory:

   await app.async_add_session_to_memory(session=initial_session)
   

3. Comprueba que el agente ha conservado la memoria de la sesión (con PreloadMemoryTool) creando una nueva sesión y pidiéndole al agente lo siguiente:

   new_session = await app.async_create_session(user_id="USER_ID")
   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="Fix the temperature!",
   ):
       print(event)
   

   El agente puede devolver una respuesta como "Poniendo la temperatura a 22 grados. ¿Es correcto?" La respuesta del agente puede variar en función del modelo y del proveedor de servicios de memoria que hayas usado.

4. Usa el método async_search_memory para mostrar los recuerdos del agente:

   response = await app.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   print(response)
   

Siguientes pasos

• Resumen de las sesiones
• Descripción general de Memory Bank
• Usa un agente de Agent Development Kit.
• Evalúa un agente.
• Desplegar un agente.
• Solucionar problemas al desarrollar un agente
• Obtener asistencia