Blocchi di codice

Quando definisci un playbook, puoi facoltativamente fornire blocchi di codice, ovvero codice Python incorporato che ti consente di controllare meglio il comportamento dell'agente. Questo codice è costituito da funzioni con decoratori speciali e da tutte le funzioni di utilità di cui hai bisogno.

Quando scrivi il codice, puoi utilizzare la libreria di sistema dei blocchi di codice per controllare il comportamento dell'agente.

Limitazioni

Si applicano le seguenti limitazioni:

• I blocchi di codice non possono contenere oggetti che conservano i dati. Tuttavia, puoi utilizzare strumenti per rendere persistenti i dati e mantenere lo stato.
• I blocchi di codice non possono effettuare chiamate remote direttamente. Ad esempio, non puoi utilizzare la libreria di richieste Python. Tuttavia, puoi utilizzare strumenti per effettuare chiamate remote indirettamente.
• I nomi delle risorse convertiti in nomi Python devono essere nomi Python validi.
• I blocchi di codice non possono scrivere parametri di sessione, a meno che non avvenga una transizione di flusso.

Azioni incorporate

Le azioni in linea si comportano in modo simile alle azioni degli strumenti. Hanno uno schema di input e output definito, determinato dalla firma della funzione Python, incluse le annotazioni dei tipi e la docstring. Come per le chiamate agli strumenti, l'LLM non è a conoscenza del codice che implementa l'azione.

Ad esempio:

@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

Per questa funzione, l'LLM riceve informazioni sull'azione, sul suo input e sul suo output.

Per fare riferimento a un'azione incorporata nelle istruzioni del playbook, fai riferimento al nome dell'azione tra apici inversi e descrivi come utilizzarla.

Ecco un esempio di un'azione in linea place_order:

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

Per creare esempi che utilizzano azioni inline, utilizza il tipo di strumento inline-action nella sezione Input e output.

Per saperne di più, consulta la documentazione di riferimento di @Action.

Funzioni di attivazione

Le funzioni di attivazione vengono utilizzate per definire azioni condizionali nel codice.

Le funzioni trigger vengono dichiarate utilizzando i decoratori.

Puoi utilizzare i seguenti decoratori delle funzioni di attivazione:

Decoratore	Parametri del decoratore	Descrizione
@EventTrigger	event: str, condition: str, dove la condizione è facoltativa	Attivato da un evento
@BeforeModelTrigger	condition: str, dove la condizione è facoltativa	Attivato ogni volta prima che l'LLM preveda l'azione successiva.
@BeforeActionTrigger	condition: str, dove la condizione è facoltativa	Attivato ogni volta prima che l'LLM esegua un'azione.
@BeforePlaybookTrigger	condition: str, dove la condizione è facoltativa	Si attiva la prima volta che viene avviato un playbook.

Ad esempio, queste funzioni mostrano come utilizzare questi decoratori e i relativi parametri, nonché come utilizzare la funzione della libreria di sistema del blocco di codice respond.

# 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 ☕")

Riferimenti a flussi, playbook e strumenti

Nel blocco di codice, puoi fare riferimento a flussi, playbook e strumenti specifici utilizzando le variabili globali flows, playbooks e tools.

Ognuno di questi oggetti ha membri che corrispondono ai nomi delle risorse corrispondenti. Questi nomi devono essere nomi Python validi.

Ad esempio:

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

Quando fai riferimento a flussi e playbook in un blocco di codice, devi fare riferimento anche alle istruzioni del playbook utilizzando la seguente sintassi:

${RESOURCE_TYPE: my_resource_name}

Ad esempio, se il blocco di codice contiene flows.myflow e playbooks.myplaybook, le istruzioni del playbook devono includere:

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

Azioni di override

Utilizza i blocchi di codice per creare una coda di azioni che verranno eseguite prima di qualsiasi altra azione determinata dall'LLM, con la possibilità di eseguirne l'override. Crea override delle azioni utilizzando la funzione globale add_override.

Tutte le azioni di override in coda vengono eseguite in sequenza e l'output dell'azione è disponibile per l'LLM. Una volta svuotata la coda, l'operazione torna all'LLM per la selezione dell'azione e dell'input, a meno che un override non termini il turno con respond o un'altra funzione che completa il turno.

Argomenti della funzione:

• Azione: specifica l'azione da eseguire. Per un'azione in linea, utilizza my_function_name. Per un'azione dello strumento, utilizza tools.my_tool_name.my_tool_action. Per un'azione di flusso, utilizza flows.my_flow_name.
• Input: specifica gli input facoltativi per l'azione, ad esempio {"location": "Omaha"}.

Ad esempio:

# 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)

Override delle risposte

Puoi utilizzare la funzione globale respond per forzare l'agente a rispondere all'utente con contenuti specifici, in modo simile agli override delle azioni, ma in modo specifico per le risposte dell'agente.

Ad esempio:

respond("Hello")

Chiamata degli strumenti

Puoi chiamare gli strumenti definiti per l'agente nelle funzioni del blocco di codice. A differenza di quando esegui l'override di un'azione dello strumento, quando chiami uno strumento direttamente, l'LLM non può accedere ai risultati dell'esecuzione dello strumento.

Ad esempio:

# 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"]

Intent di corrispondenza

I blocchi di codice possono trovare in modo programmatico un intent per un determinato flusso utilizzando la funzione Flow.match_intent.

Ad esempio:

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?")

Leggi i parametri di sessione

I blocchi di codice possono leggere i parametri disponibili al momento dell'esecuzione.

Ad esempio:

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

Debug

Utilizza il simulatore per eseguire il debug delle funzioni dei blocchi di codice. Queste funzioni vengono visualizzate come azioni nel simulatore e forniscono dettagli di debug, se necessario.

Controllo aggiuntivo

Questo documento illustra alcuni utilizzi comuni della libreria di sistema dei blocchi di codice. Per altri tipi di controllo, consulta la documentazione della libreria.