@agentskit/adapters — for agents

#Purpose

Every LLM provider, one contract. Stream, tool calls, retry, abort all normalized. Plus higher-order adapters that compose candidates (router, ensemble, fallback) and a createAdapter factory for custom providers.

#Contract and failure semantics

• Every stream ends exactly once with done or error. Error chunks expose an Error as metadata.error; a provider connection that closes before its native completion marker is an error, not a partial success.
• abort(reason) propagates to active transports. Custom parsers receive the request signal and response so they can cancel work and validate protocols.
• Tool-capable native adapters serialize assistant calls and correlated tool results across turns. Parallel results are grouped into one provider turn for Anthropic and Gemini/Vertex.
• Gemini authenticates through x-goog-api-key, keeping credentials out of request URLs. vercelAI validates and parses the Vercel UI message stream v1 framing rather than treating it as OpenAI SSE.
• Embedders reject empty, missing, or non-numeric vectors instead of returning unusable data.

The package remains beta. Its implementation is being prepared for an API freeze, but ADR 0024 still requires the elapsed beta window, qualifying release lines, an accepted package RFC, and complete repository evidence before 1.0.

#Install

npm install @agentskit/adapters

#Primary exports

#Native adapters

• anthropic, openai, gemini, grok, ollama, deepseek, kimi, langchain, langgraph, vercelAI, generic.
• azureOpenAI / azureOpenAIAdapter — Azure-hosted OpenAI deployments.
• vertex / vertexAdapter — Google Vertex AI (Gemini, Anthropic-on-Vertex).
• bedrock / bedrockAdapter — AWS Bedrock.
• replicate / replicateAdapter — Replicate inference.
• bail / bailAdapter (alias qwen) — Alibaba DashScope / Qwen.
• webllm / webllmAdapter — browser-only WebGPU via @mlc-ai/web-llm (peer dep).
• createAdapter({ send, parse, abort }) — build your own. See Custom adapter recipe.

#OpenAI-compatible providers

mistral, cohere, together, groq, fireworks, openrouter, huggingface, lmstudio, vllm, llamacpp, cerebras (with cerebrasAdapter factory variant). All share the createOpenAICompatibleAdapter base; each exposes a default baseUrl and accepts an override.

#Composition

• createRouter({ candidates, policy, classify, onRoute }) — pick one per request by cost / latency / tags / custom. See Adapter router.
• createEnsembleAdapter({ candidates, aggregate }) — fan-out + merge (majority-vote / concat / longest / fn). See Ensemble.
• createFallbackAdapter([candidates], { shouldRetry, onFallback }) — try in order, fall through on open / first-chunk / zero-chunk failures. See Fallback chain.

#Testing + utilities

• mockAdapter, recordingAdapter, replayAdapter, inMemorySink — ship without network.
• simulateStream, chunkText, fetchWithRetry — lower-level helpers.

#Cost / carbon / lifecycle

• applyCarbonTable, estimateCO2Grams, DEFAULT_CARBON_TABLE — carbon-aware routing inputs; feed into createRouter policy.
• resolveModel, withDeprecationPolicy, DEFAULT_DEPRECATION_TABLE — auto-upgrade deprecated model IDs at adapter construction.
• refreshCredentials, createRotatingCredentials — opt-in credential-rotation primitives. Stock adapters do not call these automatically; wire them yourself (e.g. resolve current() per request) or reconstruct the adapter after rotation.

#Embedders

• openaiEmbedder, geminiEmbedder, ollamaEmbedder, deepseekEmbedder, grokEmbedder, kimiEmbedder, createOpenAICompatibleEmbedder.

#Catalog (@agentskit/adapters/catalog subpath)

Data-driven provider/model metadata adapted from models.dev, cached as a committed snapshot. Large, so it ships only via the ./catalog subpath — never bundled into the main entry. The runtime never fetches models.dev; regenerate with pnpm sync:models and commit the diff.

• getProvider, getModel, listProviders, listOpenAICompatibleProviders — query the catalog.
• dispatchFromCatalog({ provider, model, apiKey, baseUrl? }) — build a native OpenAI-compatible adapter for any provider the snapshot marks compatible (first-class anthropic/openai/gemini/ollama keep their own factories). Throws typed CatalogDispatchError.
• resolveCost(provider, model, { live?, timeoutMs? }) — cache-only by default; opt-in live tries models.dev then falls back to cache, never throwing on a network failure. Returns { cost, source, stale }.
• applyOverrides(snapshot, { allowedProviders, disabledProviders, allowedModels }) — local policy without forking the catalog.
• detectCatalogDrift() — CI guard; flags undispatchable providers.
• catalogSnapshotSchema (JSON Schema, public contract), catalogSource() (provenance + generatedAt for staleness).

#Minimal example

import { openai } from '@agentskit/adapters'

const adapter = openai({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o-mini' })

#Common patterns

• Rank candidates by cost and fall back on errors: compose createRouter with createFallbackAdapter.
• A/B providers without users: speculate or replayAgainst.
• Test without keys: pair recordingAdapter + replayAdapter (deterministic replay).

#Related packages

• @agentskit/core — the AdapterFactory contract lives here.
• @agentskit/runtime
• @agentskit/eval

#Source

• npm: https://www.npmjs.com/package/@agentskit/adapters
• repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/adapters