plungeai-platform

THE PlungeAI (Ocean) platform capability map: a growing live registry of agents and structured tools, CNL multi-agent workflows, bounded harness missions, injectable skills/plugins/experts/personas, model routing with an OpenAI-compatible inference API, cron scheduling, per-user long-term memory, and full run observability — how the five layers fit together and which capability skill covers which job. Use when the user asks "what can PlungeAI do", "which PlungeAI capability/agent/tool for X", wants an end-to-end mental model of the platform, hits a trust fence (403 refused / needs_approval / 409) and needs the doctrine, or is planning multi-step work and needs to pick between a single agent call, a CNL workflow, and a harness mission. For which door (MCP/REST/CLI/Studio) to use, load choose-your-plungeai-door first; each capability's own deep-dive skill (named below) covers its exact tools/params.

Download zip (opens in a new tab) · View raw SKILL.md (opens in a new tab)

PlungeAI (internally "Ocean") is a Cloudflare-native agent runtime: every agent, tool, and workflow runs as a deployed edge service, connected by RPC. You do not install or host anything — you operate the live platform through one of four doors (MCP, One API, Ocean CLI, Ocean Studio — see choose-your-plungeai-door) and compose its capabilities. There is no local mode: everything you execute runs on the deployed platform, and everything you read (catalogs, contracts, results) is live.

The platform is discovery-first by design: the agent catalog, tool contracts, model list, and workflow inventory change without notice, so look things up ("Discovery first" below) and never assert them from memory.

Connect

