Lists the agent blueprints in the current environment.
cURL
| curl "https://api.workos.com/agents/blueprints" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.list_blueprints |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.list_blueprints() |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().ListBlueprints(context.Background()) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->agents()->listBlueprints(); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.agents.listBlueprints(); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.ListBlueprintsAsync(); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .list_blueprints() | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "list", | |
| "data": [ | |
| { | |
| "object": "agent_blueprint", | |
| "id": "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "name": "Prospecting Agent", | |
| "description": "Finds and qualifies sales prospects.", | |
| "permissions": [ | |
| "crm:read", | |
| "email:send" | |
| ], | |
| "invocable_by": { | |
| "role_slugs": [ | |
| "manager" | |
| ], | |
| "organization_ids": [ | |
| "org_01EHWNCE74X7JSDV0X3SZ3KJNY" | |
| ] | |
| }, | |
| "session_settings": { | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600 | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } | |
| ], | |
| "list_metadata": { | |
| "before": "agent_blueprint_01HXYZ123456789ABCDEFGHIJ", | |
| "after": "agent_blueprint_01HXYZ987654321KJIHGFEDCBA" | |
| } | |
| } |
Feature flagged
GET/agents
Parameters
Returns object
Creates an agent blueprint: the template describing what an agent may do (its permission ceiling), who may invoke it, and the lifetimes of its sessions.
cURL
| curl --request POST \ | |
| --url "https://api.workos.com/agents/blueprints" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "name": "Prospecting Agent", | |
| "session_settings": { | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600 | |
| } | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.create_blueprint( | |
| name: "Prospecting Agent", | |
| session_settings: { | |
| max_age_seconds: 3600, | |
| access_token_ttl_seconds: 300, | |
| refresh_token_ttl_seconds: 3600 | |
| } | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.create_blueprint( | |
| name="Prospecting Agent", | |
| session_settings={ | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600, | |
| }, | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().CreateBlueprint(context.Background(), &workos.AgentsCreateBlueprintParams{ | |
| Name: "Prospecting Agent", | |
| SessionSettings: map[string]any{ | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600, | |
| }, | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->agents()->createBlueprint( | |
| name: "Prospecting Agent", | |
| sessionSettings: [ | |
| "max_age_seconds" => 3600, | |
| "access_token_ttl_seconds" => 300, | |
| "refresh_token_ttl_seconds" => 3600, | |
| ], | |
| ); |
| import com.workos.WorkOS; | |
| import com.workos.agents.AgentsApi.CreateBlueprintOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| CreateBlueprintOptions options = CreateBlueprintOptions.builder() | |
| .name("Prospecting Agent") | |
| .sessionSettings(Map.of("max_age_seconds", | |
| 3600, | |
| "access_token_ttl_seconds", | |
| 300, | |
| "refresh_token_ttl_seconds", | |
| 3600)) | |
| .build(); | |
| workos.agents.createBlueprint(options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.CreateBlueprintAsync(new AgentsCreateBlueprintOptions { | |
| Name = "Prospecting Agent", | |
| SessionSettings = | |
| new Dictionary<string, object> { | |
| { "max_age_seconds", 3600 }, | |
| { "access_token_ttl_seconds", 300 }, | |
| { "refresh_token_ttl_seconds", 3600 }, | |
| }, | |
| }); |
| use workos::Client; | |
| use workos::agents::CreateBlueprintParams; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .create_blueprint( | |
| CreateBlueprintParams { | |
| name: "Prospecting Agent".into(), | |
| session_settings: serde_json::json!({ | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600, | |
| }), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "agent_blueprint", | |
| "id": "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "name": "Prospecting Agent", | |
| "description": "Finds and qualifies sales prospects.", | |
| "permissions": [ | |
| "crm:read", | |
| "email:send" | |
| ], | |
| "invocable_by": { | |
| "role_slugs": [ | |
| "manager" | |
| ], | |
| "organization_ids": [ | |
| "org_01EHWNCE74X7JSDV0X3SZ3KJNY" | |
| ] | |
| }, | |
| "session_settings": { | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600 | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
Feature flagged
POST/agents
Returns
Retrieves an agent blueprint by ID.
cURL
| curl "https://api.workos.com/agents/blueprints/agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.get_blueprint(agent_blueprint_id: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.get_blueprint( | |
| agent_blueprint_id="agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().GetBlueprint(context.Background(), "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->agents() | |
| ->getBlueprint( | |
| agentBlueprintId: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| ); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.agents.getBlueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.GetBlueprintAsync("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .get_blueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "agent_blueprint", | |
| "id": "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "name": "Prospecting Agent", | |
| "description": "Finds and qualifies sales prospects.", | |
| "permissions": [ | |
| "crm:read", | |
| "email:send" | |
| ], | |
| "invocable_by": { | |
| "role_slugs": [ | |
| "manager" | |
| ], | |
| "organization_ids": [ | |
| "org_01EHWNCE74X7JSDV0X3SZ3KJNY" | |
| ] | |
| }, | |
| "session_settings": { | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600 | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
Feature flagged
GET/agents
Parameters
Returns
Updates an agent blueprint. Omitted fields are left unchanged; provided lists replace the existing configuration.
cURL
| curl --request PATCH \ | |
| --url "https://api.workos.com/agents/blueprints/agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "name": "Prospecting Agent", | |
| "description": "Finds and qualifies sales prospects.", | |
| "permissions": [ | |
| "crm:read", | |
| "email:send" | |
| ], | |
| "invocable_by": { | |
| "role_slugs": [ | |
| "manager" | |
| ], | |
| "organization_ids": [ | |
| "org_01EHWNCE74X7JSDV0X3SZ3KJNY" | |
| ] | |
| }, | |
| "session_settings": { | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600 | |
| } | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.update_blueprint(agent_blueprint_id: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.update_blueprint( | |
| agent_blueprint_id="agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().UpdateBlueprint(context.Background(), "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->agents() | |
| ->updateBlueprint( | |
| agentBlueprintId: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| ); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.agents.updateBlueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.UpdateBlueprintAsync("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .update_blueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "agent_blueprint", | |
| "id": "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "name": "Prospecting Agent", | |
| "description": "Finds and qualifies sales prospects.", | |
| "permissions": [ | |
| "crm:read", | |
| "email:send" | |
| ], | |
| "invocable_by": { | |
| "role_slugs": [ | |
| "manager" | |
| ], | |
| "organization_ids": [ | |
| "org_01EHWNCE74X7JSDV0X3SZ3KJNY" | |
| ] | |
| }, | |
| "session_settings": { | |
| "max_age_seconds": 3600, | |
| "access_token_ttl_seconds": 300, | |
| "refresh_token_ttl_seconds": 3600 | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
Feature flagged
PATCH/agents
Parameters
Returns
Deletes an agent blueprint along with its configuration, instances, and sessions.
cURL
| curl --request DELETE \ | |
| --url "https://api.workos.com/agents/blueprints/agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.delete_blueprint(agent_blueprint_id: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.delete_blueprint( | |
| agent_blueprint_id="agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY" | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().DeleteBlueprint(context.Background(), "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->agents() | |
| ->deleteBlueprint( | |
| agentBlueprintId: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| ); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.agents.deleteBlueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.DeleteBlueprintAsync("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .delete_blueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY") | |
| .await?; | |
| Ok(()) | |
| } |
Feature flagged
DELETE/agents
Parameters
Returns
Mint an agent access token (and backing session) from an agent blueprint. The session can be user-delegated (exchanging a user access token), autonomous (the agent acting as itself in an organization), agent-delegated (the agent exchanging its own access token for a new session on the same instance), or a refresh of a previously issued refresh token.
cURL
| curl --request POST \ | |
| --url "https://api.workos.com/agents/blueprints/agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY/tokens" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "type": "user_delegated", | |
| "user_access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6..." | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.agents.create_blueprint_token( | |
| agent_blueprint_id: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| type: "user_delegated" | |
| ) |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.agents.create_blueprint_token( | |
| agent_blueprint_id="agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| type="user_delegated", | |
| ) |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v10" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Agents().CreateBlueprintToken(context.Background(), "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", &workos.AgentsCreateBlueprintTokenParams{ | |
| Type: "user_delegated", | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos | |
| ->agents() | |
| ->createBlueprintToken( | |
| agentBlueprintId: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| type: "user_delegated", | |
| ); |
| import com.workos.WorkOS; | |
| import com.workos.agents.AgentsApi.CreateBlueprintTokenOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| CreateBlueprintTokenOptions options = | |
| CreateBlueprintTokenOptions.builder().type("user_delegated").build(); | |
| workos.agents.createBlueprintToken("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Agents.CreateBlueprintTokenAsync("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| new AgentsCreateBlueprintTokenOptions { | |
| Type = "user_delegated", | |
| }); |
| use workos::Client; | |
| use workos::agents::CreateBlueprintTokenParams; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .agents() | |
| .create_blueprint_token( | |
| "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| CreateBlueprintTokenParams { | |
| type_: "user_delegated".into(), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...", | |
| "token_type": "Bearer", | |
| "expires_in": 300, | |
| "refresh_token": "njGkA8Wyht0GBEGGA0Zh1Q3wZzL2...", | |
| "agent_instance_id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "new_instance": false, | |
| "agent_instance_session_id": "agent_session_01EHWNCE74X7JSDV0X3SZ3KJNY", | |
| "permissions": [ | |
| "crm:read" | |
| ] | |
| } |
Feature flagged
POST/agents
Common
When
type is user_delegatedWhen
type is autonomousWhen
type is agent_delegatedWhen
type is refresh