Variablen

Variablen werden verwendet, um Daten über Gesprächsrunden hinweg zu speichern und abzurufen. So können sich Agenten Informationen merken und den Kontext beibehalten. Wenn Sie Prompt-Anweisungen für Ihren Agenten schreiben, können Sie Verweise auf diese Variablen einfügen.

Variablentypen

Der Agent Builder unterstützt zwei verschiedene Arten von Variablen in Anweisungen: statische Variablen und dynamische Variablen.

Die Wahl des richtigen Typs hängt davon ab, ob sich der Wert der Variablen während der Sitzung des Nutzers ändern muss und wie stark Sie die Latenz optimieren müssen.

Statische Variablen

Statische Variablen werden direkt in den Agent-Prompt kompiliert, bevor der Modellaufruf erfolgt. Sie dienen als direkte 1:1-Textersetzung und werden nur selten aktualisiert.

Statische Variablen maximieren die Qualität der Anweisungsbefolgung und eignen sich für bedingte Anweisungen in vielen Szenarien. Verwenden Sie statische Variablen für Konfigurationsdaten, starre Geschäftsregeln oder große kontextbezogene Nutzlasten, die sich während einer einzelnen Unterhaltung nicht ändern.

Wenn Sie in Ihren Anweisungen auf eine statische Variable anhand ihres Namens verweisen möchten, verwenden Sie doppelte geschweifte Klammern: {{variable_name}}.

Wenn Sie beispielsweise einen Einzelhandelsagenten mit einem großen, statischen Produktkatalog erstellen, können Sie eine Anweisung wie diese verwenden:

You are a helpful shopping assistant.
Please follow these business rules: {{business_rules}}.

Dynamische Variablen

Dynamische Variablen können jederzeit während einer Unterhaltung von Tools, Callbacks oder API-Anfragen aktualisiert werden. Sie werden nicht direkt in den Text Ihres Prompts eingefügt. Stattdessen werden ihre neuen Werte als state update-Ereignisse an den Unterhaltungsverlauf angehängt, wenn sie aktualisiert werden. Beispiel: <state_update>var_name: value</state_update>.

Verwenden Sie dynamische Variablen für Informationen, die während der Sitzung vom Nutzer extrahiert wurden, für Ausgaben, die von externen APIs (Tools) abgerufen wurden, oder für jeden Status, der sich im Laufe der Unterhaltung ändert.

Für dynamische Variablen gelten die folgenden Nachteile:

  • Dynamische Variablen werden an den Unterhaltungsverlauf angehängt. Wenn eine lange Sitzung das Limit für das Kontextfenster überschreitet, kann der Agent Variablenwerte vergessen, die beim Kürzen des Verlaufs verloren gehen.
  • Dynamische Variablen können im Vergleich zu statischen Variablen zu einer etwas geringeren Anweisungsbefolgung führen. Das liegt daran, dass die Variablenwerte weiter von den Anweisungen entfernt definiert werden. Dies kann auch die Latenz erhöhen, da das Modell den Wert weiter von der Anweisung entfernt finden muss.

Wenn Sie in Ihren Anweisungen auf eine dynamische Variable anhand ihres Namens verweisen möchten, verwenden Sie einfache geschweifte Klammern: {variable_name}.

Wenn Sie beispielsweise einen Agenten erstellen, der einen Nutzer authentifizieren und dann mit einem Tool seine spezifischen Kontodetails nachschlagen muss, können Sie eine Anweisung wie diese verwenden:

If the user asks for their balance, call the {@TOOL: LookupBalance}.
The tool will update the {current_account_balance} variable.
Always share the {current_account_balance} with the user.

Variablendaten

Variablen haben die folgenden Daten:

  • Name: Variablenname im Snake-Case-Format
  • Typ: zugrunde liegender Datentyp:
    • Text: String-Werte
    • Zahl: numerische Werte
    • Ja/Nein: boolesche Werte
    • Benutzerdefiniertes Objekt: Sie geben ein Schema für das Objekt an.
    • Liste: Liste von Variablen. Geben Sie Werte als durch Kommas getrennte Liste an.
  • Standardwert: Standardwert für die Variable
  • Beschreibung: optionale Beschreibung der Variablen

Variablenwerte aktualisieren

Der Agent selbst kann den Wert einer Variablen nicht aktualisieren, aber Tools und Callbacks können Variablenwerte aktualisieren.

Agent-Variablen verwenden den ADK-Kontextstatus, mit dem Variablen aktualisiert werden können. Eine globale Variable namens context kann in Ihrem Python-Toolcode verwendet werden. Sie können beispielsweise die folgende Anweisung in einem Python-Tool verwenden, um eine Variable mit ADK-Funktionen zu aktualisieren:

context.state["variable_name"] = value

Integrierte Variablen für den Sitzungskontext

Neben benutzerdefinierten Variablen können OpenAPI- und MCP-Tools auf integrierte Variablen für den Sitzungskontext verweisen. Diese sind standardmäßig verfügbar und können in HTTP-Headern oder Anfrageparametern übergeben werden. Auf diese Variablen kann in Anweisungen nicht verwiesen werden und sie können nicht manuell überschrieben werden. Die folgenden integrierten Variablen sind verfügbar:

  • $context.project_id, $context.project_number, $context.location, $context.app_id, $context.session_id, $context.turn_index für Ressourcen-IDs auf App- oder Sitzungsebene.
  • $context.variables.variable_name für einen bestimmten Agentenvariablen-Wert.
  • $context.variables für alle Werte von Agent-Variablen als Objekt.