> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Herramientas como código

## Descripción general

Una [herramienta](/docs/es/eleven-agents/customization/tools) se almacena como una configuración con esquemas JSON anidados para sus parámetros. Escribir esa configuración a mano implica mantener los parámetros de ruta sincronizados con la URL, las listas `required` sincronizadas con sus propiedades y asignar a cada parámetro exactamente una fuente de valor. El creador de herramientas de los SDK de Python y JavaScript te permite describir la misma herramienta mediante llamadas a métodos encadenadas. Después genera la solicitud que `tools.create()` y `tools.update()` ya aceptan.

Úsalo para:

* Definir herramientas de webhook, cliente y sistema en código, y revisarlas como cualquier otro cambio de código.
* Cargar una herramienta, cambiar un parámetro y volver a enviarla sin modificar el resto de su configuración.
* Almacenar herramientas como JSON en el control de versiones y validarlas en CI.

> **Note**
>
> El creador se ejecuta íntegramente en el SDK. No llama a rutas de API nuevas y cualquier elemento que cree se puede
> abrir y editar en el panel de control.

## Requisitos

* Python: el paquete `elevenlabs`. El creador se importa desde `elevenlabs.agent_tools`.
* JavaScript: el paquete `@elevenlabs/elevenlabs-js`. El creador se exporta desde la raíz del paquete.

## Crear una herramienta de webhook

`Tool.webhook(name, description)` inicia una [herramienta de webhook](/docs/es/eleven-agents/customization/tools/webhook-tools). El nombre y la descripción son lo que ve el LLM al decidir si debe llamar a la herramienta. Este ejemplo busca un pedido mediante el número que proporciona la persona que llama, envía una clave de API desde los secretos del espacio de trabajo y almacena el estado del pedido en una variable dinámica:

```python
from elevenlabs import ElevenLabs
from elevenlabs.agent_tools import Header, Schema, Tool

elevenlabs = ElevenLabs()

get_order = (
    Tool.webhook("get_order", "Look up an order by the number the caller gives")
    .get("https://api.example.com/orders/{order_id}")
    .path_param("order_id", Schema.string().describe("The order number, e.g. A-1042"))
    .query_param("include", Schema.string().constant("items"))
    .header("Authorization", Header.secret("sec_orders_api"))
    .assign("order_status", "order.status")
    .options(response_timeout_secs=10)
)

tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())
```

```typescript
import { ElevenLabsClient, Header, Schema, Tool } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const getOrder = Tool.webhook("get_order", "Look up an order by the number the caller gives")
  .get("https://api.example.com/orders/{order_id}")
  .pathParam("order_id", Schema.string().describe("The order number, e.g. A-1042"))
  .queryParam("include", Schema.string().constant("items"))
  .header("Authorization", Header.secret("sec_orders_api"))
  .assign("order_status", "order.status")
  .options({ responseTimeoutSecs: 10 });

const tool = await elevenlabs.conversationalAi.tools.create(getOrder.build());
```

Los métodos de solicitud establecen el método HTTP y la URL. Los marcadores `{name}` de la URL se rellenan con parámetros de ruta:

