Skip to main content
These twelve things always hold. When something surprises you, it’s usually one of them.
  1. Every agent has exactly one profile and one identity. The identity is required at creation and never changes; create a new agent instead. See Agents and Identities.
  2. Profiles are shared. Editing one changes every agent attached to it on its next admitted turn. Turns already running keep the snapshot they started with. See How it fits together.
  3. Roles are the only source of tool access, and profiles select them. There’s no roleIds on an agent. A profile with no roles gives its agents no tools. See Roles.
  4. Allows add up, conditions narrow, denies win. An agent gets every tool its selected roles allow. A where condition narrows one grant and never subtracts from another. A deny (built-in tools only) beats every allow. See Roles.
  5. Registering a toolset grants nothing, and approving a hook grants nothing. Toolsets publish tools into a namespace; roles decide who may call them. Hooks can only pause, deny, or rewrite work the roles already allowed.
  6. Roles authorize, connections authenticate. A role says what an agent may call; a connection supplies the login. A connection is owned by the workspace or by exactly one identity; an agent may only use connections it is eligible for, and the model never sees the secret.
  7. Spending is only capped where you set a cap. An agent may carry a budget (limit in USD per 24h, 7d, or total); a thread may pin maxCost. Absent means unlimited. See Agents.
  8. Every API resource is also a built-in tool namespace. An agent can manage agents, roles, profiles, toolsets, feeds, schedules, and the rest, subject to the roles its profile selects. See Built-in tools.
  9. Agents can only narrow. A role, profile, or child agent an agent creates must fit inside the caller’s current access, must keep every deny it holds, and a child inherits the caller’s identity. No role, tool:* included, lets an agent hand out access it doesn’t have. See Permissions.
  10. Destructive configuration changes ask a human first, by default. New profiles install six removable approval hooks covering agents.delete, roles.create, sending Gmail, writing Calendar, writing Drive, and pointing a toolset at a URL. They’re ordinary profile hooks: edit them, or send hooks: [] for none. See Hooks.
  11. Threads under one agent share its memory, identity, and credentials, but not each other’s transcripts. Siblings coordinate explicitly, with thread.create and thread.wait. See Threads.
  12. Everything is readable back through the API. Every thread event, memory entry, feed message, and subscription evaluation is available through the API, in pages. Everything pages by cursor except feed messages, which page by sequence range.