Providers

Every provider implements the same LLMProvider interface. Swapping one for another is a single-line change in createAgent().

Quick start

import { createAgent } from 'personaforge';
import { OpenAIProvider } from 'personaforge';

const agent = createAgent({
  name: 'assistant',
  instructions: 'You are a helpful assistant.',
  llm: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY! }),
});

const result = await agent.run('Explain transformers in two sentences.');
console.log(result.text);

Swap OpenAIProvider for any provider below — the rest of the agent code stays the same.

---

Native SDK providers

These providers use their official SDKs at runtime (peer dependencies — install only what you use).

OpenAI

import { OpenAIProvider } from 'personaforge';

const llm = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o',          // default: gpt-4o
  // baseURL: '...'         // override for custom endpoints
  // debug: true            // log raw API calls
});

Install: npm install openai

Popular models: gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-nano, o3-mini, o4-mini

Anthropic

import { AnthropicProvider } from 'personaforge';

const llm = new AnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-sonnet-4-20250514',  // default: claude-3-5-sonnet-20241022
});

Install: npm install @anthropic-ai/sdk

Popular models: claude-opus-4-20250514, claude-sonnet-4-20250514, claude-haiku-4-20250514

Google Gemini

import { GoogleProvider } from 'personaforge';

const llm = new GoogleProvider({
  apiKey: process.env.GOOGLE_API_KEY!,
  model: 'gemini-2.5-pro-preview',  // default: gemini-2.0-flash
});

Install: npm install @google/generative-ai

Popular models: gemini-2.5-pro-preview, gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash

Amazon Bedrock

import { BedrockConverseProvider } from 'personaforge';

const llm = new BedrockConverseProvider({
  region: 'us-east-1',
  modelId: 'anthropic.claude-3-5-sonnet-20240620-v1:0',
  // client: myPrebuiltClient   // optional
});

Install: npm install @aws-sdk/client-bedrock-runtime

Uses the default AWS credential chain (env vars, instance profile, etc.).

---

Multi-model gateway

OpenRouter

Access every major model through one API key and one endpoint.

import { createOpenRouterProvider } from 'personaforge';

const llm = createOpenRouterProvider({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: 'anthropic/claude-sonnet-4',  // any OpenRouter model id
});

Popular model ids: openai/gpt-4o, anthropic/claude-opus-4, google/gemini-2.5-pro-preview, meta-llama/llama-3.3-70b-instruct

---

Fast inference

Groq (LPU)

import { createGroqProvider } from 'personaforge';

const llm = createGroqProvider({
  apiKey: process.env.GROQ_API_KEY,
  model: 'llama-3.3-70b-versatile',  // default
});

Popular models: llama-3.3-70b-versatile, llama-3.1-8b-instant, gemma2-9b-it, mixtral-8x7b-32768

Cerebras

import { createCerebrasProvider } from 'personaforge';

const llm = createCerebrasProvider({
  apiKey: process.env.CEREBRAS_API_KEY,
  model: 'llama3.3-70b',
});

Fireworks AI

import { createFireworksProvider } from 'personaforge';

const llm = createFireworksProvider({
  apiKey: process.env.FIREWORKS_API_KEY,
  model: 'accounts/fireworks/models/llama-v3p3-70b-instruct',  // default
});

SambaNova

import { createSambaNovaProvider } from 'personaforge';

const llm = createSambaNovaProvider({
  apiKey: process.env.SAMBANOVA_API_KEY,
  model: 'Meta-Llama-3.3-70B-Instruct',
});

---

Other cloud providers

xAI (Grok)

import { createXAIProvider } from 'personaforge';

const llm = createXAIProvider({
  apiKey: process.env.XAI_API_KEY,
  model: 'grok-3',  // default. Also: grok-3-mini, grok-2
});

Together AI

import { createTogetherProvider } from 'personaforge';

const llm = createTogetherProvider({
  apiKey: process.env.TOGETHER_API_KEY,
  model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',  // default
});

DeepSeek

import { createDeepSeekProvider } from 'personaforge';

const llm = createDeepSeekProvider({
  apiKey: process.env.DEEPSEEK_API_KEY,
  model: 'deepseek-chat',      // DeepSeek-V3 (default)
  // model: 'deepseek-reasoner'  // DeepSeek-R1
});

Mistral AI

import { createMistralProvider } from 'personaforge';

