Architecture Overview

How WorkOS, API keys, the control plane, the AP vault, sessions, and gateway actions fit together today.

More doing, less reading

To jump straight into developing with the Agent Platform API, follow our Quickstart. You can get started right now.

System Shape

CLI device flow / browser dashboard
                │
                ▼
          WorkOS identity
                │
                ▼
 public API key auth  ─────────────┐
                │                  │
                ▼                  │
  control plane (Go API + River workers)
      ├── Postgres
      │     orgs, workspaces, sessions, runs, grants, invocations
      ├── AP vault
      │     encrypted integration credentials
      ├── action gateway
      │     read-only Slack, Linear, and Google Workspace actions
      └── hosted model runner
            run execution for interactive sessions and API calls

What Is Fixed at Session Creation

When you create a session, Agent Platform pins:

The current organization
The current workspace

That matters because switching organizations or workspaces later does not retarget an existing session.

Current Invariants

First sign-in creates or finds a personal organization and ensures a default workspace.
Integration credentials live in the AP vault, not in session transcripts.
The AP vault stores integration credentials only. It is no longer part of model setup.
The action gateway only exposes read-only actions.
Non-admin users need grants to use shared actions, while admins are implicitly allowed.
User-private connections auto-seed owner grants for the matching read actions.

Where to Go Next

Organization and Workspace

Membership, workspace selection, connection scopes, and how context is resolved.

Platform Gateway

AP vault storage, permission checks, connection resolution, and audit behavior.

Sessions and Execution

How sessions and runs execute, and what durable state exists today.