Core concepts
The vocabulary the rest of these docs assume. Every other page links here instead of re-defining a term — if a word looks unfamiliar, it is defined once, on this page.
Organization and Workspace
An Organization is the account-level container — billing, SSO, and membership live here. A Workspace is a tenant inside it: agents, API keys, budgets, guardrails and the audit log all belong to exactly one workspace, and never leak across into another. Row-level isolation is enforced at the database, not just the UI — a query scoped to one workspace cannot see another workspace's rows even if it tried.
Most organizations run one workspace per environment or per team — a prod
workspace and a staging workspace, say — so that a runaway budget or a
revoked key in one has no way to touch 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 is allowed to use. An agent is an identity with a lifecycle, not just a config blob — it moves through exactly four states, and the set is deliberately closed:
| State | Meaning |
|---|---|
registered | Governed and listed, but has not made a call yet. Its identity and credential exist; nothing has authenticated with them. |
active | Has made at least one governed call. The first call flips it — there is no separate go-live step, because a manual step is a step that gets skipped, and a skipped step is an agent that reads as governed while actually running ungoverned. |
paused | A reversible stop. Its credential is refused at authentication while the row, its bindings, and its history stay intact. |
retired | Terminal. The record is kept — ledger rows still point at it — but the agent can never call again. |
API key
Your code authenticates with an API key (sk_...), never with a
username/password or a provider credential directly. There are three shapes,
and which one you are looking at changes what the key is for:
| Kind | What it is |
|---|---|
| Provider key | Your actual OpenAI/Anthropic/Gemini credential. Vault-encrypted, tenant-global (one per provider), injected into the call server-side. Your code never holds it. |
| Developer key | Issued to a person, parented to a provider key. Carries its own scopes, model allowlist and daily/monthly spend caps, and every call it makes is attributed to that developer. |
| Agent key | Belongs to exactly one Agent (never a person). This is what makes a per-key spend ceiling also a per-agent ceiling — with a 1:1 binding, there is no ambiguity about whose spend a cap is protecting. |
All three are the same underlying credential row — the difference is only
which owner column is set: a developer key points at a person (owner_identity_id),
an agent key points at an Agent (agent_id). The secret itself is shown once,
at creation, and only a hash is ever stored. See API keys and spend
for the full model and how rotation works.
Budget
A Budget is a spend ceiling enforced before a call is forwarded, not reconciled after. Ceilings compose across three levels — workspace, per-key, and per-agent — and a call must pass every ceiling that applies to it. See Budgets.
Guardrail
A Guardrail is a content check run over completed traces — PII, secrets, denylisted terms — producing findings you review per agent, and which can auto-pause an agent once findings pass a threshold you set. A guardrail is deliberately not the same mechanism as a budget: budgets gate spend before the call, guardrails inspect content after it.
Policy
Policy is the umbrella term for everything that constrains what a call or an agent is allowed to do: the model allowlist on a key, the tool bindings on an agent, the guardrail configuration, the budget ceilings. When these docs say "policy", they mean this whole bundle, not one specific setting.
The governed chokepoint
The governed chokepoint is the one path every call takes: authenticate, gate the budget, inject the provider credential, forward the call, meter it, write the audit row. There is deliberately no other path — a call that skips any of these steps is not a faster route, it is not a supported one. That is what makes the record trustworthy: nothing that happened is missing from it.
trace_id
Every governed call returns a trace_id in its response. It is the thread
that ties one call to its audit entry, its metering record and its trace, so
"what did the agent do at 14:32" has one answer you can look up instead of
reconstructing from timestamps. See Make your first call
for where it shows up, and Traces / Audit
for what each system does with it.