Open Agent API

Open source · Self-hosted · Apache-2.0 · v0.0.70

Open Agent API

Turn agents into an API.

Dispatch complete agents equipped with tools, project memory, and permission boundaries—not bare models. One call delivers one task. Native wire compatibility with official OpenAI, Claude, and Gemini SDKs plus MCP; your code needs only a Base URL and an API key.

Wire protocols
OpenAI · Claude · Gemini · MCP
Engine & runner presets
32+ CLI / ACP / Local LLMs
CI test suite
1,305 tests across 3 OSes
Compatibility lab
14 SDKs · 456 live scenarios
Click screenshot to zoom · light/dark videos stream on demand
Open Agent API console overview: sidebar navigation for Overview, Workbench, Agents, Workflows, Connections, and Usage alongside pending approvals, 24h metrics, and active agents.

Two-line integration

Keep your existing SDKs, swap the endpoint

Point base_url at your gateway and set model to an agent identifier. A single-turn completion call becomes a multi-step agent run with tools and artifacts.

Python · openai SDK
from openai import OpenAI client = OpenAI(    base_url="https://api.openai.com/v1",    api_key=OPENAI_API_KEY,    base_url="http://127.0.0.1:8787/v1",  # your local or private gateway    api_key="sk-oaa-…",                   # scoped key issued in the console) resp = client.chat.completions.create(    model="gpt-4.1",    model="agent/research",               # the published agent's call name    messages=[{"role": "user", "content": "Reconcile these three vendor quotes and flag variances"}],)print(resp.choices[0].message.content)
Node.js · openai SDK (Responses continuation)
import OpenAI from 'openai'; const client = new OpenAI({  baseURL: 'https://api.openai.com/v1',  apiKey: process.env.OPENAI_API_KEY,  baseURL: 'http://127.0.0.1:8787/v1',    // point to your gateway  apiKey: process.env.OAA_API_KEY,        // key from the console}); const resp = await client.responses.create({  model: 'gpt-4.1',  model: 'agent/coder@best',              // supports @fast / @best / @eco routing  input: 'Run the auth unit tests and isolate the flaky timeout',});console.log(resp.output_text);

Three values are all a caller ever needs

A Base URL, an API key, and an agent name. Issuing a key in the console presents all three side by side—copy them individually or export them together as environment variables.

model takes an agent call name like agent/research. Which upstream model route, skill set, and workspace directory run underneath stays encapsulated on the publisher side.

  • 01 Base URL http://127.0.0.1:8787/v1
  • 02 API Key sk-oaa-…
  • 03 model agent/research
API key ready dialog showing the Base URL, one-time scoped key, and agent call name agent/research with copy buttons.
The key-ready sheet—drop these three values into any SDK, IDE extension, or backend service.

Get started

Pick an install path, run your first task

Every route converges on oaa quickstart: it boots a local gateway on 127.0.0.1:8787, publishes an offline sample agent, and completes a live call without needing any cloud model key upfront.

Cross-platform desktop app

macOS · Windows · Linux

Unified Electron sandboxed shell bundling Node.js 24, the web console, dock approval badges, and a system-tray quick-approval popover.

Linux one-liner

x64 · arm64 · rootless

Verifies release SHA256SUMS, bundles the Node runtime, and installs under ~/.local:

curl -fsSL https://github.com/jiangxingfan1-coder/Open-Agent-API/releases/latest/download/install.sh | sh

Docker Compose

amd64 · arm64 · loopback

Non-root container persisting state in /data and bound strictly to 127.0.0.1—ideal for built-in agents and remote worker nodes:

docker compose up --build -d

From source or npm tarball

Node.js 24 / 26

Install the release .tgz globally, or run directly from a repository checkout:

npm run oaa -- quickstart

Platform requirements, first-launch OS gatekeeper prompts for unsigned builds, and clean uninstall steps are covered in Installing. Ready to wire a real provider? Run oaa connect <preset> to connect cloud APIs or local runners.

Core architecture

A stateful agent runtime, not a stateless proxy

01

Execution units, not raw completions

Each published endpoint wraps its own toolset, project memory, model routing, and permission scope. One call runs a tracked task: multi-turn tool loops, streamed reasoning progress, and streaming file artifacts up to 256 MiB—with idempotency, cancellation, and resume built in.

02

Dual-layer tool bridging & strict schemas

Pushes JSON Schemas and tool_choice contracts natively to OpenAI, Anthropic, and Gemini drivers with automatic repair turns. When a caller (such as Cursor, Cline, or your app) supplies custom tools, the gateway bridges invocations back via oaa-caller.

03

Durable human-in-the-loop checkpoints

Sensitive writes or shell commands pause the run cleanly at an "awaiting approval" checkpoint rather than an ephemeral prompt. Approve from the console, system tray, CLI, or a signed webhook—and the exact same task resumes where it paused.

Interactive demo agent/coder POST /v1/responses · run_8f2a91c0
Awaiting approval
  1. 01

    Inspect workspace & auth module diff

    Located 3 validation messages in src/auth/login.ts and drafted unit tests · 120 ms

  2. 02

    Query project memory (SQLite FTS5)

    Matched 2 project conventions on error envelopes and test isolation · 48 ms

  3. 03

    Approval gate: npm test -- --run auth

    Requests shell.exec in workspace · paused for operator decision

  4. 04

    Run paused at durable checkpoint—click "Approve & continue" or "Deny" above…

Task inspector in the console showing a coding run paused at awaiting approval with the exact command payload and Reject / Approve actions.
The live task inspector: every tool call, critical-path span, approval decision, and output artifact remains auditable.

Workbench & orchestration

From single-endpoint debugging to a multi-agent workstation

Alongside headless API serving, v0.0.70 ships an interactive console workbench, one-click local IDE wiring, multi-agent routing pipelines, and durable workflows.

#workbench

Interactive chat & bridge workbench

Test multi-turn sessions (previous_response_id) right in the console with image paste, collapsible reasoning traces, inline approvals, custom JSON Schema mock bridge tools, and one-click SDK snippet export.

API + MCP

Dual-channel local client wiring

Detects installed developer tools and wires OpenCode, Codex, and DSH via API providers—or injects MCP bridges into Cursor, Windsurf, Claude Desktop, and Claude Code referencing 0600 private key files with diff preview and clean rollback.

Orchestration · FTS5

Smart routing, memory & workflows

Route dynamically with @fast / @best / @eco or recommend, chain multi-agent helpers with structured handoffs, search project memory via SQLite FTS5, and trigger workflows via IANA-timezone Cron or signed webhooks.

Desktop · Local LLM

Unified desktop shell & local runners

A single hardened Electron shell across macOS, Windows, and Linux with a system-tray quick-approval popover; automatically discovers local Ollama, LM Studio, llama.cpp, and vLLM runners to publish models as agents.

Ecosystem

Local CLIs, model runners, and wire protocols

Publish OAA-Lang built-in agents alongside external coding CLIs already installed on your machine—preserving their native skills and credentials behind one consistent API.

Engines & agents

  • Built-in kernel Defined in OAA-Lang 2.5 or JSON; token streaming, durable approvals, tool bridging, and multi-route failover
  • Codex CLI Native app-server integration; token streaming, oaa-caller tool bridging, graceful turn/interrupt, and toolless planning
  • Claude Code Powered by the official Agent SDK; incremental token streaming, approvals, and caller-tool bridging
  • Antigravity Dual native & agy acp transport; live model catalog discovery, tool bridging, and ACP approvals
  • ACP ecosystem 32+ presets including Qoder, OpenCode, Grok, and DeepSeek Harness with approvals and caller-tool bridging
  • Local LLM runners Discovers Ollama, LM Studio, llama.cpp, Jan, LocalAI, and vLLM without touching runner configs
  • A2A & custom adapters oaa/1 over stdio, stream, or HTTP plus A2A contextId continuation and remote node profile sync

Protocols & observability

  • OpenAI Chat & Responses Standing SDK regression suite; streamed reasoning progress, previous_response_id, images, and native JSON Schema
  • Claude Messages Verified against official Python & Node SDKs with full tool bridging and structured output contracts
  • Gemini Compatible with generateContent, streamed thought blocks, and native responseSchema pushdown
  • MCP entry Exposes published agents to IDEs and clients while keeping approval authority isolated to the control plane
  • oaa/1 & Webhooks Native async run lifecycle paired with HMAC-SHA256 signed HTTPS callbacks and durable retry queues
  • Metrics & W3C tracing Zero-dependency Prometheus GET /metrics and end-to-end W3C traceparent propagation across delegations

See the full capability matrix covering streaming granularity, tool isolation, and POSIX multi-slot sandboxing in Connecting external agents and Dual-layer harness.

Team & distribution

Enable a self-service portal when you are ready to share

Turn on the Developer Platform in one click so teammates or external developers can register in a dedicated portal, manage their own keys, and call listed agents against credit quotas.

  • Tenant-isolated accounts & keys: each developer manages independent keys, run histories, and uploaded artifacts in strict isolation.
  • Upfront reservation & hybrid metering: price per task with optional per-token rates; credits are reserved atomically at run start and refunded if a run does not complete.
  • Audited host-agent opt-in: listings expose built-in agents by default, with an explicit audited host_execution toggle per external agent.
  • Clean quota ledger & persistent rate limits: auth rate limits persist in SQLite with optional verification webhooks, while credit accounting stays cleanly decoupled from external billing processors.
Developer portal home page displaying the gateway endpoint, published agent catalog, and quickstart instructions.
The self-service developer portal—enabled on demand and styled on the same design system.

Engineering baseline

Verified baseline and architectural scope

Capabilities are backed by reproducible CI gates, protocol labs, and live-agent acceptance runs, paired with deliberate architectural boundaries.

Verified baseline

  • 1,305 automated tests across 3 OSes: continuously executed on Linux, macOS, and Windows (Node.js 24 & 26) alongside strict layer-ratchet and zero-any checks.
  • Live SDK compatibility lab: 14 official Python/Node SDKs and frameworks (Vercel AI SDK, LangChain, LlamaIndex, OpenAI Agents) run 456 live scenarios against an isolated gateway, plus 12 client wire replays.
  • End-to-end live agent acceptance: verified against real Qoder CLI (all 11 oaa verify scenarios plus platform billing), Antigravity 1.5.10 (native & agy acp forced tool bridging and tracing), and Codex 0.167.0 (streaming, graceful interrupt, and routing).
  • Soak stability & multi-slot sandboxing: passed 62-minute continuous load and SIGKILL recovery checks, backed by a per-subject multi-slot srt sandbox pool on POSIX.

Architectural scope & boundaries

  • Single-node SQLite footprint: engineered for personal workstations and private team gateways with embedded SQLite (including FTS5) and zero external infrastructure dependencies, rather than multi-node shared-DB clustering.
  • Quota ledger decoupled from payments: portal credits track internal usage quotas without bundling payment gateways or outbound SMTP servers, keeping integration with your own billing stack straightforward.
  • Host permissions & OS sandboxing: external CLIs run with the host user’s privileges unless POSIX srt policies are enabled (local sandboxing is not yet available on Windows); desktop installers are distributed unsigned by default.
  • Extensible live verification: run oaa verify <agent> on your own setup to produce redacted acceptance reports for additional cloud providers and platforms.

Dated test runs, version numbers, and raw measurements are recorded in Verification evidence and Stability & retention.

Run your first agent endpoint locally today

Binds strictly to localhost out of the box with zero external dependencies—no cloud model key required upfront.

npm run oaa -- quickstart
Quickstart guide