How an agent connects and what it can reach
An agent signs in as a person — a one-time code sent to their email — and then carries that authorization on every request, because the connection keeps no sticky session. It works in one business at a time, chosen explicitly, and can do exactly what that person's role permits. Nothing more.
Requirements: an account in the business, with a role carrying the permissions the work needs.
Before an agent can do anything with your records it has to establish two things: who it is acting as, and which business it is working in. Both are explicit, and both bound everything that follows.
Signing in
Authorization begins with a person, not a faceless key you paste once and forget. The agent starts a sign-in for an email address, a one-time code is sent to that inbox, and submitting the code establishes the authorization. That flow has a deliberate consequence: someone with access to that mailbox has to approve the connection. An agent cannot quietly grant itself entry to a business.
The resulting authorization is then carried on every request. The connection keeps no sticky session in the background — each call identifies itself. In practice this means holding the authorization for the length of the work and re-establishing it when it lapses, which it will on a long-running job.
Choosing the business
Authorization tells the system who you are; it does not say where you are working. An agent works in one business at a time, and that choice is explicit — it can be listed and switched, but never assumed. Everything read or written belongs to the business currently selected.
This is worth being careful about when someone belongs to several businesses. The most common cause of "the collection does not exist" is not a missing collection — it is the right collection in a different business than the one currently selected. Confirm where you are before concluding something is missing.
An agent is bounded by its role
Because an agent acts as a person, it inherits exactly that person's permissions — the same roles described in how access works. A role that can read two collections and update one gives an agent precisely that reach; a request beyond it is refused, the same as it would be in the interface.
The practical advice follows directly: give an agent its own account with a role scoped to the job, rather than connecting it as an administrator because that is convenient. An automated participant that can restructure your business is a much larger risk than one that can update the two collections it was built to work on. Scope narrowly, and widen deliberately if the work genuinely needs it.
Withdrawing access
Because access flows from a person and a role, it is withdrawn the same way. Change what the role permits and the agent's reach changes with it; remove the account and the connection stops working. There is no separate agent registry to remember to clean up — which is exactly the point of routing agent access through the ordinary access model.
Notes and limitations
- Authorization is per request — there is no persistent session; long jobs must handle re-authorizing.
- Sign-in requires access to the person's mailbox, so establishing a connection cannot be fully unattended.
- The active business is explicit and does not persist assumptions — confirm it before concluding something is missing.
- Permissions are the person's, not the agent's — there is no elevated agent mode.
- Business isolation applies to agents exactly as to people: one connection reaches one business at a time.
Related
What an agent can actually do once connected is in working with Sonta programmatically. Roles and permissions are covered in how access works, and the boundary between businesses in businesses and multi-tenancy.