MCP (Claude Code shown; other clients use the equivalent mcpServers JSON — install page: https://mcp.plungeai.com/install; full setup: plungeai-mcp-setup):

claude mcp add --transport http plungeai https://mcp.plungeai.com/v1 \
  --header "Authorization: Bearer ozk_YOUR_KEY"

One API (same ozk_ key, Authorization: Bearer or X-API-Key; full setup: plungeai-api-setup):

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

Keys are self-service ozk_ keys from Dashboard → One API → Keys (https://dashboard.plungeai.com). The same key authenticates the execution planes and the money plane (/v1/chat/completions, /v1/embeddings, /v1/models, Bearer only — plungeai-models). Rate limits by tier: free 30/min, pro 100/min (default), enterprise 300/min (the tier table at GET https://api.plungeai.com/docs is authoritative; plungeai_whoami shows your live window). A plain-text summary for any LLM: https://mcp.plungeai.com/llms.txt.

Verify

Before doing real work, prove the connection and identity once:

• MCP: call plungeai_whoami — the identity card: user id, tier, key label, rate-limit window. If it fails, the key or transport is wrong; fix that first.
• One API: curl -s https://api.plungeai.com/health (no auth) proves the router is up; an authenticated GET /v1/whoami returns the same identity card (user id, tier, key label) and proves the key.
• CLI: ocean-cli whoami.

How the platform fits together

Five layers, bottom to top — useful when deciding where a problem lives: Runtime (agents execute as deployed edge services with one task interface; providers serve models; memory stores state), Orchestration (the CNL engine runs workflows as DAGs of agent calls; the scheduler fires them), Harness (mission-bounded autonomous runs: tool fence, iteration cap, recursion guard, memory recall), Capability injection (skills, plugins, experts, personas, backgrounds, MCP servers injected per run into one loop agent) and Product (Ocean Studio to build, dashboards to operate, branded runner apps to use).

Two properties explain most behavior you will observe: internal calls are RPC between deployed Workers (so parallel fan-out is essentially free — plungeai-workflows), and every result is stored under (workflow_id, task_id) (so every execution returns redeemable pointers — plungeai-memory).

Capability map

One skill per capability. This table is the router — load the skill before working in that area. The REST column is the One API route family (setup and the three levels: plungeai-api-setup; the live contract is GET /v1/openapi.json).

Which capability for which job

• One-shot capability call ("search the web", "convert this PDF"): a single agent — prompt-driven → plungeai_execute_agent; structured (has a parameters table) → plungeai_get_tool_contract, then plungeai_execute_tool (plungeai-agents, plungeai-tools-connectors).
• Multi-step pipeline with known steps ("research A, B, C in parallel, then synthesize"): a CNL workflow (plungeai-workflows).
• Open-ended goal needing judgment ("investigate X and produce a memo"): ONE harness mission, not many small guessed tasks (plungeai-missions).
• Behavior or knowledge a run should carry (style guide, method, company context): skills, plugins, experts, personas, backgrounds (plungeai-skills-plugins).
• Raw LLM inference in your own code: the One API money plane (plungeai-models).
• "Every morning" anything: schedule it (plungeai-scheduling). Batch work over many rows: a campaign (plungeai-campaigns). "Remember this": long-term memory (plungeai-memory). "Why did that run fail / what did it cost": plungeai-results-traces.

Discovery first (non-negotiable)

Catalogs are live and execution refuses stale ids. Always:

1. Agents: plungeai_list_agents {search: "<capability in plain words>"} — hybrid semantic + keyword search; trust the ranking. REST: GET /v1/agents, GET /v1/discovery/search?q=…. Take ids verbatim (kebab-case, e.g. brave-agent) from results only.
2. Injectable ids (skills, experts, personas, models, workflows, connectors): the same tool with a kind filter (REST: GET /v1/discovery/search?kind=…). A typo'd id silently degrades to a warning (plungeai-skills-plugins).
3. Tool shapes: plungeai_get_tool_contract {agent_id} or GET /v1/tools/{id} before the first call to an unfamiliar structured agent — the contract IS the docs.
4. Routes and models: GET /v1/openapi.json and GET /v1/models (same ozk_ key, Bearer) — never invent One API paths or model names.
5. The user's own inventory: plungeai_list_workflows / GET /v1/workflows — in user parlance "my agents" means their saved workflows, not the registry.

Full mechanics (search params, cards, contracts, templates) — plungeai-discovery.

Trust fences and structured outcomes

The platform answers with structured outcomes, never raw errors. Respect them:

• Over MCP the outcome is an envelope, not an HTTP error: every tool answers HTTP 200 with a status of ok, needs_input, needs_connection, needs_api_key, needs_approval, unavailable, or error (there is no refused MCP status — fences spell as HTTP codes only on the One API).
• 403 refused (One API): a fence blocked the call — a gated or money operation attempted unattended. Surface it. Never retry; a fence is a policy, not a flake.
• 409 approval_required / needs_approval + a paused run (⏸ AWAITING USER APPROVAL): a human must decide. Relay the approval block verbatim, wait for the explicit answer, then plungeai_continue (approve: true ONLY after they said yes; a refusal goes in message) — over REST POST /v1/executions/{id}/continue with {approve} or {answer}. Never approve on your own.
• needs_input (422 invalid_params): the response names the missing fields and carries the schema — fix exactly those, retry once.
• needs_connection / needs_api_key (REST 424 connection_required, with a connect pointer): the acting user must connect a credential — in Studio, or over the API with POST /v1/connections/{provider}. Tell them exactly what to connect; retry after.
• unavailable: the outcome lists live alternatives — pick one or re-discover.

Same doctrine everywhere: follow the remediation; never blind-retry the identical call.

A complete first session (MCP)

The canonical shape of operating the platform, end to end — adapt the middle to the job:

1. plungeai_whoami                      → identity card (proves key, tier, rate window)
2. plungeai_list_agents {search: "web search", user_request: "…"}
                                        → ranked cards; take ids verbatim (e.g. brave-agent, exa-agent)
3. plungeai_execute_workflow {user_request: "…", input: "solid-state battery commercialization",
     workflow_yaml: "<a parallel brave-agent + exa-agent search feeding a one-agent brief>"}
                                        → result (final markdown — relay verbatim)
   For >3 min jobs: mode: "async" → plungeai_get_workflow_status → plungeai_get_result
4. Output is right → plungeai_workflow {action: "create", name, yaml, description}
5. plungeai_schedule {action: "create", job_type: "workflow", target: "<saved id>", schedule: "0 7 * * *"}
                                        → runs every morning; verify once with {action: "run_now"}

Steps 2-3 change per job (single agent call, tool contract + typed execution, or a harness mission via plungeai_run_mission) — the frame (verify → discover → test → save → schedule) does not. The same frame over the One API: GET /v1/whoami → GET /v1/discovery/search → POST /v1/workflows/execute → POST /v1/workflows → POST /v1/schedules.

Operating rules

• Every plungeai_* call also takes user_request — the user's ask verbatim (the platform uses it for routing and support diagnostics).
• Async for long runs. Over ~3 minutes: mode: "async" (on plungeai_execute_workflow / plungeai_execute_tool / plungeai_run_mission; plungeai_execute_agent has none — wrap it in a one-task workflow) → poll plungeai_get_workflow_status → plungeai_get_result. Over REST: GET /v1/executions/{id}.
• Results are final, user-ready markdown. Present them verbatim and in full — never re-format or re-type them. Over MCP format: "json" returns the same result as a JSON document; REST format is json, yaml, markdown or text.
• Test before saving. Run ad-hoc (plungeai_execute_workflow {workflow_yaml}) and read the output before plungeai_workflow {action: "create"}.
• Idempotency: payment-, messaging- and automation-class agents may duplicate side effects on re-runs; check execution status before re-firing.

Common pitfalls

Related skills

• choose-your-plungeai-door — which door (MCP/REST/CLI/Studio) for which job.
• plungeai-mcp-setup / plungeai-api-setup / plungeai-cli-setup — connect and verify a client.
• plungeai-sdk-setup — the official One API SDKs (TypeScript, Python, Go, Rust).
• Every capability in the map above has its own deep-dive skill by the same name.
• plungeai-in-<tool> — wiring a specific coding tool's agent to PlungeAI over MCP.