API e MCP do Agnose

Autenticação

Crie uma chave pessoal na sua conta e envie em cada chamada como Authorization: Bearer <chave>. Cada chave tem permissões (scopes) e pode ser revogada quando quiser.

Criar uma chave

Endpoints

Fluxo típico

Envie uma mensagem (responde 202 com o id da execução) e consulte a execução até o status ser done ou failed. Ou assine um webhook e nós 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": "…"}

Especificação OpenAPI 3.1

Servidor MCP

O Agnose fala MCP por HTTP (streamable HTTP). Ferramentas: list_agents, send_message e get_run. Para limitar a uma instância use /api/mcp/<id da instância>.

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

Webhooks

Enviamos um POST assinado quando uma execução termina (run.completed), falha (run.failed) ou você cancela uma instância (instance.cancelled). Se o seu servidor não responder 2xx, tentamos de novo com espera crescente, até 8 vezes.

Verificar a assinatura

O cabeçalho agnose-signature traz t=<segundos unix>,v1=<HMAC-SHA256 hex de "t.corpo"> com o seu segredo. Rejeite assinaturas com mais 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));
}

Limites

60 chamadas por minuto por chave e 120 por IP. Acima disso respondemos 429 com Retry-After. Os limites diários de mensagens de cada plano também valem.

Erros

Os erros vêm como {"error": {"code", "message"}}: unauthorized (401), forbidden (403), not_found (404), invalid (400), plan_limit e rate_limited (429).