agent_run_start
Start a TeamShared Cloud Agent (router + FastMCP). Not a Cursor VM.
The worker mints a short-lived org tsk_ and runs the tool loop against in-process FastMCP. github= is an optional checkout. One active run per work item — a busy run returns status=busy. When the compact bootstrap profile is non-empty it is prepended (capped). When work_id has playbook_slug, that named playbook is prepended after the profile, its skills listed by name for the run to load with memory_skill_get. Unset slug or omitted work_id: no playbook inject. run.model is the model that will run: a model= the router would refuse is substituted (see model_substitution). agent_slug= binds the run to an agent record (#733); the result's agent.inherited says which settings came from it. When that record has a spend cap and the period's spend is at or over it, the start is refused (agent_budget_exceeded) and nothing is queued. From inside a run, tools cannot exceed that run's allowlist (tools_not_permitted when nothing overlaps), and the new run is nested under that run. A chain of nested starts stops at a fixed depth (nesting_depth_exceeded). With no calling run, parent_run_id must name a run in this org (parent_run_not_found, or bad_id).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Optional workspace slug stored on the run | |
| agent | No | Override agent attribution label | |
| model | No | Router model id (prefixed, e.g. openrouter/...); omit to use TEAMSHARED_AGENT_RUN_MODEL. An id the router would refuse (no routable prefix) is replaced by that default and the result carries model_substitution={requested, model, reason}. | |
| tools | No | Tool name/prefix patterns this run may bind (e.g. ['work_*','memory_recall']). Narrows the box allowlist; never widens it. Omit for the deployment default. From inside a run, the list cannot exceed that run's tools. | |
| github | No | owner/repo checkout. Omit on a work item tagged code to use the org's only connected repo (github_repo_list); omit otherwise for a no-repo run. A slug the App does not serve is refused once an installation exists. A failed installation read refuses a named slug (github_binding_unavailable) | |
| prompt | Yes | Task prompt for the TeamShared Cloud Agent | |
| runtime | No | Every value starts a TeamShared Cloud Agent on the in-box worker. Omit it, or pass cloud or teamshared. cursor, cursor_cloud, and cursor-cloud are refused with runtime_disabled while TEAMSHARED_CURSOR_CLOUD_RUNTIME_ENABLED is off; with the flag on those names still run on the same TeamShared worker. | |
| work_id | No | Work item UUID; reuses that item's TeamShared agent | |
| agent_slug | No | Agent record to run as (agent-<label> or <label>; see agent_list). The run inherits the record's model and tools: an explicit model= wins, an explicit tools= can only narrow the agent's. Unknown, paused or archived agents are refused. A record that has spent its budget_usd cap for the current period is refused with agent_budget_exceeded; a run already going is left to finish. | |
| spawned_by | No | Parent Agent slug or label (dispatcher that spawned this worker) | |
| parent_run_id | No | Parent agent run UUID when this is a nested child run. From inside a run, that run is the parent. With no calling run, the id must be a run in this org | |
| auto_create_pr | No | Hint to open a PR when a coding worker finishes. Defaults to true when the run checks out a repo, and stays unset when it does not | |
| durable_memory | No | Nested runs are ephemeral: no capture session or run memory of their own, the parent's work thread is the record. Set true for a specialist that must keep its own memory. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||