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.
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.
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.
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.
FAQ
Pydantic AI on Twin — common questions
tool_plain or tool?
Can I validate what the browser returns?
Related
More ways to connect Twin
- Language
Python
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.
- Agent framework
LangChain
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.
- API
REST 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.
Integrations
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.