> ## Documentation Index
> Fetch the complete documentation index at: https://developers.insuranceboosters.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Herramientas

> Crea, consulta, actualiza, prueba y elimina las herramientas de tus agentes de IA.

Las herramientas permiten que tus agentes consulten APIs, ejecuten código y controlen acciones de una conversación. Puedes administrar todos los tipos compatibles con `x-ib-api-key`.

> [!WARNING]
>
> Las respuestas de listar y consultar devuelven la configuración sin redactar.
> Pueden incluir tokens y headers de herramientas HTTP, además del código de
> herramientas `run_code`. Trátalas y almacénalas como secretos.

## Flujo recomendado

**1. Elige el tipo**

Revisa [Tipos de herramienta](https://developers.insuranceboosters.com/agentes/herramientas/tipos-de-herramienta.md) y sus requisitos de ejecución.

**2. Crea la herramienta**

Define su nombre, instrucciones, parámetros y configuración específica.

**3. Asigna la herramienta**

Usa el `id` de la respuesta para asignarla al agente correspondiente.

## Operaciones

> **[Tipos de herramienta](https://developers.insuranceboosters.com/agentes/herramientas/tipos-de-herramienta.md)**
>
> Configura HTTP, transferencia humana, fin de conversación, llamada, disponibilidad o código.

> **[Listar herramientas](https://developers.insuranceboosters.com/agentes/herramientas/listar-herramientas.md)**
>
> Consulta las herramientas configuradas.

> **[Crear herramienta](https://developers.insuranceboosters.com/agentes/herramientas/crear-herramienta.md)**
>
> Define una nueva herramienta de cualquier tipo compatible.

> **[Consultar herramienta](https://developers.insuranceboosters.com/agentes/herramientas/consultar-herramienta.md)**
>
> Obtén la configuración de una herramienta por ID.

> **[Actualizar herramienta](https://developers.insuranceboosters.com/agentes/herramientas/actualizar-herramienta.md)**
>
> Modifica campos comunes o la configuración de su tipo.

> **[Consultar uso](https://developers.insuranceboosters.com/agentes/herramientas/consultar-uso.md)**
>
> Obtén los agentes que tienen asignada una herramienta.

> **[Probar código](https://developers.insuranceboosters.com/agentes/herramientas/probar-codigo.md)**
>
> Ejecuta una configuración `run_code` sin crearla.

> **[Eliminar herramienta](https://developers.insuranceboosters.com/agentes/herramientas/eliminar-herramienta.md)**
>
> Elimina una herramienta que no esté asignada a un agente.

## Campos comunes

| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `name` | `string` | Sí | Nombre visible de la herramienta. |
| `apiName` | `string` | Sí | Nombre que usa el agente al llamar la herramienta. |
| `instructions` | `string` | Sí | Explica cuándo y para qué debe usarla. |
| `toolType` | `string` | Sí | Tipo de herramienta. |
| `inputs` | `array` | No | Parámetros que puede enviar el agente. |
| `details` | `object` | Según el tipo | Configuración específica. |

> [!WARNING]
>
> No uses `endTurn` como `apiName`. Es un nombre reservado que el agente usa
> para terminar su turno y esperar la siguiente entrada.

Consulta los campos y caveats de cada variante en [Tipos de herramienta](https://developers.insuranceboosters.com/agentes/herramientas/tipos-de-herramienta.md).

## Configuración HTTP

`details` acepta estos campos:

| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `endpoint` | `string` | Sí | URL que recibirá la solicitud. |
| `method` | `string` | Sí | `GET`, `POST`, `PUT`, `DELETE` o `PATCH`. |
| `authentication` | `object` | Sí | Usa `{"type":"no_auth"}` o autenticación bearer. |
| `headers` | `object` | No | Headers adicionales con valores de tipo string. |
| `queryParams` | `object` | No | Parámetros de consulta con valores de tipo string. |
| `body` | `object` | No | Body JSON para la solicitud. |

Para usar autenticación bearer:

```json theme={null}
{
  "type": "bearer",
  "token": "<token-secreto>"
}
```

> [!WARNING]
>
> `token` y los valores sensibles de `headers` se devuelven sin redactar al
> listar o consultar la herramienta. Usa credenciales de servicio con permisos
> mínimos y no registres esas respuestas.

La API acepta el valor de `endpoint` al guardar la herramienta y construye la
URL cuando el agente la ejecuta. La solicitud saliente no verifica el
certificado TLS. Usa únicamente destinos que controles y en los que confíes; no
uses direcciones internas ni dependas de esta herramienta para validar la
identidad del servidor.

## Parámetros y placeholders

Cada elemento de `inputs` define un dato que el agente puede proporcionar:

```json theme={null}
{
  "name": "clienteId",
  "type": "string",
  "description": "Identificador del cliente.",
  "required": true,
  "collectFromUser": false,
  "examples": ["cliente_123"]
}
```

Los tipos disponibles son `string`, `number`, `boolean`, `enum` y `object`. Si usas `enum`, incluye `options`. Un parámetro requerido no puede tener `default`.

Usa `{{nombreDelParametro}}` en `endpoint`, `headers`, `queryParams` o `body`:

```json theme={null}
{
  "endpoint": "https://api.ejemplo.com/clientes/{{clienteId}}",
  "method": "GET",
  "authentication": {
    "type": "no_auth"
  }
}
```

## Autenticación

Incluye tu API key en todas las solicitudes:

```http theme={null}
x-ib-api-key: <tu-api-key>
```

Consulta [Autenticación](https://developers.insuranceboosters.com/autenticacion.md) si todavía no tienes una clave.

## Formas de error

La forma de la respuesta depende del error:

| Caso | Forma |
| - | - |
| Validación al crear o actualizar | `{"error":[<issues>]}` |
| Validación al probar código | `{"error":{"formErrors":[],"fieldErrors":{}}}` |
| Operación no permitida | `{"success":false,"code":"<codigo>","message":"<mensaje>"}` con `403` |
| Herramienta inexistente | `{"error":"<mensaje>"}` con `404` |
| Servicio temporalmente no disponible | `{"success":false,"code":"<codigo>","message":"<mensaje>"}` con `503` |
| Eliminación bloqueada | `{"error":"<mensaje>","agents":[{"id":"<agentId>","name":"<nombre>"}]}` con `409` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.