> ## Documentation Index > Fetch the complete documentation index at: https://www.plungeai.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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… 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](https://skills.plungeai.com/plungeai-platform.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-platform/SKILL.md) 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`): ```bash 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`): ```bash 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`). | Capability | What it gives you | REST | Skill | |---|---|---|---| | **Discovery** | Find agents, tools, models, skills, connectors, templates on the live registry | `/v1/discovery/*`, `/v1/templates` | `plungeai-discovery` | | **Agents** | Registry building-block agents: discover and execute one; run your saved agent or bot by id | `/v1/agents`, `POST /v1/execute` | `plungeai-agents` | | **Tools & connectors** | Structured tool-agents with typed contracts (params, operations, approval gates, connected accounts) | `/v1/tools`, `/v1/connections`, `/v1/channels` | `plungeai-tools-connectors` | | **Workflows** | CNL YAML multi-agent pipelines; saved workflows, agents and bots | `/v1/workflows` | `plungeai-workflows` | | **Bots** | Saved agents with stored policy (permission classes, locks, spend caps), workspace, paired chats, groups | `/v1/workflows/{id}/permissions`, `/v1/bot-groups` | `plungeai-bot-agent` | | **Models** | Provider factory inside runs + OpenAI-compatible inference API | `/v1/chat/completions`, `/v1/embeddings`, `/v1/models` | `plungeai-models` | | **Skills / Plugins / Experts / Personas** | Injectable instruction packs, plugins, voice/domain expertise, standing context | `/v1/skills`, `/v1/discovery/search?kind=skills` | `plungeai-skills-plugins` | | **Missions** | Bounded autonomous agent runs: goal, tool fence, iteration cap, success criteria | a `type: harness` task on `/v1/workflows/execute` | `plungeai-missions` | | **Scheduling** | Cron, one-time and webhook/email/hook-triggered runs of workflows, agents and missions | `/v1/schedules`, `/v1/triggers` | `plungeai-scheduling` | | **Campaigns** | Ledgered, claim-based batch work across many rows | `/v1/workflows` with `kind: campaign` | `plungeai-campaigns` | | **Memory** | Run-data exchange (SharedMemory) + per-user long-term memory | `/v1/memory` | `plungeai-memory` | | **Results & traces** | Live SSE events, execution history, steer a run, traces, cost | `/v1/executions`, `/v1/traces/{id}`, `/v1/mcp/runs` | `plungeai-results-traces` | | **Chat** | Persistent platform chat with sessions (`plungeai_chat`) | MCP and CLI only | `plungeai-mcp-setup` | ## 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: ""}` — 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: ""} → 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: "", 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 | Pitfall | Reality | |---|---| | "Show me my agents" answered with the registry | Users mean their saved workflows → `plungeai_list_workflows` | | Baking dates into scheduled workflows | Date tokens (`{week_start}`, …) roll automatically (`plungeai-scheduling`) | | Storing context as long-term memory that belongs in a background/skill | Memory is learned per-user state; authored shared context goes in backgrounds/skills (`plungeai-memory`) | | Inventing One API routes or model names in generated code | `GET /v1/openapi.json` and `GET /v1/models` are the only authorities | ## 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-` — wiring a specific coding tool's agent to PlungeAI over MCP.