Agnose API और MCP

प्रमाणीकरण

अपने खाते में एक निजी कुंजी बनाएँ और हर कॉल में Authorization: Bearer <कुंजी> के रूप में भेजें। हर कुंजी के अधिकार (scopes) होते हैं और उसे कभी भी रद्द किया जा सकता है।

कुंजी बनाएँ

एंडपॉइंट

आम तरीका

संदेश भेजें (202 और रन id लौटता है) और रन की स्थिति done या failed होने तक पूछते रहें। या webhook जोड़ें, हम आपको बता देंगे।

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": "…"}

OpenAPI 3.1 विनिर्देश

MCP सर्वर

Agnose HTTP (streamable HTTP) पर MCP चलाता है। टूल: list_agents, send_message और get_run। एक ही इंस्टेंस तक सीमित करने के लिए /api/mcp/<इंस्टेंस id> इस्तेमाल करें।

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

Webhooks

जब कोई रन पूरा होता है (run.completed), विफल होता है (run.failed) या आप इंस्टेंस रद्द करते हैं (instance.cancelled), हम एक हस्ताक्षरित POST भेजते हैं। अगर आपका सर्वर 2xx नहीं लौटाता, तो हम बढ़ते अंतराल पर 8 बार तक दोबारा कोशिश करते हैं।

हस्ताक्षर जाँचें

agnose-signature हेडर में t=<unix सेकंड>,v1=<आपकी secret से "t.body" का hex HMAC-SHA256> होता है। 5 मिनट से पुराने हस्ताक्षर अस्वीकार करें।

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));
}

सीमाएँ

हर कुंजी पर प्रति मिनट 60 कॉल और हर IP पर 120। इससे ज़्यादा पर हम Retry-After के साथ 429 लौटाते हैं। हर प्लान की दैनिक संदेश सीमा भी लागू होती है।

त्रुटियाँ

त्रुटियाँ {"error": {"code", "message"}} के रूप में आती हैं: unauthorized (401), forbidden (403), not_found (404), invalid (400), plan_limit और rate_limited (429)।