Cuando defines una guía, puedes proporcionar bloques de código de forma opcional, que son código de Python intercalado que te permite controlar mejor el comportamiento del agente. Este código consta de funciones con decoradores especiales y cualquier función de utilidad que necesites.
Cuando escribas tu código, puedes usar la biblioteca del sistema de bloques de código para controlar el comportamiento del agente.
Limitaciones
Se aplica la siguiente limitación:
- Los bloques de código no pueden contener objetos que conserven datos. Sin embargo, puedes usar herramientas para conservar los datos y mantener el estado.
- Los bloques de código no pueden realizar llamadas remotas directamente. Por ejemplo, no puedes usar la biblioteca de solicitudes de Python. Sin embargo, puedes usar herramientas para realizar llamadas remotas de forma indirecta.
- Los nombres de recursos que se convierten en nombres de Python deben ser nombres de Python legales.
- Los bloques de código no pueden escribir parámetros de sesión, a menos que se produzca una transición de flujo.
Acciones intercaladas
Las acciones intercaladas se comportan de manera similar a las acciones de herramientas. Tienen un esquema de entrada y salida definido, que se determina por la firma de la función de Python, incluidas las anotaciones de tipo y la docstring. Al igual que las llamadas a herramientas, el LLM no conoce el código que implementa la acción.
Por ejemplo:
@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
Para esta función, el LLM recibe información sobre la acción, su entrada y su salida.
Para hacer referencia a una acción intercalada en las instrucciones de tu guía, haz referencia al nombre de la acción entre acentos graves y describe cómo usarla.
Este es un ejemplo de una acción intercalada de place_order:
Take the customer's order, and then call the `place_order` action when the
order is ready.
Para crear ejemplos que usen acciones intercaladas, usa el tipo de herramienta inline-action en la sección Entrada y salida.
Para obtener más información, consulta la documentación de referencia de @Action.
Activa funciones
Las funciones de activación se usan para definir acciones condicionales en el código.
Las funciones de activador se declaran con decoradores.
Puedes usar los siguientes decoradores de funciones de activador:
| Decorador | Parámetros de decorador | Descripción |
|---|---|---|
| @EventTrigger | event: str, condition: str, donde la condición es opcional |
Se activa con un evento |
| @BeforeModelTrigger | condition: str, donde la condición es opcional |
Se activa cada vez antes de que el LLM prediga la siguiente acción. |
| @BeforeActionTrigger | condition: str, donde la condición es opcional |
Se activa cada vez que el LLM ejecuta una acción. |
| @BeforePlaybookTrigger | condition: str, donde la condición es opcional |
Se activa la primera vez que se inicia una guía. |
Por ejemplo, estas funciones muestran cómo usar estos decoradores y parámetros de decorador, y también cómo usar la función de biblioteca del sistema de bloques de código 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 ☕")
Haz referencia a flujos, guías y herramientas
En tu bloque de código, puedes hacer referencia a flujos, guías y herramientas específicos con las variables globales flows, playbooks y tools.
Cada uno de estos objetos tiene miembros que coinciden con los nombres de los recursos correspondientes. Estos nombres deben ser nombres legales de Python.
Por ejemplo:
add_override(playbooks.troubleshooting, {})
add_override(flows.billing)
add_override(tools.weather_api.get_weather, {"location": "San Francisco"})
Cuando haces referencia a flujos y guías en un bloque de código, también debes hacer referencia a ellos en las instrucciones de la guía con la siguiente sintaxis:
${RESOURCE_TYPE: my_resource_name}
Por ejemplo, si tu bloque de código contiene flows.myflow y
playbooks.myplaybook, las instrucciones de tu guía deberían incluir lo siguiente:
${FLOW: myflow}
${PLAYBOOK: myplaybook}
Anulaciones de acciones
Usa bloques de código para crear una cola de acciones que se realizarán antes de cualquier otra acción que determine el LLM y, posiblemente, anularlas. Crea anulaciones de acciones con la función global add_override.
Todas las acciones de anulación en cola se ejecutan de forma secuencial, y el resultado de la acción está disponible para el LLM. Una vez que la cola está vacía, la operación vuelve al LLM para la selección de acciones y entradas, a menos que una anulación finalice el turno con respond u otra función que complete el turno.
Argumentos de la función:
- Acción: Especifica la acción que se llevará a cabo. Para una acción intercalada, usa
my_function_name. Para una acción de herramienta, usatools.my_tool_name.my_tool_action. Para una acción de flujo, usaflows.my_flow_name. - Entradas: Especifica entradas opcionales para la acción, como
{"location": "Omaha"}.
Por ejemplo:
# 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)
Anulaciones de respuestas
Puedes usar la función global respond para forzar al agente a responder al usuario con contenido específico, similar a las anulaciones de acciones, pero específicamente para las respuestas del agente.
Por ejemplo:
respond("Hello")
Llamadas a herramientas
Puedes llamar a las herramientas que se definen para tu agente en las funciones de tu bloque de código. A diferencia de cuando anulas una acción de herramienta, cuando llamas a una herramienta directamente, el LLM no puede acceder a los resultados de la ejecución de la herramienta.
Por ejemplo:
# 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"]
Intención de coincidencia
Los bloques de código pueden hacer coincidir de manera programática un intent para un flujo determinado con la función Flow.match_intent.
Por ejemplo:
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?")
Lee los parámetros de sesión
Los bloques de código pueden leer parámetros que están disponibles en el momento de la ejecución.
Por ejemplo:
state["$session.params.my-param"]
state["$request.session-id"]
Depuración
Usa el simulador para depurar las funciones de bloque de código. Estas funciones aparecen como acciones en el simulador y proporcionan detalles de depuración según sea necesario.
Control adicional
En este documento, se describen algunos usos comunes de la biblioteca del sistema de bloques de código. Para obtener más información sobre otros tipos de control, consulta la documentación de la biblioteca.