> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operate Your First Durable Agent

> Prepare an approved bounded task, launch it through Workstream MCP, and inspect or control the execution using its workflow ID.

<div className="ss-guide-summary" role="group" aria-label="Walkthrough at a glance">
  <div><span className="ss-eyebrow">WORK IN</span><strong>Workstream MCP</strong></div>
  <div><span className="ss-eyebrow">BRING</span><p>Runtime readiness · Complete plan · Required release approval</p></div>
  <div><span className="ss-eyebrow">FINISH WITH</span><p>Workflow ID, observed final state, and output evidence</p></div>
</div>

**Outcome:** an authorized long-running task has a durable workflow ID, observable progress,
and a clear completion or stop result. This walkthrough is for Workstream's active-horizon
agents, not the support-agent records created in Response.

Start with a small task such as producing a report from an approved dataset. Define the output
and the records that prove completion before giving the agent permission to run.

## Prerequisites

* A [Workstream MCP connection](/guides/manage-platform-with-mcp) with permission for the brand
  and the operations you need.
* The deployed worker, Temporal service, and required child-workflow runtime; sandbox tasks
  also need their configured sandbox access.
* A complete start payload for the intended task, prepared against the current contract.
* For governed recipes, a validated release, verified sandbox test evidence, and release
  approval from the authorized operator.

If you have only signed up for Response, begin with [your first support agent](/guides/first-support-agent)
or [workflow trial](/guides/first-workflow-trial). A connection to MCP alone does not provision
these runtime or release requirements.

## 1. Define a bounded task

Use this worksheet with your operator or assistant. It is a planning template, not a start
request; child workflows require their own complete payloads.

```text theme={null}
Brand: [actual brand UUID]
Goal: [one measurable result]
Inputs: [approved dataset or record references]
Output: [artifact or result and where it will be stored]
Success evidence: [what a reviewer can independently verify]
Allowed operations: [reads and any explicitly authorized effects]
Allowed child workflow types: [types supported by this deployment]
Bounds: [active window, turns, failures, per-turn timeout, parallelism]
Owner: [who handles approvals, failures, and stop requests]
```

The supervisor schedules child workflows; it does not interpret any arbitrary JSON task as
an executable integration. Validate the selected child workflow's input and allowlist entry.
Bounded execution also does not make a task read-only: enforce that through the chosen tools,
credentials, workflow types, and autonomy policy.

## 2. Complete the release process

For a recipe-backed launch, the current Rust implementation requires `recipe_key`,
`recipe_version`, and an explicit `autonomy_policy`, then authorizes the final launch against
an approved `release_id` and its plan hash.

Follow the deployed authoring/operator flow and these contracts:

1. [Validate the active-horizon plan](/api-reference/temporal/workflows/v1-workflows-active-horizon-agent-validate-create).
   This creates a validated release record; it does not start the agent and is not a read-only check.
2. Run the required sandbox test for that release using the supported authoring flow, then
   [verify its test evidence](/api-reference/temporal/workflow-releases/v1-workflow-releases-by-verify-test-create).
   Verification checks an existing test execution; it does not run a test merely because an ID was supplied.
3. Have an authorized approver [approve the release](/api-reference/temporal/workflow-releases/v1-workflow-releases-by-approve-create).
4. Retain the approved plan and release ID for launch. Do not widen its task scope or budgets
   by editing the payload after approval.

The `manual` autonomy level permits validation/testing but is rejected for launch. Select the
policy appropriate to the authorized task through the release process; do not change it just
to bypass a rejection.

<Note>
  The current MCP operations expose `start_agent`, status, and controls. Do not infer a
  `validate_agent` or `approve_release` MCP tool from the REST route names. If the required
  authoring or approval operation is unavailable to your assistant, hand that step to the
  authorized operator rather than skipping it.
</Note>

## 3. Start the approved plan

Inspect `start_agent` in `tools/list`. Its input is an object with a **`payload`** property
containing the complete active-horizon REST start body. Use the actual approved body; a goal,
brand ID, and a list of tool names are not a substitute for it.

Ask your assistant:

