Agents
Give a bot, CI job or coding agent its own API keys that your organization owns. Create agents, mint and rotate their keys, and choose who may manage them.
An agent is a service account your organization owns. It has its own API keys, an owner (the organization or one of its teams) and its own usage. Because the organization owns it, an agent keeps working when the person who created it leaves, and an admin can always manage it.
Use an agent for anything that is not a person: a release bot, a CI pipeline, a nightly evaluation job, a support-triage assistant. For your own work, keep using a personal API key.
Who can manage agents
Who manages an agent depends on its owner, which you choose when you create it.
| Role | See agents | Organization agents: create, edit, disable, delete; manage keys | A team's agents: the same | See usage figures |
|---|---|---|---|---|
| Organization owner, admin | Yes | Yes | Every team | Yes |
| Team owner, admin | Yes | No | Their own team only | Their own team's agents |
| Billing administrator | Yes | No | No | Yes |
| Member | Yes | No | No | No |
A team's owners and admins manage only that team's agents. Being an admin of a parent team does not extend to its sub-teams. To let someone run a team's agents, make them an owner or admin of that team.
Create an agent
- Open Agents in the sidebar and choose New agent.
- Enter a name (lowercase letters, numbers and dashes, for example
deploy-checker) and, optionally, its purpose. - Choose the owner: a team, so the agent's usage shows under that team, or the organization. The owner cannot be changed later.
- Choose Data capture: Follow organization, Metadata only or Off (see Data capture for an agent). Pick Off when the agent handles personal, financial or customer data.
- Name the first key and choose when it expires (30 days, 90 days or one year, within your platform's maximum).
- Choose Create agent and key, then copy the key. It is shown once.
You do not pick a tool for the agent. Any client can use its key, whether Claude Code, Codex, OpenCode or your own script, and the agent's page shows which clients actually called under Clients seen.
Store the key in your CI or secret manager and use it like any Tokamak key:
curl https://api.tokamak.sh/v1/chat/completions \
-H "Authorization: Bearer $TOKAMAK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "anthropic/claude-sonnet-5", "max_tokens": 512, "messages": [{"role": "user", "content": "Summarise the failing test."}]}'What an agent key can do
- Call models. Agent keys are inference keys. Usage is billed to your organization like any other usage and appears on the agent's page and in Analytics, where the agent is listed by name with an Agent badge (leaderboard, People → Members, budgets and the monthly report). Insights describe how people work, so agents are not listed there.
- Nothing else. An agent key cannot create other keys, sign in to the CLI, switch organizations or change any setting. Those requests are refused.
Requests through an agent's keys count toward your organization's budgets, and toward its team's budgets when a team owns the agent. Each key runs at the platform's per-key rate limit.
Data capture for an agent
When your organization has data capture on, each agent can record less than the organization does. Open the agent, choose Settings, and pick one option under Data capture:
| Setting | What is recorded for this agent's requests |
|---|---|
| Follow organization (default) | Whatever the organization's data capture records |
| Metadata only | Model, tokens, cost, timing, status and tags. No prompts or responses |
| Off | Nothing |
- It only lowers. An agent's setting never records more than the organization: with the organization at Metadata only, Follow organization stays Metadata only.
- Clients can't override it. Tokamak applies it to every request the agent's keys make. No header, tag or
tokamak launchflag turns it back on. - Usage and billing are unchanged. The agent's requests still count toward analytics, budgets and billing. Only Captured data is affected.
- Who can change it: whoever manages the agent. Every change shows in the agent's Activity.
- Takes effect on the agent's next request.
Organization owners and admins also see Captured data for this agent on the same page: records, sessions and when it was last captured in the last 30 days, a link to those records in Insights → Captured data, and Purge agent data to delete them. When you turn capture off, an admin can tick Also purge this agent's captured data to delete what it already left. Settings → Data capture lists every agent whose capture is lowered.
Keys and rotation
Open an agent and choose Keys. An agent can hold up to ten active keys. To rotate without downtime:
- Choose Create key and copy the new key.
- Switch the agent over to the new key.
- Choose Revoke on the old key.
Both keys work in the meantime. A key that expires within 14 days is marked Expires soon.
Disable or delete
- Disable agent stops every one of its keys right away. You can enable it again later, and the keys work again.
- Delete agent revokes every key for good and removes the agent from the list. Its usage history is kept, and its name becomes free for a new agent.
Every change to an agent or its keys is recorded on the agent's Activity tab.
Agents on personal keys
The Agents on personal keys tab shows usage grouped by the agent label people set on their own API keys. Those keys belong to the person and stop working when they leave. To give a bot a key that outlives its creator, create a managed agent instead.