<!-- llms.txt: https://workos.com/llms.txt -->

# AgentBlueprint

:::code-group{title="Example AgentBlueprint"}

```json language="curl"
{
  "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"
}
```

:::

## Create an agent blueprint

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.

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```rb language="ruby" title="Request" tab="1"
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
  }
)
```

```py language="python" title="Request" tab="1"
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,
    },
)
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?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,
    ],
);
```

```java language="java" title="Request" tab="1"
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);
```

```cs language="dotnet" title="Request" tab="1"
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 },
        },
});
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

## Delete an agent blueprint

Deletes an agent blueprint along with its configuration, instances, and sessions.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/agents/blueprints/agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.agents.delete_blueprint(agent_blueprint_id: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY")
```

```py language="python" title="Request" tab="1"
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"
)
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->agents()
    ->deleteBlueprint(
        agentBlueprintId: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.deleteBlueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Agents.DeleteBlueprintAsync("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

:::

## Get an agent blueprint

Retrieves an agent blueprint by ID.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/agents/blueprints/agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.agents.get_blueprint(agent_blueprint_id: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY")
```

```py language="python" title="Request" tab="1"
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"
)
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->agents()
    ->getBlueprint(
        agentBlueprintId: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.getBlueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Agents.GetBlueprintAsync("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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 agent blueprints

Lists the agent blueprints in the current environment.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/agents/blueprints" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.agents.list_blueprints
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.agents.list_blueprints()
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->agents()->listBlueprints();
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.listBlueprints();
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Agents.ListBlueprintsAsync();
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
  }
}
```

:::

## Mint an agent token

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.

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```rb language="ruby" title="Request" tab="1"
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"
)
```

```py language="python" title="Request" tab="1"
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",
)
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->agents()
    ->createBlueprintToken(
        agentBlueprintId: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY",
        type: "user_delegated",
    );
```

```java language="java" title="Request" tab="1"
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);
```

```cs language="dotnet" title="Request" tab="1"
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",
                                              });
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
  ]
}
```

:::

## Update an agent blueprint

Updates an agent blueprint. Omitted fields are left unchanged; provided lists replace the existing configuration.

:::code-group

```bash language="curl" title="Request" tab="1"
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
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.agents.update_blueprint(agent_blueprint_id: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY")
```

```py language="python" title="Request" tab="1"
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"
)
```

```go language="go" title="Request" tab="1"
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 language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->agents()
    ->updateBlueprint(
        agentBlueprintId: "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.updateBlueprint("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Agents.UpdateBlueprintAsync("agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

```rust language="rust" title="Request" tab="1"
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(())
}
```

```json language="json" title="Response" tab="2"
{
  "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"
}
```

:::

### agent_blueprint

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "agent_blueprint" | Yes | Distinguishes the agent blueprint object. |
| `id` | string | Yes | Unique identifier of the agent blueprint. |
| `name` | string | Yes | Human-readable name of the agent blueprint. |
| `description` | string | No | Human-readable description of the agent blueprint. |
| `permissions` | string[] | Yes | Permission slugs forming the ceiling on what sessions minted from this blueprint may do. |
| `invocable_by` | object | Yes | Who may mint sessions from this blueprint. |
| `session_settings` | object | Yes | Token and session lifetimes for sessions minted from this blueprint. |
| `created_at` | string | Yes | Timestamp when the agent blueprint was created. |
| `updated_at` | string | Yes | Timestamp when the agent blueprint was last updated. |

### POST /agents/blueprints

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Human-readable name of the agent blueprint. |
| `description` | string | No | Human-readable description of the agent blueprint. |
| `permissions` | string[] | No | Permission slugs forming the ceiling on what sessions minted from this blueprint may do. Each slug must exist in the environment. Defaults to `[]`. |
| `invocable_by` | object | No | Who may mint sessions from this blueprint. Defaults to `{}`. |
| `session_settings` | object | Yes | Token and session lifetimes for sessions minted from this blueprint. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `agent_blueprint` | object | Distinguishes the agent blueprint object. |

### DELETE /agents/blueprints/{agent_blueprint_id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_blueprint_id` | string | Yes | The unique ID of the agent blueprint. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### GET /agents/blueprints/{agent_blueprint_id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_blueprint_id` | string | Yes | The unique ID of the agent blueprint. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `agent_blueprint` | object | Distinguishes the agent blueprint object. |

### GET /agents/blueprints

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `before` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `before="obj_123"` to fetch a new batch of objects before `"obj_123"`. |
| `after` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. For example, if you make a list request and receive 100 objects, ending with `"obj_123"`, your subsequent call can include `after="obj_123"` to fetch a new batch of objects after `"obj_123"`. |
| `limit` | integer | No | Upper limit on the number of objects to return, between `1` and `100`. Defaults to `10`. |
| `order` | "normal" \| "desc" \| "asc" | No | Order the results by the creation time. Supported values are `"asc"` (ascending), `"desc"` (descending), and `"normal"` (descending with reversed cursor semantics where `before` fetches older records and `after` fetches newer records). Defaults to `normal`. |

### POST /agents/blueprints/{agent_blueprint_id}/tokens

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | "user_delegated" \| "autonomous" \| "agent_delegated" \| "refresh" | Yes | How the session is minted: `user_delegated`, `autonomous`, `agent_delegated`, or `refresh`. |
| `user_access_token` | string | Yes | The access token of the user delegating to the agent. The token identifies the user and organization; effective permissions are resolved server-side. |
| `intent` | string | No | Optional caller-supplied context, echoed as an object with a `text` field in the `intent` claim of the minted access token. |
| `organization_id` | string | No | The organization the agent acts within when operating as itself. |
| `agent_access_token` | string | No | The agent's own access token to exchange for a new session on the same instance. The token must have been minted from this blueprint; permissions are re-derived from current authority. |
| `refresh_token` | string | No | The refresh token issued with a previous agent access token. Refresh tokens are single-use: each refresh rotates it. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_blueprint_id` | string | Yes | The unique ID of the agent blueprint. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `access_token` | string | The agent access token (a JWT) carrying the effective permissions. |
| `token_type` | "Bearer" | Always `Bearer`. |
| `expires_in` | integer | Number of seconds until the access token expires. |
| `refresh_token` | string | Single-use refresh token for rotating the access token within the session lifetime. |
| `agent_instance_id` | string | The agent instance the session belongs to. |
| `new_instance` | boolean | Whether this mint created the agent instance: `true` only for the mint that inserted the row, `false` when an existing instance was reused (including when a concurrent mint inserted it first). |
| `agent_instance_session_id` | string | The backing agent instance session. |
| `permissions` | string[] | The effective permission slugs carried by the token. |

### PATCH /agents/blueprints/{agent_blueprint_id}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Human-readable name of the agent blueprint. |
| `description` | string | No | Human-readable description of the agent blueprint. Pass `null` to clear it. |
| `permissions` | string[] | No | Permission slugs forming the ceiling on what sessions minted from this blueprint may do. Each slug must exist in the environment. |
| `invocable_by` | object | No | Who may mint sessions from this blueprint. Omitted lists are left unchanged. |
| `session_settings` | object | No | Token and session lifetimes for sessions minted from this blueprint. Omitted fields are left unchanged. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `agent_blueprint_id` | string | Yes | The unique ID of the agent blueprint. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `agent_blueprint` | object | Distinguishes the agent blueprint object. |