| Python                                                           | JavaScript                 | Establece                                                                                                                               |
| ---------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `get(url)`, `post(url)`, `put(url)`, `patch(url)`, `delete(url)` | igual                      | El método y la URL. `POST`, `PUT` y `PATCH` necesitan un cuerpo; `GET` no puede tenerlo.                                                |
| `path_param(name, schema)`                                       | `pathParam(name, schema)`  | Un parámetro de ruta para el marcador `{name}` de la URL.                                                                               |
| `query_param(name, schema)`                                      | `queryParam(name, schema)` | Un parámetro de consulta.                                                                                                               |
| `body(schema)`                                                   | `body(schema)`             | El cuerpo de la solicitud. Debe ser un esquema de objeto.                                                                               |
| `response(schema)`                                               | `response(schema)`         | El esquema del cuerpo de la respuesta. Debe ser un esquema de objeto.                                                                   |
| `header(name, value)`                                            | `header(name, value)`      | Una cabecera de solicitud. Consulta [Cabeceras y autenticación](#headers-and-authentication).                                           |
| `auth(connection)`                                               | `auth(connection)`         | La [conexión de autenticación](/docs/es/eleven-agents/customization/tools/webhook-tools#supported-authentication-methods) que se usará. |
| `assign(variable, path)`                                         | `assign(variable, path)`   | Almacena en una variable dinámica el valor de `path` en la respuesta (notación de puntos).                                              |

Establecer un parámetro o una cabecera cuyo nombre ya existe lo reemplaza y conserva su posición. `remove_path_param()`, `remove_query_param()`, `remove_header()` y `remove_assignment()` (`removePathParam()` y equivalentes en JavaScript) eliminan uno. Los nombres de los parámetros deben ser únicos entre la ruta, la consulta y el cuerpo.

Un cuerpo es un esquema de objeto construido propiedad a propiedad:

```python
refund = (
    Tool.webhook("issue_refund", "Refund an order the caller asked to return")
    .post("https://api.example.com/refunds")
    .body(
        Schema.object()
        .property("order_id", Schema.string().from_variable("order_id"))
        .property(
            "reason",
            Schema.string().describe("Why the caller wants a refund").choices(["damaged", "late", "other"]),
        )
        .property("note", Schema.string().describe("Anything else the caller said").optional())
    )
)
```

```typescript
const refund = Tool.webhook("issue_refund", "Refund an order the caller asked to return")
  .post("https://api.example.com/refunds")
  .body(
    Schema.object()
      .property("order_id", Schema.string().fromVariable("order_id"))
      .property(
        "reason",
        Schema.string()
          .describe("Why the caller wants a refund")
          .choices(["damaged", "late", "other"])
      )
      .property("note", Schema.string().describe("Anything else the caller said").optional())
  );
```

## Esquemas de parámetros

`Schema` crea los esquemas de parámetros que usan las herramientas de webhook y cliente. Cada método devuelve un esquema nuevo y deja sin modificar aquel sobre el que se llamó, por lo que puedes definir un esquema una vez y usarlo en varias herramientas.

| Constructor                                                               | Crea                                                  |
| ------------------------------------------------------------------------- | ----------------------------------------------------- |
| `Schema.string()`, `Schema.integer()`, `Schema.number()`, `Schema.bool()` | Un valor literal                                      |
| `Schema.object()`                                                         | Un objeto. Añade propiedades con `property()`.        |
| `Schema.array(items)`                                                     | Una matriz cuyos elementos cumplen el esquema `items` |

### De dónde procede un valor

Cada literal necesita exactamente una fuente de valor, aparezca donde aparezca: en un parámetro, en un cuerpo, en un esquema de respuesta o dentro de un objeto o una matriz. Un objeto o una matriz también pueden tener una, que proporciona entonces el valor completo.

| Python                | JavaScript           | El valor                                                                                                                                    |
| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `describe(text)`      | `describe(text)`     | Lo proporciona el LLM, guiado por `text`.                                                                                                   |
| `from_variable(name)` | `fromVariable(name)` | Se lee de una [variable dinámica](/docs/es/eleven-agents/customization/personalization/dynamic-variables) cuando se ejecuta la herramienta. |
| `constant(value)`     | `constant(value)`    | Siempre es `value`.                                                                                                                         |
| `system_provided()`   | `systemProvided()`   | Lo completa el sistema cuando se ejecuta la herramienta. Solo literales.                                                                    |
| `omit()`              | `omit()`             | Se omite de la solicitud. Solo para una propiedad opcional.                                                                                 |

En un objeto o una matriz, `describe()` documenta el contenedor para el LLM, y cada propiedad o elemento sigue teniendo su propia fuente.

### Otros métodos de esquema

| Python                                            | JavaScript                                    | Función                                                                                                     |
| ------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `optional()`                                      | `optional()`                                  | Hace que una propiedad sea opcional. Las propiedades son obligatorias salvo que se marquen como opcionales. |
| `choices(values)`                                 | `choices(values)`                             | Limita una cadena a un conjunto fijo de valores entre los que elige el LLM.                                 |
| `allowed_from(variable)`                          | `allowedFrom(variable)`                       | Rechaza un valor del LLM que no esté en la lista de una variable dinámica. Necesita `describe()`.           |
| `property(name, schema)` / `without(name)`        | `property(name, schema)` / `without(name)`    | Añade, reemplaza o elimina una propiedad de objeto. Una propiedad reemplazada conserva su posición.         |
| `require_any_of(names)` / `require_all_of(names)` | `requireAnyOf(names)` / `requireAllOf(names)` | Requiere al menos una, o todas, las propiedades opcionales de un grupo.                                     |

## Cabeceras y autenticación

El valor de una cabecera procede de uno de cuatro lugares. Usa un secreto o una variable de entorno para cualquier dato sensible, de modo que el valor nunca aparezca en la configuración de la herramienta:

| Constructor                                      | El valor de la cabecera es                                                                                                                 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Header.value(text)`                             | Texto fijo.                                                                                                                                |
| `Header.secret(id)`                              | Un secreto del almacén de secretos del espacio de trabajo.                                                                                 |
| `Header.variable(name)`                          | Una variable dinámica, leída al ejecutar la herramienta.                                                                                   |
| `Header.env_var(label)` / `Header.envVar(label)` | Una [variable de entorno](/docs/es/eleven-agents/integrate/environment-variables) del espacio de trabajo, resuelta para el entorno actual. |

`AuthConnection.id(id)` usa una conexión de autenticación del espacio de trabajo mediante su ID. `AuthConnection.env_var(label)` / `AuthConnection.envVar(label)` la selecciona desde una variable de entorno, para que la misma configuración de herramienta pueda usar una conexión distinta en cada entorno.

```python
from elevenlabs.agent_tools import AuthConnection, Header

update_profile = (
    Tool.webhook("update_profile", "Update the caller's email address")
    .put("https://api.example.com/profiles/{profile_id}")
    .path_param("profile_id", Schema.string().from_variable("profile_id"))
    .body(Schema.object().property("email", Schema.string().describe("The new email address")))
    .header("X-Api-Key", Header.env_var("profiles_api_key"))
    .auth(AuthConnection.env_var("profiles_oauth"))
)
```

```typescript
import { AuthConnection, Header } from "@elevenlabs/elevenlabs-js";

const updateProfile = Tool.webhook("update_profile", "Update the caller's email address")
  .put("https://api.example.com/profiles/{profile_id}")
  .pathParam("profile_id", Schema.string().fromVariable("profile_id"))
  .body(Schema.object().property("email", Schema.string().describe("The new email address")))
  .header("X-Api-Key", Header.envVar("profiles_api_key"))
  .auth(AuthConnection.envVar("profiles_oauth"));
```

## Crear una herramienta de cliente

`Tool.client(name, description)` inicia una [herramienta de cliente](/docs/es/eleven-agents/customization/tools/client-tools), que se ejecuta en tu aplicación en lugar de en un servidor. Añade sus parámetros con `param(name, schema)`. Establece `expects_response` / `expectsResponse` cuando el agente deba esperar el resultado de tu aplicación:

```python
show_map = (
    Tool.client("show_store_map", "Show the caller a map of the nearest store")
    .param("store_id", Schema.string().describe("The store to show"))
    .options(expects_response=False)
)
```

```typescript
const showMap = Tool.client("show_store_map", "Show the caller a map of the nearest store")
  .param("store_id", Schema.string().describe("The store to show"))
  .options({ expectsResponse: false });
```

## Crear una herramienta de sistema

Las [herramientas de sistema](/docs/es/eleven-agents/customization/tools/system-tools) están integradas en la plataforma. Cada una tiene su propio constructor en `SystemTool`, que recibe la configuración de esa herramienta:

| Python                                                  | JavaScript                                            |
| ------------------------------------------------------- | ----------------------------------------------------- |
| `SystemTool.end_call()`                                 | `SystemTool.endCall()`                                |
| `SystemTool.skip_turn(wait_timeout_secs=...)`           | `SystemTool.skipTurn({ waitTimeoutSecs })`            |
| `SystemTool.language_detection(...)`                    | `SystemTool.languageDetection(options?)`              |
| `SystemTool.play_keypad_touch_tone(...)`                | `SystemTool.playKeypadTouchTone(options?)`            |
| `SystemTool.voicemail_detection(voicemail_message=...)` | `SystemTool.voicemailDetection({ voicemailMessage })` |
| `SystemTool.knowledge_base(enabled_strategies=...)`     | `SystemTool.knowledgeBase({ enabledStrategies })`     |
| `SystemTool.transfer_to_number(...)`                    | `SystemTool.transferToNumber(options?)`               |
| `SystemTool.transfer_to_agent()`                        | `SystemTool.transferToAgent()`                        |

Las dos herramientas de transferencia toman sus destinos de `transfer(condition, destination, options)`. La condición indica al LLM cuándo transferir allí, y el destino usa el mismo `Destination` que los [workflows como código](/docs/es/eleven-agents/customization/agents-as-code/workflows#transfer-destinations). Una transferencia a una URI SIP necesita una transferencia SIP REFER:

```python
from elevenlabs.agent_tools import SystemTool
from elevenlabs.agent_workflows import Destination

transfer = (
    SystemTool.transfer_to_number()
    .transfer("Caller asks for billing", Destination.phone("+15551234567"))
    .transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), transfer_type="sip_refer")
)

