Herramientas - Insurance Boosters API

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.

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

Elige el tipo

Revisa Tipos de herramienta y sus requisitos de ejecución.

Crea la herramienta

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

Asigna la herramienta

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

Operaciones

Tipos de herramienta

Configura HTTP, transferencia humana, fin de conversación, llamada, disponibilidad o código.

Listar herramientas

Consulta las herramientas configuradas.

Crear herramienta

Define una nueva herramienta de cualquier tipo compatible.

Consultar herramienta

Obtén la configuración de una herramienta por ID.

Actualizar herramienta

Modifica campos comunes o la configuración de su tipo.

Consultar uso

Obtén los agentes que tienen asignada una herramienta.

Probar código

Ejecuta una configuración run_code sin crearla.

Eliminar herramienta

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.

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.

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:

{
  "type": "bearer",
  "token": "<token-secreto>"
}

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:

{
  "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:

{
  "endpoint": "https://api.ejemplo.com/clientes/{{clienteId}}",
  "method": "GET",
  "authentication": {
    "type": "no_auth"
  }
}

Autenticación

Incluye tu API key en todas las solicitudes:

x-ib-api-key: <tu-api-key>

Consulta Autenticación 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`

​Flujo recomendado

​Operaciones

Tipos de herramienta

Listar herramientas

Crear herramienta

Consultar herramienta

Actualizar herramienta

Consultar uso

Probar código

Eliminar herramienta

​Campos comunes

​Configuración HTTP

​Parámetros y placeholders

​Autenticación

​Formas de error

Flujo recomendado

Operaciones

Campos comunes

Configuración HTTP

Parámetros y placeholders

Autenticación

Formas de error