plungeai-agents

Run a PlungeAI registry agent: recognize the two kinds (prompt-driven vs structured tool-agents), list them (GET /v1/agents), execute a prompt-driven one sync or async (plungeai_execute_agent MCP / POST /v1/agents/{id}/execute REST / ocean-cli agents run, incl. streaming SSE), and redeem results by execution id (plungeai_get_result / GET /v1/agents/results/{workflowId}/{taskId}). Use when running a single building-block agent (search, LLM, documents, …), choosing the right execution door for an agent card, polling/redeeming an async run, or fixing a missing_prompt/unknown_agent/unknown_model error. For finding an agent id use plungeai-discovery; for structured tool-agents with typed params/operations use plungeai-tools-connectors; for chaining several agents use plungeai-workflows; for model/provider detail use plungeai-models. To run YOUR saved agent or bot by id (agent: <id>@n on POST /v1/execute, the Agent Call door), see the section below.

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

An agent is a deployed capability with a uniform interface: it accepts a task, does one job well, and stores its result where the platform can hand it to the next step. Agents are the building blocks workflows chain, missions call, and tools are a structured sub-species of. The catalog is live and active-only — execution refuses any id that isn't currently active.

Prerequisites

• Self-service ozk_ key from Dashboard → One API → Keys (https://dashboard.plungeai.com).
• MCP: https://mcp.plungeai.com/v1. REST: https://api.plungeai.com.

Discovery first

Never call an agent id from memory. plungeai_list_agents {search: "<capability in plain words>"} (MCP) or GET /v1/discovery/search?kind=agents&q=… (REST) — full mechanics in plungeai-discovery. Fetch the full card (plungeai_list_agents {agent_id} / GET /v1/discovery/cards/agent/{id}) before first use of an unfamiliar agent — it tells you which of the two kinds below you have, and carries "Not for → use X instead" redirects.

Two kinds — pick the right execution door

A third thing is your own saved agent or bot (kind: agent | bot): not a registry agent, run by id through the Agent Call door (below).

Sending prose to a structured agent (or typed fields to a prompt-driven one) is the most common execution mistake — the card tells you which you have.

Execute — MCP

plungeai_execute_agent {
  agent: "one-agent",
  prompt: "Summarize the three biggest risks in this text: ..."
}

Always sync (no mode param); session_id continues a conversational session; persona/model/provider/maxTokens/temperature/top_p/ reasoning_effort/thinking_level/streaming override per call. Full parameter table, failures, and plungeai_get_result — references/mcp-execute-and-result.md.

Execute — REST

curl -s -X POST https://api.plungeai.com/v1/agents/one-agent/execute \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "One-paragraph brief: the current state of solid-state batteries",
       "model": "claude-sonnet-5", "maxTokens": 2048}'

sync: false → 202 pointer, redeemed at GET /v1/agents/results/{workflowId}/{taskId} (poll on 404 not_ready). stream: true → an OpenAI-shaped chat.completion.chunk SSE instead of a JSON body. Full field list, streaming shape, error catalogue, and the polling pattern — references/rest-agents-plane.md.

Over the One API — the agents plane

Same ozk_ key (plungeai-api-setup). The three surfaces side by side:

What builders get wrong:

• Only persona is forwarded among the capability fields. skills, experts, backgrounds, plugins and mcp sent here are ignored without an error: put them on a type: harness task (plungeai-skills-plugins).
• A 404 not_ready can be forever. A pointer that is not yours, or never existed, reads not_ready exactly like a run still in flight: cap your poll loop (2s+ steps). The terminal answers are 409 execution_failed (the message is the run's error) and 422 empty_completion (the model returned no visible content: raise maxTokens to 64 or more, or change the model).
• A pinned model is checked before the run opens (422 unknown_model; send provider next to it, and take the slug from GET /v1/models — plungeai-models).
• 424 connection_required carries error.connect ({provider, method, link}) for a connection-tier agent; read the card's credential first (plungeai-tools-connectors).
• MCP format is markdown or json. The default is markdown for an AI reader to relay verbatim; format: "json" on plungeai_get_result returns the run's status record plus result and tasks. REST takes json, yaml, markdown or text.
• A replayed x-trace-id is 409 duplicate_execution_id; send a fresh UUID or none. The workflow_id in every answer is the execution id the /v1/executions routes take (also the X-Execution-Id header on streamed and non-JSON answers).
• A paused agent turn replies with an action_token; send the same call again with approved: true and that token (both, or 400 invalid_params), allow_scope once | run | always.

Your saved agent or bot by id — the Agent Call door

POST /v1/execute (level 3 of the One API) takes the program as its body and always runs it through the engine, so a saved bot keeps its stored policy — permission presets, admin locks, spend caps — on this door as on every other:

curl -s -X POST https://api.plungeai.com/v1/execute \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"agent": "<saved id>@3", "input": "Check the pricing page"}'

• agent: <id> runs the live YAML; agent: <id>@3 pins snapshot 3 (the answer carries x-ocean-version: 3). A building-block id (agent: brave-agent + its own fields, or a bare agent: one-agent + prompt) runs as a one-task workflow; workflow: or root tasks: runs inline YAML.
• Root keys that steer the call: input, inputs, format, user_context, stream (SSE), dry_run (validates and reports {kind, agent, tasks, warnings}; no run, no row, no spend) and on_behalf_of (run a connection-tier agent on your customer's connected account).
• Answers carry x-ocean-agent, x-ocean-tasks, x-ocean-version. 404 agent_not_found for an id that is not yours; 400 invalid_body for a malformed ref or a non-boolean flag.
• The same bot is plungeai_execute_workflow {workflow_id} over MCP and ocean-cli workflows run <id> in a terminal. The per-id route POST /v1/workflows/{id}/execute is unchanged: the three API levels all stay. Every route and error: plungeai-api-setup (references/bots-and-door.md); the bot's own keys and policy: plungeai-bot-agent.

Redeem a result later

plungeai_get_result {execution_id: "<id from the run's footer>"}

Every execution — even a single agent call — hands back a workflow_id/task_id (or execution_id) pair you can redeem later, or read one step's output with task_id.

Gotchas

• "Show me my agents" ≠ the registry. Users mean their saved workflows (plungeai_list_workflows); plungeai_list_agents is the platform's own building-block catalog, for when YOU are composing.
• plungeai_execute_agent has no async mode. For a long single-agent run, use the One API with sync: false, or wrap it in a one-task workflow via plungeai_execute_workflow {mode: "async"} (plungeai-workflows).
• Unknown model fails BEFORE the run starts (needs_input / 422 unknown_model), with near-match suggestions — never a silent bad default.
• Idempotency. Payment-, messaging-, and automation-class agents may duplicate side effects on re-runs. Check execution status before re-firing a call that may already have acted.
• A 502 result_unavailable on a sync call isn't always a failure — the result may land late; its error body still carries workflow_id/task_id to redeem with.

Related skills

• plungeai-discovery — search, full cards, tool contracts, templates.
• plungeai-tools-connectors — structured tool-agents, typed params, connected-account status.
• plungeai-models — provider factory (model/provider fields) and the money plane for your own code.
• plungeai-workflows — chain several agents; async execution surface for long single-agent runs.
• plungeai-results-traces — tracing a run end-to-end, execution history, cost.

Reference pages