> ## 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.
# Ejecutar agente
> Envía un mensaje a un agente de IA y recibe su respuesta.
Invoca un agente de IA con un mensaje y obtiene su respuesta. Si el agente decide transferir a un humano, la respuesta incluye un objeto `handoff`.
## Endpoint
```text theme={null}
POST /agents/{agentId}/execute
```
## Parámetro de ruta
| Parámetro | Descripción |
| --------- | ---------------------------------------------------------------- |
| `agentId` | Identificador del agente. Solicítalo con tu ejecutivo de cuenta. |
## Body
| Campo | Tipo | Requerido | Descripción |
| --------- | ------- | --------- | ------------------------------------------------- |
| `history` | `array` | Sí | Lista con **exactamente un** mensaje del usuario. |
### Elemento de `history`
| Campo | Tipo | Requerido | Descripción |
| --------- | -------- | --------- | ------------------ |
| `role` | `string` | Sí | Debe ser `user`. |
| `content` | `string` | Sí | Texto del mensaje. |
Envía un solo mensaje por solicitud. No uses historial de varios turnos ni roles distintos de `user`.
## Ejemplo de solicitud
```bash theme={null}
curl -X POST "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute" \
-H "Content-Type: application/json" \
-H "x-ib-api-key: TU_API_KEY" \
-d '{
"history": [
{
"role": "user",
"content": ""
}
]
}'
```
## Respuesta
Usa solo estos campos:
| Campo | Tipo | Descripción |
| ---------- | -------- | ------------------------------------------------------------- |
| `response` | `string` | Respuesta textual del agente. |
| `handoff` | `object` | Presente solo cuando el agente transfiere a un agente humano. |
La respuesta puede incluir campos adicionales. Ignóralos e integra únicamente `response` y, si existe, `handoff`.
La ejecución puede tardar varios segundos. Configura un timeout generoso en tu cliente HTTP.
### `handoff`
| Campo | Tipo | Descripción |
| ------------------------ | -------- | ---------------------------------------------- |
| `handoffId` | `string` | Identificador único del handoff. |
| `department.id` | `string` | Identificador del departamento destino. |
| `department.name` | `string` | Nombre del departamento destino. |
| `message` | `string` | Mensaje de notificación del handoff. |
| `summary` | `string` | Resumen del contexto transferido. |
| `metadata.handoffReason` | `string` | Motivo del handoff. |
| `metadata.agentId` | `string` | Identificador del agente de IA (si aplica). |
| `metadata.agentName` | `string` | Nombre del agente de IA (si aplica). |
| `metadata.handoffTime` | `number` | Timestamp del handoff en milisegundos (epoch). |
### Ejemplo sin handoff
```json theme={null}
{
"response": "¡Hola! ¿En qué puedo ayudarte?"
}
```
### Ejemplo con handoff
```json theme={null}
{
"response": "Te conecto con un asesor que puede ayudarte mejor.",
"handoff": {
"handoffId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"department": {
"id": "dept_atencion",
"name": "Atención a clientes"
},
"message": "Voy a transferirte con un asesor para que pueda apoyarte.",
"summary": "El usuario solicita ser transferido con un asesor humano.",
"metadata": {
"handoffReason": "El usuario pidió hablar con un asesor humano.",
"agentId": "",
"agentName": "Asistente de Acme Seguros",
"handoffTime": 1710000000000
}
}
}
```
## Errores frecuentes
Los errores de autenticación usan `message`. Los de validación o recurso usan `error`.
| HTTP | Qué significa | Qué hacer |
| ----- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `400` | Falta `history` o el body no cumple el esquema; o el agente no está activo. | Envía `history` con un mensaje `user` y confirma con tu ejecutivo que el agente esté habilitado. |
| `401` | API key inválida o faltante. | Verifica `x-ib-api-key`. |
| `404` | El agente no existe o no pertenece a tu cuenta. | Confirma el `agentId` con tu ejecutivo de cuenta. |
| `500` | Error inesperado. | Reintenta; si continúa, contacta soporte. |
### Ejemplos de error
```json theme={null}
{ "message": "Invalid API key." }
```
```json theme={null}
{ "error": "Agent with ID not found." }
```
## OpenAPI
````yaml openapi/agentes-v1.yaml POST /agents/{agentId}/execute
openapi: 3.1.0
info:
title: Insurance Boosters API — Agentes IA
version: 1.0.0
description: >-
API pública para invocar un agente de IA configurado en tu cuenta y obtener
su respuesta.
license:
name: Propietaria
url: https://insuranceboosters.com
servers:
- url: https://api.insuranceboosters.com/api/v1
description: Producción
security:
- IbApiKey: []
tags:
- name: Agentes IA
description: Invocación de agentes de IA.
paths:
/agents/{agentId}/execute:
post:
tags:
- Agentes IA
summary: Ejecutar agente
description: >
Envía un mensaje a un agente de IA y recibe su respuesta. Cada solicitud
es independiente: envía un solo mensaje por request.
operationId: executeAgent
parameters:
- $ref: '#/components/parameters/AgentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteAgentRequest'
example:
history:
- role: user
content: ''
responses:
'200':
description: Respuesta del agente. Usa solo `response` y, si existe, `handoff`.
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteAgentResponse'
examples:
respuestaSimple:
summary: Respuesta sin handoff
value:
response: ¡Hola! ¿En qué puedo ayudarte?
conHandoff:
summary: Respuesta con handoff a un agente humano
value:
response: Te conecto con un asesor que puede ayudarte mejor.
handoff:
handoffId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
department:
id: dept_atencion
name: Atención a clientes
message: >-
Voy a transferirte con un asesor para que pueda
apoyarte.
summary: >-
El usuario solicita ser transferido con un asesor
humano.
metadata:
handoffReason: El usuario pidió hablar con un asesor humano.
agentId: ''
agentName: Asistente de Acme Seguros
handoffTime: 1710000000000
'400':
description: Body inválido o el agente no está activo.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
agenteInactivo:
value:
error: Agent is not active.
historyRequerido:
summary: Falta history
value:
error: Required
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: El agente no existe o no pertenece a tu cuenta.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Agent with ID not found.
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
AgentId:
name: agentId
in: path
required: true
description: Identificador del agente. Solicítalo con tu ejecutivo de cuenta.
schema:
type: string
schemas:
ExecuteAgentRequest:
type: object
required:
- history
additionalProperties: false
properties:
history:
type: array
description: >
Lista con exactamente un mensaje del usuario. Cada solicitud es
independiente; no envíes historial de varios turnos.
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/AgentMessage'
ExecuteAgentResponse:
type: object
required:
- response
additionalProperties: true
properties:
response:
type: string
description: Respuesta textual del agente para el usuario final.
handoff:
$ref: '#/components/schemas/Handoff'
description: >
Presente solo cuando el agente decide transferir la conversación a
un agente humano.
Error:
type: object
properties:
error:
description: Detalle del error de validación o de negocio.
oneOf:
- type: string
- type: array
items:
type: object
additionalProperties: true
message:
type: string
description: Mensaje de error de autenticación.
AgentMessage:
type: object
required:
- role
- content
additionalProperties: false
properties:
role:
type: string
const: user
description: Rol del mensaje. En esta API solo se admite `user`.
content:
type: string
minLength: 1
description: Texto del mensaje que recibe el agente.
Handoff:
type: object
required:
- handoffId
- department
- message
- summary
- metadata
properties:
handoffId:
type: string
description: Identificador único del evento de handoff.
department:
type: object
required:
- id
- name
properties:
id:
type: string
description: Identificador del departamento destino.
name:
type: string
description: Nombre del departamento destino.
message:
type: string
description: Mensaje de notificación asociado al handoff.
summary:
type: string
description: Resumen de la solicitud o contexto transferido.
metadata:
type: object
required:
- handoffReason
- handoffTime
properties:
handoffReason:
type: string
description: Motivo por el que el agente inició el handoff.
agentId:
type: string
description: Identificador del agente de IA que inició el handoff.
agentName:
type: string
description: Nombre del agente de IA que inició el handoff.
handoffTime:
type: number
description: Marca de tiempo del handoff en milisegundos (epoch).
responses:
Unauthorized:
description: API key inválida o faltante.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidApiKey:
value:
message: Invalid API key.
missingAuth:
value:
message: Invalid authorization format.
InternalError:
description: Error inesperado.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Internal server error.
securitySchemes:
IbApiKey:
type: apiKey
in: header
name: x-ib-api-key
````