Open Agent API

Cookbook: Copy-and-Run Recipes

Practical, single-file examples organized by real integration tasks. Each file documents what it demonstrates, what it expects, and how to run it in its opening lines—covering curl alongside the official openai, anthropic, and google-genai SDKs for Python and Node.js. Every script reads configuration from environment variables with zero hardcoded secrets.

Tip: You can also prototype interactively in the console's Workbench (#workbench)—attach images, toggle routing or mock bridge tools, and click Code in the header to export ready-to-run snippets for your exact session.

Every runnable script in this folder is executed automatically by the compatibility lab (npm run compat) against an isolated gateway on CI, asserting exit codes and output lines (see integrations/compat/cookbook.mjs).


Setup

Every recipe reads the same three environment variables:

VariablePurposeDefault
OAA_BASE_URLGateway origin without a path suffixhttp://127.0.0.1:8787
OAA_API_KEYScoped caller key (sk-oaa-…)Required
OAA_AGENTPublished agent call name (as listed by GET /v1/models)agent/sample

OAA_PROMPT (plus OAA_LONG_PROMPT in recipe 02) optionally overrides the prompt text.

1. Run Immediately Offline (Zero Model Keys Needed)

Two commands start a local gateway and wire up a caller key against the offline sample agent:

oaa quickstart                                        # boots 127.0.0.1:8787 and publishes agent/sample
export OAA_API_KEY="$(cat .oaa/keys/quickstart.key)"  # caller key with invoke, read, files & approve scopes

Registering outbound webhooks in recipe 03 is an admin operation and additionally reads export OAA_ADMIN_KEY="$(cat .oaa/admin.token)".

2. Point the Same Scripts at a Real Agent

Once you publish a real CLI or model-backed agent (via the console or oaa connect codex / oaa connect ollama), point OAA_AGENT at it to run the exact same scripts against live tasks:

export OAA_AGENT="agent/codex"  # or agent/antigravity, agent/assistant, etc.

3. Install Your Preferred SDKs

Install only the SDKs you plan to run (curl scripts require nothing extra):

pip install openai anthropic google-genai
npm install openai @anthropic-ai/sdk @google/genai

Avoid naming your own test script openai.py or anthropic.py in Python, which would shadow the installed SDK package.


Recipe Index

Run any recipe directly from examples/cookbook:

python 01-first-call/hello_openai.py
node 04-caller-tools/tools_anthropic.mjs
sh 05-structured-output/structured.sh

Offline agent/sample vs. Live Agents

agent/sample (examples/sample-agent.mjs) is a deterministic, zero-cost ACP process with no LLM behind it. It is ideal for verifying connectivity offline, while multi-turn tool and schema recipes shine when pointed at a real agent:

RecipeBehavior with Offline agent/sampleRecommended Agent for Full Flow
01 First callRuns end-to-end with deterministic rule-based textAny agent
02 Long-runningBackground queuing and polling work; cancel finishes as incomplete (effect_outcome_unknown) and previous_response_id returns native_resume_unsupported because the sample process is statelessBuilt-in kernel agent, or a session-resumable Codex / ACP agent
03 ApprovalsRuns end-to-end: prompts containing approve trigger a file-write checkpoint; approving completes the run, denying fails with permission_deniedAny agent with approval gates
04 Caller toolsSample process never invokes caller functions (exits cleanly with code 3 explaining why)Built-in kernel agent, or Codex / Claude Code / Antigravity / ACP agent (Dual-Layer Harness)
05 Structured outputExercises the validation-failure branch (structured_output_invalid, exit code 3)Built-in kernel agent or multi-turn external agent (Structured Output)
06 ImagesAccepts image payloads; fixed reply does not describe visual contentVision-capable agent (image_input in GET /v1/models)
07 Errors & retriesRuns end-to-endAny agent
08 Connect toolsRuns end-to-endAny agent

Exit code convention across scripts: 0 = completed target flow; 2 = request rejected or unsupported by the chosen agent (e.g. sending images to a text-only agent); 3 = script completed cleanly, but the offline sample agent did not exercise the advanced branch.


Wiring IDEs, Chat Clients & Automation Platforms

  • One-click local wiring (recommended): For Cursor, Windsurf, Claude Desktop, Claude Code, OpenCode, Codex CLI, and DSH installed on the same machine, open Local Connections in the console to inject API providers or MCP bridges automatically without editing config files by hand.
  • Standard three-value setup: Any other OpenAI-, Claude-, or Gemini-compatible tool needs only your Base URL, API Key, and Agent call name (full client notes in Compatibility):
Tool / PlatformWhere to ConfigureBase URLModel FieldConfig Template
Open WebUIAdmin Settings → Connections → OpenAIhttp://<host>:8787/v1Fetched from /models or entered under Model IDs—
LibreChatlibrechat.yaml → endpoints.custom[]http://<host>:8787/v1models.default or models.fetch: truelibrechat.yaml
ChatboxProvider → API Hosthttp://<host>:8787/v1Fetch models or add agent name manually—
Cherry StudioModel Provider → Add → OpenAI → API Hosthttp://<host>:8787 or .../v1Fetch list or add manually—
LobeChatAI Service Provider → OpenAI → API Proxy URLhttp://<host>:8787/v1Fetch models or add manually—
NextChatSettings → Custom Endpoint → OpenAI Endpointhttp://<host>:8787 without /v1Settings → Custom Models—
DifyModel Provider → OpenAI-API-compatiblehttp://host.docker.internal:8787/v1 when Dify runs in DockerAgent call name—
n8nCredentials → OpenAIhttp://<host>:8787/v1Select from list or enter ID—
Continueconfig.yaml → models[]http://<host>:8787/v1model: agent/samplecontinue.config.yaml
Cline / Roo CodeAPI Provider → OpenAI Compatiblehttp://<host>:8787/v1Agent call name—
Zedsettings.json → language_models.openai_compatiblehttp://<host>:8787/v1available_models[].namezed.settings.json
CursorOverride OpenAI Base URL (cloud-relayed; use MCP via Local Connections for localhost)unverified for 127.0.0.1Custom model ID—

Quick tips:

  1. /v1 path convention: OpenAI SDKs and most OpenAI-compatible apps expect /v1 at the end of the Base URL; Anthropic and Gemini SDKs take the root origin without /v1:

    export OPENAI_BASE_URL="$OAA_BASE_URL/v1"   OPENAI_API_KEY="$OAA_API_KEY"
    export ANTHROPIC_BASE_URL="$OAA_BASE_URL"   ANTHROPIC_API_KEY="$OAA_API_KEY"
  2. Docker & browser origins: Containerized apps reaching the host via host.docker.internal require adding host.docker.internal to allowedHosts in .oaa/config.json; browser-only web apps require adding their origin to allowedOrigins.

  3. Clients that send custom tools: IDE agents (Cline, Continue agent mode, Zed) send client-side tool schemas. Bridging-capable backends (built-in kernel, Codex, Claude Code, Antigravity, ACP) bridge those calls automatically; for non-bridging adapters, point the client at http://<host>:8787/v1/compat so external tool schemas are ignored cleanly.

On this page