plungeai-agents
Executing agents over MCP — execute_agent, get_result
Two execution styles, chosen by the agent's card:
Two execution styles, chosen by the agent's card:
- Prompt-driven agents (a prose brief does the work — research, writing,
LLM tasks) →
plungeai_execute_agent. - Structured tool-agents (cards with a Parameters table — posting,
document conversion, weather, payments) take typed fields, not prose →
plungeai_get_tool_contractthenplungeai_execute_tool(seeplungeai-tools-connectors).
When unsure, fetch the card (plungeai_list_agents {agent_id}, see
plungeai-discovery) — a Parameters table means structured.
plungeai_execute_agent
Purpose: run a single PROMPT-DRIVEN agent once. Pre-built agent cards
(capability packs rather than deployed services) are lowered automatically to
a harness run — same call shape either way. Always sync (no mode param).
Parameters
| Param | Type | Notes |
|---|---|---|
agent | string, required | Agent id from a live plungeai_list_agents search. |
prompt | string ≤65536, required | The brief. |
persona | string | Persona id to inject. |
model | string | Model override — must exist in the platform model catalog (see failure below). Omit to use the agent's default. |
provider | string | Provider id override (anthropic, openai, gemini, …) — pairs with a pinned model. |
maxTokens | int 1–64000 | Output cap. |
max_tokens | int 1–64000 | Same as maxTokens — the One API / snake_case spelling. |
temperature | number 0–2 | Sampling temperature. |
top_p | number 0–1 | Nucleus sampling. |
reasoning_effort | low | medium | high | xhigh | Reasoning budget on models that expose one. |
thinking_level | string | Provider thinking-level id (Gemini-style), forwarded to the task as-is. |
streaming | boolean | Default on — the engine streams the run internally so the answer lands the moment the model finishes; false switches that off. No token stream reaches an MCP client either way (results are one envelope). |
session_id | string | Start/continue a conversational agent session — reuse the same id across turns. |
format | markdown | json | Response serialization; default markdown. |
Example
{"user_request": "summarize this week's AI safety news",
"agent": "llm-agent",
"prompt": "Summarize the most important AI safety developments this week, with sources."}Returns: an outcome envelope. ok → the agent's final markdown +
execution-id footer. A conversational agent that stops mid-dialog returns
needs_approval / needs_input with a ⏸ block → relay and use
plungeai_continue.
Failures & fixes
- Unknown agent id →
unavailable: "No such agent ... ids cannot be guessed"- live alternatives. Re-discover; never retry the same id.
- Inactive agent id →
unavailable: "notstatus:active". Pick an alternative from the remediation or a fresh search. - Unknown
model→needs_inputBEFORE anything runs, with near-match catalog models. Omitmodelor pick a suggested catalog id. (The preflight exists because a bogus model would otherwise time out minutes later with no cause.) - Structured tool-agent called with prose → may run its default operation or
reject inputs; switch to the contract +
plungeai_execute_tool.
plungeai_get_result
Purpose: retrieve the output of one of the caller's executions by
execution id — the id from any run's footer, from plungeai_executions, or
from plungeai_schedule {action: "runs"}. Read-only, ownership-checked.
Parameters
| Param | Type | Notes |
|---|---|---|
execution_id | string | Preferred id param (matches run_mission/get_workflow_status/continue output). |
workflow_id | string | Back-compat alias for execution_id. Engine ids (exec-..., hyphen) also resolve. |
task_id | string | Read one step's output instead of the final result. Step ids come from the result's own "Steps in this run" index. |
format | markdown | json | Response serialization; default markdown. |
Exactly one of execution_id/workflow_id is required (enforced at call
time, not by the schema — both stay optional in the advertised tool
signature).
Example
{"user_request": "show me the full result of that run",
"execution_id": "d3adb33f-...."}Returns (full result): an identity header (workflow name — the question
— timestamp — execution id), the final output verbatim, then as applicable:
a Steps in this run index (multi-task runs persist only the final task's
output; every other step is readable via task_id), the full
Conversation thread (all follow-up turns, Studio-parity), and a ⏸
continuation block if the run is paused. Show it to the user whole.
Failures & fixes
- "No result found for <id>, or it is not one of your executions." → wrong
or foreign id; take the id from the run's own footer or
plungeai_executions {action: "list"}. - "still running. Poll plungeai_get_workflow_status, then retry." → do that; don't hammer get_result.
- "This run failed: <reason>" → surface the reason; fix per its content
(often a
needs_*classification on the original call). - "completed, but its stored result is no longer retrievable (expired from SharedMemory)" → step outputs and old results expire; only the final result blob is durable. Re-run if the user needs it again.
- Scheduler run ids (
exec_..., underscore) never resolve here → useplungeai_schedule {action: "runs"}and take its Execution ID column (seeplungeai-scheduling).
Putting it together — the canonical single-agent run
1. plungeai_list_agents {search: "summarize a pdf"} → llm-agent (or a domain agent)
2. plungeai_execute_agent {agent: "llm-agent",
prompt: "Summarize the attached brief in three bullets."} → ok, final markdown + execution id
3. plungeai_get_result {execution_id: "<id>"} → re-fetch the same output later, or a step's output by task_idFor long-running prompt-driven work, wrap it in a one-task workflow via
plungeai_execute_workflow {mode: "async"} (plungeai-workflows) — a bare
plungeai_execute_agent call has no async mode.