Docs · build an agent

Build your own AI ops agent. Scoped, safe, accountable.

24observe is built to be driven by your AI agent, not just ours. Mint a least-privilege token, point your agent at the tool definitions, and it can run an observe → reason → act loop over your telemetry, incidents, detections, and topology — with hard guardrails, daily caps, and a full audit trail.

1. Mint a least-privilege token

Grant only the scopes the agent needs — and cap how much it can change per day. From the dashboard (Settings → API tokens) or the API:

curl -X POST https://api.24observe.com/api/v1/me/tokens \
  -H 'Authorization: Bearer obs_<your-admin-token>' \
  -H 'content-type: application/json' \
  -d '{
    "name": "incident-responder-agent",
    "scopes": ["incidents:read", "incidents:write", "context:read"],
    "dailyMutationLimit": 200
  }'
# → { "token": "obs_…", ... }   (shown once)

Pick scopes for the job (combine a read scope to reason with a narrow write scope to act):

Agent	Scopes
Incident responder	`incidents:read incidents:write context:read`
Detection engineer	`siem:read siem:write`
AI-agent cost/security watchdog	`ai-agents:read`
Monitor provisioner	`monitors:read monitors:write`
On-call / maintenance ops	`on-call:write escalations:write maintenance:write`

2. Wire it up — no integration code

Use the MCP server with any MCP client, or hand the pre-converted tool definitions straight to your framework:

# Point any agent framework at the pre-converted tool definitions:
#   OpenAI:     https://api.24observe.com/openapi/openai-tools.json
#   Anthropic:  https://api.24observe.com/openapi/anthropic-tools.json
#   LangChain:  https://api.24observe.com/openapi/langchain-tools.json
# Every tool call becomes an HTTP request with:
#   Authorization: Bearer obs_<agent-token>

3. The loop — observe → reason → act

# Event-driven: subscribe to incident.opened (no polling), then the loop:
# 1. OBSERVE   GET  /api/v1/incidents/{id}                 # the incident
#              GET  /api/v1/incidents/{id}/analysis        # the AI-Analyst verdict
#              GET  /api/v1/context/incident/{id}/blast     # impacted services + owners
# 2. REASON    your model decides from the evidence (every edge is deep-linked)
# 3. ACT       POST /api/v1/incidents/{id}/updates          # post what you found
#              POST /api/v1/incidents/{id}/acknowledge|resolve
#              POST /api/v1/maintenance-windows              # mute alerts during a fix

The same shape works for any agent: a detection engineer reads the catalog and POSTs new rules; a monitor provisioner creates + tunes monitors; a cost watchdog reads /ai-agents/overview and opens a case when spend spikes. Reasoning is grounded — every context-graph edge carries evidence that deep-links back into the product, so the agent cites, it doesn't guess.

Safety rails (on by design)

Authorization: Bearer obs_<agent-token>   # scoped — only what you granted
Idempotency-Key: <uuid>                  # safe to retry; a dup is a no-op
X-Agent-Id: incident-responder           # who acted  (lands in the audit log)
X-Conversation-Id: conv-8f21             # which run  (lands in the audit log)

Scoped token — the agent can only reach what you granted; org-locked server-side.
Daily mutation cap — dailyMutationLimit on the token; a runaway agent gets 429, not a mess.
Idempotent writes — send an Idempotency-Key; retries can't double-act.
Full attribution — every change records the token + X-Agent-Id + X-Conversation-Id in the audit log, readable via audit:read.

What an agent can never do

Even with a write token, the agent cannot disable or rewrite a detection (no switching off the SIEM), delete anything, read secrets (monitor credentials, webhook URLs), or touch billing / settings / data export — those require a full token or a human session. You can hand an agent real power without handing it the keys.

See also API for Agents and Connect an AI agent (instrument your own agent's telemetry).