AgentOS Roles
Define roles in your AgentOS database, typically for your application's end users, or resolve them from an identity-provider JWT.
AgentOS roles, called managed roles in the SDK, are role definitions and assignments that Authorization stores in your AgentOS database, typically for your application's end users. Your backend or identity provider supplies signed JWTs identifying each caller; the runtime resolves permissions from the role store on each request. Manage roles in code, through the admin /authz API, or from os.agno.com → Manage OS → Roles.
These APIs are part of the open-source runtime. Organization roles for your team in the control plane are separate and have their own subscription requirements.
Configure Managed Roles
Install the runtime, model client, PostgreSQL driver, and asymmetric JWT support:
uv pip install -U "agno[os]>=3.1.3" openai "psycopg[binary]" "PyJWT[crypto]"Start PostgreSQL using the PostgreSQL setup. Set DATABASE_URL to your connection string, JWT_VERIFICATION_KEY to your issuer's RS256 public key, AGNO_ADMIN_SUBJECT to the admin's JWT sub, and OPENAI_API_KEY before starting the application. Configure your issuer to send aud="managed-roles-os" and a usable sub in its tokens.
import os
from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS, Authorization
db = PostgresDb(db_url=os.environ["DATABASE_URL"])
authz = Authorization(
verification_keys=[os.environ["JWT_VERIFICATION_KEY"]],
algorithm="RS256",
verify_audience=True,
audience="managed-roles-os",
audit=True,
)
authz.define_role("admin", ["agent_os:admin"])
authz.define_role("viewer", ["agents:read"])
authz.define_role(
"runner",
["agents:research-agent:read", "agents:research-agent:run"],
)
authz.seed(admin=os.environ["AGNO_ADMIN_SUBJECT"])
authz.assign("user-123", "runner")
agent = Agent(
id="research-agent",
model=OpenAIResponses(id="gpt-5.6-luna"),
)
agent_os = AgentOS(
id="managed-roles-os",
agents=[agent],
db=db,
authorization=authz,
user_isolation=True,
)
app = agent_os.get_app()
if __name__ == "__main__":
agent_os.serve(app="managed_roles_app:app", port=7777)Run python managed_roles_app.py, then send an issuer-signed JWT in the Authorization: Bearer <token> header, as described in BYO Token.
Authorization borrows the database passed to AgentOS. Defining roles before constructing AgentOS enables the managed-role provider and mounts the admin-gated /authz API. audit=True records role changes and authorization decisions in the bound database. user_isolation=True separately scopes built-in user-owned data to the caller.
Once AgentOS roles are enabled, the runtime ignores JWT scopes, including those in your team's os.agno.com tokens. Set trust_token_scopes=True to keep the control plane working alongside AgentOS roles. See Combine Managed Roles with Token Scopes.
The JWT for user-123 can carry identity and audience without a scopes claim. The stored runner role permits reading and running research-agent. Other routes require grants of their own: for example, browsing the Registry requires registry:read, and reading sessions requires sessions:read.
define_role, seed, and assign are bootstrap operations. Existing role definitions and assignments survive application restarts. assign seeds a role only when the subject has no stored roles; use the runtime API when changing an existing assignment. seed restores an admin assignment only when the store has no admin, so handing administration to another subject survives a restart. Bootstrap with a synchronous SQL database when using define_role, seed, or assign. For an asynchronous database, configure role policy through the async runtime API after the database is bound.
Update Roles at Runtime
Once AgentOS has bound the database, use the Authorization object or the admin-gated /authz API to change permissions:
authz.set_role("user-123", "viewer")
authz.set_role_scopes("viewer", ["agents:research-agent:read"])For async callers, use the corresponding methods:
await authz.aset_role("user-123", "viewer")
await authz.aset_role_scopes("viewer", ["agents:research-agent:read"])Managed-role changes affect subsequent authorization decisions without requiring a new JWT. The admin role authorizes role management; it does not automatically remove the separate per-user isolation boundary.
Read Roles from an Identity Provider
If your identity provider sends role names instead of Agno scopes, set roles_claim when constructing Authorization:
authz = Authorization(
verification_keys=[os.environ["JWT_VERIFICATION_KEY"]],
algorithm="RS256",
verify_audience=True,
audience="managed-roles-os",
roles_claim="roles",
)
authz.define_role("runner", ["agents:research-agent:read", "agents:research-agent:run"])Pass this object to AgentOS(authorization=authz, db=db). A JWT with sub="user-123" and roles=["runner"] selects the locally defined role without a per-user assign call. A single string role is also accepted; use roles_claim="role" if that is your issuer's claim name. Configure verification keys, algorithm, audience, and optional issuer for the actual issuer, as described in BYO Token.
An undefined role grants no permissions. An absent, empty, or unusable role claim falls back to stored assignments and the default role, if configured. Require your issuer to send a usable claim if token roles must be the only source of role selection.
Combine Managed Roles with Token Scopes
With trust_token_scopes=True, either source can grant access, and resource listings include the union of their grants. A denial in one source cannot restrict a grant from the other source.
Service-account PAT scopes are enforced independently of the JWT role provider. A PAT with the admin scope can bypass self-scoping; use narrower scopes for ordinary machine callers.