Codeblöcke

Beim Definieren eines Playbooks, können Sie optional Codeblöcke angeben. Das ist Inline-Python-Code, mit dem Sie das Verhalten von Agenten besser steuern können. Dieser Code besteht aus Funktionen mit speziellen Decorators und allen erforderlichen Hilfsfunktionen.

Beim Schreiben von Code, können Sie die Systembibliothek für Codeblöcke verwenden, um das Verhalten von Agenten zu steuern.

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 zu speichern und den Status beizubehalten.
• 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 indirekte Remote-Aufrufe auszuführen.
• Ressourcennamen, die in Python-Namen konvertiert werden müssen gültige Python-Namen sein.
• Codeblöcke können keine Sitzungsparameter schreiben, es sei denn, es findet eine Ablaufübergabe statt.

Inline-Aktionen

Inline-Aktionen verhalten sich ähnlich wie Tool-Aktionen. Sie haben ein definiertes Eingabe- und Ausgabeschema, das durch die Python-Funktionssignatur bestimmt wird, einschließlich Typanmerkungen und Docstring. Ähnlich wie bei Tool-Aufrufen weiß das LLM nichts über den Code, der die Aktion implementiert.

Beispiel:

@Action
def is_prime(n: int) -> bool:
  """Returns true if n is prime."""
  if not isinstance(n, int) or n < 2:
    return False

  for i in range(2, int(n ** 0.5) + 1):
    if n % i == 0:
      return False

  return True

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

Wenn Sie in Ihren Playbook-Anweisungen auf eine Inline-Aktion verweisen möchten, geben Sie einfach den Aktionsnamen in Backticks an und beschreiben Sie, wie er verwendet werden soll.

Beispiel für eine Inline-Aktion place_order:

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

Wenn Sie Beispiele erstellen möchten, die Inline-Aktionen verwenden, wählen Sie im Bereich Eingabe und Ausgabe den Tool-Typ inline-action aus.

Weitere Informationen finden Sie in der @Action Referenzdokumentation.

Triggerfunktionen

Triggerfunktionen werden verwendet, um bedingte Aktionen im Code zu definieren.

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

Decorator	Decorator-Parameter	Beschreibung
@EventTrigger	event: str, condition: str, wobei „condition“ optional ist	Wird durch ein Ereignis ausgelöst
@BeforeModelTrigger	condition: str, wobei „condition“ optional ist	Wird jedes Mal ausgelöst, bevor das LLM die nächste Aktion vorhersagt.
@BeforeActionTrigger	condition: str, wobei „condition“ optional ist	Wird jedes Mal ausgelöst, bevor das LLM eine Aktion ausführt.
@BeforePlaybookTrigger	condition: str, wobei „condition“ optional ist	Wird beim ersten Start eines Playbooks ausgelöst.

Diese Funktionen zeigen beispielsweise, wie Sie diese Decorators und Decorator-Parameter verwenden und wie Sie die Funktion „respond“ der Systembibliothek 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 ☕")

Verweise auf Abläufe, Playbooks und Tools

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 Member, 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 den Playbook-Anweisungen mit der folgenden Syntax darauf verweisen:

${RESOURCE_TYPE: my_resource_name}

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

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

Aktionsüberschreibungen

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

Alle in die Warteschlange gestellten Ü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, eine Überschreibung beendet die Runde mit „respond“ oder einer anderen Funktion, die die Runde 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 Ablaufaktion 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 Aktionsüberschreibungen, aber speziell für Agentenantworten, können Sie die respond globale Funktion verwenden, um den Agenten zu zwingen, dem Nutzer mit bestimmten Inhalten zu antworten.

Beispiel:

respond("Hello")

Tools aufrufen

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

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 abgleichen

Codeblöcke können mit der Funktion Flow.match_intent programmatisch eine Absicht für einen bestimmten Ablauf 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?")

Sitzungsparameter lesen

Codeblöcke können Parameter lesen, die zum Zeitpunkt der Ausführung verfügbar sind.

Beispiel:

state["$session.params.my-param"]
state["$request.session-id"]

Debugging

Sie können den Simulator verwenden, um Ihre Codeblockfunktionen zu debuggen. Diese Funktionen werden im Simulator als Aktionen angezeigt und liefern bei Bedarf Details.

Zusätzliche Steuerungsmöglichkeiten

In dieser Anleitung werden einige häufige Anwendungsfälle der Systembibliothek für Codeblöcke behandelt. Weitere Steuerungsmöglichkeiten finden Sie in der Bibliotheksdokumentation.