> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

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

> **Note**
>
> Esta función solo está disponible para Enterprise.

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

> **Info**
>
> Para una sola llamada a una API externa sin lógica personalizada, las [herramientas de webhook](/docs/es/eleven-agents/customization/tools/webhook-tools) suelen ser más fáciles de configurar. Para
> activar acciones en el navegador o la app de un usuario, utiliza en su lugar las [herramientas de cliente](/docs/es/eleven-agents/customization/tools/client-tools).

## 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:

```javascript
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](/docs/es/eleven-agents/customization/tools/webhook-tools#tool-configuration).

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

| Propiedad              | Descripción                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ctx.args`             | Los parámetros de llamada de la herramienta proporcionados por el agente.                                                                                                                                                                                                                                                                                                                              |
| `ctx.config`           | Variables de texto sin formato que has asignado al contexto de esta herramienta.                                                                                                                                                                                                                                                                                                                       |
| `ctx.secrets`          | Secretos del espacio de trabajo que has asignado al contexto de esta herramienta para usarlos en encabezados de solicitudes. El secreto sin procesar nunca se expone a tu código; la inyección se produce al salir y exclusivamente en los encabezados.                                                                                                                                                |
| `ctx.auth_connections` | Referencias a [conexiones de autenticación](/docs/es/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) configuradas que has asignado al contexto de esta herramienta, para usarlas en el encabezado de solicitud `X-With-Auth-Connection`. La credencial subyacente nunca se expone a tu código; la inyección se produce al salir y exclusivamente en los encabezados. |

> **Note**
>
> Solo `ctx.args` es visible para el agente cuando llama a la herramienta. Los secretos, valores de configuración y conexiones
> de autenticación nunca se revelan al agente.

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

![Definición de un parámetro de herramienta de código](/docs/_fern-img/d492e864ae15f3a355251faae3b719544e1ab56b703c02740b51be6c6769ccf7.webp)

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

![Asignación de un secreto del espacio de trabajo al objeto de contexto de una herramienta de código](/docs/_fern-img/ad58ee53f3591f447b108191aff760f1134350911933b968b06798fa6d42f438.webp)

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

> **Warning**
>
> Editar **Acceso a red de herramientas de código** requiere permisos de administrador del espacio de trabajo.

### 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:

#### Crea una nueva herramienta de código

En la sección **Agente** de la página de configuración de tu agente, elige **Añadir herramienta**. Selecciona **Código** como tipo de herramienta y, a continuación, establece un nombre y una descripción:

| Campo       | Valor                                                |
| ----------- | ---------------------------------------------------- |
| Nombre      | convert_temperature                                  |
| Descripción | Convierte una temperatura entre Celsius y Fahrenheit |

#### Define los parámetros

Añade dos parámetros para que el LLM sepa qué debe proporcionar:

| Tipo de dato | Identificador | Obligatorio | Descripción                                   |
| ------------ | ------------- | ----------- | --------------------------------------------- |
| number       | value         | true        | El valor de temperatura que se va a convertir |
| string       | from_unit     | true        | La unidad de origen: `"C"` o `"F"`            |

#### Escribe el código

Abre el editor de código y sustituye el código predeterminado por lo siguiente:

```javascript
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` };
};
```

Usa **Run** con algunos valores de ejemplo (por ejemplo, `value: 100, from_unit: "C"`) para confirmar el resultado antes de guardar.

#### Orquestación

Actualiza el prompt de sistema de tu agente para que sepa cuándo usar la herramienta:

**`Prompt de sistema`**

```plaintext Prompt de sistema
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.
```

#### Pruebas

Inicia una conversación y prueba lo siguiente:

> *¿A cuánto equivalen 100 grados Celsius en Fahrenheit?*

El agente debería llamar a la herramienta y leer el valor convertido.

### Ejemplos de autenticación

**Llamar a una API con un secreto**

```javascript
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**

```javascript
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](/docs/es/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) 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&#xA;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:

```plaintext
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:

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

#### Selección del LLM

> **Warning**
>
> Al usar herramientas, recomendamos elegir modelos de alta inteligencia como GPT 6 o Claude Sonnet 5.5.

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.