AdkApp en Agent Platform SDK para Python, puedes crear agentes que muestren tipos de cambio y administren interacciones con estado.
En este documento, se explica cómo desarrollar un agente del ADK, lo que incluye definir el modelo, agregar herramientas y administrar sesiones y memorias.
Para obtener más información sobre cómo administrar los agentes implementados, consulta Administra agentes implementados.
Antes de comenzar
Asegúrate de que tu entorno esté configurado con los pasos que se indican en Configura tu entorno.
Define y configura un modelo
Especifica el modelo que quieres usar:
model = "gemini-2.0-flash"
Opcional: Configura los parámetros de seguridad del modelo. Si quieres obtener más información sobre las opciones disponibles de parámetros de seguridad en Gemini, consulta Configura los atributos de seguridad. A continuación, se muestra un ejemplo de cómo puedes configurar los parámetros de configuración 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 ejecutas en un entorno interactivo, como la terminal o un
notebook de Colab, puedes ejecutar una consulta con el
AdkApp.async_stream_query
método como un 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 con un límite de 128 caracteres.
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: Define y usa una herramienta
Después de definir el modelo, define las herramientas que usa el modelo para el razonamiento.
Cuando definas tu función, es importante incluir comentarios que describan de manera completa y clara los parámetros de la función, lo que hace y lo que muestra. El modelo usa esta información para determinar qué función usar. También debes probar la función de forma local para confirmar que funciona.
Usa el siguiente código para definir una función que muestre 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 podría ser similar a la siguiente:
{'amount': 1.0, 'base': 'USD', 'date': '2025-04-03', 'rates': {'SEK': 9.6607}}
Para usar la herramienta dentro de
AdkApp,
agrégala a la lista de herramientas en el tools= argumento:
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 si realizas consultas de prueba con el
AdkApp.async_stream_query
método. Ejecuta el siguiente comando para probar el agente de forma local con dólares estadounidenses y corona sueca:
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 definiste. 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: Administra sesiones
AdkApp
usa sesiones en memoria cuando se ejecuta de forma local y usa sesiones administradas basadas en la nube después de implementar
el agente en el Entorno de ejecución de agentes. En esta sección, se describe cómo configurar tu agente del ADK para que funcione con sesiones administradas.
Opcional: Personaliza tu base de datos de sesiones
Si quieres anular el servicio de sesión administrada predeterminado con tu propia
base de datos, puedes definir una
session_service_builder función
de la siguiente manera:
def session_service_builder():
from google.adk.sessions import InMemorySessionService
return InMemorySessionService()
Pasa 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.
)
Usa el agente con sesiones
Cuando ejecutas el
AdkApp
de forma local, las siguientes instrucciones usan sesiones en memoria.
Para crear una sesión para tu agente, usa el
AdkApp.async_create_session
método:
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.
Para enumerar las sesiones asociadas con tu agente, usa el
AdkApp.async_list_sessions
método:
await app.async_list_sessions(user_id="USER_ID")
Para obtener una sesión en particular, usa el
AdkApp.async_get_session
método::
session = await app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")
donde
USER_ID es el ID de usuario que definiste. Por ejemplo,
user-123.SESSION_ID es el ID de la sesión en particular que quieres recuperar.
Para consultar el agente de forma asíncrona, usa el
AdkApp.async_stream_query
método:
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)
Es posible que el agente responda 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 dentro de la sesión correspondiente a session
si especificas 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: Administra memorias
De forma predeterminada, AdkApp usa una implementación en memoria de la memoria del agente cuando se ejecuta de forma local y usa Agent Platform Memory Bank después de implementar el agente en Agent Runtime.
Cuando desarrolles tu agente del ADK, puedes incluir un PreloadMemoryTool que controle cuándo el agente recupera memorias y cómo se incluyen en el mensaje. El siguiente agente de ejemplo siempre recupera memorias al comienzo de cada turno y las incluye en la instrucción del sistema:
from google.adk.agents import Agent
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from vertexai.agent_engines import AdkApp
agent = 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=[PreloadMemoryTool()],
)
app = AdkApp(agent=agent)
Opcional: Personaliza tu servicio de memoria
Si quieres anular el servicio de memoria predeterminado, puedes definir una
memory_service_builder función que muestre un
BaseMemoryService
de la siguiente manera:
def memory_service_builder():
from google.adk.memory import InMemoryMemoryService
return InMemoryMemoryService()
Pasa 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.
)
Usa el agente con memorias
Prueba tu agente del ADK con memorias:
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 memorias disponibles durante la primera sesión y el agente no conoce las preferencias del usuario, es posible que responda 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)Es posible que el agente responda con una respuesta como "Se estableció la temperatura en 22 grados Celsius. La temperatura se cambió correctamente". La respuesta del agente puede variar según el modelo que usaste.
Genera memorias de la sesión. Para almacenar información de la sesión para usarla en sesiones futuras, usa el
async_add_session_to_memorymétodo:await app.async_add_session_to_memory(session=initial_session)Para probar que el agente retuvo la memoria de la sesión (con
PreloadMemoryTool), crea una sesión nueva y solicita al agente: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)Es posible que el agente muestre una respuesta como "Se estableció la temperatura en 22 grados Celsius. ¿Es correcto?". La respuesta del agente puede variar según el modelo y el proveedor de servicios de memoria que usaste.
Usa el
async_search_memorymétodo para mostrar las memorias del agente:response = await app.async_search_memory( user_id="USER_ID", query="Fix the temperature!", ) print(response)
¿Qué sigue?
Implementa agentes
Obtén información sobre las cinco formas de implementar un agente en el Entorno de ejecución de Agent Platform según tus necesidades de desarrollo.
Descripción general de las sesiones
Aprende a usar sesiones para mantener el estado de la conversación con tus agentes.
Descripción general de Memory Bank
Aprende a usar Memory Bank para almacenar preferencias y datos del usuario a largo plazo.
Usa un agente del Kit de desarrollo de agentes
Usa un agente del Kit de desarrollo de agentes (ADK) con el Entorno de ejecución de Agent Platform.
Evalúa tus agentes
Crea e implementa un agente básico y usa el Gen AI Evaluation Service para evaluar el agente.
Soluciona problemas de creación de agentes
Aprende a resolver errores comunes cuando creas agentes personalizados.