Codeblöcke

Wenn Sie ein Playbook definieren, können Sie optional Codeblöcke angeben. Das ist Inline-Python-Code, mit dem Sie das Verhalten des Agents besser steuern können. Dieser Code besteht aus Funktionen mit speziellen Dekoratoren und allen erforderlichen Hilfsfunktionen.

Beim Schreiben des Codes können Sie die Systembibliothek für Codeblöcke verwenden, um das Verhalten des Agents zu steuern.

Bekannte Probleme

Es gelten die folgenden bekannten Probleme:

• Projekte in VPC-SC-Perimetern, die den Zugriff auf Artifact Registry einschränken, lehnen auch Codeblock-Bereitstellungen ab.

Beschränkungen

Es gelten folgende Einschränkungen:

• Codeblöcke dürfen keine Objekte enthalten, die Daten speichern. Sie können jedoch Tools verwenden, um Daten beizubehalten und den Status zu verwalten.
• Codeblöcke können keine direkten Remote-Aufrufe ausführen. Sie können beispielsweise nicht die Python-Bibliothek „requests“ verwenden. Sie können jedoch Tools verwenden, um indirekt Remote-Anrufe zu starten.
• Ressourcennamen, die in Python-Namen konvertiert werden, müssen gültige Python-Namen sein.
• In Codeblöcken können keine Sitzungsparameter gelesen oder geschrieben werden, es sei denn, es findet ein Flow-Übergang statt.

Inline-Aktionen

Inline-Aktionen verhalten sich ähnlich wie Tool-Aktionen. Sie haben ein definiertes Ein- und Ausgabeschema, das durch die Signatur der Python-Funktion bestimmt wird, einschließlich Typannotationen und Docstring. Ähnlich wie bei Tool-Aufrufen ist dem LLM der Code, mit dem die Aktion implementiert wird, nicht bekannt.

Beispiel:

