After a session is created, its execution flow can be controlled via a state machine, tool call approvals, and interruption mechanisms—and archived or deleted upon task completion.
State Machine
The session status appears at the top of the page. The table below outlines the trigger conditions, next states, and available actions for each status:
| Status | Trigger Condition | Next Status | Available Actions |
|---|---|---|---|
idle | Session creation completed, or one round of processing finished | On receiving a message → running; On archiving or deletion → terminated | Send message, attach files, archive, delete |
running | Message received and agent begins processing | On completion → idle; On unrecoverable error → terminated | Interrupt, approve tool calls |
terminated | Archived, deleted, or unrecoverable error occurred | Terminal state—no further transitions possible | View event history; create a new session to continue |
idle, the session_status event includes a stop_reason field indicating why:
end_turn: Model voluntarily ended the turn.requires_action: Client-side intervention is required;event_idsare included to identify pending events.retries_exhausted: All retry attempts have been exhausted.
Tool Calls
The agent autonomously decides when and which tool to invoke based on system prompts and the current message. All tools—built-in, MCP, or skills—are executed within the runtime environment bound to the session, and their invocation process is visible in real time via the event panel.
Invocation Flow
- Agent Decision: The model outputs a tool call instruction. The event panel displays a Tool Call event containing the tool name and parameters.
- Execution: The tool runs inside a sandbox; its output is sent back to the model.
- Response or Continue: The model decides whether to reply or initiate another tool call, based on the tool’s output.
Archiving and Deletion
Sessions support two distinct operations: archiving and deletion.
- Archiving: Changes the session status to
terminated(a terminal state), while preserving the full event history for future reference. Recommended for completed sessions. - Deletion: Permanently removes all session metadata, event history, and internally copied resources—this action is irreversible. Use archiving instead if you need to retain event history.
Next Steps
- Session Event Stream (SSE): Learn about all event types and how to subscribe via SSE.
- Defining an Agent: Customize your agent’s model, prompts, and toolset.
- Cloud Hosting Environment: Configure the sandbox where tool calls execute.