›/docs · quickstart

quickstart.

Conecta cualquier sistema agéntico al suite con un POST. Un dev externo razonablemente competente lo hace en menos de 15 minutos desde cero.

CA-07 · es nuestra frontera dura. Si no llegas, queremos saberlo.

Genera un token

Entra en /panel. Pulsa nuevo token, ponle un nombre describiendo dónde vivirá (ej. producción-ci). Cópialo: solo se muestra una vez. Tiene este aspecto:

// token opaco — guárdalo donde guardes tu DB_URL
"sk-oag-a1b2c3d4e5f6789012345678abcdef00"

Prompt de integración

Pega este prompt en el sistema de instrucciones de cualquier agente IA o en tu propio orquestador, y tendrá todo el contexto necesario para conectarse a la oficina sin configuración adicional.

Introduce el token del workspace al que debe conectarse el agente. Sin él el prompt está incompleto y el agente no podrá autenticarse. Puedes obtener uno en /panel.

requerido

valida tu token para ver y copiar el prompt

El prompt incluye endpoint, autenticación, los 4 estados, reglas de heartbeat y códigos de respuesta. Añade encima el rol y contexto específico de tu agente.

Manda el primer POST

Cualquier proceso de tu sistema agéntico puede emitir. El payload mínimo son tres campos: id_agente, nombre, estado. Mismo endpoint sirve transiciones efectivas y heartbeats.

# HTTP plano — vía recomendada de integración.
curl -X POST https://oficina.agenthical.ai/v1/eventos \
  -H "Authorization: Bearer $OA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id_agente":         "po-churreria",
    "nombre":            "Product Owner",
    "estado":            "activo",
    "arnes":             "miarnés",
    "proyecto":          "mi-proyecto",
    "tarea_titulo":      "redactando HU",
    "tarea_descripcion": "Detalle libre ≤50 palabras"
  }'

Si todo va bien, recibes un 202 Accepted. El avatar aparece en pantalla del observador en menos de 2 segundos.

Los cuatro estados

Es lo único que tienes que entender. Cada estado mapea a un color obligatorio y un avatar visualmente distinto:

activo

está trabajando

inactivo

ocioso, en standby

error

se rompió

esperando_humano

te espera a ti

Heartbeats

Si tu agente está en el mismo estado durante mucho tiempo, mándale un POST cada 5–10 min. Si además el contexto cambió (nueva tarea, nuevo proyecto), incluye los campos actualizados: la tarjeta se refresca en ~2 s sin animar una transición de estado.

# heartbeat con contexto actualizado — no engorda log de transiciones
curl -X POST https://oficina.agenthical.ai/v1/eventos \
  -H "Authorization: Bearer $OA_TOKEN" \
  -d '{
    "id_agente":    "po-miproyecto",
    "nombre":       "Product Owner",
    "estado":       "activo",
    "tarea_titulo": "revisando PR #42"
  }'

threshold de desconexión

Si dejas de emitir más de 1 hora sin avisar, el suite marca el agente como desconectado. El avatar pasa a semitransparente manteniendo el último color conocido. Heartbeat cada 5 min es holgado y seguro.

Campos de contexto

Cuatro campos opcionales enriquecen la tarjeta del agente y el modal de detalle. Son compatibles hacia atrás: un cliente que no los envía sigue funcionando igual que en v1.0.0.

campo	tipo	soft limit	hard cap	visible en
arnes	string	—	64 chars → 400	tarjeta · modal
proyecto	string	—	64 chars → 400	tarjeta · modal
tarea_titulo	string	50 chars (truncado silencioso)	200 chars → 400	tarjeta · modal
tarea_descripcion	string	50 palabras (truncado silencioso)	2 000 chars → 400	modal (solo)

truncado silencioso

Si superas el soft limit pero no el hard cap, el servidor acepta el POST, persiste el texto truncado y devuelve 202 normal. Solo el hard cap devuelve 400. No construyas lógica de reintentos basada en el truncado — simplemente respeta los soft limits por diseño.

El campo arnes acepta ^[a-zA-Z0-9_ .-]+$. Cuando no hay un proyecto concreto usa el valor literal "Trabajo genérico" en proyecto: la oficina lo muestra con badge especial diferenciado.

WebSocket /v1/stream

La oficina se suscribe al stream en tiempo real. Puedes conectarte tú también para leer el estado de tu workspace desde cualquier cliente.

# Conecta con el nombre del workspace (sin token)
wss://oficina.agenthical.ai/v1/stream?workspace=<nombre>

El primer mensaje es siempre estado_inicial con la lista de todos los agentes del workspace. A partir de ahí llegan transicion, actualizacion_contexto, desconexion y reconexion según ocurren.

// transición de estado — incluye todos los campos de contexto
{
  "tipo": "transicion",
  "id_agente": "po-churreria",
  "estado_nuevo": "activo",
  "arnes": "churrerIA",
  "tarea_titulo": "redactando HU",
  "last_seen_at": "2026-05-30T03:35:00Z"
}

// heartbeat con contexto nuevo — sin cambio de estado
{
  "tipo": "actualizacion_contexto",
  "id_agente": "po-churreria",
  "tarea_titulo": "revisando PR #42",
  "last_seen_at": "2026-05-30T03:40:00Z"
}