API y MCP de Agnose

Autenticación

Crea una clave personal en tu cuenta y envíala en cada llamada como Authorization: Bearer <clave>. Cada clave tiene permisos (scopes) y se puede revocar cuando quieras.

Crear una clave

Endpoints

Flujo típico

Envía un mensaje (responde 202 con el id de la ejecución) y consulta la ejecución hasta que su estado sea done o failed. O suscribe un webhook y te avisamos.

curl -X POST https://agneos.com/api/v1/instances/$INSTANCE/messages \
  -H "Authorization: Bearer $AGNOSE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"text": "Hola"}'
# 202 {"id": "run_…", "status": "queued", …}

curl https://agneos.com/api/v1/instances/$INSTANCE/runs/$RUN \
  -H "Authorization: Bearer $AGNOSE_API_KEY"
# 200 {"status": "done", "reply": "…"}

Especificación OpenAPI 3.1

Servidor MCP

Agnose habla MCP por HTTP (streamable HTTP). Herramientas: list_agents, send_message y get_run. Para limitarlo a una sola instancia usa /api/mcp/<id de instancia>.

{
  "mcpServers": {
    "agnose": {
      "type": "http",
      "url": "https://agneos.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${AGNOSE_API_KEY}"
      }
    }
  }
}

Webhooks

Te enviamos un POST firmado cuando una ejecución termina (run.completed), falla (run.failed) o cancelas una instancia (instance.cancelled). Si tu servidor no responde 2xx, reintentamos con espera creciente hasta 8 veces.

Verificar la firma

La cabecera agnose-signature trae t=<segundos unix>,v1=<HMAC-SHA256 hex de "t.cuerpo"> con tu secreto. Rechaza firmas de más de 5 minutos.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, body, header) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const want = createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return v1.length === want.length && timingSafeEqual(Buffer.from(v1), Buffer.from(want));
}

Límites

60 llamadas por minuto por clave y 120 por IP. Al pasarte respondemos 429 con Retry-After. Los límites diarios de mensajes de cada plan también aplican.

Errores

Los errores vienen como {"error": {"code", "message"}}: unauthorized (401), forbidden (403), not_found (404), invalid (400), plan_limit y rate_limited (429).