Quando definisci un playbook, puoi facoltativamente fornire blocchi di codice, ovvero codice Python inline che può essere utilizzato per controllare meglio il comportamento dell'agente. Questo codice è composto 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 persistono i dati. Tuttavia, puoi utilizzare gli 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 Python requests. Tuttavia, puoi utilizzare gli 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 si verifichi una transizione di flusso.
Azioni inline
Le azioni inline 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 di tipo e la stringa di documentazione. Analogamente alle chiamate di strumenti, il LLM non è a conoscenza del codice che implementa l'azione.
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, al LLM verranno fornite informazioni sull'azione, sul suo input e sul suo output.
Per fare riferimento a un'azione inline nelle istruzioni del playbook, fai riferimento al nome dell'azione tra virgolette inverse e descrivi come deve essere utilizzata.
Esempio per un'azione inline place_order:
Take the customer's order, 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 ulteriori informazioni, consulta la @Action documentazione di riferimento.
Funzioni di attivazione
Le funzioni di attivazione vengono utilizzate per definire azioni condizionali nel codice.
Le funzioni di attivazione vengono dichiarate utilizzando i decoratori. Puoi utilizzare i seguenti decoratori di funzioni di attivazione:
| Decoratore | Parametri del decoratore | Descrizione |
|---|---|---|
| @EventTrigger | event: str, condition: str, dove la condizione è facoltativa |
Attivata da un evento |
| @BeforeModelTrigger | condition: str, dove la condizione è facoltativa |
Attivata ogni volta prima che il LLM preveda l'azione successiva. |
| @BeforeActionTrigger | condition: str, dove la condizione è facoltativa |
Attivata ogni volta prima che il LLM esegua un'azione. |
| @BeforePlaybookTrigger | condition: str, dove la condizione è facoltativa |
Attivata la prima volta che viene avviato un playbook. |
Ad esempio, queste funzioni mostrano come utilizzare questi decoratori e i parametri dei decoratori, nonché come utilizzare la funzione della libreria di sistema dei blocchi 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 ☕")
Fare riferimento 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.
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 anche farvi riferimento nelle istruzioni del playbook con 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}
Override delle azioni
Puoi utilizzare i blocchi di codice per creare una coda di azioni che verranno eseguite prima di qualsiasi altra azione determinata dal LLM e, potenzialmente, sostituirle. Per creare override delle azioni, utilizza la add_override funzione globale.
Tutte le azioni di override in coda verranno eseguite in sequenza e l'output dell'azione sarà disponibile per il LLM. Una volta svuotata la coda, l'operazione torna al LLM per la selezione di azioni e input, a meno che un override non termini il turno con respond o un'altra funzione che completa il turno.
Argomenti delle funzioni:
- action: l'azione da eseguire.
Per un'azione inline, utilizza
my_function_name. Per un'azione dello strumento, utilizzatools.my_tool_name.my_tool_action. Per un'azione di flusso, utilizzaflows.my_flow_name. - inputs: input facoltativi per l'azione.
Ad esempio:
{"location": "Omaha"}.
Esempi:
# 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
Analogamente agli override delle azioni, ma in modo specifico per le risposte degli agenti, puoi utilizzare la respond funzione globale per forzare l'agente a rispondere all'utente con contenuti specifici.
Esempio:
respond("Hello")
Chiamare gli strumenti
Nelle funzioni dei blocchi di codice, puoi chiamare gli strumenti definiti per il tuo agente. A differenza di quando esegui l'override di un'azione dello strumento, quando chiami uno strumento direttamente, i risultati dell'esecuzione dello strumento non sono disponibili per il LLM.
Esempi:
# 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"]
Corrispondenza dell'intent
I blocchi di codice possono trovare la corrispondenza programmatica di un intent per un determinato flusso utilizzando la Flow.match_intent.
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?")
Leggere i parametri di sessione
I blocchi di codice possono leggere i parametri disponibili al momento dell'esecuzione.
Esempio:
state["$session.params.my-param"]
state["$request.session-id"]
Debug
Puoi utilizzare il simulatore per eseguire il debug delle funzioni dei blocchi di codice. Queste funzioni verranno visualizzate come azioni nel simulatore e forniranno i nostri dettagli, se necessario.
Controllo aggiuntivo
Questa guida illustra alcuni utilizzi comuni della libreria di sistema dei blocchi di codice. Per altri tipi di controllo, consulta la documentazione della libreria.