Codeblöcke

Beim Definieren eines Playbooks können Sie optional Codeblöcke angeben. Dabei handelt es sich um Inline-Python-Code, mit dem sich das Verhalten des Agenten besser steuern lässt. Dieser Code besteht aus Funktionen mit speziellen Decorators und allen erforderlichen Dienstfunktionen.

Beim Schreiben Ihres Codes können Sie die Codeblock-Systembibliothek verwenden, um das Verhalten des KI-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 beizubehalten und den Status zu verwalten.
• Codeblöcke können keine direkten Remote-Aufrufe ausführen. Sie können beispielsweise nicht die Python-Anfragebibliothek verwenden. Sie können jedoch Tools verwenden, um Remote-Aufrufe indirekt 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 ein Ablaufübergang 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 Typannotationen und Docstring. Ähnlich wie bei Toolaufrufen ist dem LLM der Code, der die Aktion implementiert, nicht bekannt.

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-Anleitungen auf eine Inline-Aktion verweisen möchten, geben Sie einfach den Aktionsnamen in Backticks an und beschreiben Sie, wie sie verwendet werden soll.

Beispiel für eine place_order-Inline-Aktion:

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 Abschnitt Eingabe und Ausgabe den Tooltyp inline-action.

Weitere Informationen finden Sie in der Referenzdokumentation zu @Action.

Triggerfunktionen

Mit Triggerfunktionen werden bedingte Aktionen im Code definiert.

Triggerfunktionen werden mit Decorators deklariert. Sie können die folgenden Triggerfunktions-Decorators verwenden:

Decorator	Decorator-Parameter	Beschreibung
@EventTrigger	event: str, condition: str, wobei die Bedingung optional ist	Durch ein Ereignis ausgelöst
@BeforeModelTrigger	condition: str, wobei die Bedingung optional ist	Wird jedes Mal ausgelöst, bevor das LLM die nächste Aktion vorhersagt.
@BeforeActionTrigger	condition: str, wobei die Bedingung optional ist	Wird jedes Mal ausgelöst, bevor das LLM eine Aktion ausführt.
@BeforePlaybookTrigger	condition: str, wobei die Bedingung optional ist	Wird ausgelöst, wenn ein Playbook zum ersten Mal gestartet wird.

Diese Funktionen zeigen beispielsweise, wie Sie diese Decorators und Decorator-Parameter sowie 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 Abläufe, 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 Mitglieder, die mit den Namen der entsprechenden Ressourcen übereinstimmen. 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 sie auch in den Playbook-Anweisungen mit der folgenden Syntax angeben:

${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 festgelegten Aktionen ausgeführt werden und diese möglicherweise überschreiben. Aktionsüberschreibungen werden mit der globalen Funktion add_override erstellt.

Alle in die Warteschlange gestellten Überschreibungsaktionen werden nacheinander ausgeführt und die Ausgabe der Aktion ist für das LLM verfügbar. Sobald die Warteschlange leer ist, wird der Vorgang an das LLM zurückgegeben, um eine Aktion und Eingabe 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 Toolaktion 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 KI-Agentenantworten, können Sie die globale Funktion respond verwenden, um den KI-Agenten zu zwingen, dem Nutzer mit bestimmten Inhalten zu antworten.

Beispiel:

respond("Hello")

Anruffunktionen

In Ihren Codeblockfunktionen können Sie die Tools aufrufen, die für Ihren Agenten definiert sind. Im Gegensatz zum Überschreiben einer Tool-Aktion sind die Ergebnisse der Tool-Ausführung beim direkten Aufrufen eines Tools für das LLM nicht 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 mithilfe der Funktion Flow.match_intent programmatisch eine Intent-Übereinstimmung für einen bestimmten Ablauf finden.

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

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

Zusätzliche Kontrolle

In diesem Leitfaden werden einige gängige Verwendungen der Codeblock-Systembibliothek behandelt. Weitere Arten von Steuerelementen finden Sie in der Dokumentation zur Bibliothek.