Agents plane

The agents plane runs one registry agent per request and hands back its result. It is the execution plane you reach with an ozk_ key (see Authentication) at POST /v1/agents/:id/execute. Every call wraps exactly one minimal CNL task in the engine envelope, so the agents plane is the single-task front door; multi-task orchestration lives on the Workflows plane and bounded autonomous missions on a type: harness task there (see capability injection).

Base URL is always https://api.plungeai.com. All examples below use $PLUNGE_API_KEY for an ozk_… key. Source: orchestration/api-gateway/routes/agents.ts.

9.1 Agent tiers

An agent is a registry card whose id equals its Worker service name. There are ~90 active agents (GET /v1/agents?limit=100 returned count: 92, live-verified 2026-09-19; the default page is 50 — follow has_more/next_offset). They fall into these tiers. Every id below is status:active in the registry unless the row says otherwise (agents/agents/README.md, agents/agents/CORE-AGENTS-DECISION.md).

Legacy ids. llm-agent, skill-agent, universal-agent and agentic-agent are frozen legacy ids: they stay callable until the switch-over, then re-point to one-agent. Write agent: one-agent everywhere — a type: harness task with no agent: line still runs on the legacy harness-agent loop today. The bare harness-agent binding is not a callable registry id on the planes (live-verified: 404 unknown_agent).

9.2 List agents & categories

• GET /v1/agents?limit=<1..100>&offset=<n> → { agents: [...], count, limit, offset, has_more, next_offset } — count is the page size (default limit 50); when has_more is true, fetch the next page at offset=next_offset. Each card carries id, a summary and tags (including status:active).
• GET /v1/agents/categories → { categories: [{name, count}], count }, aggregated from the active-agent summaries (there is no separate categories store).

curl -s "https://api.plungeai.com/v1/agents?limit=5" \
  -H "Authorization: Bearer $PLUNGE_API_KEY"

9.3 Execute — body reference

POST /v1/agents/:id/execute. JSON body (default) or an Ocean-format text/yaml body with the same fields. Every accepted field, from routes/agents.ts:

Fields not in this table (e.g. goal, mission, allowed_tools, skills, experts, mcp) are ignored on the agents plane — run those through a type: harness task on the Workflows plane. Two more fields are accepted only as a pair, the approve round-trip of 9.7: approved: true with action_token (a string of 1-128 characters), plus an optional allow_scope (once | run | always, anything else is once). One without the other, or an approved that is not exactly true or false, is 400 invalid_params; approved: false alone is a fresh turn.

Conversation without a prompt

An OpenAI-style body is a valid agent call — the model answers from the whole conversation:

curl -s "https://api.plungeai.com/v1/agents/one-agent/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"My name is Ada."},{"role":"assistant","content":"Hello Ada."},{"role":"user","content":"Reply with only my name."}],"max_tokens":16}'

Sync execute (default)

curl -s "https://api.plungeai.com/v1/agents/one-agent/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Reply with only the word: pong","max_tokens":24}'

Success (200): { "content": "...", "workflow_id": "...", "task_id": "t1", "request_id": "..." }. request_id equals the trace id (see Traces).

Model / provider pinning

Pin a model and provider together; discover models with GET /v1/models (Models plane) or GET /v1/discovery/search?kind=models (Discovery).

curl -s "https://api.plungeai.com/v1/agents/one-agent/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Reply with only: pong","provider":"openai","model":"gpt-4o-mini","max_tokens":16}'

9.4 Async execution (202 + poll)

Send "sync": false. The response is 202 with a pointer { workflow_id, task_id, request_id }; read the result from the result route once it is ready.

RESP=$(curl -s "https://api.plungeai.com/v1/agents/one-agent/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"Reply with only the word: pong","max_tokens":24,"sync":false}')
echo "$RESP"
WF=$(printf '%s' "$RESP" | sed -n 's/.*"workflow_id":"\([^"]*\)".*/\1/p')
TASK=$(printf '%s' "$RESP" | sed -n 's/.*"task_id":"\([^"]*\)".*/\1/p')
for i in 1 2 3 4 5 6 7 8; do
  R=$(curl -s "https://api.plungeai.com/v1/agents/results/$WF/$TASK" \
    -H "Authorization: Bearer $PLUNGE_API_KEY")
  case "$R" in *'"content"'*) echo "$R"; break;; *) sleep 2;; esac
done

9.5 Results route

GET /v1/agents/results/:workflowId/:taskId → { content, content_type, workflow_id, task_id }. It reconciles the run's terminal state (lib/execution-row.ts):

9.6 Streaming

Send "stream": true on POST /v1/agents/:id/execute. The agents plane emits an OpenAI-shaped chunk stream (the only stream shape on this plane) — Content-Type: text/event-stream, data: lines only (no named event: lines), each a chat.completion.chunk, terminated by data: [DONE]. This mirrors the models plane; see Streaming. Relay + encoder: lib/stream-relay.ts (relayEngineStream, openaiEncoder).

Exact request shape:

curl -sN "https://api.plungeai.com/v1/agents/one-agent/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Reply with only the word: pong","max_tokens":24,"stream":true}'

Observed wire (live-verified 2026-09-18):

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":…,"model":"gemini-3.1-flash-lite","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"pong"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":72,"completion_tokens":1,"total_tokens":73}}

data: [DONE]

Notes: model is the pinned model, else the provider's default (never the agent id); a final usage is included when the provider reported the token split. On an error after the first byte the stream emits data: {"error":{…}} and closes without [DONE] (OpenRouter behaviour); a pre-dispatch rejection is a JSON error (see 9.8), not a stream.

9.7 The concierge approval flow

concierge runs a bounded Discover→Inspect→Execute loop with three tools — find_agent (discover), agent_card (inspect), run_agent (execute) — and a payment gate (agents/agents/concierge-agent/README.md). Money operations (buy, purchase, send, transfer, pay, withdraw, shop, …) and any card gated:<op> are held for approval:

1. A gated action returns { "needs_approval": true, "pending_action": {…}, "action_token": "<10-char>", "messages": [...] }.
2. Re-invoke with the same messages, plus "approved": true and the action_token, to execute and continue. The token is held server-side for 1 hour. ask_user questions work the same way (append the user's answer to messages).

On the One API this handshake is surfaced through the MCP plane: the pause arrives as a ⏸ continuation, and you approve with plungeai_continue { approve: true } (never approve on the user's behalf). The raw agents plane takes the same pair (routes/agents.ts): send the next call with the same messages, "approved": true and the action_token (1-128 characters; a half pair is 400 invalid_params) and the agent checks the token against your key's pending actions. You can also approve by prompt: a paused reply ends with Running outside the chat? Re-run with input: approve <token>, so send {"prompt":"approve <token>"} as the next call and the held action runs for your key. An unknown, used or expired token is a graceful no-op that runs no model and spends nothing — the example uses one:

curl -s "https://api.plungeai.com/v1/agents/concierge/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"approve 0000000000","max_tokens":64}'

(A real approval run can spend money, so it is not run here.)

9.8 Errors

Pre-dispatch and post-dispatch errors from routes/agents.ts / routes/_util.ts. Full envelope and header reference: Errors, limits & headers.

curl -s "https://api.plungeai.com/v1/agents/no-such-agent-xyz/execute" \
  -H "Authorization: Bearer $PLUNGE_API_KEY" -H 'Content-Type: application/json' \
  -d '{"prompt":"hi","max_tokens":8}'