Codeblöcke

Beim Definieren eines Playbooks können Sie optional Codeblöcke angeben. Das ist Inline-Python-Code, mit dem Sie das Verhalten des KI-Agenten besser steuern können. 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 Remote-Aufrufe direkt 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 Toolaktionen. Sie haben ein definiertes Eingabe- und Ausgabeschema, das durch die Python-Funktionssignatur bestimmt wird, einschließlich Typanmerkungen und Docstring. 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, ihrer Eingabe und ihrer Ausgabe.

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

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

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

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

Weitere Informationen finden Sie in der Referenzdokumentation zu @Action.

Triggerfunktionen

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

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.

In diesen Funktionen wird beispielsweise gezeigt, 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 referenzieren:

${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. Erstellen Sie Aktionsüberschreibungen mit der globalen Funktion add_override.

Alle in der Warteschlange befindlichen Ü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:

• Aktion: Geben Sie die auszuführende Aktion an. 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.
• Eingaben: Geben Sie optionale Eingaben für die Aktion an, z. B. {"location": "Omaha"}.

Beispiel:

# 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

Mit der globalen Funktion respond können Sie den KI-Agenten zwingen, dem Nutzer mit bestimmten Inhalten zu antworten. Das funktioniert ähnlich wie Aktionsüberschreibungen, ist aber speziell für Antworten des KI-Agenten gedacht.

Beispiel:

respond("Hello")

Anruffunktionen

Sie können die Tools, die für Ihren Agenten definiert sind, in Ihren Codeblockfunktionen aufrufen. Im Gegensatz zum Überschreiben einer Toolaktion kann das LLM nicht auf die Ergebnisse der Toolausführung zugreifen, wenn Sie ein Tool direkt aufrufen.

Beispiel:

# 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 einen Intent 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

Verwenden Sie den Simulator, um Fehler in Ihren Codeblockfunktionen zu beheben. Diese Funktionen werden im Simulator als Aktionen angezeigt und liefern bei Bedarf Debugging-Details.

Zusätzliche Kontrolle

In diesem Dokument werden einige gängige Verwendungen der Codeblock-Systembibliothek beschrieben. Weitere Steuerungstypen finden Sie in der Dokumentation zur Bibliothek.