to_sales = SystemTool.transfer_to_agent().transfer(
    "Caller wants to buy something", Destination.agent("agent_sales"), transfer_message="Connecting you to sales"
)
```

```typescript
import { Destination, SystemTool } from "@elevenlabs/elevenlabs-js";

const transfer = SystemTool.transferToNumber()
  .transfer("Caller asks for billing", Destination.phone("+15551234567"))
  .transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), {
    transferType: "sip_refer",
  });

const toSales = SystemTool.transferToAgent().transfer(
  "Caller wants to buy something",
  Destination.agent("agent_sales"),
  { transferMessage: "Connecting you to sales" }
);
```

## Opciones de herramientas

La configuración compartida por todos los tipos de herramientas se incluye en `options()`, como argumentos con nombre en Python y como objeto en JavaScript. Sus nombres coinciden con los campos de la configuración de la herramienta en la API:

| Se aplica a             | Python                                                                                                                                       | JavaScript                                                                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Todas las herramientas  | `name`, `description`, `response_timeout_secs`, `interruption_mode`, `pre_tool_speech`, `tool_call_sound`, `tool_error_handling_mode`, ...   | `name`, `description`, `responseTimeoutSecs`, `interruptionMode`, `preToolSpeech`, `toolCallSound`, `toolErrorHandlingMode`, ...    |
| Herramientas de webhook | `execution_mode`, `content_type`, `response_filter`, `follow_redirects`, `follow_redirects_allowed_domains`, `dynamic_variable_placeholders` | `executionMode`, `contentType`, `responseFilter`, `followRedirects`, `followRedirectsAllowedDomains`, `dynamicVariablePlaceholders` |
| Herramientas de cliente | `execution_mode`, `expects_response`, `dynamic_variable_placeholders`                                                                        | `executionMode`, `expectsResponse`, `dynamicVariablePlaceholders`                                                                   |

El tiempo de espera de respuesta de una herramienta de webhook es de 5 a 300 segundos. El de una herramienta de cliente es de 1 a 120 segundos, o -1 para esperar el tiempo necesario, lo que requiere `expects_response` / `expectsResponse`. `follow_redirects` / `followRedirects` necesita una lista de dominios permitidos.

## Vincular herramientas a un agente

Las herramientas de webhook y cliente se crean de forma independiente con `tools.create()` y se vinculan a agentes mediante ID, por lo que una herramienta puede compartirse entre varios agentes. Las herramientas de sistema forman parte de la configuración del agente: `build_config()` / `buildConfig()` devuelve la entrada para las herramientas integradas del agente.

```python
from elevenlabs import AgentConfig, BuiltInToolsOutput, ConversationalConfig, PromptAgentApiModelOutput

