Sessions and steering

Use an execution session when a user needs to continue a conversation. Keep its ID in your application and append later messages to that session. Creating a new session starts separate context; it does not continue the last run automatically.

These examples use the authenticated client and project from the Quickstart.

Steer or queue input

Steering is the default for active work: the input joins the turn already running. Queued input (delivery_mode="queue") creates an independent follow-up.

The first message starts a turn. A steering message changes that active turn. A queued message waits and runs as its own follow-up. list_session_inputs shows how each input was delivered.

session = client.execution_sessions.create(
    project, "support", tenant_id="customer-42", user_id="user-7",
)["session"]
turn = client.execution_sessions.append_turn(
    project, session["id"], idempotency_key="case-42-analysis",
    input={"text": "Analyze this case"},
)
steering = client.execution_sessions.append_turn(
    project, session["id"], idempotency_key="case-42-focus",
    input={"text": "Focus on renewal risk"},
)
queued = client.execution_sessions.append_turn(
    project, session["id"], idempotency_key="case-42-explanation",
    input={"text": "Explain the findings"}, delivery_mode="queue",
)
receipts = client.execution_sessions.list_session_inputs(project, session["id"])

Session responses are dictionaries where the API declares open objects; run responses such as runs.start use generated models. A session preserves context across turns. Keep its ID to continue the conversation.

Set structured output and reasoning effort

Set these controls when creating a session:

session = client.execution_sessions.create(
    project, "support", tenant_id="customer-42", user_id="user-7",
    reasoning_effort="medium",
    final_output_schema={
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
        "additionalProperties": False,
    },
)["session"]

These controls do not select a model vendor. Inspect the run’s final output and terminal status rather than treating intermediate events as the schema-constrained result.

To explore another approach from a completed turn, see Session branching. For recurring input, see Schedules.

Read delivery and progress

The append response records admission of an input. Keep its receipt and inspect list_session_inputs to determine how it was delivered, especially when steering arrives near completion. Observe the associated run using Runs and tool requests.

• Use a stable idempotency key per logical input. Retrying the same input should preserve its key and payload; a genuinely new message needs a new key.
• Map sessions to your authenticated application users so one user cannot continue another user’s conversation by supplying its ID.
• A session pins its release and model. Start a new session to use a newly active release.
• Branch only when you want a separate conversation based on an eligible saved snapshot.

Next steps