plungeai-agents

Run a PlungeAI registry agent: recognize the two kinds (prompt-driven vs structured tool-agents), execute a prompt-driven one sync or async (plungeai_execute_agent MCP / POST /v1/agents/{id}/execute REST, 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, finance, CRM, …), 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.

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

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: "llm-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/llm-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.

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