Sessions

​

Durable handle

A session remains addressable by the same session_id across multiple turns. That gives clients a stable handle for:

• Sending new messages
• Checking current status
• Inspecting prior message history
• Browsing the session workspace

​

Session behavior

Sessions are intended to support ongoing interactions rather than one-off requests. Each session can contain:

• Multiple messages
• Uploaded files
• Workspace files created over time
• Status for both the session and its messages

​

Session and message status

The API returns session.status and message.status. Session statuses include:

• active
• idle
• completed
• failed
• expired

Message statuses include:

• queued
• running
• completed
• failed

Use message.status to track the progress of a specific turn. Use session.status to determine whether the session is still active.

​

Agent version behavior

Sessions use the agent version that was active when the session was created. That means:

• Publishing a new version changes future sessions
• Existing sessions keep running against their original agent version
• A stable session handle does not imply a mutable runtime target