Agent Development Kit-Agenten entwickeln

Mit der Agent Runtime können Sie KI-Agenten mithilfe der Vorlage des Agent Development Kit (ADK) entwickeln und bereitstellen. Mit der Klasse AdkApp im Agent Platform SDK für Python können Sie KI-Agenten erstellen, die Wechselkurse zurückgeben und zustandsbehaftete 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 Ihrer bereitgestellten KI-Agenten finden Sie unter Bereitgestellte KI-Agenten verwalten.

Hinweis

Folgen Sie der Anleitung unter Umgebung einrichten, um Ihre Umgebung einzurichten.

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. Das folgende Beispiel zeigt, wie Sie die Sicherheitseinstellungen konfigurieren können:

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 Inhaltserstellung 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 eine AdkApp mit den Modellkonfigurationen:

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 mit der AdkApp.async_stream_query Methode eine Abfrage als Zwischenschritt für Tests 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 maximal 128 Zeichen aus. Beispiel: user-123.

Die Antwort ist ein Python-Wörterbuch, das dem folgenden Beispiel ähnelt:

{'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, ihre Funktionsweise und die Rückgabewerte 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()

Führen Sie Folgendes 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 in der AdkApp, verwenden möchten, fügen Sie es der Liste der Tools unter dem tools= Argument 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 Testabfragen mit der AdkApp.async_stream_query Methode ausführen. Führen Sie den folgenden Befehl aus, um den 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 dem folgenden Beispiel ähnelt:

{'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 verwendet 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

Hinweis: Wenn Sie einen benutzerdefinierten In-Memory-Sitzungsdienst verwenden, werden Sitzungen möglicherweise nicht synchronisiert, wenn Sie den Agenten in der Agent Runtime bereitstellen. Wir empfehlen, Ihre Datenbank nur anzupassen, wenn Sie den Status über Sitzungen hinweg in einer bereitgestellten Umgebung synchronisieren können.

Wenn Sie den Standarddienst für verwaltete Sitzungen durch Ihre eigene Datenbank ersetzen möchten, können Sie eine definierensession_service_builder Funktion wie folgt:

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 die AdkApp lokal ausführen, verwenden die folgenden Anweisungen In-Memory-Sitzungen.

Verwenden Sie die AdkApp.async_create_session Methode, 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 Wörterbuchdarstellung eines ADK-Sitzungsobjekts erstellt.

Verwenden Sie die AdkApp.async_list_sessions Methode, um Sitzungen aufzulisten, die mit Ihrem Agenten verknüpft sind:

await app.async_list_sessions(user_id="USER_ID")

Verwenden Sie die AdkApp.async_get_session Methode, 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 AdkApp.async_stream_query Methode, 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 Agent antwortet möglicherweise mit einer Informationsanfrage wie der folgenden:

{'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 innerhalb der Sitzung, die session entspricht, eine Antwort senden (z. B. "SEK"), 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 Sequenz 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: Erinnerungen verwalten

Standardmäßig verwendet AdkApp eine In-Memory-Implementierung des Agentenspeichers, wenn es lokal ausgeführt wird, und verwendet die Agent Platform Memory Bank , nachdem Sie den Agenten in der Agent Runtime bereitgestellt haben.

Wenn Sie Ihren ADK-Agenten entwickeln, können Sie ein PreloadMemoryTool einfügen. Dieses legt fest, wann der Agent Erinnerungen abruft und wie diese in den Prompt aufgenommen werden. Der folgende Beispiel-Agent ruft Erinnerungen immer zu Beginn jedes Turns ab und nimmt sie in die Systemanweisung auf:

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: Speicherdienst anpassen

Hinweis: Wenn Sie einen benutzerdefinierten In-Memory-Speicherdienst verwenden, werden Erinnerungen möglicherweise nicht synchronisiert, wenn Sie den Agenten in der Agent Runtime bereitstellen. Wir empfehlen, den Speicherdienst nur anzupassen, wenn Sie die Erinnerungen über Instanzen hinweg in einer verteilten Umgebung synchronisieren können, wenn der Agent bereitgestellt wird.

Wenn Sie den Standardspeicherdienst überschreiben möchten, können Sie eine memory_service_builderFunktion 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 Erinnerungen verwenden

Testen Sie Ihren ADK-Agenten mit Erinnerungen:

1. Erstellen Sie eine Sitzung und interagieren Sie mit dem 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 Antwort wie „Was ist Ihre bevorzugte Temperatur?“ 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 antwortet möglicherweise mit einer Antwort wie „Die Temperatur wird auf 22 Grad Celsius eingestellt. Temperatur erfolgreich geändert.“ Die Antwort des Agenten kann je nach verwendetem Modell variieren.

2. Erinnerungen aus der Sitzung generieren. Verwenden Sie die Methode async_add_session_to_memory, um Informationen aus der Sitzung für die Verwendung in zukünftigen Sitzungen zu speichern:

   await app.async_add_session_to_memory(session=initial_session)
   

3. Testen Sie, ob sich der Agent an die Sitzung erinnert (mit PreloadMemoryTool), indem Sie eine neue Sitzung erstellen und den Agenten auffordern:

   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 auf 22 Grad einstellen. Ist das richtig?“ Die Antwort des Agenten kann je nach verwendetem Modell und Speicherdienstanbieter variieren.

4. Verwenden Sie die async_search_memory Methode um die Erinnerungen des Agenten anzuzeigen:

   response = await app.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   print(response)
   

Nächste Schritte

Anleitung

KI-Agenten bereitstellen

Hier erfahren Sie mehr über die fünf Möglichkeiten, einen Agenten in der Agent Platform Runtime bereitzustellen, je nach Ihren Entwicklungsanforderungen.

Übersicht

Übersicht zu Sitzungen

Hier erfahren Sie, wie Sie Sitzungen verwenden, um den Unterhaltungsstatus mit Ihren Agenten beizubehalten.

Übersicht

Übersicht zu Memory Bank

Hier erfahren Sie, wie Sie Memory Bank verwenden, um langfristige Nutzerpräferenzen und Fakten zu speichern.

Anleitung

Agent des Agent Development Kit verwenden

Verwenden Sie einen Agenten des Agent Development Kit (ADK) mit der Agent Platform Runtime.

Anleitung

KI-Agenten bewerten

Erstellen und stellen Sie einen einfachen Agenten bereit und verwenden Sie den Gen AI Evaluation Service, um den Agenten zu bewerten.

Fehlerbehebung

Fehlerbehebung bei der Erstellung von Agenten

Hier erfahren Sie, wie Sie häufige Fehler bei der Erstellung benutzerdefinierter Agenten beheben.

Ressource

Support anfordern

Hier finden Sie Ressourcen und Support für die Google Agent Platform.