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


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](https://skills.plungeai.com/plungeai-agents.zip) · [View raw SKILL.md](https://skills.plungeai.com/plungeai-agents/SKILL.md)

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 (`one-agent` — the LLM agent, with an optional `persona` — and 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` |

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

```json
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`](/skills/plungeai-agents/references/mcp-execute-and-result).

## Execute — REST

```bash
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`](/skills/plungeai-agents/references/rest-agents-plane).

## Over the One API — the agents plane

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

| Job | REST | MCP | CLI `ocean-cli agents …` |
|---|---|---|---|
| list | `GET /v1/agents?limit=&offset=` (≤ 100) → `{agents: [card + credential], count}`; `GET /v1/agents/categories` → `{categories: [{name, count}], count}` | `plungeai_list_agents` | `list`, `categories` |
| run | `POST /v1/agents/{id}/execute {prompt \| input \| messages, persona?, model?, provider?, maxTokens?, temperature?, top_p?, reasoning_effort?, thinking_level?, system?, sync?, stream?, user_context?, format?}` | `plungeai_execute_agent` (always sync) | `run ID PROMPT [--stream]` |
| redeem | `GET /v1/agents/results/{workflowId}/{taskId}` → `{content, content_type, workflow_id, task_id}` | `plungeai_get_result` | `result WORKFLOW_ID [TASK_ID]` |

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:

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

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

## Reference pages

<CardGroup cols={2}>
<Card title="Executing agents over MCP — execute_agent, get_result" icon="file-text" href="/skills/plungeai-agents/references/mcp-execute-and-result">
Two execution styles, chosen by the agent's card:
</Card>
<Card title="Agents — the registry, discovery, and execution" icon="file-text" href="/skills/plungeai-agents/references/registry">
An agent is a deployed capability with a uniform interface: it accepts a task, does one job well (search the web, call an LLM, convert a document, post to…
</Card>
<Card title="Agents plane — /v1/agents" icon="file-text" href="/skills/plungeai-agents/references/rest-agents-plane">
Execute any active platform agent with a plain prompt.
</Card>
</CardGroup>