Invoke agent
invoke_agentSend a message to an agent and get its reply or a run_id to poll for long-running work that outlives a single request.
Instructions
Send a message to an agent and return its reply, or a "running" run_id to poll with get_run_result. Use it for work that should outlive a single request: files written now and read later, software installed once and reused, a repo kept checked out, or a long job handed off. The hold and polling contract is in the server instructions: wait=false returns the run_id at once, wait_seconds bounds the hold, and agent turns can take minutes. A running result reports last_worklog, last_tool_step and last_activity_at; a completed one carries the reply text, files, credits (micro-US-dollars) and tokens; every result carries session_id (pass it back to continue the conversation) and a url a human can open. An account's plan caps how many runs it may have in flight at once across all its agents: over the cap returns 429, so wait for a run to finish and retry; turns on one agent are not queued for you. Pass idempotency_key when you might retry, or the retry starts and bills a second run. A paused run returns status "awaiting_input" with the request inline. Show the owner each approval's approve_url. Each external write pauses for the owner's approval in the Plori web app. The calling model cannot approve it. Use answer_pending_input to deny an action or answer a question. Cost scales with how much the agent has to explore: name the exact resources, fields and output format you want, and set max_turn_tokens for a bounded lookup.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Wait for the turn and return the reply (default true); the hold lasts as long as your client keeps the call open, or wait_seconds. Set false to return a run_id immediately and poll get_run_result — prefer this for long or tool-heavy turns so the call doesn't block your own turn. | |
| message | Yes | The message to send to the agent. | |
| agent_id | Yes | The agent's UUID. | |
| session_id | No | Optional thread/session id to continue an existing conversation (a previous invoke_agent or get_run_result result carries it as "session_id"); omit to start a new one. | |
| callback_url | No | Optional callback URL for this run. Must use http or https and resolve only to public addresses. | |
| wait_seconds | No | Optional: how many seconds to wait for the turn before returning a "running" run_id (maximum 1800). Omit to use the window your MCP client can hold. Ignored when wait=false. | |
| callback_secret | No | Optional secret used to sign callback deliveries with HMAC-SHA256. | |
| idempotency_key | No | Optional retry guard: a string you generate for this attempt. Re-sending the same key with the same agent and message within 24h returns the ORIGINAL run instead of starting a second one. Reusing a key with a different message is an error. | |
| max_turn_tokens | No | Optional cumulative cache-weighted token ceiling for this turn. 0 or omitted uses the agent's default of 2,000,000; the maximum is 5,000,000. The agent reserves its final 2% for a tool-free wrap-up. | |
| max_turn_seconds | No | Optional soft wall-clock budget for this turn in seconds, maximum 14,400. 0 or omitted uses the deployment's configured default, and where none is configured a turn has no wall-clock budget at all. It schedules an in-loop checkpoint and does not cancel the run. | |
| max_advisor_spend_micro_usd | No | Optional maximum advisor-completion spend for this turn in micro-US-dollars. 0 disables advisor completions. Omit it to use the agent setting; when neither is set, at most two advisor calls can run. The maximum is 5,000,000. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | A deep link to this run's session in the plori web app. | |
| hint | No | What to do next with this run, in one sentence. Present only while the run is non-terminal. | |
| text | No | The assistant's reply once the run has finished. While a run is still going this is the run's own status message, not an answer, and is often absent — read last_worklog and last_tool_step instead. | |
| cause | No | Machine-readable cause for a non-normal terminal state. | |
| error | No | Why a terminal error or cancelled run failed, whether it was charged and what to do about it. Absent for a run that is still going or that finished normally. | |
| files | No | Files on the agent's disk that this reply linked, in the order they appear. Each url is fetchable with the bearer token you called this tool with. Absent when the reply linked none. | |
| run_id | Yes | The public run identifier. | |
| status | Yes | The current run status. | |
| tokens | No | Attributed token count; null when attribution is unavailable. | |
| advisor | No | Advisor calls used and allowed, spend this turn, and its optional spend cap in micro-US-dollars. | |
| credits | No | Attributed spend in micro-US-dollars; null when attribution is unavailable. | |
| ended_at | No | When the run reached a terminal state. | |
| retryable | No | Whether sending the same message again could plausibly succeed. False for a cause the same request would hit again, including time_limit — split the work or raise max_turn_seconds instead of retrying it unchanged. | |
| session_id | Yes | The durable conversation/session identifier. | |
| started_at | No | When the run started. | |
| stop_reason | No | Controller-selected stop reason, when present. | |
| input_status | No | The durable status of this run's human-input request, when it has one: pending, answered, cancelled or expired. cancelled and expired are terminal — that run will never resume, so stop polling it. | |
| last_worklog | No | The agent's most recent one-sentence note about what it is doing, from the run's durable event log. Absent for a terminal result and for a run that has written none. | |
| input_expired | No | True when this run is parked on a question its session has already moved past: a later run in the same conversation has completed. Do not answer it; start a new run instead. | |
| poll_after_ms | No | Legacy spelling of poll_after_seconds in milliseconds; the two always agree. Prefer poll_after_seconds. | |
| resume_run_id | No | The exact auto-resume successor for an interrupted run; poll this run next. | |
| resume_status | No | Auto-resume disposition for an interrupted run: pending, resumed, failed, or unknown. | |
| tool_progress | No | Durable tool execution progress; absent when this run has no tool-progress telemetry. | |
| usage_by_role | No | Attributed spend, tokens, and model-call counts split into executor, advisor, and reviewer roles. | |
| last_tool_step | No | What this run last did with a tool: "running <tool>" while a call is in flight, otherwise "completed <tool>" for the most recent finished call. Absent for a terminal result and for a run with no tool-progress telemetry. | |
| pending_inputs | No | Human inputs blocking an awaiting_input run. | |
| elapsed_seconds | No | Seconds since the run started; absent for a terminal result. | |
| upstream_status | No | The model provider's HTTP status when this run died on an upstream fault; absent otherwise. | |
| last_activity_at | No | When the run last wrote a note or finished a tool call. Absent for a terminal result and for a run that has done neither. | |
| last_heartbeat_at | No | Most recent durable executor heartbeat. | |
| poll_after_seconds | No | Suggested seconds before polling again, paced to this run's recent tool-completion rate; absent for a terminal result. | |
| continuation_run_id | No | The exact continuation created for an answered input; poll this run next. |