# Agent Runtime (/agent-runtime)



## Runtime model [#runtime-model]

Production agents are hard in ways ordinary request-response features are not: work runs long, state must survive, users leave, and runs need clean control when something goes wrong. The [Agents template](/agents-template/) ships Agent Runtime as part of the project foundation, so those execution, state, sandbox, and control patterns are in place from the first commit.

```mermaid
sequenceDiagram
  participant C as Client
  participant A as Chat API
  participant R as Agent run
  participant S as Sandbox
  participant D as Postgres
  C->>A: Send message
  A->>D: Queue message
  A->>R: Start run
  C->>A: Open live stream
  loop Each turn
    R->>S: Run tools
    R-->>A: Live events
    A-->>C: Live events
  end
  R->>D: Save transcript and outcome
```

1. **Request**: The project accepts an agent message through its signed-in chat API.
2. **Durable execution**: A Temporal workflow on the project's dedicated worker runs the agent, so the run does not depend on the browser tab or the web request.
3. **Tool work**: Each chat thread gets its own isolated sandbox, and its files persist between runs. Tools that need approval pause until the user decides.
4. **Live and durable state**: Live run events stream to the client, while Postgres keeps the thread, its transcript, queued messages, and the latest run outcome.
5. **Control**: The user can stop a run, approve or reject held tool calls, and send another message to continue. Messages sent during a run queue for the next turn.

Users can leave and return: the thread and transcript are still there, and the client reconnects to the live stream.

<Accordions>
  <Accordion title="Under the hood: run lifecycle">
    Chat routes live under `/chats` and require a signed-in user; runs act as the thread owner. `RunAgentWorkflow` runs on the template's Temporal worker using the OpenAI Agents SDK and the [LLM Gateway](/llm-gateway/). The model-turn activity is not retried, because a streamed turn is not safely repeatable; a failed turn ends the run with an `error` outcome, and the next message starts a new run. Bookkeeping activities retry up to five times, and a sweep releases runs whose claim went stale. Live events travel over Redis pub/sub and reach the client through server-sent events. The sandbox is a Ghost sandbox session whose workspace persists through data-disk snapshots.
  </Accordion>
</Accordions>