Answer a run that is paused on a human-input request (from list_pending_inputs). For an approval, set approved=true/false. For an input request, set value to the requested text. A successful answer starts a continuation run: the returned run_id is that new continuation run, not the parked run, and is the id to poll with get_run_result.

Stop an in-flight agent run. Cancellation is asynchronous: a successful call returns status "cancelling"; poll get_run_result until the run becomes "cancelled". A run that already finished cannot be cancelled.

Get or create an agent by name: a persistent cloud environment running plori's agent, with its own disk, tools, and memory. Create one when the work should accumulate somewhere the user can return to: a project with files that build up, a repo to keep checked out, tools to install once and reuse, or a long job to hand off. You do not need one for a question you can answer yourself or for a one-off script with no state worth keeping. If the account already has an agent with this name, that agent is returned (marked "existing": true) instead of a duplicate — safe to call repeatedly, and the right way to reconnect to an agent you used before. Creation is subject to the account's agent-count limit. The Plori Router chooses the model for each task.

Create an empty workflow. Returns the new workflow, including its id and — for a webhook trigger — its hook URL. trigger_kind defaults to "manual" (run it on demand with run_workflow); "cron" needs a cron_expr; "webhook" mints a public hook URL. trigger_kind is not read from description: a schedule stated only there leaves the workflow manual. The build can still change it — when the owning agent gives the workflow a schedule or webhook trigger step, trigger_kind and cron_expr follow that step. A new workflow has no steps and cannot run until its owning agent builds them.

Permanently delete an agent and revoke its disk. This cannot be undone. Workflows the agent built are NOT deleted — they belong to the account — but the ones that were live are paused, and none of them run again until you assign them to another agent.

Apply a batch of constrained edits as one new draft version under base_version compare-and-swap. Supported ops are set_params, add_step, remove_step, and add_router. Read the exact current definition with get_workflow_version first; a stale base_version is rejected instead of overwriting concurrent work. Editing does not activate the draft.

Permanently empty one agent's trash. Deleting a file moves it into a trash that keeps counting against the account's disk until this is called — get_disk's trash_bytes says how much a call would free. Only works while the agent's pod is asleep: while it has run recently this returns an error asking you to wait for it to go idle (about two minutes with no run) or cancel the run first.

Get one agent's details (name, type, model, status) by its id, and its mailbox: same-account mail from other agents, open letters first (accepted, delivering, blocked), then applied or undeliverable ones, newest within each group, capped at 20.

Get the authenticated account's US-dollar balance and plan. Running agents spends this prepaid balance, so check it before invoking. For where the money went, use get_usage instead. balance_usd is the dollar-formatted balance.

Get the authenticated account's disk state (included, purchased, used bytes, and monthly cost).

Get a run's status, timing, attributed credits (micro-US-dollars) and tokens, and what it is doing while it runs: last_worklog (the agent's own most recent note), last_tool_step ("running ", or "completed " between calls), last_activity_at, and tool_progress (active calls, last completion time, completed-call count) when telemetry exists. With wait=true it holds your turn until the run finishes, pauses for input, or the hold ends (contract in the server instructions; wait_seconds bounds it). A completed run includes the reply text and a url to its session; files the reply linked come back as absolute URLs in the text and as a "files" list, fetched with the same bearer token you called this tool with. A failed or cancelled run includes its cause, whether it is retryable, and an "error" object saying what happened, whether the work was charged and what to do next. Status "awaiting_input" includes the pending request for answer_pending_input. Once that request is answered, input_status reads "answered" and continuation_run_id names the run to poll next; "cancelled" or "expired" means the run will never resume, so stop polling it. Keep polling a non-terminal run at poll_after_seconds.

Get the authenticated account's usage rollup (US-dollar spend by role, meter, and agent, with recent runs). Use this to answer where the money went; for the current balance use get_credits.

Get one workflow's metadata and step projection. The projection is the version pinned for execution (active_version), falling back to current_version for a draft that has not been activated.

Get one workflow execution's status, billing, timing, credits, and full persisted per-step input/output payloads. fault explains why a non-succeeded execution ended. user means the workflow's own steps or limits. A platform fault is never billed. fault is null when the execution succeeded. billed is the billing flag. Use this tool to poll a run or inspect each step. list_workflow_executions omits step payloads.

Get one exact workflow version, including its full builder definition with step parameter values and its value-light projection. Use current_version from get_workflow unless you intentionally need an older version.

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 run that pauses for a human returns status "awaiting_input" with the request inline; answer it with answer_pending_input. 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.

List the agents owned by the authenticated account, newest first, with each one's model, live session status, web page url and when it last ran. An agent whose model is empty is not unconfigured: effective_model says what a run will use, and plori-auto means the hosted router chooses per turn.

List the authenticated account's third-party OAuth connections, including each provider's status, authorization and expiry times, and configured scopes. Read needs_reauth for whether a human has to go and reconnect one; status is the same fact spelled out (authorized needs no action, reconnect_needed and unauthorized do). Never derive it from expires_at: tokens refresh lazily when used, so an authorized row may have a past expires_at, and authorized with expires_at=null means the grant never expires. Token and client-secret material is never returned.

List the agent's runs that are paused awaiting a human approval or input (the HITL queue). A row with a "consent_tool" is a write-consent approval: answering it with always_allow=true also stops the agent asking for that tool, and scope="thread" allows only the rest of this conversation's calls to the same connection, method and host. A request whose session has already moved on is not listed: a later run in that conversation has completed, so answering it would resume a superseded turn.

List an agent's run history, most recently STARTED first, with each run's status, timing and attributed cost. Returns the newest 20 runs unless you pass limit (maximum 100). When more history exists the result carries next_cursor; pass it back as cursor for the next page, and stop when it is absent. Each row's session_id (the same value as thread_id) continues that conversation through invoke_agent. tool_progress is null for a terminal run and for a run with no telemetry; a non-terminal row reports the same progress get_run_result does. A row with input_expired is parked on a question its session has already moved past — start a new run rather than answering it.

List a workflow's recent executions, most recent first. Each record includes status, fault, billing, trigger source, timing, credits, and timestamps. fault explains why a non-succeeded execution ended. user means the workflow's own steps or limits. A platform fault is never billed. fault is null when the execution succeeded. billed is the billing flag.

List the workflows owned by the authenticated account, with each one's status, trigger, current version, and the agent that holds it (agent_id). Each workflow belongs to one agent — the one that built it — and that agent is the only one that can edit or run it from a chat. Pass agent_id to list just that agent's workflows, or agent_id="none" for the unassigned ones (created here or in the web app with no agent).

Run a workflow now — a real execution with real side effects, billed like any run (a flat per-execution fee plus model usage). Waits briefly and returns the execution: terminal if it finished, else status "running" to poll with get_workflow_execution. The workflow must already have steps.

Schedule a ONE-SHOT deferred run of an agent: it will be invoked once, later, with the given prompt, billed like any run, and appears in list_runs when it fires. Provide either delay_seconds (relative) or fire_at (an RFC3339 timestamp). For a recurring schedule, use create_workflow with a cron trigger instead.

Assign one of your agents to a workflow. Use this after delete_agent reports paused workflows, or when run_workflow returns workflow_agentless. If base_version is omitted, this tool reads the workflow's current version before it assigns the agent. A supplied stale base_version is rejected with the current version.