Herramientas de código

Las herramientas de código permiten a tu agente ejecutar 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.

Resumen

Una herramienta de código es una función de JavaScript que se ejecuta cuando el agente la llama. Escribes todo el cuerpo de la función, por lo 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 de 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 de la herramienta, sin necesitar 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 de un servicio externo.

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 devuelvas se convierte en el resultado de la herramienta. Se devuelve al agente, aparece en la transcripción de la conversación y puede usarse 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 el agente proporciona 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 dato, 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 tu código necesita llamar en Configuración de ElevenAgents, dentro de Acceso a red de 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: las herramientas de código no admiten actualmente 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ámetro de ejemplo:

• Params — establece valores de prueba para cada parámetro que defina tu herramienta.
• Output — consulta el resultado devuelto o el error si la ejecución ha fallado.
• Logs — consulta todo lo 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 de texto con un formato claro:

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 Acceso a red de herramientas de código para permitir la salida de la solicitud. El valor al que haces referencia es un marcador de posición: el secreto real se sustituye en el encabezado al salir 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 el encabezado al salir y nunca es visible para tu código.

Buenas prácticas

Usa nombres intuitivos para las herramientas y descripciones detalladas

Si ves que el asistente no llama a las herramientas correctas, quizá debas actualizar los nombres y las descripciones de tus herramientas para que el asistente entienda mejor cuándo debe seleccionar cada una. Evita usar abreviaturas o acrónimos para acortar los nombres de las herramientas y los argumentos.

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

Usa nombres intuitivos para los parámetros de las herramientas y 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, YYYY-mm-dd o dd/mm/yy para una fecha).

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

Dar instrucciones claras en el prompt de sistema puede mejorar considerablemente la precisión de las llamadas a herramientas del asistente. 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 del 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.