browserbase-router

Cost-aware routing across Chat, Browserbase Search, Browserbase Fetch, and Browserbase Agent Runs.

npm install browserbase-router
npm install @browserbasehq/sdk ai zod

@browserbasehq/sdk, ai, and zod are peer dependencies. The publishable package lives at packages/browserbase-router in the @browserbase-router/monorepo repository.

Usage

import Browserbase from "@browserbasehq/sdk";
import { createGateway } from "ai";
import { createBrowserbaseRouter } from "browserbase-router";

const gateway = createGateway({ apiKey: process.env.AI_GATEWAY_API_KEY });
const router = createBrowserbaseRouter({
  client: new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY }),
  model: gateway("openai/gpt-5-mini"),
  onProgress(event) {
    console.log(event.type, event.route, event.message);
  },
});

const decision = await router.classify({
  task: "Find the latest Browserbase Agents news",
});
console.log(decision.route, decision.reason);

const result = await router.run({
  task: "Find the latest Browserbase Agents news",
});
console.log(result.route);

The caller supplies the official Browserbase client and an AI SDK LanguageModel. The package owns rules-first Capability Assessment, deterministic Route Decision, Browserbase translation, Attempt history, Agent polling, progress reporting, and the narrow Fetch fallback.

Routes

| Route | Capability requirement | Result | | --- | --- | --- | | chat | No external capability | Immediate handoff with no Browserbase Attempt | | search | Discovery or fresh information | Ranked links and snippets | | fetch | Reading a supplied HTTP(S) URL | Page content and response metadata | | agent | Interaction, authentication, state change, or complex research | Structured Agent result and optional replay URL |

The model assesses capabilities when deterministic rules are inconclusive or rule confidence is below 0.6. It never selects a product endpoint. If model assessment is unavailable, or model confidence is below 0.5, the policy falls back to Search with confidence 0. Chat is never selected from a model-only assessment.

Managed Agents

Managed Agent matching happens only after deterministic policy selects Agent:

const router = createBrowserbaseRouter({
  client,
  model,
  agents: [
    {
      agentId: "agent_123",
      name: "Commerce researcher",
      description: "Compare product inventory and shipping across stores",
      resultSchema: {
        type: "object",
        required: ["answer"],
        properties: { answer: { type: "string" } },
        additionalProperties: false,
      },
    },
  ],
});

A task without a strong metadata match uses the default Browserbase Agent. run({ resultSchema }) overrides a matched Agent's schema for that run.

Results, progress, and failures

run() returns a route-discriminated result containing the Route Decision, Attempt audit trail, duration, sources, limitations, and route-specific data.

Fetch falls back once to Agent only for connection failures or server-side failures. Client errors, authentication errors, rate limits, cancellation, successful empty content, Search failures, and Agent failures never trigger another route.

Terminal execution failure throws RouterAggregateError with every Attempt. Progress callbacks and loggers are observational: their errors cannot change a Route Decision or result. A local Agent polling timeout includes the remote run ID but does not imply that the remote run stopped.

The package returns structured data and never generates user-facing prose. Consumers are responsible for bounding and treating Browserbase output as untrusted before passing it to another model or interface.

Public Interface

• createBrowserbaseRouter(config): BrowserbaseRouter
• BrowserbaseRouter.classify(input)
• BrowserbaseRouter.run(input)
• RouterAggregateError
• normalizeTask / extractHttpUrl helpers
• MODEL_CONFIDENCE_FLOOR / RULE_CONFIDENCE_FLOOR
• Routing, result, Attempt, progress, source, Agent, and configuration types

Development

From the repository root:

bun install --frozen-lockfile
bun run check
bun run test:coverage