MindGraphDocs

Agents

Autonomous research agents that read, reason about, and write to your knowledge graph on a schedule or on demand. Each agent is a managed session with its own instructions, model, and credit budget — and every node or edge it creates is stamped with its agent_id so you always know who said what.

Agents are managed from the dashboard — create, pause, and schedule them without writing code. This page documents the HTTP surface powering that experience so you can build custom integrations or in-app agent UIs against the same endpoints.

Note:Agent management endpoints (/v1/agents/*) are intentionally not exposed in the TypeScript or Python SDKs. They are dashboard-first; the HTTP surface is stable and documented below.

Concepts

Three resource types power the Agents feature:

  • Agent — a persistent configuration: template, model, custom instructions, daily credit budget, pause state.
  • Session — a single conversation with an agent. Messages and tool calls stream as Server-Sent Events.
  • Schedule — a cron expression + message template that spawns sessions automatically (e.g. daily briefings, nightly sweeps).

Agents use the Anthropic Managed Agents runtime with web_search, web_fetch, and MindGraph-native tools for reading and writing the graph. Everything an agent produces is queryable through the normal graph API, scoped by agent_id.

Plan Requirements

Managed agents require a Pro or higher plan. Requests from Free-tier orgs return 403 Forbidden.

Agents

POST/v1/agentsCreate an agent
GET/v1/agentsList agents in the current org
GET/v1/agents/{id}Get one agent
PATCH/v1/agents/{id}Update name, instructions, model, budget, or pause state
POST/v1/agents/{id}/archiveSoft-delete an agent and its sessions
GET/v1/agents/templatesList available agent templates

Create an agent

curl -X POST https://api.mindgraph.cloud/v1/agents \
  -H "Authorization: Bearer mg_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Market Briefing",
    "template_type": "researcher",
    "custom_instructions": "Focus on AI infrastructure companies; flag material changes.",
    "model": "claude-opus-4-7",
    "daily_credit_budget": 500
  }'

Sessions

POST/v1/agents/sessionsCreate a new session for an agent
GET/v1/agents/sessionsList sessions (filter by agent_id)
GET/v1/agents/sessions/{sid}Get one session
POST/v1/agents/sessions/{sid}/messageSend a user message to the session
POST/v1/agents/sessions/{sid}/interruptCancel any in-flight inference
POST/v1/agents/sessions/{sid}/archiveArchive a session
GET/v1/agents/sessions/{sid}/eventsPaginated event history for a session
GET/v1/agents/sessions/{sid}/streamSubscribe to live events (Server-Sent Events)
GET/v1/agents/sessions/{sid}/pending-inputIf the agent is waiting on a user question, return it
POST/v1/agents/sessions/{sid}/respondAnswer a pending input request

Conversation flow

  1. Create a session via POST /v1/agents/sessions. Optionally include an initial message.
  2. Subscribe to the SSE stream at /v1/agents/sessions/{sid}/stream to receive assistant tokens, tool calls, tool results, and completion events.
  3. Send follow-up messages with POST .../message. The server queues them via the agent runtime; new events arrive on the same stream.
  4. If the agent calls its request_input tool, a pending input is exposed at .../pending-input; answer via POST .../respond.

Schedules

POST/v1/agents/schedulesSchedule an agent with a cron expression and message template
GET/v1/agents/schedulesList schedules (filter by agent_id)
PATCH/v1/agents/schedules/{id}Update cron, template, budget, or enabled state
DELETE/v1/agents/schedules/{id}Delete a schedule

The scheduler checks for due schedules every 60 seconds and spawns a new session with the interpolated message template. Use this for daily briefings, nightly knowledge sweeps, or weekly synthesis runs.

curl -X POST https://api.mindgraph.cloud/v1/agents/schedules \
  -H "Authorization: Bearer mg_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_...",
    "cron_expression": "0 9 * * 1-5",
    "message_template": "Summarize changes in the AI infra space since yesterday.",
    "daily_credit_budget": 200
  }'

Activity & work

GET/v1/agents/activityGlobal event feed for the org (all agents, all sessions)
GET/v1/agents/activity/wsActivity WebSocket for real-time dashboards
GET/v1/agents/{id}/workActive sessions, pending decisions, upcoming schedules
GET/v1/agents/{id}/articlesWiki articles authored by this agent
POST/v1/agents/{id}/resolve-decisionApprove or reject a decision the agent has raised

Querying agent output

Once an agent has written to the graph, its output is indistinguishable from any other node — except for the agent_id stamped on every version record. Fetch an agent's contributions through the normal graph API:

curl https://api.mindgraph.cloud/agent/agt_.../nodes \
  -H "Authorization: Bearer mg_..."

Cognitive agent layer vs. Managed agents

MindGraph has two distinct concepts that both use the word "agent":

  • Managed Agents — the autonomous research agents documented on this page. Managed under /v1/agents/*. Cloud-only.
  • Cognitive Agent layer — graph primitives for planning, governance, and execution. Used by any agent (managed or your own) to record tasks, request approvals, and track runs. See Cognitive Endpoints for /agent/plan, /agent/governance, and /agent/execution.