order_tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())

agent = elevenlabs.conversational_ai.agents.create(
    name="Support line",
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            prompt=PromptAgentApiModelOutput(
                prompt="You are a support agent for Acme.",
                tool_ids=[order_tool.id],
                built_in_tools=BuiltInToolsOutput(
                    end_call=SystemTool.end_call().build_config(),
                    transfer_to_number=transfer.build_config(),
                ),
            )
        )
    ),
)
```

```typescript
const orderTool = await elevenlabs.conversationalAi.tools.create(getOrder.build());

const agent = await elevenlabs.conversationalAi.agents.create({
  name: "Support line",
  conversationConfig: {
    agent: {
      prompt: {
        prompt: "You are a support agent for Acme.",
        toolIds: [orderTool.id],
        builtInTools: {
          endCall: SystemTool.endCall().buildConfig(),
          transferToNumber: transfer.buildConfig(),
        },
      },
    },
  },
});
```

> **Warning**
>
> El campo `prompt.tools` del agente, que contiene configuraciones de herramientas integradas, está obsoleto. No se puede
> combinar con `tool_ids` y, cuando una solicitud lo incluye, las herramientas integradas del agente se reemplazan
> por las herramientas de sistema que contiene. En su lugar, crea herramientas con `tools.create()` y vincúlalas mediante ID.

## Editar una herramienta existente

`Tool.from_response()` / `Tool.fromResponse()` carga una herramienta devuelta por `tools.get()`. Se conservan los campos que el creador no modela y los valores predeterminados que completa la API, por lo que al volver a enviarla solo cambia lo que hayas modificado. `as_webhook()`, `as_client()` y `as_system()` (`asWebhook()` y equivalentes en JavaScript) te proporcionan la herramienta tipada para editarla, o `None` / `undefined` si es de otro tipo.

Para cambiar una propiedad del cuerpo, lee el esquema del cuerpo, vuelve a establecer la propiedad y establece el cuerpo:

```python
from elevenlabs.agent_tools import ObjectSchema

