# Orchestrate sessions, state machines, and bounded agents

## When to use

Use this task for multi-turn interaction, explicit state transitions, or an LLM/tool loop. Stop if a single graph execution already owns the full lifecycle. Adding a session, state machine, and agent together without distinct responsibilities is not a valid design.

## Inspect first

- Identify the current owner of interaction state, transition rules, termination, timeout, and recovery.
- List deterministic business rules separately from model-generated proposals.
- Inventory tools and their external effects, authorization, idempotency, and result types.
- Read the relevant chapters: [sessions](/en/v/0.9.8-RC1/14-multi-turn-sessions), [state machines](/en/v/0.9.8-RC1/15-state-machines), [composition](/en/v/0.9.8-RC1/16-composing-sessions-and-state-machines), and [agents](/en/v/0.9.8-RC1/17-agent-orchestration).

## Required inputs

Obtain the lifecycle states or phases, allowed transitions, retained context, round limit, timeout behavior, termination condition, tool allowlist, approval boundary, and durable recovery requirement. Missing business transitions must be resolved by the owner, not guessed from current code.

## Implementation path

1. Choose one outer lifecycle owner: graph, session, or state machine.
2. Represent deterministic transitions explicitly in that owner.
3. Put the agent inside one bounded phase/node that returns a typed proposal or result.
4. Constrain tool dispatch with an allowlist, input contract, attempt/round limits, and explicit terminal states.
5. Keep approval and irreversible effects outside model discretion unless the business contract explicitly grants them.
6. Add durability only after in-memory lifecycle behavior and restore inputs are proven.

## MUST / SHOULD / MAY

- **MUST** define one owner for state, timeout, termination, and recovery.
- **MUST** bound agent rounds and tool capabilities.
- **MUST** validate model output before it changes deterministic state or triggers effects.
- **SHOULD** return typed outcomes rather than unstructured text across boundaries.
- **SHOULD** preserve enough event/checkpoint evidence to explain each transition.
- **MAY** use an agent for classification or proposal generation; it must not silently become the business policy owner.

## Failure patterns

- Two lifecycle owners persist the same state: choose an outer owner and make the inner component return a result.
- The agent loops until “done”: add a hard round limit and explicit terminal outcomes.
- A tool call equals approval: split recommendation, approval, and execution.
- A restored session lacks definition/version identity: persist and verify the definition binding before resuming.

## Validation

Test legal transition, illegal transition, timeout, maximum rounds, denied tool, malformed model result, and restore. For durable variants, repeat recovery with a fresh manager/runtime instance. Do not call an in-memory restore test crash-safe.

## Evidence

- [Session lifecycle](/en/v/0.9.8-RC1/14-multi-turn-sessions)
- [State-machine ownership](/en/v/0.9.8-RC1/15-state-machines)
- [Bounded agent orchestration](/en/v/0.9.8-RC1/17-agent-orchestration)
- [Safe change boundaries policy](/agent/en/v/0.9.8-RC1/policies/safe-change-boundaries.md)