```text theme={null}
Use Workstream for brand [brand UUID]. Inspect start_agent and the supplied
approved start payload at [reference]. Check that the release ID, recipe,
request ID, task scope, and bounds match the authorized plan.
I authorize launching that plan once. Do not fill missing fields by guessing.
Return the workflow ID and inspect get_agent_status. If launch is rejected,
report the error and missing prerequisite without changing the approved plan.
```

Keep the returned workflow ID. Closing the initiating assistant conversation does not cancel
the durable execution. Conversely, a returned ID is not evidence that its child tasks succeeded.

If the start response is lost, reconcile the original request and visible executions before
starting a new run. Do not create a fresh request ID merely to retry uncertain work.

## 4. Read progress

Call `get_agent_status` with these MCP arguments, replacing the placeholder:

```json theme={null}
{
  "workflow_id": "<returned workflow ID>"
}
```

Inspect the phase, current task, completed work, failures, available evidence, and remaining
bounds exposed in the status. If you lost the ID, use Workstream's `list_agents` for the actual
`brand_id`, then inspect the matching execution. Response's `list_agents` lists support-agent
records and cannot substitute for this lookup.

Long-running execution uses a bounded ledger across checkpoints. Store large artifacts in the
configured durable destination and retain their references; do not assume the supervisor
retains every transcript forever.

<div className="ss-checkpoint">
  **Success:** a status read identifies the expected task and its observed progress. When it ends,
  check the result and output evidence rather than treating every stopped run as completed work.
</div>

## 5. Pause, steer, or cancel deliberately

`control_agent` accepts a workflow ID, action, and optional action-specific payload. For example,
authorized steering uses:

```json theme={null}
{
  "workflow_id": "<returned workflow ID>",
  "action": "steer",
  "payload": {
    "note": "Prioritize the report summary; do not expand the approved input set."
  }
}
```

To request cancellation:

```json theme={null}
{
  "workflow_id": "<returned workflow ID>",
  "action": "cancel"
}
```

The supported MCP actions are `pause`, `resume`, `steer`, `enqueue`, `reprioritize`,
`extend_budget`, and `cancel`. Inspect the specific action's schema/contract before using it.
A note does not authorize a new business action, and extending a runtime budget does not grant
permission to broaden the task.

An accepted control means the request was accepted. Read status again to observe its effect;
do not assume an in-flight child stopped instantly or that completed external effects were
reversed. Emergency termination is a separate REST operation, not an action in this MCP enum;
use the [operator reference](/next-temporal/active-horizon-agents#steering-a-running-agent).

## 6. Hand off the result

Record the workflow ID, release ID, final state, completed/remaining tasks, consumed bounds,
output references, and unresolved approvals or failures. A budget-exhausted run may have useful
partial work, but it is not the same as achieving the goal.

Have the owner verify the report or business result. For an external action, retain the provider's
outcome too: durable execution does not remove the need to reconcile an uncertain provider response.

## Troubleshooting

| Symptom                                          | Next check                                                                    |
| ------------------------------------------------ | ----------------------------------------------------------------------------- |
| Start rejects missing autonomy policy or release | Complete the current recipe release flow; do not use an older minimal payload |
| Release authorization fails                      | Approved plan, tenant, release state, and any changed payload fields          |
| Start returns an ID but no task progresses       | Status, worker/task-queue availability, and child runtime readiness           |
| Agent stops early                                | Final state, budgets, failures, and ledger entries                            |
| Control accepted but state seems unchanged       | Poll status and inspect the in-flight task before assuming immediate effect   |
| Expected artifact is missing                     | Task result and its durable output references, not just the supervisor status |

## Next steps

<CardGroup cols={2}>
  <Card title="Inspect operator controls" icon="sliders-horizontal" href="/next-temporal/active-horizon-agents">
    Review lifecycle controls, execution bounds, and recovery.
  </Card>

  <Card title="Explore related engines" icon="cpu" href="/guides/rust-engines-and-mcp">
    Choose the commerce, workflow, or agent capabilities for your next task.
  </Card>
</CardGroup>

Related: [Onboarding troubleshooting](/guides/onboarding-troubleshooting).