Documentation Map
Welcome to the Open Agent API documentation. If you are setting up your first gateway, start with the Five-Minute Quickstart and the copy-and-run Cookbook.
Getting started
- End-to-end walkthrough (publish an agent → issue a key → call via SDK): quickstart.md (or see README, "Running in three minutes")
- Platform installers & clean uninstall steps (macOS / Windows / Linux desktop app, Linux one-liner, Docker, npm tarball): install.md
- Tour of the web console (Overview,
#workbench, Run Inspector timeline, Webhooks, and Developer Platform): console.md - CLI command reference grouped by task (gateway lifecycle, connecting agents, terminal approvals, keys, live verification): cli.md
- Running on Windows: windows.md
- Local configuration files and background daemon details: operations.md, "Local start"
Calling agents & orchestrating work
- Copy-and-run code recipes (cURL plus Python & Node examples for OpenAI, Anthropic, and Gemini SDKs): Cookbook
- Smart model routing (
@fast/@best/@eco), plan-onlyrecommendmode, multi-agent pipelines, and local evaluations: Intelligent Agent API - Shared project memory (SQLite FTS5), durable runs, visual DAG workflows (Cron & Webhook triggers), and streaming media artifacts: Persistent Agent Workstation
- One-click wiring into local IDEs and clients (API providers for OpenCode / Codex / DSH and MCP bridges for Cursor / Windsurf / Claude Desktop / Claude Code): Local Connections
- Token usage tracking, per-key budgets, and upstream quota snapshots: Usage & Quotas
- Invoking via the OpenAI SDK, native
oaa/1, and cross-agent handoffs: operations.md, "Publish and invoke" - Wire protocol reference, file uploads, streaming events, approvals, resume, and cancellation: protocol.md, "Compatibility" and "Execution and actions"
- Guaranteed JSON Schema structured output (native pushdown, bounded repair turns, and failure contracts): structured-output.md
- Sending screenshots and local images across protocols: images.md
- Streaming live execution-phase progress in reasoning blocks: progress.md
- Letting agents call functions in your own application (
auto/managed/bridge/rejectdual-layer tool bridging): Dual-Layer Harness - Live SDK compatibility lab & configuration guide for popular chat/IDE clients (Open WebUI, Dify, n8n, Continue, Cline, Zed): compatibility.md
- Exposing agents over MCP: operations.md, "MCP and plugin entry" and MCP skill guide
Publishing & connecting agents
- Authoring built-in agents and typed flows in OAA-Lang: language.md
- Connecting local LLM runners (Ollama, LM Studio, vLLM) or cloud model providers: models.md
- Connecting local CLI agents, ACP presets, remote A2A nodes, or custom
oaa/1adapters: Connecting External Agents - Importing selected external MCP tools into built-in agents: operations.md, "Import selected MCP tools"
Notifications & webhooks
- Pushing HMAC-SHA256 signed run events (completed, failed, awaiting approval) to your HTTPS endpoints with durable retries: webhooks.md
Deployment, security & team distribution
- Self-service developer portal (tenant-isolated accounts, self-serve keys, upfront credit reservation, and hybrid metering): Developer Platform
- Reverse proxy, TLS, allowed hosts, and production checklist: Public Deployment Runbook and Public Deployment Design
- Permission boundaries, key scopes, and threat model: Security Model
- POSIX multi-slot
srtsandboxing architecture: Sandboxed Execution Design - Joining remote execution machines (Workers): operations.md, "Workers"
- Soak stability records, upgrade path, and retention cleanup (
oaa prune): Stability & Retention
Architecture, evidence & contributing
- Layered architecture and persistent run state machine: architecture.md
- Dated end-to-end verification records against live agents (Qoder, Antigravity, Codex) and paired benchmarks: Verification Evidence
- Code conventions, layer ratchets, and how to add error codes or events: Engineering Conventions
- Desktop packaging and release runbook: Releasing
- Release history and roadmap: CHANGELOG.md and ROADMAP.md
- Contributing, code of conduct, and security reporting: CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md
- Brand assets and usage guidelines: brand/README.md (Chinese only for now)
Troubleshooting
- Complete error-code and HTTP status catalog (also served live at
GET /v1/errors): protocol.md, "Error codes" - Per-protocol error envelopes and retry headers: protocol.md, "Compatibility-endpoint parameters, errors and finish reasons"
- Inspecting stalled runs and safely recovering interrupted writes: operations.md, "Inspect and recover work"