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

# AgentInstance

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

```json language="curl"
{
  "object": "agent_instance",
  "id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "agent_blueprint_id": "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "organization_membership_id": "om_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "type": "delegated",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Delete an agent instance

Deletes an agent instance along with its sessions, invalidating their refresh tokens.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/agents/instances/agent_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_instance(agent_instance_id: "agent_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_instance(agent_instance_id="agent_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().DeleteInstance(context.Background(), "agent_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()
    ->deleteInstance(agentInstanceId: "agent_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.deleteInstance("agent_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.DeleteInstanceAsync("agent_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_instance("agent_01EHWNCE74X7JSDV0X3SZ3KJNY")
        .await?;

    Ok(())
}
```

:::

## Get an agent instance

Retrieves an agent instance by ID.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/agents/instances/agent_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_instance(agent_instance_id: "agent_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_instance(agent_instance_id="agent_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().GetInstance(context.Background(), "agent_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()
    ->getInstance(agentInstanceId: "agent_01EHWNCE74X7JSDV0X3SZ3KJNY");
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.getInstance("agent_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.GetInstanceAsync("agent_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_instance("agent_01EHWNCE74X7JSDV0X3SZ3KJNY")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "agent_instance",
  "id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "agent_blueprint_id": "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "organization_membership_id": "om_01EHWNCE74X7JSDV0X3SZ3KJNY",
  "type": "delegated",
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## List agent instances

Lists the agent instances in the current environment. Instances are created implicitly when tokens are minted.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/agents/instances" \
  --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_instances
```

```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_instances()
```

```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().ListInstances(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()->listInstances();
```

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

WorkOS workos = new WorkOS("sk_example_123456789");

workos.agents.listInstances();
```

```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.ListInstancesAsync();
```

```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_instances()
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "agent_instance",
      "id": "agent_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "agent_blueprint_id": "agent_blueprint_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "organization_id": "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "organization_membership_id": "om_01EHWNCE74X7JSDV0X3SZ3KJNY",
      "type": "delegated",
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "agent_01HXYZ123456789ABCDEFGHIJ",
    "after": "agent_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

### agent_instance

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "agent_instance" | Yes | Distinguishes the agent instance object. |
| `id` | string | Yes | Unique identifier of the agent instance. |
| `agent_blueprint_id` | string | Yes | The blueprint this instance was minted from. |
| `organization_id` | string | Yes | The organization the instance acts within. |
| `organization_membership_id` | string | No | The organization membership of the delegating user; `null` for autonomous instances. |
| `type` | "delegated" \| "autonomous" | Yes | Whether the instance acts on behalf of a specific user (`delegated`) or as itself (`autonomous`). |
| `created_at` | string | Yes | Timestamp when the agent instance was created. |
| `updated_at` | string | Yes | Timestamp when the agent instance was last updated. |

### DELETE /agents/instances/{agent_instance_id}

#### Parameters

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

#### Returns

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

### GET /agents/instances/{agent_instance_id}

#### Parameters

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

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `agent_instance` | object | Distinguishes the agent instance object. |

### GET /agents/instances

#### 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`. |
| `organization_id` | string | No | Only return instances acting within this organization. |
| `agent_blueprint_id` | string | No | Only return instances minted from this blueprint. |