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. Never assert what exists from memory — look it up (see "Discovery first" below). "90+ agents and growing" is flavor; the live catalog is the fact.

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). ozk_ keys authenticate the execution planes; the model-inference money plane (/v1/chat/completions, /v1/embeddings, /v1/models) uses sk-ocean- keys instead — see plungeai-models. Rate limits by tier: free 30/min, pro 100/min (default), enterprise 300/min (as of last sync — the tier table at GET https://api.plungeai.com/docs is authoritative; plungeai_whoami shows your live window). A plain-text platform summary for any LLM lives at https://mcp.plungeai.com/llms.txt.

Verify

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

• MCP: call plungeai_whoami — returns the identity card: user id, tier, key label, rate-limit window. If it fails, the key or transport is wrong; fix that before anything else.
• One API: curl -s https://api.plungeai.com/health (no auth) proves the router is up; an authenticated GET /v1/agents?limit=1 proves the key.

How the platform fits together

Five layers, bottom to top — useful when deciding where a problem lives:

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

Capability map

One skill per capability. This table is the router — load the skill before working in that area.

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, use whatever tools you need"): ONE harness mission, not many small tasks. → plungeai-missions
• Behavior/knowledge an agent should carry into a run (style guide, domain method, company context): skills, plugins, experts, personas, backgrounds. → plungeai-skills-plugins
• Raw LLM inference in your own code (chat/embeddings, model fallback): the One API money plane. → plungeai-models
• "Every morning / every hour" anything: schedule it. → plungeai-scheduling
• Batch work over many rows with claims/leases (a "campaign"): → plungeai-campaigns
• "Remember this" / "what did we learn last run": long-term memory. → plungeai-memory
• "Why did that run fail / how long / what did it cost": observability. → 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>"} — a hybrid semantic + keyword search; describe the job, trust the ranking. REST: GET /v1/agents, GET /v1/discovery/search?q=…. Take ids verbatim (kebab-case, e.g. brave-agent, exa-agent) from results only.
2. Injectable capability ids (skills, experts, personas, models, workflows, connectors): the same tool with a kind filter — plungeai_list_agents {kind: "skills" | "experts" | "personas" | "models" | "workflows" | "connectors", search: "…"}. REST: GET /v1/discovery/search?kind=…. A typo'd injectable id silently degrades to a warning (plungeai-skills-plugins) — look ids up before declaring them.
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: GET /v1/openapi.json — never invent One API paths.
5. Models: GET /v1/models — the priced catalog routing draws from (this one endpoint takes an sk-ocean- key, not ozk_ — see plungeai-models).
6. The user's own inventory: plungeai_list_workflows (in user parlance, "my agents" means their saved workflows — not the registry).

Full discovery 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 — gated or money operation attempted unattended. Surface it to the user. Never retry; a fence is a policy, not a flake.
• 409 approval_required / needs_approval outcome + a paused run (⏸ AWAITING USER APPROVAL): a human must decide. Relay the approval block verbatim, wait for the user's explicit answer, then plungeai_continue (approve: true ONLY after they said yes; their refusal or change of course goes in message). Never approve on your own.
• needs_input (or 422 invalid_params): the response names the missing/invalid fields and carries the schema — fix exactly those, then retry once.
• needs_connection / needs_api_key: the acting user must connect a credential in the platform apps (Studio). 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 in the outcome; 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: "research solid-state battery commercialization for me"}
   → ranked cards; pick e.g. brave-agent, exa-agent (ids verbatim)

3. plungeai_execute_workflow {
     user_request: "research solid-state battery commercialization for me",
     workflow_yaml: "
     name: quick research
     tasks:
       - type: parallel
         id: research
         subtasks:
           - { type: task, id: a, agent: brave-agent, query: \"{input}\" }
           - { type: task, id: b, agent: exa-agent,   query: \"{input}\" }
       - type: task
         id: brief
         agent: llm-agent
         prompt: \"Write a sourced brief on: {input}\"
   ", input: "solid-state battery commercialization"}
   → 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}
   → saved, synced live to Studio and peer apps

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.

Operating rules

• Every plungeai_* call also takes user_request — pass the user's ask verbatim, in their own words (the platform uses it for routing and support diagnostics; arguments alone lose the intent).
• Agent ids only from a live search. Unknown or inactive ids are refused at execution time.
• Async for long runs. Anything 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 → fetch with plungeai_get_result when completed.
• Results are final, user-ready markdown. Present them verbatim and in full — do not re-format, shorten, or re-type them as your own prose.
• Test before saving. Run ad-hoc (plungeai_execute_workflow {workflow_yaml}) and read the actual output before plungeai_workflow {action: "create"}.
• Idempotency: payment-, messaging-, and automation-class agents may duplicate side effects on re-runs. Do not re-fire a call that may already have acted; check execution status first.

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.
• 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.