🚧 Roadmap — The capability described here is on the roadmap. The concepts and design are settled; interfaces and steps are subject to the final release.
Register and manage your agents
By the end of this guide you will know:
- The five actions an agent passes through, from "someone wants to build one" to "formally retired"
- Who performs each action, and what it means when you get stuck at a given step
- Why "register" is the one step you cannot skip — it is the mount point for every governance action that follows
Prerequisites
- A workspace (the isolation unit for agents and access keys — see the workspace endpoints in API Reference)
- Named candidates for Owner and Sponsor (how the two roles divide the work is in The Agent Identity model)
- The list of resources this agent needs to reach — you use it to derive which scopes it should get
The five actions
1. Register: give it an identity first
Registration gives the agent a recognizable identifier, a description, and a pair of accountable people. What this step produces is not permission, only identity — a freshly registered agent can do nothing at all, and that is the design intent.
Four things to state clearly at registration:
| Item | Why it matters |
|---|---|
| Agent identifier and purpose | Six months from now someone will ask "what is this for" — the answer has to be on the record |
| Owner | Who to find for configuration, key rotation, and incidents |
| Sponsor | Who to find for why it exists, whose books it lands on, and whether to renew it |
| Requested capability scope | The thing approval will evaluate |
The Sponsor is a required field
Owners can change, and an Owner may be a contractor — but a Sponsor must always be in place. This is the institutional guarantee that "who is accountable for this agent?" always has an answer: when a Sponsor leaves, ownership transfers automatically to their manager, so no agent is ever left unowned.
2. Approve: put the permissions in front of a human
After registration, submit the capability request and let an approver evaluate it: is the scope this agent wants reasonable? Does it match its stated purpose? Does it exceed the Sponsor's own responsibility boundary?
Only after approval does the agent go from "on the record" to "usable." If the request is rejected or withdrawn, it drops back to a needs-work state.
Approval is granted at the granularity of a capability set, not a single task. Authorization for a single task is granted at runtime by a user or the organization (see Consent and approval) — the two layers stack: what an agent can obtain at runtime never exceeds the approved boundary.
3. Connect resources: tell it what it may touch
After approval, associate the agent with concrete resources: which APIs, which data domains, which types of third-party accounts. This step defines the menu that later delegations can choose from.
Configuration discipline: configure for the minimum set, not for "we might need it someday." Widening can always be requested again; narrowing is the thing nobody remembers to do.
4. Review: look back on a schedule
The most likely thing to happen after an agent goes live is that it quietly persists: the business stopped, the people left, and the agent is still running with its permissions still in force. A review has to answer three questions on a schedule:
- Is this agent still being used?
- Does its permission scope still match what it actually does today?
- Is the Sponsor still here, and do they still stand behind it?
If any of the three is a no, it goes into the retire or narrow flow. For the fleet-level view of reviews, see Governing an enterprise agent fleet.
5. Retire: shut it down cleanly
Retiring is not deleting the record. It is making the agent thoroughly ineffective while leaving the trail behind: disable credentials, terminate in-flight grants, move the agent's status to retired, and keep the audit records.
After retirement the ledger still shows that this agent existed, what it did, and who was accountable — that is an audit requirement, and it is also the precondition for any post-mortem. For pulling permissions back immediately in an emergency, see Revocation and emergency response.
Who performs the five actions
| Action | Primary performer | Who needs to be involved |
|---|---|---|
| Register | Owner | Sponsor confirms ownership |
| Approve | Approver (security or business manager) | Sponsor explains the purpose |
| Connect resources | Owner | Resource owner confirms the scope |
| Review | Security / platform team | Sponsor makes the renewal call |
| Retire | Owner | Security team confirms no in-flight dependencies |
FAQ
Can register and approve be merged? You can merge the UI, but not the semantics. Registration answers "what is this"; approval answers "what is it allowed to do." The first records a fact, the second makes a risk decision. Blend them and approval turns into a rubber stamp.
Do throwaway test agents have to go through the whole flow? We recommend they do, but you can apply a lighter approval policy to test workspaces. The dangerous thing is not a heavy process — it is a test agent with wide permissions that made it into production and is not in the ledger.
Can one agent represent multiple users at once? Yes. There is one agent identity, and delegations are granted one at a time — the same agent can hold multiple delegations from different users, isolated from one another, each expiring on its own. This is also why the audit has to record both sub and act (see Audit and accountability chain).
Next steps
- The Agent Identity model — the full model of templates and agents, accountable people, and the state machine.
- Governing an enterprise agent fleet — from one agent to a fleet.
- Revocation and emergency response — how to pull permissions back when something goes wrong.