Agenten mit dem Agent Development Kit entwickeln

Auf dieser Seite erfahren Sie, wie Sie einen Agent mit der Vorlage für das Agent Development Kit (der Klasse AdkApp im Vertex AI SDK for Python) entwickeln. Der Agent gibt den Wechselkurs zwischen zwei Währungen an einem bestimmten Datum zurück.

Gehen Sie dazu so vor:

  1. Modell definieren und konfigurieren
  2. (Optional) Tool definieren und verwenden
  3. Optional: Sitzungen verwalten
  4. Optional: Erinnerungen verwalten

Hinweise

Richten Sie Ihre Umgebung ein, indem Sie die Schritte unter Umgebung einrichten ausführen.

Modell definieren und konfigurieren

Definieren Sie die Modellversion:

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 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 eine interaktive Umgebung wie das Terminal oder ein Colab-Notebook verwenden, können Sie eine Abfrage 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 einem Zeichenlimit von 128 Zeichen aus. Beispiel: user-123.

Die Antwort ist ein Python-Dictionary, 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, 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 Agent 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 Agent lokal testen, indem Sie Testabfragen an ihn durchfü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 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 sie lokal ausgeführt wird, und cloudbasierte verwaltete Sitzungen, nachdem Sie den Agent in Vertex AI Agent Engine 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 mit Ihrer eigenen 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 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 den folgenden Anleitungen In-Memory-Sitzungen verwendet:

So erstellen Sie eine Sitzung für Ihren Agent:

session = await app.async_create_session(user_id="USER_ID")
print(session)

Die Sitzung wird als Wörterbuchdarstellung eines ADK-Sitzungsobjekts erstellt.

Sitzungen auflisten, die mit Ihrem Agent verknüpft sind:

await app.async_list_sessions(user_id="USER_ID")

So rufen Sie eine bestimmte Sitzung ab:

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.

So fragen Sie AdkApp mit Sitzungen ab:

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 antwortet möglicherweise mit einer Bitte um Informationen wie die 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 eine Antwort (z. B. "SEK") im Namen von USER_ID 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 sie lokal ausgeführt wird, und die Speicherbank der Vertex AI Agent Engine, nachdem Sie den Agent in der Vertex AI Agent Engine bereitgestellt haben.

Beim Entwickeln Ihres ADK-Agents können Sie ein PreloadMemoryTool einfügen, das steuert, wann der Agent Erinnerungen abruft und wie Erinnerungen in den Prompt aufgenommen werden. Der folgende Beispiel-Agent ruft zu Beginn jeder Runde immer Erinnerungen ab und fügt sie in die Systemanweisung ein:

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)

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 Erinnerungen verwenden

ADK-Agent mit Erinnerungen testen:

  1. Sitzung erstellen und mit dem Agent interagieren:

    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 „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 antwortet möglicherweise mit „Stelle die Temperatur auf 22 Grad Celsius ein. Die Temperatur wurde geändert.“ Die Antwort des Agenten kann je nach verwendetem Modell variieren.

  2. Erinnerungen 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)

  3. Testen Sie, ob der Agent sich 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 „Stelle die Temperatur auf 22 Grad ein. Ist das richtig?“ Die Antwort des Agenten kann je nach verwendetem Modell und Memory-Dienstanbieter variieren.

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

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

Nächste Schritte