---
name: plungeai-agents
description: "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`."
---

# PlungeAI Agents

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

| Kind | How you recognize it | How to execute |
|---|---|---|
| **Prompt-driven** | Card describes free-text input (`llm-agent`, `skill-agent`, search agents like `brave-agent`, `exa-agent`) | This skill: `plungeai_execute_agent` / `POST /v1/agents/{id}/execute` with a `prompt` |
| **Structured tool-agent** | Card carries a **Parameters table** / operations (document converters, weather, data-table, calendar, payments) | `plungeai-tools-connectors`: fetch the contract, then typed `params` |

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

```json
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

```bash
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

```json
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.