Agent framework integration

Twin Browser + Vercel AI SDK

The Vercel AI SDK is a TypeScript toolkit for building AI applications — a unified interface across model providers, streaming, structured output and tool calling. A tool is defined with the `tool()` helper: a description, an `inputSchema`, and an `execute` function.

Get an API key Read the docs

Agent framework4-step setupBearer key auth

How Twin plugs into Vercel AI SDK

One `tool()` definition wrapping `/api/v1/run` gives a `generateText` or `streamText` call a real browser. This is the natural pairing for a Next.js route handler: the SDK streams the conversation, Twin does the web work server-side where the Bearer key belongs, and the structured result flows back into the stream. There is no `@twin-browser/*` package involved — `fetch` and a key are the whole dependency.

Twin is the browser execution layer your stack calls. The first run cold-compiles a skill via skill compilation; every similar request after that is matched from the cache and replayed deterministically, so your marginal cost per run trends toward zero rather than climbing with usage.

app.example.com

Vercel AI SDK → Twin

Receive goal from Vercel AI SDKdone
Compile DOM → token-efficient indexed statedone
Match the semantic dispatch cacherunning
Replay compiled skill — 0 LLM callsqueued

What you get through Vercel AI SDK

Every integration is a thin wrapper over the same execution layer, so the cache, the replay, and the corpus apply no matter how you call in.

Semantic dispatch cache

A re-phrased goal fuzzy-matches an already-compiled skill, so most calls never touch the LLM.

Deterministic replay

A compiled skill replays the exact action path with zero LLM calls — fast, repeatable, cheap.

Cross-tenant skill corpus

A skill compiled once can be safely reused across tenants, so the hit rate climbs as the network runs.

One Bearer key

Auth, usage-based billing, and an audit log run on every call — the same key works from every integration.

Wire it up

Drop Twin into Vercel AI SDK.

Copy, paste, and swap in your Bearer key. The first run compiles a skill; repeats match the semantic dispatch cache and replay deterministically.

Vercel AI SDK — Twin as a tooltypescript

import { tool, generateText } from 'ai';
import { z } from 'zod';

const twinRun = tool({
  description: 'Perform a task in a real browser on an authorized URL.',
  inputSchema: z.object({
    url: z.string().describe('The page to start from'),
    prompt: z.string().describe('What to do there, in plain language'),
  }),
  execute: async ({ url, prompt }) => {
    const res = await fetch('https://twin-browser.com/api/v1/run', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.TWIN_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ url, prompt, success: { kind: 'extracted' } }),
    });
    return res.json();
  },
});

const { text } = await generateText({
  model,
  tools: { twinRun },
  prompt: 'Get the latest invoice total from the billing portal.',
});

Base URL https://twin-browser.com/api/v1 · auth Authorization: Bearer ab_live_… · over MCP the same engine is run_goal, compile_skill and run_skill — the full tool table.

Install the AI SDK
npm i ai zod plus your provider package. Nothing Twin-specific is installed.
Set your key
Put TWIN_API_KEY in your server environment. It must never reach the client bundle.
Define the tool
Use tool({ description, inputSchema, execute }) with execute POSTing to /api/v1/run.
Pass it to the model
Hand it to generateText or streamText in the tools map and stream the result.

Read the Vercel AI SDK docs API reference

FAQ

Vercel AI SDK on Twin — common questions

Where should the Twin call actually run?

Server-side only — a route handler, a server action or an edge function. The Bearer key is a tenant credential; anything that ships it to the browser gives away your account.

A browser run can take a while. How do I handle that?

Either raise the timeout on the route and stream around it, or use the async path: POST /api/v1/jobs returns a job id immediately and you poll GET /api/v1/jobs/{id} — with an optional signed callback when it completes.

Go deeper

Node.js & TypeScript

Language

Node is the other half of the agent ecosystem — the Vercel AI SDK, LangChain.js, and the OpenAI and Anthropic TypeScript SDKs all run here, and it is where most production API routes and background workers live.

Anthropic (Claude tool use)

LLM provider

Claude’s Messages API supports tool use: you pass a `tools` array where each tool has a `name`, a `description` and an `input_schema`. When Claude decides to use one, the response comes back with `stop_reason: "tool_use"`, you execute it, and you return a `tool_result` block in the next message.

REST API

API

Twin’s REST API is the universal integration path: HTTPS endpoints under `/api/v1/*`, authenticated with a Bearer key. Any language that can make an HTTP request can drive the browser execution layer — no SDK required, and none is published.

Wire up Vercel AI SDK in minutes.

Free to start. Usage-based credits from $29/mo — each call billed the higher of its flat action price or its metered cost.

Get an API key See pricing