Agentes IA
Ejecutar agente
Envía un mensaje a un agente de IA y recibe su respuesta.
POST
/
agents
/
{agentId}
/
execute
Ejecutar agente
curl --request POST \
--url https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute \
--header 'Content-Type: application/json' \
--header 'x-ib-api-key: <api-key>' \
--data '
{
"history": [
{
"role": "user",
"content": ""
}
]
}
'import requests
url = "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute"
payload = { "history": [
{
"role": "user",
"content": ""
}
] }
headers = {
"x-ib-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-ib-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({history: [{role: 'user', content: ''}]})
};
fetch('https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'POST',
headers: {'x-ib-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({history: [{role: 'user', content: ''}]})
};
fetch('https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute';
const options = {
method: 'POST',
headers: {'x-ib-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({history: [{role: 'user', content: ''}]})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute")
.header("x-ib-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-ib-api-key", "<api-key>");
request.AddJsonBody("{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
using RestSharp;
var options = new RestClientOptions("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-ib-api-key", "<api-key>");
request.AddJsonBody("{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute"
payload := strings.NewReader("{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-ib-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-ib-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'history' => [
[
'role' => 'user',
'content' => ''
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-ib-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}val client = OkHttpClient()
val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}")
val request = Request.Builder()
.url("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute")
.post(body)
.addHeader("x-ib-api-key", "<api-key>")
.addHeader("Content-Type", "application/json")
.build()
val response = client.newCall(request).execute()falseimport Foundation
let parameters = ["history": [
[
"role": "user",
"content": ""
]
]] as [String : Any?]
let postData = try JSONSerialization.data(withJSONObject: parameters, options: [])
let url = URL(string: "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
"x-ib-api-key": "<api-key>",
"Content-Type": "application/json"
]
request.httpBody = postData
let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))$headers=@{}
$headers.Add("x-ib-api-key", "<api-key>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
"history": [
{
"role": "user",
"content": ""
}
]
}'{
"response": "¡Hola! ¿En qué puedo ayudarte?"
}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
Elemento de
handoff.
Endpoint
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
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": "<mensaje>"
}
]
}'
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
{
"response": "¡Hola! ¿En qué puedo ayudarte?"
}
Ejemplo con handoff
{
"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": "<agentId>",
"agentName": "Asistente de Acme Seguros",
"handoffTime": 1710000000000
}
}
}
Errores frecuentes
Los errores de autenticación usanmessage. 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
{ "message": "Invalid API key." }
{ "error": "Agent with ID <agentId> not found." }
Authorizations
Path Parameters
Identificador del agente. Solicítalo con tu ejecutivo de cuenta.
Body
application/json
Lista con exactamente un mensaje del usuario. Cada solicitud es independiente; no envíes historial de varios turnos.
Required array length:
1 elementShow child attributes
Show child attributes
Was this page helpful?
Ejecutar agente
curl --request POST \
--url https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute \
--header 'Content-Type: application/json' \
--header 'x-ib-api-key: <api-key>' \
--data '
{
"history": [
{
"role": "user",
"content": ""
}
]
}
'import requests
url = "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute"
payload = { "history": [
{
"role": "user",
"content": ""
}
] }
headers = {
"x-ib-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-ib-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({history: [{role: 'user', content: ''}]})
};
fetch('https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const options = {
method: 'POST',
headers: {'x-ib-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({history: [{role: 'user', content: ''}]})
};
fetch('https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));const url = 'https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute';
const options = {
method: 'POST',
headers: {'x-ib-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({history: [{role: 'user', content: ''}]})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute")
.header("x-ib-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-ib-api-key", "<api-key>");
request.AddJsonBody("{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
using RestSharp;
var options = new RestClientOptions("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-ib-api-key", "<api-key>");
request.AddJsonBody("{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute"
payload := strings.NewReader("{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-ib-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}require 'uri'
require 'net/http'
url = URI("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-ib-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'history' => [
[
'role' => 'user',
'content' => ''
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-ib-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}val client = OkHttpClient()
val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n \"history\": [\n {\n \"role\": \"user\",\n \"content\": \"\"\n }\n ]\n}")
val request = Request.Builder()
.url("https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute")
.post(body)
.addHeader("x-ib-api-key", "<api-key>")
.addHeader("Content-Type", "application/json")
.build()
val response = client.newCall(request).execute()falseimport Foundation
let parameters = ["history": [
[
"role": "user",
"content": ""
]
]] as [String : Any?]
let postData = try JSONSerialization.data(withJSONObject: parameters, options: [])
let url = URL(string: "https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.timeoutInterval = 10
request.allHTTPHeaderFields = [
"x-ib-api-key": "<api-key>",
"Content-Type": "application/json"
]
request.httpBody = postData
let (data, _) = try await URLSession.shared.data(for: request)
print(String(decoding: data, as: UTF8.self))$headers=@{}
$headers.Add("x-ib-api-key", "<api-key>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.insuranceboosters.com/api/v1/agents/{agentId}/execute' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
"history": [
{
"role": "user",
"content": ""
}
]
}'{
"response": "¡Hola! ¿En qué puedo ayudarte?"
}
