Skip to main content
GET
JavaScript
The agents in a workspace, newest first. This is the read behind an agent picker or a dashboard.

Archived agents are hidden by default

The list returns STATE_DRAFT and STATE_PUBLISHED agents and leaves archived ones out. To see archived agents, ask for them by state:
The state filter narrows to one state, and there are three you can pass: So state: 'STATE_ARCHIVED' is the only way to list archived agents, and state: 'STATE_DRAFT' is how you find the agents that still need a variation before they can publish.

info comes for free

Each row carries info on every call, includeInfo is a no-op here:
variationCount is the quick way to spot an agent that cannot run yet: a published agent needs at least one variation, and a 0 on a draft is why it cannot publish.

Paging and filtering

The usual list controls apply: limit (1 to 100), cursor, prefix (name starts-with), and query (free-text over name and description). A pagination block with a nextCursor comes back while more pages remain, and is absent on the last page.

Get an agent

One agent by id, canonical or external_id:.

Create an agent

What a STATE_DRAFT agent starts as.

Publish an agent

Move a draft to STATE_PUBLISHED so it can run.

List variations

The variations behind info.variationCount.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Query Parameters

limit
integer<int32>

Maximum number of results to return

cursor
string

Pagination cursor from previous response

prefix
string

Filter expression (query param: prefix)

query
string

Free-form search query

state
enum<string>

Filter by agent lifecycle state

Available options:
STATE_UNSPECIFIED,
STATE_DRAFT,
STATE_PUBLISHED,
STATE_ARCHIVED
variationSelectionMode
enum<string>

Filter by variation selection mode

Available options:
VARIATION_SELECTION_MODE_UNSPECIFIED,
VARIATION_SELECTION_MODE_RANDOM,
VARIATION_SELECTION_MODE_WEIGHTED
labels
string

Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).

sortOrder
string

Sort order for results (asc or desc by creation time)

includeInfo
boolean

When true, the info field on each returned agent is populated. Requests with this flag count more against your rate limit.

Response

OK

List agents response

items
object[]
pagination
object

Page carries cursor-based pagination state. There is no total: the cursor walks the result set without ever counting it, and a count would cost a second query on every list.