Reliable session workflows

​

The core rule

​

Retry safely with idempotency keys

import uuid

# Generate the key once per logical action, and store it with your job.
key = str(uuid.uuid4())

message = {
    "type": "agent.session.input.message",
    "input": [{"role": "user", "content": [{"type": "input_text", "text": "Continue."}]}],
}
sessions.events.create(
    session_id,
    events=[message],
    extra_headers={"Idempotency-Key": key},
)
# If this times out, retry with the SAME key.

• Reuse the key only for the identical request. A different body with the same key is rejected.
• Make a new key for a new action, never to get past an error.
• If the original request is still being processed, or was interrupted, a retry returns HTTP 409 instead of a result. Look up the state (see the table above) before deciding what to do.
• max_retries=0 on the client turns off automatic retries so that your own code decides when to retry. It does not by itself prevent duplicates; idempotency keys do.

​

After a stream disconnects

1. Call sessions.retrieve(session_id) and sessions.turns.list(session_id).
2. If the turn ended, read the result. You are done.
3. If not, reconnect with sessions.events.stream(session_id). Raw SSE consumers can send Last-Event-ID to replay missed events; ignore duplicate IDs.

​

When the session needs you

• function_call: send one agent.session.input.tool_result for each call_id. Track which you answered, and do not rerun side effects for a call you already answered. See function tools.
• environment_connection: start or restart your self-hosted executor. See execution environments.

​

When the Orca server restarts

• Running turns are marked failed. Orca does not re-run them, because the agent may already have changed things in the outside world. Check those systems, then send a new message if the work should continue.
• Managed sandboxes reconnect to the same sandbox. If it no longer exists, Orca restores it from its last saved workspace, or reports an error. It never silently gives you an unrelated empty sandbox.
• History is intact. Every accepted message and every finished item is stored.

​

A bounded status loop

import time
end = time.monotonic() + 300
while time.monotonic() < end:
    current = sessions.retrieve(session_id)
    # Skip subagent turns: they finish before the turn that spawned them.
    turns = [t for t in sessions.turns.list(session_id).data if t.subagent_id is None]
    if turns and turns[0].status in ("completed", "failed", "cancelled"):
        print(turns[0].status, current.error)
        break
    if current.required_actions:
        print("needs attention:", current.required_actions)
    time.sleep(0.5)
else:
    raise TimeoutError("Inspect the session before retrying input")

​

Cancel and clean up

• To stop work, send {"type": "agent.session.input.cancel"} with sessions.events.create. Closing a stream does not stop anything.
• Delete sessions you no longer need; this releases their sandbox. Download artifacts first.
• Delete other resources separately: agents, files, skills, templates, and vaults are not deleted with sessions.
• Self-hosted executors are your processes. Stop them yourself.

​

Outcomes to handle separately