loaded = Tool.from_response(elevenlabs.conversational_ai.tools.get("tool_id")).as_webhook()
if loaded is None:
    raise ValueError("Not a webhook tool")

body = loaded.body_schema
assert isinstance(body, ObjectSchema)
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")))
loaded.query_param("locale", Schema.string().describe("The caller's language").optional())

elevenlabs.conversational_ai.tools.update("tool_id", request=loaded.build())
```

```typescript
import { type ObjectSchema, Schema, Tool } from "@elevenlabs/elevenlabs-js";

const loaded = Tool.fromResponse(
  await elevenlabs.conversationalAi.tools.get("tool_id")
).asWebhook();
if (!loaded) throw new Error("Not a webhook tool");

const body = loaded.bodySchema as ObjectSchema;
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")));
loaded.queryParam("locale", Schema.string().describe("The caller's language").optional());

await elevenlabs.conversationalAi.tools.update("tool_id", loaded.build());
```

## Almacenar herramientas en el control de versiones

`to_json_string()` / `toJSONString()` escribe la herramienta en el formato de transferencia de la API: claves en snake_case, ordenadas en todos los niveles y con sangría de 2 espacios. Tiene la misma estructura que conserva la [CLI](/docs/es/eleven-agents/operate/cli) en su directorio `tool_configs/`, y ambos SDK escriben archivos idénticos byte a byte para la misma herramienta, de modo que las diferencias se mantienen pequeñas. `Tool.from_json()` / `Tool.fromJSON()` lo vuelve a leer.

```python
from pathlib import Path

