Agent Interfaces & API

AGENTOS DOCS / AUTOMATION & INTEGRATION

Every AgentOS workspace is an agent that other software can call, whether that's editors, scripts, chat UIs or other AI agents.

Interfaces at a glance

Interface	How	Typical client
Headless CLI	`agentos -p "<prompt>"`	Scripts and agent harnesses
MCP (stdio)	`agentos mcp serve`	Claude Code/Desktop, Codex, Gemini CLI, Cursor
MCP (HTTP)	`POST /api/mcp`	Remote MCP clients
ACP (stdio)	`agentos acp`	Zed and other ACP editors
A2A	`/.well-known/agent-card.json`, `POST /a2a/<agent>`	Other agents, the Agent Service Bus
OpenAI-compatible	`/v1/models`, `/v1/chat/completions`	Any OpenAI SDK or chat UI
Webhook / native HTTP	`/api/webhook/…`, `/api/agent/chat`	Automations and integrations

Each agent keeps one persistent conversation, so calls from any interface continue that conversation. You can address an agent by its ID, name or slug (for example personal-assistant).

Authentication

HTTP interfaces require the server API key from Global Settings → API Key. Send it as X-API-Key: <key> or Authorization: Bearer <key>. The server listens only on 127.0.0.1 unless you turn on Listen on all network interfaces.

Headless CLI

agentos -p "Summarize today's inbox" --agent "Personal Assistant"
echo "what changed?" | agentos -p --output-format json
agentos agents          # list callable agents

Output formats are text, json and stream-json. If you don't pass --agent, AgentOS uses AGENTOS_AGENT, then the agent whose workspace contains the current folder, then the only agent.

Use AgentOS from Claude Code, Cursor, Codex and more

agentos mcp install                        # add to every detected client
agentos mcp install --client claude,codex  # or pick clients
agentos mcp config                         # print the entry for manual setup
agentos mcp uninstall

Your agents then appear as tools (list_agents, ask_agent and one ask_<agent> per agent). AgentOS backs up each client config before changing it.

OpenAI-compatible API

curl http://localhost:3456/v1/chat/completions \
  -H "Authorization: Bearer $AGENTOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"personal-assistant","messages":[{"role":"user","content":"What is on my calendar today?"}]}'

Use the agent slug from GET /v1/models as the model. Only the latest user message is delivered, because the agent keeps its own history.

Webhook API

POST /api/webhook/jobs/:workspaceId        queue a job
POST /api/webhook/jobs/:workspaceId/run    create and run a job immediately
POST /api/webhook/chat/:workspaceId        send a chat message
GET  /api/status                           health check (no auth)

{ "title": "Research competitors",
  "description": "Find the top 5 competitors and summarise their pricing",
  "priority": "medium" }

Agent Service Bus (ASB)

Connect AgentOS to the Agent Service Bus so your local agents can work with agents on other machines and in the cloud.

In Global Settings → Agent Service Bus, enter the ASB host and an API key or username and password.
Click Check Connection. Your workspaces are registered as A2A agents on the bus and kept alive automatically.
Click Fetch Agents to see the remote agents your agents can now send tasks to.

ASB telemetry (off by default) streams agent activity to the bus for monitoring and auditing. Turn it on only if your organization runs the bus and wants that audit trail.