Create, list, update, and delete agents — the registered endpoints your evaluations run against.

Agents API

The Agents API manages agent records: the endpoint, request template, response handling, and channel of the system under test. Agents created here appear on the Agent Management page and can be used by experiments, scenarios, and the Conversation Simulator.

Authentication

All endpoints require Basic Auth with a project's public key and secret key (exported below as AISDK_PUBLIC_KEY / AISDK_SECRET_KEY). The project is derived from the API key — projectId is never part of the request input.

All request bodies are validated strictly: unknown fields are rejected.

Create Agent

POST /api/public/agents

Field	Type	Required	Description
`name`	`string`	Yes	Agent name (1–100 characters)
`type`	`string`	Yes	Record type, e.g. `REST`
`method`	`string`	Yes	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, or `OPTIONS`
`url`	`string`	Yes	The agent's endpoint URL
`description`	`string`	No	Grounding description (up to 10,000 characters)
`contentType`	`string`	No	Request content type
`includeCredentials`	`boolean`	No	Send credentials with the request
`headers`, `displayHeaders`, `queryParams`, `pathVariables`	`array`	No	Key/value lists — arrays of single-entry objects, e.g. `[{ "X-API-Key": "..." }]`
`body`	`object \| array \| string`	No	Request body template. A string is a whole-body template — `"{{$input}}"` sends the dataset input as the entire payload
`bodyContainer`	`object`	No	Structured body container
`response`	`object`	No	Response handling config — mode, connection topology, field mappings, streaming spec
`variableConfig`	`object`	No	`{{variable}}` bindings
`callbackConfig`	`object`	No	Async callback mapping — status path, success/error values, result and error paths
`apiWebhooks`	`array`	No	Async completion callbacks. One or more webhooks classify the agent as asynchronous; mutually exclusive with a streaming `response.mode`
`purpose`	`string`	No	`DATASET_RUN` or `S3_SIGNING`
`channel`	`string`	No	`HTTP` (default) or `VOICE`
`direction`	`string`	No	Voice agents: `OUTBOUND` or `INBOUND`
`simulatorNumber`	`string`	No	Voice: the simulator's phone number (read-mostly; up to 32 characters)
`apiEnvironmentId`	`string \| null`	No	Route requests through a private environment

curl -X POST https://evals-api.browserstack.com/api/public/agents \
  -u "$AISDK_PUBLIC_KEY:$AISDK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-copilot",
    "type": "REST",
    "method": "POST",
    "url": "https://api.acme-support.example/chat",
    "description": "A customer support copilot for an e-commerce store. Handles refunds, order tracking, and policy questions.",
    "body": { "message": "{{input}}", "conversationHistory": [] }
  }'

Response (201):

{
  "id": "agent-uuid-1",
  "projectId": "project-uuid-1",
  "name": "support-copilot",
  "description": "A customer support copilot for an e-commerce store. Handles refunds, order tracking, and policy questions.",
  "type": "REST",
  "method": "POST",
  "url": "https://api.acme-support.example/chat",
  "contentType": null,
  "includeCredentials": false,
  "headers": [],
  "displayHeaders": [],
  "queryParams": [],
  "pathVariables": [],
  "body": { "message": "{{input}}", "conversationHistory": [] },
  "bodyContainer": null,
  "response": null,
  "variableConfig": null,
  "callbackConfig": null,
  "purpose": "DATASET_RUN",
  "channel": "HTTP",
  "direction": null,
  "simulatorNumber": null,
  "apiEnvironmentId": null,
  "groundingDocMediaId": null,
  "authType": null,
  "authStatus": null,
  "createdAt": "2026-08-27T10:00:00.000Z",
  "updatedAt": "2026-08-27T10:00:00.000Z"
}

apiWebhooks is write-only: it is accepted on POST and PATCH but never returned on any GET response. Some response, variableConfig, and managed-auth capabilities are feature-gated per project — writes to a gated capability are rejected with an error naming it, for example "Request variables are not enabled for this project".

List Agents

GET /api/public/agents

Query param	Type	Required	Description
`apiEnvironmentId`	`string`	No	Only agents routed through this environment

The response is a bare array of agent objects — the list is not paginated and returns every agent in the project.

curl https://evals-api.browserstack.com/api/public/agents \
  -u "$AISDK_PUBLIC_KEY:$AISDK_SECRET_KEY"

Get Agent

GET /api/public/agents/{agentId}

curl https://evals-api.browserstack.com/api/public/agents/agent-uuid-1 \
  -u "$AISDK_PUBLIC_KEY:$AISDK_SECRET_KEY"

Returns the same agent object shape as create.

Update Agent

PATCH /api/public/agents/{agentId}

Accepts the same fields as create, with one caveat:

method and url are required on every PATCH, even when updating an unrelated field. Send the agent's current values alongside your change — a GET → modify → PATCH round-trip works as-is.

curl -X PATCH https://evals-api.browserstack.com/api/public/agents/agent-uuid-1 \
  -u "$AISDK_PUBLIC_KEY:$AISDK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "url": "https://api.acme-support.example/chat",
    "description": "A customer support copilot. Handles refunds, order tracking, policy questions, and returns."
  }'

Returns the updated agent object.

Delete Agent

DELETE /api/public/agents/{agentId}

curl -X DELETE https://evals-api.browserstack.com/api/public/agents/agent-uuid-1 \
  -u "$AISDK_PUBLIC_KEY:$AISDK_SECRET_KEY"

Response:

{ "success": true }

Past experiment runs that referenced the agent retain their snapshot.

Errors

Status	Meaning	When it happens
`400`	Validation error	Missing required field, unknown field (schemas are strict), or an invalid combination such as webhooks together with a streaming response mode
`401`	Unauthenticated	Invalid API key
`403`	Forbidden	Key lacks scope, or the write targets a capability not enabled for the project
`404`	Not found	Agent does not exist or belongs to a different project

Agents — managing agents in the dashboard.
Connection modes — what the response, variableConfig, and callbackConfig blobs configure.

Agents API

On this page