Agents — the registry, discovery, and execution

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 Slack, enrich a CRM contact), and stores its result where the platform can hand it to the next step. Agents are the building blocks everything else composes: workflows chain them, missions call them, tools are a structured sub-species of them.

The catalog is live and active-only: every listed agent is deployed and callable, and execution refuses any id that is not currently active. That is why ids must come from a live lookup, never from memory or an example you saw yesterday.

Two kinds of agent — 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 agent card tells you which kind you have.

Terminology trap: "my agents"

Users call their saved workflows "agents" too. An unqualified "show me my agents" means their saved workflows → plungeai_list_workflows. The registry (plungeai_list_agents) is the platform capability catalog — building blocks like exa-agent — and is what YOU use when selecting components. Only use the registry listing when the user explicitly asks about platform capabilities, or when you are composing.

Discovery

MCP: plungeai_list_agents

search is a hybrid semantic + keyword query over live agent cards. Describe the capability in natural language and trust the ranking:

plungeai_list_agents {search: "convert pdf to markdown"}
plungeai_list_agents {search: "web search"}
plungeai_list_agents {category: "financial"}
plungeai_list_agents {agent_id: "exa-agent"}     # full card for one agent

• Prefer search/category filters. An unfiltered listing returns the whole catalog (large, slow to read, rarely what you want — discover, don't page through).
• Fetch the full card (agent_id) before first use of an unfamiliar agent. Cards carry: operations, parameters, good-at examples, and — critically — "Not for → use X instead" redirects that save you a wrong pick.

One API

# List active agents (paged)
curl -s "https://api.plungeai.com/v1/agents?limit=20&offset=0" \
  -H "Authorization: Bearer ozk_YOUR_KEY"

# Hybrid search over the whole registry (agents, mcp-servers, …)
curl -s "https://api.plungeai.com/v1/discovery/search?q=web%20search&kind=agents&fields=summary" \
  -H "Authorization: Bearer ozk_YOUR_KEY"

# Ask the platform to recommend the best card for a task
curl -s -X POST https://api.plungeai.com/v1/discovery/recommend \
  -H "Authorization: Bearer ozk_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"type": "agent", "task": "find recent news about a company"}'

# Full card, markdown LLM view
curl -s https://api.plungeai.com/v1/discovery/cards/agent/exa-agent \
  -H "Authorization: Bearer ozk_YOUR_KEY"

Search response envelope: {cards: [...], count, searchMethod}. Each card carries id, name, type, category, status, description, tags. Add include=quality to get a quality block per card (score, success_rate, runs — null when unmeasured); use it to prefer proven agents when several match.

mode=hybrid|keyword|vector forces a search leg; the default hybrid is almost always right — do not re-implement ranking client-side.

Categories (orientation, not an inventory)

Agents are organized by domain: search (Brave, Tavily, Exa, Perplexity, Serper), generic LLM (llm-agent, skill-agent), documents, financial, CRM (large family: enrichment, outreach, scoring), coding, legal, healthcare, logistics, marketing, market research, social, payments, e-commerce, news, travel, design, automation, Google Workspace (gmail, calendar, drive), Microsoft 365, and more. Category names are stable; membership is not — discover live.

Stable id shape: kebab-case, usually <thing>-agent (brave-agent, exa-agent, llm-agent). Beware near-misses: brave-agent exists, brave-search may not — take the id character-for-character from the search result.

Execution

MCP: plungeai_execute_agent

plungeai_execute_agent {
  agent: "llm-agent",
  prompt: "Summarize the three biggest risks in this text: ...",
  session_id: "optional — start/continue a conversational session"
}

• The id parameter is agent (not agent_id, which belongs to the tool-contract door). Optional per-call overrides: persona, model, maxTokens.
• Returns a structured outcome. ok → the result content (final, user-ready markdown — relay verbatim). Anything else names the remediation (see SKILL.md "Trust fences").
• session_id makes conversational agents stateful across calls.
• This tool has no mode parameter — it is always sync. For a long single-agent run, use the One API with "sync": false (below), or run it as a one-task workflow via plungeai_execute_workflow {mode: "async"} → poll plungeai_get_workflow_status, fetch with plungeai_get_result.

One API: POST /v1/agents/{id}/execute

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": true
  }'

Sync response (default):

{
  "content": "…final markdown…",
  "workflow_id": "exec-…",
  "task_id": "…",
  "request_id": "…"
}

input is an alias for prompt; persona injects a persona (see the plungeai-skills-plugins skill); model/maxTokens override per call.

Async: "sync": false → 202 with {workflow_id, task_id, request_id}. Redeem:

curl -s https://api.plungeai.com/v1/agents/results/{workflowId}/{taskId} \
  -H "Authorization: Bearer ozk_YOUR_KEY"
# 200 {content, content_type, workflow_id, task_id} | 404 {error: {code: "not_ready"}}

404 not_ready means still running — poll again; it is not a failure.

Errors you will actually see

Under the hood (why it behaves this way)

Every agent implements the same interface — executeTask(yaml) → string over Cloudflare service-binding RPC — which is what makes agents interchangeable inside workflows and lets the engine fan them out in parallel with ~10-20 ms dispatch overhead. Results are written to SharedMemory keyed by (workflow_id, task_id, your user id), which is why every execution — even a single agent call — hands back a workflow_id/task_id pair you can redeem later. See the plungeai-memory skill for retrieval and plungeai-workflows for composition.

Checklist before any agent call

1. Id from a live search (never memory).
2. Full card read if unfamiliar — right kind (prompt vs structured), right agent ("Not for" redirects honored).
3. Right door: prompt-driven → execute_agent; structured → contract + execute_tool.
4. Long run → async mode.
5. Outcome remediation followed; fences surfaced, never retried blind.