Questa pagina mostra come sviluppare un agente utilizzando il modello Agent Development Kit (la classe AdkApp nell'SDK Vertex AI Python). L'agente restituisce il tasso di cambio tra due valute in una data specificata.
Segui questi passaggi:
- Definisci e configura un modello
- (Facoltativo) Definisci e utilizza uno strumento
- (Facoltativo) Gestisci le sessioni
- (Facoltativo) Gestisci i ricordi
Prima di iniziare
Assicurati che l'ambiente sia configurato seguendo i passaggi descritti in Configurare l'ambiente.
Definisci e configura un modello
Definisci la versione del modello:
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 della 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'operazione in un ambiente interattivo, ad esempio il terminale o un notebook Colab, puoi eseguire una query 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) Definisci e utilizza 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 il comando seguente:
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 nella sezione
dell'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. Esegui il seguente comando 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) Gestisci sessioni
AdkApp utilizza sessioni in memoria durante l'esecuzione in locale e utilizza sessioni gestite basate sul cloud dopo il deployment dell'agente in Vertex AI Agent Engine. Questa sezione descrive come configurare l'agente ADK per l'utilizzo con le sessioni gestite.
(Facoltativo) Personalizza il database delle sessioni
Se vuoi sostituire il servizio di sessione gestito predefinito con il tuo database, puoi definire una funzione session_service_builder nel seguente modo:
def session_service_builder():
from google.adk.sessions import InMemorySessionService
return InMemorySessionService()
Passa 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 AdkApp localmente, le seguenti istruzioni utilizzano sessioni in memoria:
Crea una sessione per l'agente:
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.
Elenca le sessioni associate al tuo agente:
await app.async_list_sessions(user_id="USER_ID")
Recuperare una sessione specifica:
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.
Esegui una query su AdkApp utilizzando le sessioni:
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 i ricordi
Per impostazione predefinita, AdkApp
utilizza un'implementazione in memoria della memoria dell'agente quando viene eseguito localmente e utilizza
Vertex AI Agent Engine Memory Bank
dopo aver eseguito il deployment dell'agente in Vertex AI Agent Engine.
Quando sviluppi l'agente ADK, puoi includere un PreloadMemoryTool che
controlla quando l'agente recupera i ricordi e come vengono inclusi nel
prompt. L'agente di esempio seguente recupera sempre i ricordi all'inizio di ogni turno
e li include nell'istruzione di 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)
(Facoltativo) Personalizzare il servizio di memoria
Se vuoi eseguire l'override del servizio di memoria predefinito, puoi definire una
funzione memory_service_builder che restituisce un BaseMemoryService come segue:
def memory_service_builder():
from google.adk.memory import InMemoryMemoryService
return InMemoryMemoryService()
Passa 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 i ricordi
Testa il tuo agente ADK con i ricordi:
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 ricordi durante la prima sessione e l'agente non conosce le preferenze dell'utente, potrebbe rispondere con una frase come "Qual è la tua temperatura preferita?" 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 un messaggio come "Imposto la temperatura a 22 gradi Celsius. Temperatura modificata correttamente." La risposta dell'agente può variare a seconda del modello utilizzato.
Genera ricordi dalla sessione. Per memorizzare le informazioni della sessione da utilizzare nelle sessioni future, utilizza il metodo
async_add_session_to_memory: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 come "Imposto la temperatura a 22 gradi. È corretto?" La risposta dell'agente può variare a seconda del modello e del fornitore di servizi di memoria che hai utilizzato.
Utilizza il metodo
async_search_memoryper visualizzare i ricordi dell'agente:response = await app.async_search_memory( user_id="USER_ID", query="Fix the temperature!", ) print(response)
Passaggi successivi
- Panoramica delle sessioni
- Panoramica di Memory Bank
- Utilizza un agente Agent Development Kit.
- Valuta un agente.
- Esegui il deployment di un agente.
- Risolvi i problemi relativi allo sviluppo di un agente.
- Richiedere assistenza.