from elevenlabs.agent_tools import Tool

Path("tool_configs/get_order.json").write_text(get_order.to_json_string())

stored = Tool.from_json(Path("tool_configs/get_order.json").read_text())
elevenlabs.conversational_ai.tools.update("tool_id", request=stored.build())
```

```typescript
import { Tool } from "@elevenlabs/elevenlabs-js";
import { readFile, writeFile } from "node:fs/promises";

await writeFile("tool_configs/get_order.json", getOrder.toJSONString());

const stored = Tool.fromJSON(await readFile("tool_configs/get_order.json", "utf8"));
await elevenlabs.conversationalAi.tools.update("tool_id", stored.build());
```

Una configuración habitual es la misma que para los [workflows](/docs/es/eleven-agents/customization/agents-as-code/workflows#store-workflows-in-version-control): inicializa los archivos con `elevenlabs tools pull`, edítalos directamente o con el creador, ejecuta `Tool.from_json(file).build()` / `Tool.fromJSON(file).build()` en CI para cada pull request y envíalos con `tools.update()` o `elevenlabs tools push` al fusionar.

## Validación

Las llamadas encadenadas nunca fallan por sí solas. `build()`, `build_config()` / `buildConfig()`, `to_json()` / `toJSON()` y `to_json_string()` / `toJSONString()` comprueban toda la herramienta y generan o lanzan un único `ToolValidationError` cuya lista `issues` enumera cada problema, cada uno con un `code`, un `message` y la `path` de la parte a la que afecta, como `body.reason`.

```python
from elevenlabs.agent_tools import ToolValidationError

try:
    request = refund.build()
except ToolValidationError as err:
    for issue in err.issues:
        print(issue.code, issue.path, issue.message)
```

```typescript
import { ToolValidationError } from "@elevenlabs/elevenlabs-js";

try {
  const request = refund.build();
} catch (err) {
  if (err instanceof ToolValidationError) {
    for (const issue of err.issues) console.error(issue.code, issue.path, issue.message);
  } else {
    throw err;
  }
}
```

Los errores incluyen:

* Un marcador de URL sin parámetro de ruta, o un parámetro de ruta sin marcador. Las plantillas de variables de entorno, como `{{system__env_api_host}}`, no son marcadores.
* Un literal sin fuente de valor, o con más de una.
* Un cuerpo en un `GET`, o la ausencia de cuerpo en un `POST`, `PUT` o `PATCH`.
* El mismo nombre de parámetro en más de una de estas ubicaciones: ruta, consulta y cuerpo.
* `omit()` en una propiedad obligatoria, `choices()` en un esquema que no es una cadena o una constante que no coincide con el tipo del esquema.
* Una herramienta de transferencia sin destinos, un destino del tipo incorrecto o un destino de URI SIP sin transferencia SIP REFER.
* Una opción que no se aplica al tipo de herramienta o un tiempo de espera fuera de su intervalo.

## Tipos de herramientas más recientes que tu SDK

Una herramienta cargada desde la API o desde un archivo puede ser de un tipo que el creador no puede editar, como una herramienta MCP. Se carga con el tipo `"other"` y se conserva sin cambios al pasar por `from_json()` / `fromJSON()` y `to_json_string()` / `toJSONString()`, y `build()` la informa como advertencia mediante `on_warning` / `onWarning`.