@Action
def is_prime(n: int): bool
  """Returns true if n is prime."""
  import math
  return (all([False for i in range(2, math.sqrt(n)
               if n % i == 0 ]) and not n < 2)

Für diese Funktion erhält das LLM Informationen zur Aktion, ihrer Eingabe und ihrer Ausgabe.

Wenn Sie in der Anleitung Ihres Playbooks auf eine Inline-Aktion verweisen möchten, geben Sie einfach den Namen der Aktion in Backticks an und beschreiben Sie, wie sie verwendet werden soll.

Beispiel für eine Inline-Aktion vom Typ place_order:

Take the customer's order, then call the `place_order` action when the order is ready.

Wenn Sie Beispiele mit Inline-Aktionen erstellen möchten, verwenden Sie im Bereich Ein- und Ausgabe den Tooltyp inline-action.

Weitere Informationen finden Sie in der @Action-Referenzdokumentation.

Funktionen auslösen

Mit Triggerfunktionen werden bedingte Aktionen im Code definiert.

Triggerfunktionen werden mit Decorators deklariert. Sie können die folgenden Dekoratoren für Triggerfunktionen verwenden:

Diese Funktionen zeigen beispielsweise, wie Sie diese Dekoratoren und Dekoratorparameter verwenden und wie Sie die Systembibliotheksfunktion respond für Codeblöcke verwenden.

# No decorator parameter
@PlaybookStartTrigger
def my_playbook_conditional_action():
  respond("How can I help?")

# With a condition decorator parameter
@BeforeActionTrigger('$next-action.name = "search"')
def my_before_action_conditional_action():
  respond("One moment please")

# Event
@EventTrigger(event="welcome")
def my_welcome_event():
  respond("hi")

# Event with a condition:
@EventTrigger(event="welcome",
              condition="$sys.func.NOW().hours < 10")
def my_good_morning_event():
  respond("Good morning ☕")

Auf Flows, Playbooks und Tools verweisen

In Ihrem Codeblock können Sie mit den globalen Variablen flows, playbooks und tools auf bestimmte Abläufe, Playbooks und Tools verweisen.

Jedes dieser Objekte hat Elemente, die den Namen der entsprechenden Ressourcen entsprechen. Diese Namen müssen gültige Python-Namen sein.

Beispiel:

  add_override(playbooks.troubleshooting, {})
  add_override(flows.billing)
  add_override(tools.weather_api.get_weather, {"location": "San Francisco"})

Wenn Sie in einem Codeblock auf Abläufe und Playbooks verweisen, müssen Sie auch in der Playbook-Anleitung mit der folgenden Syntax darauf verweisen:

${RESOURCE_TYPE: my_resource_name}

Wenn Ihr Codeblock beispielsweise flows.myflow und playbooks.myplaybook enthält, sollten die Playbook-Anweisungen Folgendes umfassen:

${FLOW: myflow}
${PLAYBOOK: myplaybook}

Aktionsüberschreibungen

Mit Codeblöcken können Sie eine Warteschlange mit Aktionen erstellen, die vor allen weiteren vom LLM bestimmten Aktionen ausgeführt werden und diese möglicherweise überschreiben. Sie erstellen Aktionsüberschreibungen mit der globalen Funktion add_override.

Alle in der Warteschlange befindlichen Überschreibungsaktionen werden sequenziell ausgeführt und die Aktionsausgabe ist für das LLM verfügbar. Sobald die Warteschlange leer ist, kehrt der Vorgang zum LLM zurück, um Aktionen und Eingaben auszuwählen, es sei denn, ein Override beendet den Zug mit respond oder einer anderen Funktion, die den Zug abschließt.

Funktionsargumente:

• action: Die auszuführende Aktion. Verwenden Sie für eine Inline-Aktion my_function_name. Verwenden Sie für eine Tool-Aktion tools.my_tool_name.my_tool_action. Verwenden Sie für eine Flow-Aktion flows.my_flow_name.
• inputs: Optionale Eingaben für die Aktion. Beispiel: {"location": "Omaha"}.

Beispiele:

# Assuming remote tool named "dmv" with operationId "search_offices"
# remote tool with only requestBody
add_override(tools.dmv.search_offices,{"address": "95030"})

# remote tool with only parameters
add_override(tools.pets.get_pet, {"id": "123"})

# remote tool with requestBody + parameters:
add_override(tools.pets.create_pet, {"requestBody": {"arg1":"foo"}, "param1": "bar"})

# datastore. Assumes existing datastore tool named "Menu".
add_override(tools.menu.Menu, {"query": "what is the menu"})

# code block action. Assumes another code block @Action my_action.
add_override(my_action)

Antwortüberschreibungen

Ähnlich wie bei der Überschreibung von Aktionen, aber speziell für Agent-Antworten, können Sie die globale Funktion respond verwenden, um den Agenten zu zwingen, dem Nutzer mit bestimmten Inhalten zu antworten.

Beispiel:

respond("Hello")

Anruftools

In Ihren Codeblockfunktionen können Sie die Tools aufrufen, die für Ihren Agent definiert sind. Anders als beim Überschreiben einer Tool-Aktion sind die Ergebnisse der Tool-Ausführung nicht für das LLM verfügbar, wenn Sie ein Tool direkt aufrufen.

Beispiele:

# Assumes existing tool named "DMV" with operationId "search_offices"
# remote tool with only request body.
offices = tools.dmv.search_offices({"address": "95030"})

# remote tool with parameters and request body
offices = tools.dmv.search_offices({"requestBody": {"address":"95030"}, "param1":"foo"})

# datastore actions. Assumes existing datastore tool named "Menu".
data = tools.menu.Menu({"query": "get the menu"})["snippets"]

Absicht der Übereinstimmung

Codeblöcke können programmatisch eine Intention für einen bestimmten Ablauf mithilfe der Funktion Flow.match_intent abgleichen.

Beispiel:

matches = flows.flow1.match_intent(history.last_user_utterance).matches
if matches and matches[0].intent == "some_intent":
  to_country = matches[0].parameters.get("to_country")
  if to_country:
    respond(f"To confirm, you're going to {to_country}, right?")

Debugging

Mit dem Simulator können Sie Fehler in Ihren Codeblockfunktionen beheben. Diese Funktionen werden im Simulator als Aktionen angezeigt und liefern bei Bedarf unsere Details.

Zusätzliche Kontrolle

In diesem Leitfaden werden einige gängige Anwendungsfälle der Systembibliothek für Codeblöcke behandelt. Weitere Arten von Steuerelementen finden Sie in der Bibliotheksdokumentation.