cookbook/05_agent_os/04_run_lifecycle/README.md
These five examples cover the lifecycle APIs around an AgentOS agent run: background submission and polling, cancellation, resumable SSE, persisted checkpoints, and background hooks.
From the repository root, use the cookbook environment:
./scripts/demo_setup.sh
export OPENAI_API_KEY=your-key
Each server example listens on port 7777. Start only one at a time.
| File | What it teaches |
|---|---|
background_run.py | Submit a database-backed run for HTTP 202/PENDING and poll its nested run route. |
cancel_run.py | Cancel an accepted background run and observe its persisted terminal status. |
sse_reconnect.py | Resume both a new background SSE run and a background continuation with raw httpx. |
checkpoints.py | List tool-batch checkpoints and continue from a selected message_index. |
hooks_in_background.py | Choose AgentOS-wide background hooks or mix blocking and per-hook background work. |
RunStatus has seven members: PENDING, RUNNING, PAUSED, COMPLETED,
CANCELLED, ERROR and REGENERATED. The persisted run output is where you
read them — no run event carries a status field except WorkflowPaused, and a
cancelled run's stream ends on a completed event, because cancellation emits
the pair (cancelled, then completed).
A cancelled run keeps the work it finished: agents and teams in content, a
workflow in step_results.
The three components do not share a continue contract, which is the difference most likely to break a client:
| Agent | Team | Workflow | |
|---|---|---|---|
Field on /continue | tools | requirements | step_requirements |
| Also accepts | input, continue_from, fork, regenerate, replace_original, additional_instructions, session_id, user_id, stream, background | same as agent | session_id, user_id, stream, background, factory_input |
| Error event | RunError | TeamRunError | WorkflowError |
Send the array back as it arrived with the resolution added. A continued run can
pause again — the next tool call or step may need approval too — so loop on the
status rather than treating the /continue response as terminal. The array
carries the decisions already resolved as well as the new one, so resolve only
the entries still awaiting a decision.
run_id and session_id both survive a /continue: it is the same run. A
/continue with regenerate=true is the exception, keeping session_id and
returning a new run_id; workflows have no regenerate.
Driving a pause and continue over HTTP is shown for teams in
05_human_in_the_loop/user_input.py.
background_run.pyTerminal 1:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/background_run.py
Terminal 2:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/background_run.py --demo
The client explicitly sends background=true, stream=false, and a
session_id. AgentOS returns HTTP 202 with PENDING; the client then polls
GET /agents/{agent_id}/runs/{run_id}?session_id=... until completion.
A database on the served agent is required because the detached task and poll request use persisted run state. This mode does not support remote agents.
cancel_run.pyTerminal 1:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/cancel_run.py
Terminal 2:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/cancel_run.py --demo
The client starts the same HTTP 202/PENDING background flow, posts to
/agents/{agent_id}/runs/{run_id}/cancel with the returned session_id, and
polls the nested run route until it observes CANCELLED.
sse_reconnect.pyTerminal 1:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/sse_reconnect.py
Terminal 2 can exercise either reconnection path:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/sse_reconnect.py --demo run
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/sse_reconnect.py --demo continue
Both clients track the latest event_index, disconnect from a
background=true, stream=true response, and reconnect with
POST /agents/{agent_id}/runs/{run_id}/resume. The second client first creates
a confirmation pause and calls the nested /continue route in background mode.
AgentOSClient does not currently expose a resume method, so this example
intentionally uses raw httpx for both the original SSE response and the
resume request.
checkpoints.pyTerminal 1:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/checkpoints.py
Terminal 2:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/checkpoints.py --demo
The agent uses checkpoint="tool-batch". The client calls the nested
/checkpoints route with session_id, selects an interior boundary by its
message_index, and posts that value as continue_from to /continue.
checkpoint_id is a display ordinal; it is not the continuation coordinate.
hooks_in_background.pyRun the AgentOS-wide mode:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/hooks_in_background.py --mode global
Then POST a run for global-hooks-agent. In this mode,
AgentOS(run_hooks_in_background=True) schedules every non-guardrail pre- and
post-hook as a FastAPI background task. Guardrails remain synchronous so they
can still block unsafe input or output.
curl -X POST http://localhost:7777/agents/global-hooks-agent/runs \
-F 'message=Explain background hooks in one sentence.' \
-F 'stream=false' \
-F 'session_id=global-hooks-demo'
Run the fine-grained mode:
.venvs/demo/bin/python cookbook/05_agent_os/04_run_lifecycle/hooks_in_background.py --mode mixed
Then POST a run for mixed-hooks-agent. This mode leaves
run_hooks_in_background at its default so the plain hook and first
AgentAsJudgeEval block. The @hook(run_in_background=True) notification and
the second AgentAsJudgeEval(run_in_background=True) are scheduled after the
response.
curl -X POST http://localhost:7777/agents/mixed-hooks-agent/runs \
-F 'message=Explain mixed hook execution in one sentence.' \
-F 'stream=false' \
-F 'session_id=mixed-hooks-demo'
The same global switch and per-hook controls apply to AgentOS teams and workflows.