Request lifecycle
Send a POST request with the session key in Authorization. Keep parsing the SSE stream until its event named end arrives. Buffer partial event text between network reads; dispatch only complete events.
See Handling responses for event framing and Sending actions for the request contract.
Request errors
These checks run before the action starts. They apply to Streaming and non-streaming HTTP requests:
Once streaming has begun, runtime failures arrive as an SSE error event, followed by connection closure. Preserve any output already received and check the action’s effects before deciding to replay it.
Interrupted streams
A stream that closes before its end event has incomplete delivery. The agent may already have run the action or a tool.
- Retain the session key: use it for the active conversation’s later actions.
- Show an interrupted state: retain output already displayed without treating it as a completed turn.
- Resolve the action’s result before replaying it: a new POST does not resume the old stream.
Session lifetime
The SSE event named end finishes one turn’s delivery. An agent trace with type: "end" finishes the conversation. A completion trace whose payload.state is end finishes only that model generation.
See response framing for the distinction between the SSE end event and an end trace.
Recover a non-streaming request
Check the HTTP result and resolve an interrupted turn before retrying.
HTTP status
Send an action with the session key in Authorization. Read the HTTP status and JSON body before accepting the next action.
Sending actions owns the request fields and examples. Handling responses owns trace interpretation.
Interrupted requests
A failed connection can hide a response after the agent has already acted. Before retrying:
- Keep the session key: a transport error alone does not end the conversation.
- Mark the turn as interrupted: do not present a missing response as success.
- Check external effects: if the action could have called a tool, check its result before sending that action again.
Starting another conversation
A trace with type: "end" finishes the conversation. Creating a new session for the same user in the resolved Environment replaces their previous session there. Use Sessions when starting another conversation.