AdministerAgent accounts

Agent accounts

Create machine accounts with their own API keys, set what they can read, and rotate, revoke or delete them.

Create an agent account when software, not a person, needs to ask Gurusup: an internal bot, a script, a workflow. It gets its own API keys and reads only the categories you pick.

Admins only. Agent accounts live in the Agents tab of Team, a table that lists the agents of your organization. The Seats tile at the top of Team counts "Members, invites and API-key agents", and an empty table says "Agents that use an API key appear here and occupy one seat each." Knowledge access uses the same categories as people. For what an agent can see through the tools, read What an agent can see.

Before you start

  • You are an admin.
  • Your plan has a free seat. An agent takes one, like a person. On Free, the one seat is yours, so upgrade first. If every seat is taken, API key agent opens Bring your whole team in instead. See Plan and usage.
  • To give the agent categories, your memory has been built.
  • You have an email address that belongs to no other account.

How an agent differs from a person

Agent accountPerson
RoleAlways MemberMember or Admin
Sign-inAPI keys onlyBrowser sign-in
SeatOneOne
KnowledgeOnly the categories you pickCategories granted, or all for an admin
Restricted sourcesNever. Agents are not offered when you pick people.Only the ones they were picked for
Assistant toolsThe same as a member, see RolesDepends on the role
In the member listNo, in the Agents tableYes

Create an agent account

Open Agents

Go to Team, open the Agents tab and click API key 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 add them later.

Create the key

Click Create & mint key. You should see "Agent [name] created." and the dialog Copy this API key now.

Copy the key

Click the copy icon ("Copied to clipboard."), store the key somewhere safe and click Done.

The full key is shown once. Afterwards you only see a shortened version. If you lose it, generate a new key and revoke the old one.

Use the key

Point your software at the Gurusup MCP server, https://mcp.brain.gurusup.com/mcp, and send the key as a bearer token in the Authorization header. It gets the same tools as a member's assistant, limited to the agent's categories. Add ?profile=catalog to the URL to also get learn and the operation tools.

To connect a person's assistant instead, use Connect an assistant.

Manage an agent

Each agent is a row of the Agents tab with these columns: Agent, Owner, Apps, Access, Visibility, Created and Last activity. Paused shows as a badge next to the name when it applies, and the table is sorted by name in natural order (for example, Agent 2 comes before Agent 10). Owner is the current owner for an agent created in Gurusup (the owner can change after creation) and the person who created it for an API key agent. It reads "Former member" when that person has left. Access reads "All" or a number of categories, for example "3 categories". For an agent created in Gurusup, Apps is one count of the apps assigned to it, private ones included: "3 apps", "1 app" or "No apps". For an agent that uses an API key, Apps and Visibility show a dash, because it cannot have apps. To add apps to an agent created in Gurusup, see Connect apps for agents, and to follow its work, see Follow agent activity. Only API key agents have a menu on their row, with Manage agent and Delete agent. Click Manage agent.

ToDo thisYou should see
Change what it readsIn Knowledge access, click a category to grant or remove it. It saves straight away.The category ticked or unticked
Add a keyClick Generate new key and copy it. An agent can hold several keys, so you can swap one without a gap."API key created." and Copy this API key now with "[name] · new key"
Revoke a keyClick the trash icon on the key, then Revoke in "Revoke API key"."API key revoked." With none left, "No active keys."
Delete the agentUse Delete agent in the row's menu, and confirm in "Delete [name]". All its keys go with it and its seat is freed."Agent deleted."

A revoked key can keep working for up to five minutes, because Gurusup remembers a checked key for that long. If a key leaked, revoke it straight away and allow for that delay.

Give each agent only the categories it needs, and use one agent per system so you can revoke one without touching the others.

If something fails

MessageWhat to do
"No agents yet."The table is empty. Click API key agent to create one.
"We can't show your agents right now. This is on our side and your agents keep working. Contact support if it lasts."The table did not load. Your agents and their keys keep working. Reload, and contact support if it stays.
"Give the agent a name."Enter a name.
"Enter a valid email."The email needs an @.
"That email already belongs to another account. Use a different email for the agent."Use an address that is only for this agent.
"This conflicts with an account that already exists. Contact support and we'll sort it out."Contact support.
A message saying agent accounts aren't enabled yetContact support.
"We couldn't create this agent. Nothing was saved: try again in a minute, and contact support if it keeps failing."Try again in a minute. No half-made account is left.
"Couldn't create agent. Category access can't be changed until Gurusup has finished building your company knowledge. Contact support if this keeps happening."Create the agent without categories and add them later. Gurusup 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.
"Agent accounts are always members; their role can't be changed."Nothing to do: agents cannot be admins.