Agent framework integration

Twin Browser + Pydantic AI

Pydantic AI is an agent framework from the Pydantic team, built around typed inputs and validated outputs. Tools are registered on an agent with decorators — `@agent.tool_plain` for a tool that needs no run context, `@agent.tool` for one that does.

Get an API key Read the docs

Agent framework4-step setupBearer key auth

How Twin plugs into Pydantic AI

Pydantic AI’s appeal is that the model’s output is validated against a type rather than hoped for. Twin fits that: the browser call returns a structured result, so you can declare the shape you expect and let Pydantic enforce it at the boundary instead of parsing prose. Register the browser as a plain tool — it needs no run context — and the agent gets a typed web capability.

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

Pydantic AI → Twin

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

What you get through Pydantic AI

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 Pydantic AI.

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

Pydantic AI — a plain browser toolpython

import os, requests
from pydantic_ai import Agent

TWIN = "https://twin-browser.com/api/v1"
agent = Agent("openai:gpt-4o")

@agent.tool_plain
def twin_run(url: str, prompt: str) -> dict:
    """Perform a task in a real browser on an authorized URL."""
    r = requests.post(
        f"{TWIN}/run",
        headers={"Authorization": f"Bearer {os.environ['TWIN_API_KEY']}"},
        json={"url": url, "prompt": prompt, "success": {"kind": "extracted"}},
        timeout=300,
    )
    r.raise_for_status()
    return r.json()

print(agent.run_sync("Get the latest invoice total from the billing portal.").output)

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 Pydantic AI
pip install pydantic-ai. Nothing Twin-specific is installed.
Create the agent
Declare your Agent with the model and, if you want one, an output_type.
Register the tool
Decorate a function that POSTs to /api/v1/run with @agent.tool_plain.
Run it
Call agent.run_sync (or run) — the model invokes the tool when the task needs a browser.

Read the Pydantic AI docs API reference

FAQ

Pydantic AI on Twin — common questions

tool_plain or tool?

tool_plain — the browser call needs nothing from the run context. Use @agent.tool only if you want to pass dependencies such as a per-user account label through RunContext.

Can I validate what the browser returns?

Yes, and that is the point of using Pydantic AI here. Annotate the tool’s return type, or declare an output_type on the agent, and the structured result is validated before it reaches your code.

Go deeper

Python

Language

Python is where most agent code lives — LangChain, LlamaIndex, CrewAI, AutoGen, Pydantic AI and the OpenAI and Anthropic SDKs are all Python-first. Anything you can express as a function call, an agent can be given as a tool.

LangChain

Agent framework

LangChain is a Python and JavaScript framework for building LLM applications. Its agent loop lets a model pick a tool, observe the result, and decide the next action — which makes browser access a natural tool to add.

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 Pydantic AI 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