AdkApp in Agent Platform SDK per Python, puoi creare agenti che restituiscono tassi di cambio e gestiscono interazioni con stato.
Questo documento spiega come sviluppare un agente ADK, inclusa la definizione del modello, l'aggiunta di strumenti e la gestione di sessioni e memorie.
Per ulteriori informazioni sulla gestione degli agenti di cui hai eseguito il deployment, vedi Gestire gli agenti di cui hai eseguito il deployment.
Prima di iniziare
Assicurati che l'ambiente sia configurato seguendo i passaggi descritti in Configurare l'ambiente.
Definire e configurare un modello
Specifica il modello che vuoi utilizzare:
model = "gemini-2.0-flash"
(Facoltativo) Configura le impostazioni di sicurezza del modello. Per scoprire di più sulle opzioni disponibili per le impostazioni di sicurezza in Gemini, vedi Configurare gli attributi di sicurezza. Di seguito è riportato un esempio di come puoi configurare le impostazioni di sicurezza:
from google.genai import types
safety_settings = [
types.SafetySetting(
category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
threshold=types.HarmBlockThreshold.OFF,
),
]
(Facoltativo) Specifica i parametri di generazione dei contenuti:
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
utilizzando le configurazioni del modello:
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)
Se esegui l'applicazione in un ambiente interattivo, ad esempio il terminale o un
notebook di Colab, puoi eseguire una query utilizzando il
AdkApp.async_stream_query
metodo come passaggio di test 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: scegli il tuo ID utente con un limite di 128 caratteri.
Ad esempio,
user-123.
La risposta è un dizionario Python simile al seguente esempio:
{'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}
(Facoltativo) Definire e utilizzare uno strumento
Dopo aver definito il modello, definisci gli strumenti che utilizza per il ragionamento.
Quando definisci la funzione, è importante includere commenti che descrivano in modo completo e chiaro i parametri della funzione, cosa fa la funzione e cosa restituisce. Queste informazioni vengono utilizzate dal modello per determinare quale funzione utilizzare. Devi anche testare la funzione localmente per verificare che funzioni.
Utilizza il seguente codice per definire una funzione che restituisce un tasso di 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()
Per testare la funzione prima di utilizzarla nell'agente, esegui quanto segue:
get_exchange_rate(currency_from="USD", currency_to="SEK")
La risposta dovrebbe essere simile alla seguente:
{'amount': 1.0, 'base': 'USD', 'date': '2025-04-03', 'rates': {'SEK': 9.6607}}
Per utilizzare lo strumento all'interno di
AdkApp,
aggiungilo all'elenco degli strumenti sotto l'argomento tools=:
from google.adk.agents import Agent
agent = Agent(
model=model, # Required.
name='currency_exchange_agent', # Required.
tools=[get_exchange_rate], # Optional.
)
Puoi testare l'agente localmente eseguendo query di test utilizzando il
AdkApp.async_stream_query
metodo. Esegui il comando seguente per testare l'agente localmente utilizzando dollari statunitensi e corone svedesi:
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)
dove USER_ID è l'ID utente che hai definito. Ad esempio, user-123.
La risposta è una sequenza di dizionari simile alla seguente:
{'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',
# ...
}
(Facoltativo) Gestire le sessioni
AdkApp
utilizza sessioni in memoria quando viene eseguito localmente e utilizza sessioni gestite basate sul cloud
dopo aver eseguito il deployment
dell'agente in Agent Runtime. In questa sezione viene descritto come configurare l'agente ADK per utilizzare le sessioni gestite.
(Facoltativo) Personalizzare il database delle sessioni
Se vuoi sostituire il servizio di sessioni gestite predefinito con il tuo
database, puoi definire una
session_service_builder funzione
come segue:
def session_service_builder():
from google.adk.sessions import InMemorySessionService
return InMemorySessionService()
Trasmetti il database a AdkApp come session_service_builder=:
from vertexai.agent_engines import AdkApp
app = AdkApp(
agent=agent, # Required.
session_service_builder=session_service_builder, # Optional.
)
Utilizzare l'agente con le sessioni
Quando esegui il
AdkApp
localmente, le seguenti istruzioni utilizzano sessioni in memoria.
Per creare una sessione per l'agente, utilizza il
AdkApp.async_create_session
metodo:
session = await app.async_create_session(user_id="USER_ID")
print(session)
La sessione viene creata come rappresentazione del dizionario di un oggetto sessione ADK.
Per elencare le sessioni associate all'agente, utilizza il
AdkApp.async_list_sessions
metodo:
await app.async_list_sessions(user_id="USER_ID")
Per ottenere una sessione specifica, utilizza il
AdkApp.async_get_session
metodo:
session = await app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")
dove
USER_ID è l'ID utente che hai definito. Ad esempio,
user-123.SESSION_ID è l'ID della sessione specifica che vuoi recuperare.
Per eseguire una query asincrona dell'agente, utilizza il
AdkApp.async_stream_query
metodo:
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)
L'agente potrebbe rispondere con una richiesta di informazioni come la seguente:
{'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',
#...
}
Puoi inviare una risposta (ad esempio, "SEK") per conto di
USER_ID all'interno della sessione corrispondente a session
specificando:
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)
Dovresti ricevere una continuazione della conversazione come la seguente sequenza di dizionari:
{'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',
# ...
}
(Facoltativo) Gestire le memorie
Per impostazione predefinita, AdkApp
utilizza un'implementazione in memoria della memoria agentica quando viene eseguito localmente e utilizza
Agent Platform Memory Bank
dopo aver eseguito il deployment dell'agente in Agent Runtime.
Quando sviluppi l'agente ADK, puoi includere un PreloadMemoryTool che controlla quando l'agente recupera le memorie e come vengono incluse nel prompt. Il seguente agente di esempio recupera sempre le memorie all'inizio di ogni turno e le include nell'istruzione di 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)
(Facoltativo) Personalizzare il servizio di memoria
Se vuoi sostituire il servizio di memoria predefinito, puoi definire una
memory_service_builder funzione che restituisce un
BaseMemoryService
come segue:
def memory_service_builder():
from google.adk.memory import InMemoryMemoryService
return InMemoryMemoryService()
Trasmetti il database a AdkApp come memory_service_builder=:
from vertexai.agent_engines import AdkApp
app = AdkApp(
agent=agent, # Required.
memory_service_builder=memory_service_builder, # Optional.
)
Utilizzare l'agente con le memorie
Testa l'agente ADK con le memorie:
Crea una sessione e interagisci con l'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)Poiché non sono disponibili memorie durante la prima sessione e l'agente non conosce le preferenze dell'utente, potrebbe rispondere con una risposta del tipo "Qual è la temperatura che preferisci?" Puoi rispondere con il seguente 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)L'agente potrebbe rispondere con una risposta del tipo "Impostazione della temperatura a 22 gradi. Temperatura modificata correttamente." La risposta dell'agente può variare a seconda del modello utilizzato.
Genera memorie dalla sessione. Per archiviare le informazioni della sessione da utilizzare nelle sessioni future, utilizza il
async_add_session_to_memorymetodo:await app.async_add_session_to_memory(session=initial_session)Verifica che l'agente abbia conservato la memoria della sessione (utilizzando
PreloadMemoryTool) creando una nuova sessione e chiedendo all'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)L'agente potrebbe restituire una risposta del tipo "Impostazione della temperatura a 22 gradi. È corretto?" La risposta dell'agente può variare a seconda del modello e del fornitore di servizi di memoria utilizzati.
Utilizza il
async_search_memorymetodo per visualizzare le memorie dell'agente:response = await app.async_search_memory( user_id="USER_ID", query="Fix the temperature!", ) print(response)
Passaggi successivi
Eseguire il deployment degli agenti
Scopri i cinque modi per eseguire il deployment di un agente in Agent Platform Runtime in base alle tue esigenze di sviluppo.
Panoramica delle sessioni
Scopri come utilizzare le sessioni per mantenere lo stato della conversazione con gli agenti.
Panoramica di Memory Bank
Scopri come utilizzare Memory Bank per archiviare fatti e preferenze degli utenti a lungo termine.
Utilizzare un agente Agent Development Kit
Utilizza un agente Agent Development Kit (ADK) con Agent Platform Runtime.
Valutare gli agenti
Crea ed esegui il deployment di un agente di base e utilizza Gen AI evaluation service per valutare l'agente
Risolvere i problemi relativi alla creazione di agenti
Scopri come risolvere gli errori comuni durante la creazione di agenti personalizzati.