AdkApp im Agent Platform SDK für Python können Sie Agents erstellen, die Wechselkurse zurückgeben und statusbehaftete Interaktionen verwalten.
In diesem Dokument wird beschrieben, wie Sie einen ADK-Agenten entwickeln, einschließlich der Definition des Modells, des Hinzufügens von Tools und der Verwaltung von Sitzungen und Erinnerungen.
Weitere Informationen zum Verwalten bereitgestellter Agents finden Sie unter Bereitgestellte Agents verwalten.
Hinweis
Richten Sie Ihre Umgebung ein, indem Sie die Schritte unter Umgebung einrichten ausführen.
Modell definieren und konfigurieren
Geben Sie das gewünschte Modell an:
model = "gemini-2.0-flash"
Optional: Konfigurieren Sie die Sicherheitseinstellungen des Modells. Weitere Informationen zu den verfügbaren Optionen für Sicherheitseinstellungen in Gemini finden Sie unter Sicherheitsattribute konfigurieren. Im Folgenden finden Sie ein Beispiel für die Konfiguration der Sicherheitseinstellungen:
from google.genai import types
safety_settings = [
types.SafetySetting(
category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
threshold=types.HarmBlockThreshold.OFF,
),
]
Optional: Geben Sie Parameter für die Inhaltsgenerierung an:
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,
)
Erstellen Sie mit den Modellkonfigurationen einen AdkApp:
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)
Wenn Sie die Ausführung in einer interaktiven Umgebung wie dem Terminal oder einem Colab-Notebook vornehmen, können Sie eine Abfrage mit der Methode AdkApp.async_stream_query als Zwischenschritt zum Testen ausführen:
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: Wählen Sie Ihre eigene Nutzer-ID mit einem Zeichenlimit von 128 Zeichen aus.
Beispiel:
user-123.
Die Antwort ist ein Python-Wörterbuch, das in etwa so aussieht:
{'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}
Optional: Tool definieren und verwenden
Nachdem Sie Ihr Modell definiert haben, definieren Sie die Tools, die Ihr Modell für Logik verwendet.
Wenn Sie Ihre Funktion definieren, ist es wichtig, Kommentare einzufügen, die die Parameter der Funktion, die Funktion selbst und die Rückgabe der Funktion vollständig und klar beschreiben. Anhand dieser Informationen bestimmt das Modell, welche Funktion verwendet werden soll. Sie müssen Ihre Funktion auch lokal testen, um zu bestätigen, dass sie funktioniert.
Verwenden Sie den folgenden Code, um eine Funktion zu definieren, die einen Wechselkurs zurückgibt:
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()
So testen Sie die Funktion, bevor Sie sie in Ihrem Agenten verwenden:
get_exchange_rate(currency_from="USD", currency_to="SEK")
Die Antwort sollte in etwa so aussehen:
{'amount': 1.0, 'base': 'USD', 'date': '2025-04-03', 'rates': {'SEK': 9.6607}}
Wenn Sie das Tool in AdkApp verwenden möchten, fügen Sie es der Liste der Tools unter dem Argument tools= hinzu:
from google.adk.agents import Agent
agent = Agent(
model=model, # Required.
name='currency_exchange_agent', # Required.
tools=[get_exchange_rate], # Optional.
)
Sie können den Agenten lokal testen, indem Sie mit der Methode AdkApp.async_stream_query Testabfragen an ihn senden. Führen Sie den folgenden Befehl aus, um den KI-Agenten lokal mit US-Dollar und schwedischen Kronen zu testen:
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)
Dabei ist USER_ID die von Ihnen definierte Nutzer-ID. Beispiel: user-123
Die Antwort ist eine Folge von Dictionaries, die in etwa so aussieht:
{'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',
# ...
}
Optional: Sitzungen verwalten
AdkApp verwendet In-Memory-Sitzungen, wenn es lokal ausgeführt wird, und cloudbasierte verwaltete Sitzungen, nachdem Sie den Agent in der Agent Runtime bereitgestellt haben. In diesem Abschnitt wird beschrieben, wie Sie Ihren ADK-Agent für die Verwendung mit verwalteten Sitzungen konfigurieren.
Optional: Sitzungsdatenbank anpassen
Wenn Sie den verwalteten Standardsitzungsdienst durch Ihre eigene Datenbank überschreiben möchten, können Sie eine session_service_builder-Funktion wie folgt definieren:
def session_service_builder():
from google.adk.sessions import InMemorySessionService
return InMemorySessionService()
Übergeben Sie Ihre Datenbank an AdkApp als session_service_builder=:
from vertexai.agent_engines import AdkApp
app = AdkApp(
agent=agent, # Required.
session_service_builder=session_service_builder, # Optional.
)
Agent mit Sitzungen verwenden
Wenn Sie AdkApp lokal ausführen, werden in der folgenden Anleitung In-Memory-Sitzungen verwendet.
Verwenden Sie die Methode AdkApp.async_create_session, um eine Sitzung für Ihren Agent zu erstellen:
session = await app.async_create_session(user_id="USER_ID")
print(session)
Die Sitzung wird als Dictionary-Darstellung eines ADK-Sitzungsobjekts erstellt.
Verwenden Sie die Methode AdkApp.async_list_sessions, um Sitzungen aufzulisten, die mit Ihrem Agent verknüpft sind:
await app.async_list_sessions(user_id="USER_ID")
Wenn Sie eine bestimmte Sitzung abrufen möchten, verwenden Sie die Methode AdkApp.async_get_session:
session = await app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")
Dabei gilt:
USER_ID ist die von Ihnen definierte Nutzer-ID. Beispiel:
user-123.SESSION_ID ist die ID der Sitzung, die Sie abrufen möchten.
Verwenden Sie die Methode AdkApp.async_stream_query, um den Agenten asynchron abzufragen:
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)
Der Kundenservicemitarbeiter kann mit einer Anfrage nach Informationen wie den folgenden antworten:
{'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',
#...
}
Sie können im Namen von USER_ID eine Antwort (z. B. "SEK") in der Sitzung senden, die session entspricht, indem Sie Folgendes angeben:
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)
Sie sollten eine Fortsetzung des Gesprächs wie die folgende Sequenz von Dictionaries erhalten:
{'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',
# ...
}
Optional: Erinnerungen verwalten
Standardmäßig verwendet AdkApp eine In-Memory-Implementierung des Agentenspeichers, wenn es lokal ausgeführt wird, und Agent Platform Memory Bank, nachdem Sie den Agent in der Agent Runtime bereitgestellt haben.
Wenn Sie Ihren ADK-Agenten entwickeln, können Sie ein PreloadMemoryTool einfügen, das festlegt, wann der Agent Erinnerungen abruft und wie diese in den Prompt aufgenommen werden. Der folgende Beispiel-KI-Agent ruft Erinnerungen immer zu Beginn jedes Turns ab und fügt sie in die Systemanweisung ein:
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)
Optional: Erinnerungsdienst anpassen
Wenn Sie den Standardspeicherdienst überschreiben möchten, können Sie eine memory_service_builder-Funktion definieren, die ein BaseMemoryService zurückgibt:
def memory_service_builder():
from google.adk.memory import InMemoryMemoryService
return InMemoryMemoryService()
Übergeben Sie Ihre Datenbank an AdkApp als memory_service_builder=:
from vertexai.agent_engines import AdkApp
app = AdkApp(
agent=agent, # Required.
memory_service_builder=memory_service_builder, # Optional.
)
Agent mit gemerkten Informationen verwenden
So testen Sie Ihren ADK-Agenten mit Erinnerungen:
So erstellen Sie eine Sitzung und interagieren mit dem KI-Agenten:
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)Da in der ersten Sitzung keine Erinnerungen verfügbar sind und der Agent keine Nutzerpräferenzen kennt, antwortet er möglicherweise mit einer Frage wie „Welche Temperatur bevorzugst du?“. Sie können mit dem folgenden Befehl antworten:
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)Der Agent gibt möglicherweise eine Antwort wie „Stelle die Temperatur auf 22 Grad Celsius ein. Die Temperatur wurde geändert.“ Die Antwort des Agents kann je nach verwendetem Modell variieren.
Gemerkte Informationen aus der Sitzung generieren Wenn Sie Informationen aus der Sitzung für die Verwendung in zukünftigen Sitzungen speichern möchten, verwenden Sie die Methode
async_add_session_to_memory:await app.async_add_session_to_memory(session=initial_session)Testen Sie, ob der Agent sich an die Sitzung erinnert (mit
PreloadMemoryTool). Erstellen Sie dazu eine neue Sitzung und geben Sie folgenden Prompt ein: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)Der Agent gibt möglicherweise eine Antwort wie „Stelle die Temperatur auf 22 Grad ein. Ist das richtig?“ Die Antwort des Agents kann je nach verwendetem Modell und Memory-Dienstanbieter variieren.
Verwenden Sie die Methode
async_search_memory, um die Erinnerungen des Agents aufzurufen:response = await app.async_search_memory( user_id="USER_ID", query="Fix the temperature!", ) print(response)
Nächste Schritte
KI-Agenten bereitstellen
Hier erfahren Sie, wie Sie einen Agenten in der Agent Platform Runtime bereitstellen können.
Sitzungsübersicht
Hier erfahren Sie, wie Sie Sitzungen verwenden, um den Unterhaltungsstatus Ihrer Agents beizubehalten.
Übersicht zu Memory Bank
Informationen zur Verwendung von Memory Bank zum Speichern langfristiger Nutzerpräferenzen und Fakten.
Agent Development Kit-Agenten verwenden
Einen ADK-Agenten (Agent Development Kit) mit der Agent Platform-Laufzeit verwenden
KI-Agenten bewerten
Einen einfachen Agenten erstellen und bereitstellen und den Gen AI Evaluation Service verwenden, um den Agenten zu bewerten
Fehlerbehebung bei der Agentenerstellung
Hier erfahren Sie, wie Sie häufige Fehler beim Erstellen benutzerdefinierter Agents beheben können.