Herramientas de código

Las herramientas de código permiten que tu agente ejecute JavaScript personalizado en un entorno aislado del lado del servidor, sin que tengas que configurar y alojar tu propia ruta de webhook. Escribe la lógica una vez en el editor de código integrado y ElevenLabs la ejecutará cada vez que el agente llame a la herramienta.

Descripción general

Una herramienta de código es una función de JavaScript que se ejecuta cuando el agente la llama. Tú escribes todo el cuerpo de la función, así que la herramienta puede hacer tanto o tan poco como requiera la tarea:

• Cálculos personalizados: aplica reglas de precios, conversiones de unidades, lógica de puntuación o cálculos de fechas usando solo los parámetros de llamada a la herramienta. No requiere acceso a la red.
• Llamadas a API externas: usa fetch desde dominios permitidos, con secretos del espacio de trabajo y conexiones de autenticación inyectados en el contexto de la función.
• Combinación de varias fuentes: llama a dos o tres API y combina, compara o concilia sus resultados antes de devolver una única respuesta.
• Ramificación condicional: ejecuta lógica distinta según los parámetros de llamada a la herramienta, sin necesidad de una herramienta independiente para cada rama.
• Transformación de datos: devuelve exactamente la estructura que quieres que vea el agente, en lugar de una respuesta sin procesar del sistema de origen.

Cómo funciona

Tu código es un módulo de JavaScript que exporta una única función asíncrona predeterminada. La función recibe un objeto ctx y devuelve el resultado de la herramienta:

export default async (ctx) => {
  // ctx.args.<paramName> — the parameters the agent passed to this tool call
  const { city } = ctx.args;
  return { message: `Hello from ${city}!` };
};

El valor que devuelves se convierte en el resultado de la herramienta. Se devuelve al agente, se muestra en la transcripción de la conversación y puede utilizarse para la asignación dinámica de variables.

El objeto ctx

ctx es tu punto de acceso a todo lo que la herramienta puede consultar en el momento de la llamada. Los parámetros que proporciona el agente siempre llegan en ctx.args; los secretos, valores de configuración y conexiones de autenticación son opcionales y solo aparecen si los asignas en la sección Objeto de contexto de la herramienta.

Configurar parámetros

Los parámetros son los valores que proporciona el agente cuando llama a la herramienta y llegan en ctx.args. Defínelos en la sección Parámetros del formulario de configuración de la herramienta o en el editor de código, en la pestaña Params, dentro de la subpestaña Define Params. Cada parámetro requiere un tipo de datos, un identificador y una descripción que el agente usa para determinar el valor correcto a partir de la conversación. Tu código lee ese valor mediante el identificador, como ctx.args.appointment_datetime a continuación.

Configurar el objeto de contexto

Añade secretos, valores de configuración y conexiones de autenticación en la sección Objeto de contexto de la herramienta. Cada entrada requiere un tipo y un nombre. El panel muestra el acceso exacto para cada entrada, como ctx.secrets.DEMO_KEY a continuación.

Acceso a la red

El código que se ejecuta en el entorno aislado solo puede acceder a dominios que tu espacio de trabajo haya permitido explícitamente. Añade los dominios a los que debe llamar tu código en Configuración general de tu espacio de trabajo, en Dominios permitidos para herramientas de código. Las solicitudes a cualquier otro dominio fallarán.

Límites de ejecución

• Tiempo de espera: cada ejecución debe completarse dentro del tiempo de espera de respuesta configurado para la herramienta, de 1 a 30 segundos.
• Sin paquetes externos: actualmente, las herramientas de código se ejecutan sin dependencias de npm.

Probar tu código

Antes de guardar, usa Run en el editor de código para ejecutar tu código con valores de parámetros de ejemplo:

• Params: establece valores de prueba para cada parámetro definido por tu herramienta.
• Output: consulta el resultado devuelto o el error si la ejecución falló.
• Logs: consulta cualquier contenido escrito con console.log, console.warn o console.error, además de los tiempos de compilación y ejecución.

Guía

En esta guía, crearemos una herramienta de código que convierte una temperatura y devuelve una cadena con formato fácil de entender:

export default async (ctx) => {
  const { value, from_unit } = ctx.args;
  if (from_unit === "C") {
    const fahrenheit = (value * 9) / 5 + 32;
    return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` };
  }
  const celsius = ((value - 32) * 5) / 9;
  return { result: `${value}°F is ${celsius.toFixed(1)}°C` };
};

When the user asks to convert a temperature, call convert_temperature with the
value and its unit ("C" or "F"), and read back the result naturally.

Ejemplos de autenticación

Llamar a una API con un secreto

export default async (ctx) => {
  const { order_id } = ctx.args;
  const response = await fetch(`https://api.example.com/orders/${order_id}`, {
    headers: {
      Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

Asigna EXAMPLE_API_KEY a un secreto del espacio de trabajo en la sección Objeto de contexto de la herramienta y, después, añade api.example.com a Dominios permitidos para herramientas de código para que se permita la salida de la solicitud. El valor al que haces referencia es un marcador de posición: el secreto real se sustituye en la cabecera durante la salida y nunca es visible para tu código.

Llamar a una API con una conexión de autenticación OAuth

export default async (ctx) => {
  const { customer_id } = ctx.args;
  const response = await fetch(`https://api.example.com/customers/${customer_id}`, {
    headers: {
      "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

Asigna EXAMPLE_CRM a una conexión de autenticación configurada en la sección Objeto de contexto de la herramienta. El valor al que haces referencia es un marcador de posición: la credencial real se sustituye en la cabecera durante la salida y nunca es visible para tu código.

Buenas prácticas

Asigna nombres intuitivos a las herramientas y añade descripciones detalladas

Si el asistente no llama a las herramientas correctas, quizá tengas que actualizar sus nombres y descripciones para que entienda con mayor claridad cuándo debe seleccionar cada herramienta. Evita usar abreviaturas o acrónimos para acortar los nombres de las herramientas y los argumentos.

También puedes incluir descripciones detalladas sobre cuándo debe llamarse a una herramienta. Para herramientas complejas, incluye descripciones de cada argumento para ayudar al asistente a saber qué debe pedir al usuario para obtener ese argumento.

Asigna nombres intuitivos a los parámetros de las herramientas y añade descripciones detalladas

Usa nombres claros y descriptivos para los parámetros de las herramientas. Si procede, especifica en la descripción el formato esperado para un parámetro (por ejemplo, AAAA-mm-dd o dd/mm/aa para una fecha).

Plantéate proporcionar información adicional sobre cómo y cuándo llamar a las herramientas en el prompt del sistema de tu asistente

Proporcionar instrucciones claras en el prompt del sistema puede mejorar significativamente la precisión con la que el asistente llama a las herramientas. Por ejemplo, guía al asistente con instrucciones como las siguientes:

Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.

Proporciona contexto para situaciones complejas. Por ejemplo:

Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.

Selección de LLM

Es importante tener en cuenta que la elección del LLM influye en el éxito de las llamadas a funciones. Algunos LLM pueden tener dificultades para extraer de la conversación los parámetros relevantes.