AdkApp im Agent Platform SDK für Python können Sie Agenten erstellen, die Wechselkurse zurückgeben und zustandsorientierte 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 gemerkten Informationen.
Weitere Informationen zum Verwalten Ihrer bereitgestellten Agenten finden Sie unter Bereitgestellte Agenten 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. Hier 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 mithilfe der 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 in einer interaktiven Umgebung wie dem Terminal oder einem Colab-Notebook arbeiten, 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 eine eigene Nutzer-ID mit einer Zeichenbeschränkung 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 Funktionsweise und die Rückgabewerte der Funktion vollständig und klar beschreiben. Diese Informationen werden vom Modell verwendet, um zu bestimmen, welche Funktion verwendet werden soll. Außerdem müssen Sie Ihre Funktion lokal testen, um zu prüfen, ob 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()
Führen Sie den folgenden Befehl aus, um die Funktion zu testen, 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 im 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 Sequenz von Wörterbüchern, 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 er lokal ausgeführt wird, und cloudbasierte verwaltete Sitzungen, nachdem Sie den Agenten in der Agent Runtime bereitgestellt haben. In diesem Abschnitt wird beschrieben, wie Sie Ihren ADK-Agenten für die Verwendung mit verwalteten Sitzungen konfigurieren.
Optional: Sitzungsdatenbank anpassen
Wenn Sie den standardmäßigen verwalteten Sitzungsdienst durch Ihre eigene Datenbank überschreiben möchten, können Sie eine session_service_builder-Funktion so definieren:
def session_service_builder():
from google.adk.sessions import InMemorySessionService
return InMemorySessionService()
Übergeben Sie Ihre Datenbank als session_service_builder= an AdkApp:
from vertexai.agent_engines import AdkApp
app = AdkApp(
agent=agent, # Required.
session_service_builder=session_service_builder, # Optional.
)
KI-Agenten mit Sitzungen verwenden
Wenn Sie AdkApp lokal ausführen, werden in der folgenden Anleitung speicherinterne Sitzungen verwendet.
Verwenden Sie die Methode AdkApp.async_create_session, um eine Sitzung für Ihren Agenten 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")
Verwenden Sie die Methode AdkApp.async_get_session, um eine bestimmte Sitzung abzurufen:
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 KI-Agent könnte 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 eine Antwort (z. B. "SEK") im Namen von USER_ID innerhalb der Sitzung, die session entspricht, senden, 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 der Unterhaltung wie die folgende Abfolge von Wörterbüchern 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: Gemerkte Informationen verwalten
Standardmäßig verwendet AdkApp eine speicherinterne Implementierung des agentischen Speichers, wenn er lokal ausgeführt wird. Nach der Bereitstellung des KI-Agenten in der Agent Runtime wird die Agent Platform Memory Bank verwendet.
Wenn Sie Ihren ADK-Agenten entwickeln, können Sie ein PreloadMemoryTool einfügen. Dieses legt fest, wann der Agent gemerkte Informationen abruft und wie diese in den Prompt aufgenommen werden. Der folgende Beispiel-KI-Agent ruft zu Beginn jedes Turns immer gemerkte Informationen 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: Memory-Dienst anpassen
Wenn Sie den Standard-Memory-Dienst überschreiben möchten, können Sie eine memory_service_builder-Funktion definieren, die einen BaseMemoryService zurückgibt, wie hier gezeigt:
def memory_service_builder():
from google.adk.memory import InMemoryMemoryService
return InMemoryMemoryService()
Übergeben Sie Ihre Datenbank als memory_service_builder= an AdkApp:
from vertexai.agent_engines import AdkApp
app = AdkApp(
agent=agent, # Required.
memory_service_builder=memory_service_builder, # Optional.
)
KI-Agenten mit gemerkten Informationen verwenden
Testen Sie Ihren ADK-Agenten mit gemerkten Informationen:
Erstellen Sie eine Sitzung und interagieren Sie 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 gemerkten Informationen verfügbar sind und der Agent keine Nutzerpräferenzen kennt, antwortet er möglicherweise mit einer Frage wie „Welche Temperatur bevorzugen Sie?“. 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 „Temperatur wird auf 21 Grad Celsius eingestellt“ zurück. Die Temperatur wurde geändert.“ Die Antwort des KI-Agenten 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 sich der Agent die Sitzung gemerkt hat (mit
PreloadMemoryTool). Erstellen Sie dazu eine neue Sitzung und geben Sie dem Agenten folgenden Prompt: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 „Temperatur wird auf 21 Grad eingestellt“ zurück. Ist das richtig?“ Die Antwort des KI-Agenten kann je nach verwendetem Modell und Memory-Dienstanbieter variieren.
Verwenden Sie die Methode
async_search_memory, um die gemerkten Informationen des KI-Agenten anzuzeigen:response = await app.async_search_memory( user_id="USER_ID", query="Fix the temperature!", ) print(response)
Nächste Schritte
Agenten bereitstellen
Hier erfahren Sie, wie Sie einen Agenten auf der Agent Platform Runtime auf fünf verschiedene Arten bereitstellen können, je nach Ihren Entwicklungsanforderungen.
Sitzungsübersicht
Hier erfahren Sie, wie Sie Sitzungen verwenden, um den Unterhaltungsstatus mit Ihren Agenten beizubehalten.
Memory Bank – Übersicht
Informationen zum Speichern langfristiger Nutzereinstellungen und Fakten mit der Memory Bank
Agenten des Agent Development Kit verwenden
Agenten des Agent Development Kit (ADK) mit der Agent Platform Runtime verwenden
KI-Agenten bewerten
Einfachen Agenten erstellen und bereitstellen und mit dem Gen AI Evaluation Service bewerten
Fehlerbehebung bei der Agentenerstellung
Hier erfahren Sie, wie Sie häufige Fehler beim Erstellen benutzerdefinierter KI-Agenten beheben können.