Integration Guide - Arbytra

Every integration channel provides Arbytra’s routing, fallback, cost optimization, and rate limiting — these features are server-side. The channel you choose affects developer ergonomics, not platform capability.

Which integration should I use?

If you…	Use	Tier
Want the full Arbytra experience	Native SDK (TypeScript) (`arbytra.AsyncClient`)	1 — Primary
Already use LangChain, LlamaIndex, CrewAI, or ADK	Framework adapter	2 — Framework
Use the Vercel AI SDK (TypeScript)	`@arbytra/ai-sdk-provider`	2 — Framework
Use Claude Code or Claude Agent SDK	Set `ANTHROPIC_BASE_URL` env var (guide)	2 — Framework
Want to point existing OpenAI code at Arbytra	`AsyncOpenAI(base_url="https://api.arbytra.com/v1")`	3 — Migration
Need to pass an OpenAI client to a framework that discards routing metadata	`ArbytraAsyncOpenAI` (experimental)	4 — Experimental

If you just want to point existing OpenAI code at Arbytra, use AsyncOpenAI(base_url=...) directly. ArbytraAsyncOpenAI is experimental and only needed when a framework discards routing metadata from responses.

Feature comparison

Feature	Native SDK	Framework Adapters	Plain OpenAI API	`ArbytraAsyncOpenAI` (experimental)	Vercel AI SDK Provider	Claude Agent SDK / Anthropic SDK
Routing options	`gateway={...}` or `GatewayOptions(...)`	Adapter-specific params	`extra_body={"gateway": {...}}`	`extra_body={"gateway": {...}}`	`createArbytra({ routing })`	`extra_body={"gateway": {...}}`
Metadata access	`response.routing_metadata`	Adapter-specific	`parse_routing_metadata(response)` or headers	`client.last_routing_metadata`	`result.providerMetadata?.arbytra`	Response headers
Error types	`ArbytraAPIError` hierarchy	`ArbytraAPIError` (automatic)	`openai.APIStatusError`	Dual-inheritance (both hierarchies)	`APICallError` (`@ai-sdk/provider`)	`anthropic.APIStatusError`
Streaming metadata	On stream object	Adapter-specific	Response headers	Automatic	`await result.providerMetadata`	`arbytra_metadata` SSE event
Dependencies	`arbytra`	`arbytra[framework]`	`openai` (or any HTTP client)	`arbytra[openai-compat]`	`@arbytra/ai-sdk-provider` + `ai ^6.0.0`	`anthropic` SDK or Claude Code CLI

Error behavior by channel

Channel	Error type	Automatic?
Native SDK	`ArbytraAPIError` hierarchy	Yes
Framework adapters	`ArbytraAPIError` via `map_openai_error()`	Yes
Plain OpenAI API	`openai.APIStatusError`	Opt-in via `map_openai_error()`
`ArbytraAsyncOpenAI` (experimental)	Dual-inheritance (both hierarchies)	HTTP-level only
Vercel AI SDK provider	`APICallError` (`@ai-sdk/provider`)	Yes
Claude Agent SDK / Anthropic SDK	`anthropic.APIStatusError`	Yes

ArbytraAsyncOpenAI dual-inheritance errors are catchable as both arbytra.RateLimitError and openai.RateLimitError. Mid-stream SSE errors (raised after the HTTP 200 during stream=True) remain unmapped openai.APIError — the bridge covers HTTP-level status errors only.