const llm = createMistralProvider({
  apiKey: process.env.MISTRAL_API_KEY,
  model: 'mistral-large-latest',  // default. Also: codestral-latest
});

Perplexity (web-grounded)

import { createPerplexityProvider } from 'personaforge';

const llm = createPerplexityProvider({
  apiKey: process.env.PERPLEXITY_API_KEY,
  model: 'sonar-pro',  // default. Also: sonar-reasoning-pro
});

Cohere (Command R)

import { createCohereProvider } from 'personaforge';

const llm = createCohereProvider({
  apiKey: process.env.COHERE_API_KEY,
  model: 'command-r-plus-08-2024',  // default
});

NVIDIA NIM

import { createNvidiaProvider } from 'personaforge';

const llm = createNvidiaProvider({
  apiKey: process.env.NVIDIA_API_KEY,
  model: 'meta/llama-3.3-70b-instruct',
});

Hyperbolic

import { createHyperbolicProvider } from 'personaforge';

const llm = createHyperbolicProvider({
  apiKey: process.env.HYPERBOLIC_API_KEY,
  model: 'meta-llama/Llama-3.3-70B-Instruct',
});

Deep Infra

import { createDeepInfraProvider } from 'personaforge';

const llm = createDeepInfraProvider({
  apiKey: process.env.DEEPINFRA_API_KEY,
  model: 'meta-llama/Meta-Llama-3.1-70B-Instruct',
});

Hugging Face Inference API

import { createHuggingFaceProvider } from 'personaforge';

const llm = createHuggingFaceProvider({
  apiKey: process.env.HF_API_KEY,
  model: 'meta-llama/Llama-3.3-70B-Instruct',
});

Replicate

import { createReplicateProvider } from 'personaforge';

const llm = createReplicateProvider({
  apiKey: process.env.REPLICATE_API_KEY,
  model: 'meta/meta-llama-3-70b-instruct',
});

---

Enterprise

Azure OpenAI

import { createAzureOpenAIProvider } from 'personaforge';

const llm = createAzureOpenAIProvider({
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  resource: process.env.AZURE_OPENAI_RESOURCE,      // Azure resource name
  deployment: process.env.AZURE_OPENAI_DEPLOYMENT,  // deployment name
  apiVersion: '2025-01-01-preview',                 // default
});

IBM watsonx.ai

import { createWatsonxProvider } from 'personaforge';

const llm = createWatsonxProvider({
  apiKey: process.env.WATSONX_API_KEY,
  model: 'ibm/granite-13b-chat-v2',
});

Snowflake Cortex

import { createSnowflakeProvider } from 'personaforge';

const llm = createSnowflakeProvider({
  apiKey: process.env.SNOWFLAKE_API_KEY,
  model: 'snowflake-arctic-instruct',
});

Cloudflare AI

import { createCloudflareProvider } from 'personaforge';

const llm = createCloudflareProvider({
  apiKey: process.env.CLOUDFLARE_API_KEY,
  model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
});

---

Self-hosted and local

Ollama

import { OpenAIProvider } from 'personaforge';

// Ollama exposes an OpenAI-compatible API on port 11434
const llm = new OpenAIProvider({
  baseURL: 'http://localhost:11434/v1',
  apiKey: 'ollama',   // required by the SDK, ignored by Ollama
  model: 'llama3.2',  // run: ollama pull llama3.2
});

vLLM

import { createVllmProvider } from 'personaforge';

const llm = createVllmProvider({
  baseURL: 'http://localhost:8000/v1',  // default (VLLM_BASE_URL env)
  model: 'meta-llama/Llama-3.3-70B-Instruct',
});
// Start server: vllm serve meta-llama/Llama-3.3-70B-Instruct --port 8000

LM Studio

import { createLmStudioProvider } from 'personaforge';

const llm = createLmStudioProvider({
  baseURL: 'http://localhost:1234/v1',  // default
  model: 'local-model',
});

Generic OpenAI-compatible endpoint

import { createOpenAICompatibleProvider } from 'personaforge';

const llm = createOpenAICompatibleProvider({
  baseURL: 'https://my-gateway.internal/v1',
  apiKey: process.env.MY_API_KEY!,
  model: 'my-fine-tuned-model',
});

---

Chinese frontier providers

