API de Agentes

Ruta base: /builder/v1/agents. Autenticación con Authorization: Bearer <token>. Las operaciones actúan sobre los agentes del usuario autenticado. Atributos en camelCase, fechas ISO 8601 en UTC.

Objeto Agente

Campo	Tipo	Descripción
id	string (UUID)	Identificador.
name	string	Nombre.
description	string o null	Descripción.
type	single o multiple	Individual o equipo.
status	published, paused, needs_attention, permissions_required, archived	Estado.
requests	integer	Consultas acumuladas.
createdAt, updatedAt	string	Fechas.

Ejemplo

curl "https://api.<tu-dominio>/builder/v1/agents?perPage=2&sort=updatedAt" \
  -H "Authorization: Bearer <token>"

{
  "data": [
    {
      "id": "73d2a8dd-51bf-42bc-bc6e-3ff7cd0d03f9",
      "name": "Asistente de políticas",
      "description": "Responde preguntas sobre el reglamento interno",
      "type": "single",
      "status": "published",
      "requests": 12,
      "scope": "global",
      "workflowId": null,
      "createdAt": "2026-08-20T15:02:11Z",
      "updatedAt": "2026-08-25T09:41:03Z"
    }
  ],
  "meta": { "page": 1, "perPage": 2, "total": 7, "totalPages": 4 }
}

scope indica si el agente es reutilizable (global) o privado de un workflow (workflow, con workflowId). Los agentes privados de un flujo no aparecen en la lista de Agentes de IA.

Operaciones

GET /builder/v1/agents

Parámetro	Por defecto	Descripción
page	1	Página.
perPage	20	Elementos por página, máximo 100.
search		Búsqueda por nombre, sin distinguir mayúsculas.
status		Filtro por estado; admite lista separada por comas.
type		Filtro por tipo; admite lista.
sort	updatedAt	name, createdAt, updatedAt, requests.
order	desc	asc o desc.

POST /builder/v1/agents

Crea un agente con valores por defecto (name "Nuevo agente", type single, status published). Sin cuerpo. Admite la cabecera Idempotency-Key (UUID): si se repite dentro de 24 horas devuelve la creación anterior en lugar de crear otro agente.

GET /builder/v1/agents/{id}, PATCH /builder/v1/agents/{id}, DELETE /builder/v1/agents/{id}

Leer, modificar y eliminar. DELETE es lógico: el agente deja de listarse y sus ejecuciones se conservan.

GET /builder/v1/models

Modelos disponibles para configurar agentes.

Errores

HTTP	code	Cuándo
400	invalid_query	Parámetros inválidos.
401	unauthorized	Sin token o token inválido.
404	agent_not_found	No existe, no es tuyo o fue eliminado. No se distingue entre los tres casos.

{ "error": { "code": "agent_not_found", "message": "Agent not found" } }

El OpenAPI completo, con el detalle de configuración (instrucciones, herramientas, fuentes), se sirve desde tu instalación en /builder/v1/openapi.json.