Bloques de código

Cuando defines una guía, puedes proporcionar bloques de códigode forma opcional, que son código de Python intercalado que se puede usar para controlar mejor el comportamiento del agente. Este código se compone de funciones con decoradores especiales y las funciones 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 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 utilizar 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 está determinado por la firma de la función de Python, incluidas las anotaciones de tipo y la cadena de documentación. Al igual que con las llamadas a herramientas, el LLM no conoce el código que implementa la acción.

Muestra:

@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, se le proporcionará al LLM información sobre la acción, su entrada y su salida.

Para hacer referencia a una acción intercalada en las instrucciones de la guía, solo debes hacer referencia al nombre de la acción entre comillas inversas y describir cómo se debe usar.

Ejemplo de una acción intercalada place_order:

Take the customer's order, 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 Input &Output.

Para obtener más información, consulta la documentación de referencia de@Action.

Activar funciones

Las funciones de activación se usan para definir acciones condicionales en el código.

Las funciones de activación se declaran con decoradores. Puedes usar los siguientes decoradores de funciones de activación:

Decorador Parámetros del decorador Descripción
@EventTrigger event: str, condition: str, donde la condición es opcional Se activa por 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 antes de que el LLM ejecute 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 decoradores, y también cómo usar la respuesta función de biblioteca del sistema de bloques de código.

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

Cómo hacer 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 de flujos, guías y herramientas.

Cada uno de estos objetos tiene miembros que coinciden con los nombres de los recursos correspondientes. Estos nombres deben ser nombres de Python legales.

Muestra:

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

Cuando hagas 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 la guía deben incluir lo siguiente:

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

Anulaciones de acciones

Puedes usar bloques de código para crear una cola de acciones que se realizarán antes de cualquier otra acción determinada por el LLM y, potencialmente, anularlas. Para crear anulaciones de acciones, usa la add_override función global.

Todas las acciones de anulación en cola se ejecutarán de forma secuencial, y la salida de la acción estará disponible para el LLM. Una vez que la cola esté vacía, la operación volverá al LLM para la selección de acciones y entradas, a menos que una anulación finalice el turno con respond o con otra función que complete el turno.

Argumentos de la función:

  • action: Es la acción que se llevará a cabo. Para una acción intercalada, usa my_function_name. Para una acción de herramienta, usa tools.my_tool_name.my_tool_action. Para una acción de flujo, usa flows.my_flow_name.
  • inputs: Son las entradas opcionales para la acción. Por ejemplo: {"location": "Omaha"}.

Ejemplos:

# 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

De manera similar a las anulaciones de acciones, pero específicamente para las respuestas del agente, puedes usar la función global respond para obligar al agente a responder al usuario con contenido específico.

Muestra:

respond("Hello")

Cómo invocar herramientas

En las funciones de bloque de código, puedes invocar las herramientas que se definen para tu agente. A diferencia de cuando anulas una acción de herramienta, cuando invocas una herramienta directamente, los resultados de la ejecución de la herramienta no están disponibles para el LLM.

Ejemplos:

# 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 forma programática una intención para un flujo determinado con la Flow.match_intent.

Muestra:

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

Leer 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.

Muestra:

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

Depuración

Puedes usar el simulador para depurar las funciones de bloque de código. Estas funciones se mostrarán como acciones en el simulador y proporcionarán nuestros detalles según sea necesario.

Control adicional

En esta guía, se abarcan algunos usos comunes de la biblioteca del sistema de bloques de código. Para obtener más tipos de control, consulta la documentación de la biblioteca.

Anterior
Instrucciones de la guía
Siguiente
Acciones condicionales de la guía