Setting the file. One moment.
Skill 14 · Optimize Agent Prompt
Subchapter 14.1
references/api.mdMarkdown3 KBView on GitHub
Send X-BB-API-Key: $BROWSERBASE_API_KEY to https://api.browserbase.com/v1. Never write the key into experiment artifacts.
POST /agents
{
"name": "POC prompt experiment",
"systemPrompt": "...",
"resultSchema": {}
}Save agentId in the ignored experiment state. Create once per experiment.
PATCH /agents/{agentId}
{
"systemPrompt": "...",
"resultSchema": {}
}Persist the exact prompt in each run directory because retrieving the Agent later returns only its newest prompt.
POST /agents/runs
{
"agentId": "...",
"task": "...",
"resultSchema": {},
"variables": {
"query": { "value": "example", "description": "Search term" }
},
"browserSettings": {
"proxies": true,
"verified": true
}
}The run begins as PENDING, then becomes RUNNING, and terminates as COMPLETED, FAILED, STOPPED, or TIMED_OUT.
GET /agents/runs/{runId}
The requested JSON Schema payload is normally at result.output; runner metadata can coexist at result.summary, result.stepsTaken, and result.taskDuration. Normalize with:
const output = run.result?.output ?? run.result ?? null;Use result.taskDuration for the run duration in milliseconds. If it is unavailable, calculate the duration from startedAt and endedAt when both timestamps are present.
POST /agents/runs/{runId}/stop
Stop when the message or time budget is exceeded. Continue polling until a terminal status so final artifacts are complete.
GET /agents/runs/{runId}/messages
Query parameters:
since: last received message ID;limit: 1–100;all=true: return all messages after since.Responses are chronological:
{
"data": [{ "id": "...", "createdAt": "...", "message": {} }],
"nextSince": "..."
}Pass nextSince as the next since cursor while polling. Expect AI SDK UIMessage parts such as tool-call, tool-result, reasoning, and text/final output. Readable reasoning text is not guaranteed; tool actions and results are the primary evidence surface.
GET /sessions/{sessionId}/logs
Returns CDP command/event records with method, request, response, timestamps, frame IDs, and loader IDs. Use these logs to validate browser-level causes. Do not treat an empty array as failure when the Agent chose non-browser search/fetch tools.