Integrating Agents

Create and manage Agents, trigger runs, pass variables, and track runs to completion.

Once you’ve built an Agent in the dashboard, you can integrate it into your application with the official SDK/API: manage reusable Agents, trigger runs, pass per-run values, track each run to completion, and read the result.

Runs are asynchronous. You create a run, then track it to a terminal state by polling.

Install an SDK

Node.js

npm install @browserbasehq/sdk

Python

pip install browserbase

Initialize the client once:

Node.js

Node.js

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({
  apiKey: process.env.BROWSERBASE_API_KEY!,
});

Python

import os
from browserbase import Browserbase

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

See the Node.js SDK reference or Python SDK reference for every Agents SDK method, parameter, and response field.

To scaffold the integration quickly, open an Agent’s run view in the dashboard and use Build API in to open the Agent’s API prompt in a coding tool like Cursor.

Endpoints at a glance

Agents define reusable configuration.

Endpoint	Use
Create an Agent	Define a reusable Agent with a system prompt and result schema.
List Agents	Page through your Agents.
Get an Agent	Fetch a single Agent.
Update an Agent	Change an Agent’s configuration.
Delete an Agent	Remove an Agent.

Runs are single executions of a task.

Endpoint	Use
Run an Agent	Start a run, optionally against an existing Agent.
List runs	Page through runs, filtered by Agent or status.
Get a run	Fetch a run’s status and result.
List run messages	Stream the run’s step-by-step transcript.

Trigger a run

Start a run with Run an Agent. Pass an agentId to run an existing Agent, along with per-run options like variables, resultSchema, and browserSettings.

Node.js

Node.js

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({
  apiKey: process.env.BROWSERBASE_API_KEY!,
});

const { runId } = await bb.agents.runs.create({
  agentId: "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  task: "Find the best matching open role at Browserbase",
  browserSettings: { proxies: true },
});

console.log("Run started:", runId);

Python

import os
from browserbase import Browserbase

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

run = bb.agents.runs.create(
    agent_id="a1b2c3d4-5678-90ab-cdef-1234567890ab",
    task="Find the best matching open role at Browserbase",
    browser_settings={"proxies": True},
)

print("Run started:", run.run_id)

cURL

curl -X POST https://api.browserbase.com/v1/agents/runs \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "task": "Find the best matching open role at Browserbase",
    "browserSettings": { "proxies": true }
  }'

A call with no agentId creates a new Agent and its first run, returning both an agentId and a runId. See Run an Agent for every field.

Manage reusable Agents with the SDK

The SDKs support the complete reusable Agent lifecycle:

Node.js

Node.js

const agent = await bb.agents.create({
  name: "Job Finder",
  systemPrompt: "Find the best matching role on the company's official job board.",
  resultSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      url: { type: "string" },
    },
    required: ["title", "url"],
  },
});

const current = await bb.agents.retrieve(agent.agentId);

const updated = await bb.agents.update(agent.agentId, {
  name: "Official Job Board Finder",
  systemPrompt: "Use only the company's official careers site or applicant tracking system.",
});

const page = await bb.agents.list({ limit: 20 });

await bb.agents.delete(agent.agentId);

Python

agent = bb.agents.create(
    name="Job Finder",
    system_prompt="Find the best matching role on the company's official job board.",
    result_schema={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
        },
        "required": ["title", "url"],
    },
)

current = bb.agents.retrieve(agent.agent_id)

updated = bb.agents.update(
    agent.agent_id,
    name="Official Job Board Finder",
    system_prompt="Use only the company's official careers site or applicant tracking system.",
)

page = bb.agents.list(limit=20)

bb.agents.delete(agent.agent_id)

Deleting an Agent doesn’t affect runs that already referenced it. Updates are partial: omitted fields remain unchanged.

Passing variables

Use variables to pass per-run dynamic values without writing them into the prompt. Each variable pairs a value the placeholder resolves to with an optional description that tells the Agent when to use it. Reference a variable in the task or system prompt as %variableName%.

