# Agent Blueprints > Agent Blueprints must be enabled for your environment. Contact your WorkOS account team if it is not yet available. ## Introduction Agent Blueprints give AI agents first-class, revocable identities in your AuthKit-powered app. Instead of handing an agent a long-lived API key or a borrowed user credential, you define a blueprint — a reusable agent definition with a permission ceiling and token lifetimes — and mint short-lived, scoped access tokens from it on demand. Agent Blueprints are designed for your own first-party agents: agents that you build and operate as part of your application. Every blueprint and token operation is a server-side call authenticated with your [WorkOS API key](https://workos.com/docs/reference/api-authentication), so your backend stays in control of which agents run and what they can do. Third-party agents connecting to your app from the outside are not covered by this guide. Agents run in one of two modes: [delegated](#delegated-and-autonomous-instances), acting on behalf of a specific signed-in user and capped by that user's permissions, or [autonomous](#delegated-and-autonomous-instances), acting as itself in an organization with no user principal. Agent Blueprints are built around four concepts: | Concept | Description | | ------- | ----------- | | [Blueprint](https://workos.com/docs/reference/agents/blueprint) | A reusable agent definition: name, permission ceiling, who may invoke it, and session lifetimes. | | [Instance](https://workos.com/docs/reference/agents/instance) | A blueprint instantiated in a specific organization — delegated (acting for a specific user) or autonomous (acting as itself). | | [Session](https://workos.com/docs/reference/agents/session) | The revocable state backing a mint: each mint creates (or chains) a session that bounds the tokens issued under it. | | Session tokens | The access token (a JWT) and single-use refresh token returned by a mint, scoped by the session. | ## Creating a blueprint Create a blueprint with the [Create an agent blueprint](https://workos.com/docs/reference/agents/blueprint/create) endpoint. The blueprint's configuration controls everything minted from it: - `permissions` — permission slugs forming the ceiling on what sessions minted from this blueprint may do. - `invocable_by` — which role slugs may mint user-delegated sessions, and which organizations sessions may be minted in. Empty lists allow any member or any organization in the environment. - `session_settings` — token and session lifetimes, described in [Token and session lifetimes](#token-and-session-lifetimes). ```bash curl -X POST https://api.workos.com/agents/blueprints \ -H "Authorization: Bearer sk_example_123456789" \ -H "Content-Type: application/json" \ -d '{ "name": "Prospecting Agent", "description": "Finds and qualifies sales prospects.", "permissions": ["crm:read", "email:send"], "invocable_by": { "role_slugs": ["manager"], "organization_ids": [] }, "session_settings": { "max_age_seconds": 86400, "access_token_ttl_seconds": 300, "refresh_token_ttl_seconds": 3600 } }' ``` ## Delegated and autonomous instances An agent instance is created automatically the first time a session is minted from a blueprint for a given organization (and user, when delegated). Instances come in two kinds, reported in the instance's `type` field: - `delegated` — the agent acts on behalf of a specific user. Minting requires presenting that user's access token, and the effective permissions are the intersection of the user's permissions and the blueprint's ceiling. - `autonomous` — the agent acts as itself in an organization, with no user principal. The effective permissions are the blueprint's ceiling. ## Minting tokens Mint tokens with the [Mint an agent token](https://workos.com/docs/reference/agents/blueprint/token/mint-token) endpoint. Like all Agent Blueprint endpoints, minting is a server-side call authenticated with your WorkOS API key — your backend requests the token (presenting the user's access token for delegated sessions) and hands the resulting agent token to your agent. Agents never hold your API key, only the short-lived, scoped tokens minted for them. The request body is discriminated on `type`: | `type` | Presents | Use case | | ------ | -------- | -------- | | `user_delegated` | `user_access_token` | Start an agent session on behalf of a signed-in user. | | `autonomous` | `organization_id` | Start a session for the agent acting as itself in an organization. | | `agent_delegated` | `agent_access_token` | Chain: exchange an agent's own token for a new session on the same instance. | | `refresh` | `refresh_token` | Rotate a previously issued refresh token. | For example, to mint a user-delegated session: ```bash curl -X POST https://api.workos.com/agents/blueprints/agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY/tokens \ -H "Authorization: Bearer sk_example_123456789" \ -H "Content-Type: application/json" \ -d '{ "type": "user_delegated", "user_access_token": "", "intent": "renew-contract-123" }' ``` The response includes the access token, a single-use refresh token, and the identifiers of the instance and backing session: ```json { "access_token": "eyJhb...", "token_type": "Bearer", "expires_in": 300, "refresh_token": "yAjhKk...", "agent_instance_id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY", "new_instance": true, "agent_instance_session_id": "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY", "permissions": ["crm:read", "email:send"] } ``` ### Declaring intent Every mint variant accepts an optional `intent` string — caller-supplied context describing what the token will be used for. The intent is never persisted; it is echoed into the minted access token as an object with a `text` field: ```json { "intent": { "text": "renew-contract-123" } } ``` Your API can read the claim when authorizing requests, and it travels with the token through logs and downstream services. ### Agent token claims The agent access token is a JWT signed with the same keys as your environment's user access tokens. Its claims include: | Claim | Description | | ----- | ----------- | | `sub` | The agent instance ID. | | `sub_profile` | Always `ai_agent` on agent tokens, distinguishing them from user access tokens, which currently omit this claim. | | `sid` | The backing agent instance session ID. | | `org_id` | The organization the agent acts within. | | `permissions` | The effective permission slugs. | | `act` | For delegated sessions, identifies the delegating user (`act.sub`). Absent on autonomous sessions. | | `intent` | The declared intent as `{ "text": "..." }`, when provided. | Check for `sub_profile: "ai_agent"` to identify agent callers without parsing ID formats; tokens without the claim are user access tokens. ## Token and session lifetimes A blueprint's `session_settings` define three lifetimes: | Setting | Description | Maximum | | ------- | ----------- | ------- | | `max_age_seconds` | Hard ceiling on a session chain's total lifetime; refreshes and chained sessions never extend past it. | 31,536,000 (365 days) | | `access_token_ttl_seconds` | Lifetime of each minted access token. | 3,600 (1 hour) | | `refresh_token_ttl_seconds` | Lifetime of each rotated refresh token, which is also the session's lifetime between refreshes. | 5,184,000 (60 days) | Token lifetimes are clamped to the remaining session lifetime: an access token never advertises validity past its backing session's expiry, and a refresh never extends a session past the chain's `max_age_seconds` window. ### Refresh token rotation Refresh tokens are single-use. Each `refresh` mint rotates the refresh token and returns a fresh access token, and authorization is fully re-derived at refresh time — a revoked role or removed membership stops taking effect at the next refresh rather than living on for the session's lifetime. ### Session chaining An agent can present its own access token in an `agent_delegated` mint to create a child session on the same instance. Each child session records its parent, forming a chain back to the root session. Chains do not extend authority: - The chain's maximum lifetime is anchored at the root session: no hop can extend the chain past the root session's `created_at` plus `max_age_seconds`, regardless of how many chains or refreshes happen in between. - Permissions are re-derived from current authority at each hop rather than trusted from the presenting token, and the delegating user (if any) is carried through unchanged. - An agent can only chain as itself — the presented token must have been minted from the same blueprint, and the new session is created on the same instance. ## Revoking sessions Revoke a session with the [Revoke an agent instance session](https://workos.com/docs/reference/agents/session/revoke) endpoint. Revocation invalidates the session's refresh token and every access token minted under it, and cascades to descendant sessions — revoking a session also revokes every session chained under it. For delegated sessions, authority also flows from the delegating user's own session: when that user session ends, chain mints and refreshes are refused. ## Lifecycle events Agent Blueprints emit the following [events](https://workos.com/docs/events), available via webhooks and the Events API: - `agent.blueprint.created` - `agent.blueprint.updated` - `agent.blueprint.deleted` - `agent.instance.created` - `agent.instance.deleted` - `agent.instance.session.created` - `agent.instance.session.revoked` ## API reference - [Agent blueprints](https://workos.com/docs/reference/agents/blueprint) — create, list, get, update, and delete blueprints. - [Mint an agent token](https://workos.com/docs/reference/agents/blueprint/token/mint-token) — mint, chain, and refresh sessions. - [Agent instances](https://workos.com/docs/reference/agents/instance) — list, get, and delete instances. - [Agent instance sessions](https://workos.com/docs/reference/agents/session) — list, get, and revoke sessions.