Core concepts
Terms used throughout these docs.
Organization and Workspace
An Organization is the account: billing, SSO and membership live here. A Workspace is an isolated environment inside it. Agents, API keys, budgets, guardrails and the audit log each belong to exactly one workspace. Isolation is enforced in the database, not only in the UI.
Most organizations run one workspace per environment or team, such as prod
and staging, so a runaway budget or revoked key in one can't affect the other.
Agent
An Agent is the unit you author in the console: a name, a default model, a system prompt, and the tools and policy it may use. An agent has four states:
| State | Meaning |
|---|---|
registered | Governed and listed, but hasn't made a call yet. |
active | Has made at least one governed call. The first call activates it; there is no separate go-live step. |
paused | Stopped, reversibly. Its credential is refused, but its bindings and history are kept. |
retired | Permanent. The record is kept, but the agent can never call again. |
API key
Your code authenticates with an API key (sk_...), never with a password or
a provider credential. There are three kinds:
| Kind | What it is |
|---|---|
| Provider key | Your OpenAI, Anthropic or Gemini credential. Stored encrypted, one per provider per workspace, and added to calls server-side. Your code never holds it. |
| Developer key | Issued to a person and linked to a provider key. Has its own scopes, model allowlist and daily/monthly spend caps. Every call is attributed to that developer. |
| Agent key | Belongs to exactly one agent, so a per-key spend cap is also a per-agent cap. |
The secret is shown once, at creation. See API keys and spend for details and rotation.
Budget
A Budget is a spend cap checked before a call is forwarded. Caps apply at three levels (workspace, per key and per agent), and a call must pass every cap that applies. See Budgets.
Guardrail
A Guardrail scans completed traces for PII, secrets and denylisted terms. You review findings per agent, and an agent can be paused automatically once findings pass a threshold you set. Budgets act before a call; guardrails act after it.
Policy
Policy means everything that limits what a call or agent can do: the key's model allowlist, the agent's tool bindings, guardrail settings and budget caps.
The governed path
Every call takes one path: authenticate, check the budget, add the provider credential, forward the call, meter it, and write the audit entry. There is no other supported path, so the record is complete.
trace_id
Every governed call returns a trace_id. It links the call to its audit
entry, metering record and trace. See Make your first call
for where it appears, and Traces and Audit
for how each uses it.