Agent accounts
Create machine accounts with their own API keys, set what they can read, and rotate, revoke or delete them.
An agent account is a machine account for software, not a person. It has a name, an email, its own knowledge categories and API keys. Admins create and manage agent accounts in the Agents section of Team.
For what an agent can see and how that follows the account, read What an agent can see. This page covers managing the accounts.
Before you start
- You are an admin.
- Your plan has a free seat. An agent takes one seat, the same as a person. If every seat is taken, Agent opens Bring your whole team in instead of the New agent dialog. See Plan and usage.
- To give the agent categories, Brain must have finished building your memory. Before that, category changes are refused.
What makes an agent account different
| Agent account | Person | |
|---|---|---|
| Role | Always Member. It can't be an admin. | Member or Admin |
| Sign-in | API keys, no interactive sign-in | Sign-in in the browser |
| Seat | Uses one seat | Uses a seat |
| Knowledge | Only the categories you pick | Categories granted, or all for an admin |
| In the member list | Not shown there | Shown |
Trying to change an agent's role gives "Agent accounts are always members; their role can't be changed."
Create an agent account
Open Agents
Go to Team and scroll to Agents. The section reads "Machine accounts that authenticate with a static API key. Their knowledge access is scoped by the same categories as people." Click Agent.
Fill in the New agent dialog
Enter a Name and an Email. Under Knowledge categories, click the categories the agent may read. You can leave them all off and add them later.
Create the key
Click Create & mint key. Brain shows "Agent [name] created." and opens the dialog Copy this API key now.
Copy the key
Click the copy icon. Brain shows "Copied to clipboard." Store the key somewhere safe, then click Done.
The full key is shown once. Brain says you can't retrieve it later, and afterwards you only see a shortened version. If you lose it, generate a new key and revoke the old one.
The email rule
The email must have an @, or Brain says "Enter a valid email." The name can't be empty: Brain says "Give the agent a name."
The email must not already belong to another account. If it does, Brain says "That email already belongs to another account. Use a different email for the agent." Pick an address that is only for this agent. If Brain says "This conflicts with an account that already exists. Contact support and we'll sort it out.", contact support.
If creation fails
| Message | What to do |
|---|---|
| Agent accounts aren't enabled for your organization yet. Contact support to turn them on. | Contact support. |
| "We couldn't create this agent. Nothing was saved: try again in a minute, and contact support if it keeps failing." | Wait and try again. No half-made account is left behind. |
| "Category access can't be changed until Brain has finished building your company knowledge. Contact support if this keeps happening." | Create the agent without categories and add them later, or contact support if it keeps happening. Brain removes the account it had started, so you can try again. |
| "This category no longer exists. Reload to see current categories." | Reload Team and pick again. |
Manage an agent
Each agent has a card with its name, email, the number of categories it can read and the number of keys ("1 key" or "[n] keys"). Click Manage on the card.
Change what it can read
In Knowledge access, click a category to grant it, and click again to remove it. Changes save straight away. If none are configured, the dialog reads "No categories configured yet."
Generate a new key
Click Generate new key. Brain shows "API key created." and the Copy this API key now dialog again with the label "[name] · new key". Copy it. An agent can have several keys at once, which lets you swap a key without a gap.
Revoke a key
Each key is listed with its name and a shortened value. Click the trash icon, then confirm Revoke in the dialog "Revoke API key". It says "The agent will immediately lose access with this key. This can't be undone." Brain shows "API key revoked." With none left, the list reads "No active keys."
Delete the agent
Click Delete agent, or the trash icon on the card, and confirm in the dialog "Delete [name]". It says "The agent account and all its API keys are removed. This can't be undone." Brain shows "Agent deleted." With no agents left, the section reads "No agents yet."
Good practice
- Give each agent only the categories it needs.
- Use one agent account per system, so you can revoke one without touching others.
- Revoke any key you think has leaked, then generate a new one.
- To connect a person's assistant, use Connect an assistant. Agent accounts are a different thing.