Skip to content

Architecture

An Organization owns shared configuration. An End User owns Sessions and files. A Session freezes selected Template content and execution settings in a Configuration Epoch.

An End User owns a Session. The Session freezes Template content and contains successive Turns.
Resource Role
Organization Security and billing boundary for configuration and resources.
End User Your application’s identity within that Organization; distinct from a Console Platform Account and Membership.
AgentTemplate Shared behavior: instructions, enabled capabilities and dependencies. One mutable entity whose saves take effect immediately.
Session An End User’s private conversation. Creation freezes the selected Template’s current content.
Turn One Full Agent execution or completed Realtime exchange in the Session.

Example: Session A starts with the Template’s current content. You edit and save the Template. A new Session B uses the saved content; later Turns in Session A keep the original recipe. Fixed configuration preserves provenance, while current ownership, policy and dependency availability still govern execution.

A Session has at most one active Full Agent Turn; completed Realtime Turns do not occupy that slot. A new plain-text requirement during execution steers that Turn; it does not queue another one. Saved interactions distinguish admission, incorporation and the original result. See Core concepts and Sessions and Turns.

Session-client example: a customer backend submits a message with a User Key to the API. The owned Session and current checks lead to Turn execution and the model; allowed operations use Sandbox or private files. Progress and results return to the customer. Physical devices remain with the customer application; text Session Client Tools are declared and run by the client.
  1. Your backend authenticates with the End User’s User API Key and submits a command through POST events, receiving a JSON receipt.
  2. The service resolves the Session’s fixed recipe and checks current access and applicable limits.
  3. The Turn runs the model. The model may select tools enabled by the Template; controlled operations provide tool results.
  4. Your backend reads progress and results from the Turn, or, holding the Organization API Key, receives the Session’s events over a Backend Connection and continues from a cursor after reconnecting. Disconnecting does not cancel execution; cancellation is explicit. Interactions and Turns provide original receipts and saved history.

Your application or device can declare Client Tools on an ordinary text Session and execute their calls. The platform routes required actions and results; your integration owns device transport and physical execution. Voice device actions delegate to Full Agent Turns, which use the same Session Client Tools; Realtime exposes no direct device or Session-client tools.

Continue with Capabilities and examples or Quickstart.

On a narrow screen, scroll each diagram horizontally to read its labels.

See reading Realtime conversation history for transcript metadata, narration and pagination behavior.