Agent
Headless agent conversation and run operations.
Operations
Each operation lists its specific responses. See Common error responses for errors shared by every operation on this page.
Get the agent configuration
GET /api/v1/agent/config
Operation ID: getAgentConfig
Effect: read
Confirmation: never
Focused reference: JSON · Markdown
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update the agent configuration
PATCH /api/v1/agent/config
Operation ID: updateAgentConfig
Effect: write
Confirmation: conditional
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List agent conversations
GET /api/v1/agent/conversations
Operation ID: listAgentConversations
Effect: read
Confirmation: never
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create an agent conversation
POST /api/v1/agent/conversations
Operation ID: createAgentConversation
Effect: write
Confirmation: conditional
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
201 |
The request has succeeded and a new resource has been created as a result. |
List archived agent conversations
GET /api/v1/agent/conversations/archived
Operation ID: listArchivedAgentConversations
Effect: read
Confirmation: never
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Manage an owned agent conversation
POST /api/v1/agent/conversations/manage
Operation ID: manageAgentConversations
Effect: write
Confirmation: conditional
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Archive an agent conversation
DELETE /api/v1/agent/conversations/{conversation}
Operation ID: archiveAgentConversation
Effect: destructive
Confirmation: required
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string |
Responses
| Status | Description |
|---|---|
204 |
There is no content to send for this request, but the headers may be useful. |
Get an agent conversation
GET /api/v1/agent/conversations/{conversation}
Operation ID: getAgentConversation
Effect: read
Confirmation: never
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Update an agent conversation
PATCH /api/v1/agent/conversations/{conversation}
Operation ID: updateAgentConversation
Effect: write
Confirmation: conditional
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
If-Match |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List agent messages
GET /api/v1/agent/conversations/{conversation}/messages
Operation ID: listAgentMessages
Effect: read
Confirmation: never
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
List agent runs
GET /api/v1/agent/conversations/{conversation}/runs
Operation ID: listAgentRuns
Effect: read
Confirmation: never
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Create an asynchronous agent run
POST /api/v1/agent/conversations/{conversation}/runs
Operation ID: createAgentRun
Effect: write
Confirmation: conditional
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Request body
Content types: application/json.
Responses
| Status | Description |
|---|---|
202 |
The request has been accepted for processing, but processing has not yet completed. |
Get an agent run
GET /api/v1/agent/conversations/{conversation}/runs/{run}
Operation ID: getAgentRun
Effect: read
Confirmation: never
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
run |
path | Yes | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Cancel an agent run
POST /api/v1/agent/conversations/{conversation}/runs/{run}/cancel
Cancels an existing run and its queued work synchronously. The 202 response reports the resulting run state; this operation does not create a new asynchronous execution.
Operation ID: cancelAgentRun
Effect: write
Confirmation: conditional
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
run |
path | Yes | string | |
Idempotency-Key |
header | Yes | string |
Responses
| Status | Description |
|---|---|
202 |
The request has been accepted for processing, but processing has not yet completed. |
List agent run events
GET /api/v1/agent/conversations/{conversation}/runs/{run}/events
Operation ID: listAgentEvents
Effect: read
Confirmation: never
Focused reference: JSON · Markdown
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
conversation |
path | Yes | string | |
run |
path | Yes | string | |
accept |
header | No | string | |
Last-Event-ID |
header | No | string | |
limit |
query | No | integer | |
pageToken |
query | No | string |
Responses
| Status | Description |
|---|---|
200 |
The request has succeeded. |
Common error responses
These error responses apply to every operation on this page.
| Status | Description |
|---|---|
400 |
The server could not understand the request due to invalid syntax. |
401 |
Access is unauthorized. |
403 |
Access is forbidden. |
404 |
The server cannot find the requested resource. |
409 |
The request conflicts with the current state of the server. |
412 |
Precondition failed. |
413 |
Client error |
415 |
Client error |
422 |
Client error |
429 |
Client error |
500 |
Server error |
502 |
Server error |
503 |
Service unavailable. |