> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plungeai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# plungeai_execute_agent

> Execute a single PROMPT-DRIVEN agent (e.g.


Execute a single PROMPT-DRIVEN agent (e.g. "llm-agent", or "skill-agent" with a persona). Pass session_id to start/continue a conversational agent. Structured tool-agents (cards with a Parameters table, e.g. markitdown, weather-agent) take typed fields, not prose — use plungeai_get_tool_contract + plungeai_execute_tool for those. Always answers with a structured outcome (never a raw error) — follow the remediation instead of retrying the identical call.

Execute a single prompt-driven agent (for example `llm-agent`, or `skill-agent` with a persona). Pass `session_id` to start or continue a conversational agent. Structured tool-agents (cards with a Parameters table, such as `markitdown` or `weather-agent`) take typed fields, not prose: use `plungeai_get_tool_contract` and `plungeai_execute_tool` for those. Always answers with a structured outcome, never a raw error: follow the remediation instead of retrying the identical call.

**Returns.** `ok` with the agent's output and the execution-id footer. `unavailable` for an unknown or inactive agent, with live alternatives and no run created. `needs_input` for a model that is not in the catalog (``Unknown model `<id>` … Nothing was executed.``) with up to five near matches. `needs_approval` / `needs_input` when the agent pauses. Failures are classified into an outcome.

Runs a model and costs credits (not verified here):

```bash
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_execute_agent","arguments":{"user_request":"ask llm-agent what a Durable Object is","agent":"llm-agent","prompt":"In one sentence: what is a Cloudflare Durable Object?","model":"claude-sonnet-4-5","max_tokens":80}}}'
```

<Note>
Two parameters recur across the tools: `user_request` (on every tool: a string of up to 4,000 characters, optional; clients should always send it) and `format` (`markdown` by default, or `json`). Both are described once in [Recurring parameters](/mcp-reference/overview#recurring-parameters) on the MCP overview.
</Note>

## Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user_request": {
      "description": "The user's original request, verbatim and in their own words, before you translated it into this call. Always include it — the platform uses it for request context, routing and support diagnostics.",
      "type": "string",
      "maxLength": 4000
    },
    "agent": {
      "type": "string",
      "maxLength": 256
    },
    "prompt": {
      "type": "string",
      "maxLength": 65536
    },
    "persona": {
      "type": "string",
      "maxLength": 256
    },
    "model": {
      "type": "string",
      "maxLength": 256
    },
    "provider": {
      "type": "string",
      "maxLength": 256
    },
    "maxTokens": {
      "type": "integer",
      "minimum": 1,
      "maximum": 64000
    },
    "max_tokens": {
      "type": "integer",
      "minimum": 1,
      "maximum": 64000
    },
    "temperature": {
      "type": "number",
      "minimum": 0,
      "maximum": 2
    },
    "top_p": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "reasoning_effort": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high",
        "xhigh"
      ]
    },
    "thinking_level": {
      "type": "string",
      "maxLength": 256
    },
    "streaming": {
      "type": "boolean"
    },
    "session_id": {
      "type": "string",
      "maxLength": 256
    },
    "format": {
      "default": "markdown",
      "description": "markdown (default): rendered for an AI reader · json: the same outcome as a JSON document in `text` plus `structuredContent`",
      "type": "string",
      "enum": [
        "markdown",
        "json"
      ]
    }
  },
  "required": [
    "agent",
    "prompt"
  ]
}
```