{
  "agentId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "task": "Check in to my flight using confirmation %confirmation%",
  "variables": {
    "confirmation": {
      "value": "XYZ123",
      "description": "The flight confirmation code to enter at check-in"
    }
  }
}

Variables suit values like account numbers, dates of birth, and confirmation codes. The Agent fills the placeholder without the value appearing inline in the task.

Tracking a run to completion

A run moves through these states:

PENDING → RUNNING → COMPLETED
                  → FAILED
                  → TIMED_OUT
                  → STOPPED

PENDING and RUNNING are active. The rest are terminal.

Poll for the result

Poll Get a run until the run reaches a terminal state, then read result:

Node.js

Node.js

async function pollRun(runId: string) {
  const terminal = ["COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"];
  while (true) {
    const run = await bb.agents.runs.retrieve(runId);
    if (terminal.includes(run.status)) return run;
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
}

const run = await pollRun(runId);
console.log("Result:", run.result);

Python

import time

def poll_run(run_id):
    terminal = {"COMPLETED", "FAILED", "STOPPED", "TIMED_OUT"}
    while True:
        run = bb.agents.runs.retrieve(run_id)
        if run.status in terminal:
            return run
        time.sleep(2)

run = poll_run(run_id)
print("Result:", run.result)

cURL

curl https://api.browserbase.com/v1/agents/runs/$RUN_ID \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

Read or stream progress

To follow what the Agent is doing while it runs, poll List run messages. Save the response’s nextSince and pass it back as since to fetch only newer messages:

Node.js

Node.js

let since: string | undefined;

while (true) {
  const page = await bb.agents.runs.listMessages(runId, {
    since,
    limit: 100,
  });

  for (const item of page.data) {
    console.log(item.message);
  }

  since = page.nextSince ?? since;

  const run = await bb.agents.runs.retrieve(runId);
  if (!["PENDING", "RUNNING"].includes(run.status)) break;
  await new Promise((resolve) => setTimeout(resolve, 2000));
}

Python

import time

since = None

while True:
    params = {"limit": 100}
    if since:
        params["since"] = since

    page = bb.agents.runs.list_messages(run_id, **params)

    for item in page.data:
        print(item.message)

    since = page.next_since or since

    run = bb.agents.runs.retrieve(run_id)
    if run.status not in {"PENDING", "RUNNING"}:
        break
    time.sleep(2)

cURL

curl "https://api.browserbase.com/v1/agents/runs/$RUN_ID/messages?since=$LAST_MESSAGE_ID" \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

Messages conform to the AI SDK UIMessage format. Each item includes an id, createdAt, and a message with a role and content. Content can be text or typed parts such as reasoning, files, tool calls, and tool results.

Integration is poll-based today: track runs with Get a run and List run messages. Webhook notifications are planned.

Listing and filtering

Both list endpoints use cursor pagination. Pass the nextCursor from a response back as cursor to fetch the next page.

List runs filters by agentId, status, and a startAt/endAt time range:

Node.js

Node.js

const runs = await bb.agents.runs.list({
  agentId,
  status: "COMPLETED",
  limit: 20,
});

if (runs.nextCursor) {
  const nextPage = await bb.agents.runs.list({
    agentId,
    status: "COMPLETED",
    limit: 20,
    cursor: runs.nextCursor,
  });
}

Python

runs = bb.agents.runs.list(
    agent_id=agent_id,
    status="COMPLETED",
    limit=20,
)

if runs.next_cursor:
    next_page = bb.agents.runs.list(
        agent_id=agent_id,
        status="COMPLETED",
        limit=20,
        cursor=runs.next_cursor,
    )

cURL

curl "https://api.browserbase.com/v1/agents/runs?agentId=$AGENT_ID&status=COMPLETED&limit=20" \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

List Agents pages through your Agents with the same cursor pagination pattern.

Next steps

Node.js SDK

Complete Agents SDK method and type reference

Python SDK

Complete Agents SDK method and type reference

Run an Agent

Full request and response reference for a run

List run messages

Stream a run’s step-by-step transcript

Managing files

Retrieve files an Agent downloads during a run

How it works

The execution loop, run lifecycle, and observability