run_agent
Execute a task via a pooled agent, with subagents, findings tool, and dynamic capabilities. Start new or resume existing sessions.
Instructions
Run the pooled agent live and record every agent that participates. The entry's first-ever run starts a fresh session; later runs resume it. Requires the claude CLI at runtime.
Every run is granted the full capability set — for the main agent and, when named, for each
dispatched subagent: fan-out subagents (resolved from their own pool entries and wired in via
with_subagents), the run-scoped findings-writer (with_findings_tool), and dynamic capability
acquisition (with_acquire_tool). The findings tool needs the run id at wiring time, so the run
is started here and its id handed to run_with_capture rather than minted inside it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | What the generated agent should do — the job it is being built to perform. | |
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. | |
| resume_agent_id | No | When set, continue one specific previously-dispatched subagent (its `AgentId`, captured from an earlier `RunOutcome.agent_runs[i].agent_id`) rather than just re-prompting the main agent: this run resumes the main session, is granted the harness's `SendMessage` tool (`with_agent_resume`), and its literal turn wraps `task` as `"Resume agent {id} and now: {task}"` — while the run record still logs `task`. It composes with `subagent_agent_keys`, since the resumed turn may dispatch further subagents too. | |
| subagent_agent_keys | No | A subagent name → pooled `agent_key` mapping; each referenced entry's spec is wired in as a dispatchable subagent that also carries the findings and acquire tools. Empty runs the agent solo. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run | Yes | One invocation of a pooled agent — appended when a run starts and stamped when it finishes. Distinct from `PoolEntry`'s "current state per problem" role: an entry has many runs over its life. `finished_at` and the outcome fields (`output`, `structured_output`, `total_cost_usd`, `error`) stay None while the run is in flight, and the outcome fields stay None afterward too if the run finished without a captured outcome. `error` is set instead of the outcome fields when the run raised rather than completed. | |
| output | Yes | The collected assistant text of a finished run, persisted on its record; text over 200000 characters is truncated to that bound. | |
| agent_runs | Yes | ||
| total_cost_usd | No | ||
| structured_output | No |