Variablen

Variablen werden verwendet, um Daten über mehrere Unterhaltungsrunden hinweg zu speichern und abzurufen. Sie ermöglichen es KI-Agenten, sich Informationen zu merken und den Kontext beizubehalten. 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 vor dem Modellaufruf direkt in den Agenten-Prompt kompiliert. Sie dienen als direkte 1:1-Textersetzung und werden selten aktualisiert.

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

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

Wenn Sie beispielsweise einen Einzelhandels-Agenten mit einem großen, statischen Produktkatalog erstellen, könnten Sie eine Anweisung wie die folgende verwenden:

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

Warnung: Wenn Sie statische Variablenwerte aktualisieren, wird das Prompt-Caching ungültig, was zu einer höheren Latenz bei Modellaufrufen führen kann.

Dynamische Variablen

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

Verwenden Sie dynamische Variablen für Informationen, die während der Sitzung vom Nutzer extrahiert werden, für Ausgaben, die von externen APIs (Tools) abgerufen werden, oder für alle Zustände, die sich im Laufe der Unterhaltung ändern.

Dynamische Variablen haben die folgenden Nachteile:

• Dynamische Variablen werden an den Unterhaltungsverlauf angehängt. Wenn eine lange Sitzung das Limit des Kontextfensters überschreitet, kann es passieren, dass der Agent Variablenwerte vergisst, die beim Kürzen des Verlaufs verloren gehen.
• Dynamische Variablen können im Vergleich zu statischen Variablen zu einer etwas geringeren Einhaltung von Anweisungen 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 entfernt von der Anweisung finden muss.

Wenn Sie in Ihren Anweisungen namentlich auf eine dynamische Variable 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 abrufen muss, können Sie eine Anweisung wie die folgende 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 enthalten die folgenden Daten:

• Name: Variablenname in Snake Case
• Typ: Zugrunde liegender Datentyp:
  • Text: Stringwerte
  • Zahl: Numerische Werte
  • Ja/Nein: Boolesche Werte
  • Benutzerdefiniertes Objekt: Sie geben ein Schema für das Objekt an.
  • Liste: Liste von Variablen. Die Werte geben Sie als durch Kommas getrennte Liste an.
• Standardwert: Standardwert für die Variable
• Beschreibung: Optionale Beschreibung der Variable

Variablenwerte aktualisieren

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

KI-Agentenvariablen verwenden den ADK-Kontextstatus, mit dem Variablen aktualisiert werden können. In Ihrem Python-Toolcode ist eine globale Variable namens context verfügbar. Sie können beispielsweise die folgende Anweisung in einem Python-Tool verwenden, um eine Variable mithilfe von ADK-Funktionen zu aktualisieren:

context.state["variable_name"] = value

Warnung: Anweisungsvorlagen werden zwischen dem before_agent-Callback und dem before_model-Callback gerendert. Variablenaktualisierungen, die in einem before_agent-Callback vorgenommen werden, werden sofort in der aktuellen Runde wirksam. Variablenaktualisierungen, die in einem before_model-Callback vorgenommen werden, sind dagegen erst in der nächsten Gesprächsrunde in den gerenderten Anweisungen sichtbar. Referenzvariablen, die von before_model-Callbacks aktualisiert werden, als statische {{variable_name}}-Variablen und nicht als dynamische {variable_name}-Variablen, da before_model-Callbacks keine <state_update>-Ereignisse an den Unterhaltungsverlauf anhängen.

Integrierte Sitzungskontextvariablen

Neben benutzerdefinierten Variablen können OpenAPI- und MCP-Tools auch auf integrierte Sitzungskontextvariablen verweisen. Diese sind standardmäßig verfügbar und können in HTTP-Headern oder Anfrageparametern übergeben werden. Diese Variablen können nicht in Anweisungen referenziert und nicht manuell überschrieben werden. Folgende integrierte 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 Wert der Agent-Variablen.
• $context.variables für alle Agent-Variablenwerte als Objekt.