import {
  createHunyuanProvider,     // Tencent Hunyuan
  createVolcengineProvider,  // ByteDance Volcengine (Doubao)
  createMinimaxProvider,     // MiniMax
  createBaichuanProvider,    // Baichuan
  createStepfunProvider,     // Stepfun
  createInternLMProvider,    // InternLM (Shanghai AI Lab)
  createMoonshotProvider,    // Moonshot (Kimi)
  createDashScopeProvider,   // Alibaba DashScope (Qwen)
  createZhipuProvider,       // Zhipu AI (GLM)
  createYiProvider,          // 01.AI (Yi)
} from 'personaforge';

const llm = createDashScopeProvider({
  apiKey: process.env.DASHSCOPE_API_KEY,
  model: 'qwen-max',
});

---

Fallback chain

Chain multiple providers so failures cascade automatically.

import { FallbackChainProvider, FallbackStrategy } from 'personaforge';

const llm = new FallbackChainProvider({
  providers: [
    createGroqProvider({ model: 'llama-3.1-8b-instant' }),  // fast, cheap
    new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o-mini' }),
    new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o' }),
  ],
  strategy: FallbackStrategy.ANY_ERROR,
  // strategy: FallbackStrategy.RATE_LIMIT  // cascade only on 429s
  debug: true,
});

Strategies: ANY_ERROR · RATE_LIMIT · TIMEOUT · API_ERROR

---

AI SDK Provider — 300+ models via @ai-sdk/*

Add-on for the long tail. The 30 native providers above are the recommended default — smaller bundle, zero extra dependencies, tighter integration with PF's guardrails/cost/HITL. Use the AI SDK adapter only when you need a model that isn't in the native list.

Wraps any @ai-sdk/provider LanguageModelV1 into personaforge's LLMProvider interface — unlocking the entire AI SDK provider ecosystem (~300 model packages) without per-provider maintenance.

import { createAiSdkProvider } from 'personaforge/providers';
import { createOpenAI } from '@ai-sdk/openai';    // npm install @ai-sdk/openai
import { createAnthropic } from '@ai-sdk/anthropic'; // npm install @ai-sdk/anthropic
import { createGoogle } from '@ai-sdk/google';      // npm install @ai-sdk/google
import { createGroq } from '@ai-sdk/groq';
import { createMistral } from '@ai-sdk/mistral';
import { createCohere } from '@ai-sdk/cohere';
// ... and 300+ more provider packages

const model = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! })('gpt-4o');

const agent = createAgent({
  name: 'ai-sdk-agent',
  instructions: 'You are helpful.',
  model: createAiSdkProvider(model),
});

Why this matters:

• 300+ providers — any model that ships an @ai-sdk/provider adapter works immediately. New models land in the AI SDK ecosystem weeks before PF's native adapter list.
• Same tool loop — the step/tool loop remains personaforge's own (guardrails, cost tracking, HITL at every step). The provider protocol layer is delegated to the battle-tested AI SDK.
• Zero additional deps — @ai-sdk/provider is NOT bundled. Install only the provider packages you need.

Options

const provider = createAiSdkProvider(model, {
  modelId: 'gpt-4o-custom',   // override model name returned in results
});

How it works

1. PF Messages → AI SDK messages (roles: system/user/assistant/tool, content parts: text/image/tool-call/tool-result)
2. PF GenerateOptions → AI SDK call options (tools, toolChoice, maxTokens, temperature, stop)
3. AI SDK doGenerate() / doStream() → PF GenerateResult (text, toolCalls, finishReason, usage)
4. Finish reason mapping: stop → stop, length → max_tokens, tool-calls → tool_calls, error → error, content-filter → error

Supported finish reasons

AI SDK	personaforge	Meaning
stop	stop	Model completed naturally
length	max_tokens	Hit token limit
tool-calls	tool_calls	Model requested tool use
content-filter	error	Content policy blocked
error	error	Provider error

---

Bring your own provider

Any object that satisfies this interface works:

interface LLMProvider {
  generateText(messages: Message[], options?: GenerateOptions): Promise<GenerateResult>;
  streamText?(messages: Message[], options?: StreamOptions): Promise<GenerateResult>;
}

---

Where to go next

• LLM Router — route each request to the best model per task, cost, and speed.
• Stream utilities — consume and transform provider streams.
• Production — circuit breakers, budget limits, and observability for provider calls.