Agents and workspaces

Open Workspaces > Directory and click the new-agent action.

Give the agent a role-based name and one-sentence objective. The wizard should preselect an available runtime.

Write a compact role prompt covering responsibility, output format, and boundaries.

Leave tools at None for the first save. Add memory scope, skills, personality, standing orders, or hooks only when the role needs them.

Preview the assembled prompt, save, and reopen the agent.

Open the agent in Workspaces > Directory and inspect Tool Access.

Choose explicit tools or a reviewed Tool Group. Avoid broad shell, file-write, browser, channel-send, or external-system access unless essential.

Set the tool policy so sensitive actions require confirmation.

Save and run a small task that needs one allowed tool and one harmless request for a disallowed tool.

Confirm the allowed call works and the disallowed call is refused or requires a policy change.

In Workspaces > Directory, create a workspace and choose sequential execution.

Add stages in dependency order, for example Researcher → Analyst → Writer → Reviewer.

For each stage, state what input it receives and what output the next stage needs.

Set stop/retry behavior and approval policy. Save.

Preview the workspace to check there is no circular or missing handoff.

Create a workspace and choose parallel/mirrored execution.

Add agents that can work from the same original task, such as security reviewer, UX reviewer, and performance reviewer.

Give every branch the same scope and a structured result format so outputs can be compared.

Add a final synthesis/reviewer stage if the workspace supports combining results.

Save and check Monitor before launching a resource-heavy local run.

Open Workspaces > Run, choose the workspace, and enter a task with a concrete deliverable.

Start the run and watch stage status and messages. Do not leave a sensitive approval waiting unattended.

For each confirmation, inspect the agent, tool, arguments, and affected target before approving or rejecting.

Use Stop if the scope is wrong or the run loops. Correct the task, tool policy, or route.

If one stage fails, use its retry/resume action so later skipped stages continue after recovery.

Open the run in Workspaces > Run and review its summary first.

Use Export Report and choose a destination outside temporary/cache folders.

Open the exported report and check the workspace identity, task, stage order, statuses, approvals, errors, and final output.

Redact secrets or personal data before sharing the report outside your trusted team.

Understand what a sub-agent is before you spawn one. It is a child session with its own prompt, its own tool allowance, and its own budget — not another workspace member. It runs, reports, and ends.

Use a sub-agent for a side quest inside one conversation. Use a workspace when you want a repeatable team you run again next week.

In an agent-mode chat, ask for the work to be delegated, or call the sessions_spawn tool directly. Give it a name and the prompt — the task itself.

Restrict its tools. The spawn accepts either Only allow these tools or Block these tools — prefer the allow list and name the two or three tools the task genuinely needs.

A sub-agent inherits nothing by accident when you set an allow list. This is the single most useful safety control here.

Set a timeout. The default is 300 seconds. Lower it for a quick lookup; raise it only when you have watched the task take longer.

A timed-out spawn is marked timedOut and stops. That is the intended outcome for a task that stalls — not a failure you need to debug.

Optionally override the model or provider for this one spawn, and set a token budget, so a cheap helper does not run on your most expensive route.

Watch the status. A spawn moves through queued → running → one of completed, failed, timedOut, or cancelled. On spawn you will see a line like Sub-agent 'research' queued (depth 1).

Read the returned result in the parent conversation before acting on it. Treat it as a proposal from a helper, not a verified fact.

The parent session is where approvals and your judgement live. The sub-agent's output arrives as content, not as an executed decision.

If it misbehaves, cancel it from the parent. A cancelled spawn is recorded as Cancelled by parent.

Decide whether you need an orchestrator at all. A plain sequential workspace already runs agents in order. An orchestrator adds a coordinator that plans, dispatches work, and synthesizes the results into one answer.

If your stages are fixed and always run in the same order, a plain workspace is simpler and easier to audit.

Open Workspaces > Directory and nominate one agent as the orchestrator. Give it planning instructions — how to split work and how to combine results — not domain instructions.

Give the workers narrow roles and the minimum tools each needs. The orchestrator does not need their tools; it needs to be able to reason and delegate.

Choose the execution mode. Sequential (Managed) runs each step after the previous one completes. Parallel (Mirrored) dispatches all steps to their targets simultaneously.

Choose Sequential when a later step needs an earlier step's output. Choose Parallel only when the workers are genuinely independent — otherwise you get fast, confidently wrong work.

Start the run from Workspaces > Run and watch the progress messages. You will see Orchestrator … is thinking, then Queued delegated job … or Delegated … in parallel, then Agent … is working, and finally Orchestrator is synthesizing.

Keep approvals on for the first few runs. Approve each side-effecting tool call yourself and read what the worker was actually about to do.

Parallel mode means several agents can ask for approval at once. That is exactly when it is easiest to approve something you did not read.

Wait for Orchestration complete, then judge the synthesized answer against the workers' individual outputs — not instead of them.

Cancel cleanly if it goes wrong. A cancelled delegation is recorded as Delegated job cancelled, and the run report keeps the partial history.

Open the run in Workspaces > Run. The job list is the record of what was dispatched — read it before drawing conclusions from the final answer.

Use the inspection tool, which exists to inspect delegated worker jobs and collect finished results. Call it with no filter first to see the whole picture.

Narrow down when the list is long: filter by worker id to follow one agent, or pass a job id to open a single job.

Match each job to a status. Anything not finished has not contributed to the final answer, however convincing that answer reads.

Collect the finished results you actually need, then export the run report so the evidence survives the session.

See Export and review a workspace run report — the live run is not a durable record.

Run the task by hand first and time one iteration. You cannot set a sane bound on a task you have never watched.

Almost every runaway agent is a task that was automated before anyone knew what normal looked like.

Choose how queued requests behave with /queue. serial processes one at a time in order; parallel allows concurrent requests; dropNew discards new requests while one is in flight; replaceInFlight cancels the running request when a new one arrives.

For an unattended agent, serial or dropNew is almost always right. Parallel multiplies both speed and damage.

For a recurring agent, configure it as a heartbeat in Automation > Flows rather than leaving a chat running, and set an explicit iteration bound.

Keep approvals required for anything that writes files, runs commands, sends messages, or touches the network. An unattended agent with blanket approval is an unattended script with a language model attached.

Learn the stop controls before you need them: /stop ends the current generation, /kill terminates a running agent session or background task, and /steer redirects it to a different agent or mode instead of killing it outright.

Let it run once while you watch, then check System > Requests and the Audit Trail for what it actually did — not what it said it did.