Providers

import { resolveProvider, LLMProviderRegistry } from '@lousho/build-ai-agent';

// The convenient way — reads the credential from the environment
const openai = resolveProvider('openai/gpt-4o-mini');       // OPENAI_API_KEY
const anthropic = resolveProvider('anthropic/claude-sonnet-5'); // ANTHROPIC_API_KEY
const openrouter = resolveProvider('openrouter/openai/gpt-4o-mini'); // OPENROUTER_API_KEY
const ollama = resolveProvider('ollama/llama3.1');           // OLLAMA_BASE_URL

// Or construct a provider directly via the registry
const custom = LLMProviderRegistry.create('openai', {
  apiKey: process.env.OPENAI_API_KEY,
  defaultModel: 'gpt-4o-mini',
});

​

Choosing the provider in createAgent()

1. model: 'provider/model' - resolved with resolveProvider(); the key comes from the provider’s conventional environment variable (see Provider credentials).
2. provider: <LLMProvider> - your own provider, a configured built-in one, or a mock. You may also pass model (a bare id such as 'gpt-4o'): it becomes this agent’s model, overriding the provider’s default.
3. Neither - resolved from the environment: LOUSHO_MODEL (a provider/model string) if set, otherwise the first of OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OLLAMA_BASE_URL that is present. With none set it throws an error listing the fixes.

import { createAgent, createMockProvider, resolveProvider } from '@lousho/build-ai-agent';

const fromString = createAgent({ model: 'anthropic/claude-sonnet-5' });
const fromInstance = createAgent({ provider: resolveProvider('openai/gpt-4o-mini'), model: 'gpt-4o' });
const offline = createAgent({ provider: createMockProvider({ responses: ['Hi! How can I help?'] }) });

​

Retries and fallback models

import { createAgent } from '@lousho/build-ai-agent';

const agent = createAgent({
  model: 'openai/gpt-4o-mini',
  retry: { maxRetries: 3 }, // or false
  fallbackModels: ['anthropic/claude-3-5-haiku-latest', 'openrouter/meta-llama/llama-3.1-70b-instruct'],
});

​

Which model runs?

​

Multimodal input

import { readFileSync } from 'node:fs';
import { AgentBuilder, AgentExecutor, createAgent, resolveProvider, textOf, type Message } from '@lousho/build-ai-agent';

const agent = AgentBuilder.create().setName('vision').setPrompt('Describe images briefly.').build();
const input: Message[] = [
  {
    role: 'user',
    content: [
      { type: 'text', text: 'What is in these pictures?' },
      { type: 'image', image: 'https://example.com/cat.png' },
      { type: 'image', image: new Uint8Array(readFileSync('dog.png')), mimeType: 'image/png' },
    ],
  },
];

const result = await AgentExecutor.execute({ agent, input, provider: resolveProvider('openai/gpt-4o-mini') });
console.log(textOf(input[0]), '->', result.text); // textOf(): the text parts of a message

// The same through the public API: parts become one user message.
const answer = await createAgent({ prompt: 'Describe images briefly.', model: 'openai/gpt-4o-mini' }).send([
  { type: 'text', text: 'What is in this picture?' },
  { type: 'image', image: 'https://example.com/cat.png' },
]);
console.log(answer.text);

• Images go to the model on user messages with every built-in provider (an image URL is downloaded by the ai SDK first for Anthropic and Ollama). Pick a vision model: Ollama ignores images for a text-only model, and OpenRouter rejects them for one.
• Files are not sent by the built-in providers, on any ai major: a file part is sent as a text note ([file report.pdf (application/pdf) not sent]) and the provider warns once. A provider subclass whose model takes files sets protected readonly acceptsFileParts = true to send them as ai v4 file parts.
• system, assistant and tool messages are sent as their text parts.
• Everything that reads message text uses textOf(): estimateTokens() (each image or file part counts as a flat 1,000 tokens), compaction, recordReplay() cassettes (which store the text and a digest of each image or file, or its URL) and mockModel(). FileSessionStore saves bytes as base64 ({ "$bytes": "..." }) and loads them back as Uint8Arrays; SqliteStore (sessions and checkpoints) does the same.

​

Provider classes

​

Vercel AI SDK versions

• messages become ModelMessages: a tool call’s arguments are its input, a tool result is an output (json or text, error-json or error-text when the tool failed), and an image or file part’s mimeType is its mediaType. System messages are kept in place (allowSystemInMessages).
• maxTokens is sent as maxOutputTokens, one step as stopWhen: stepCountIs(1), tools as inputSchema (a zod schema as it is, a JSON Schema through jsonSchema()) with no execute, and responseFormat as a JSON-mode output that leaves the reply text alone.
• usage comes from inputTokens / outputTokens / totalTokens, with cachedInputTokens from inputTokenDetails.cacheReadTokens and reasoningTokens from outputTokenDetails.reasoningTokens.
• stream() reads the SDK’s fullStream on either major into the same chunks: text-delta (v6/v7 text, v4 textDelta), tool-call (the whole call v6/v7 sends after tool-input-start/-delta/-end, or one assembled from that input when the model sends none), and finish with the SDK’s finish reason and the usage above (v6/v7 totalUsage). An error part rejects the stream with its error, on v4 too (v4 used to end such a stream with finish reason error), and an abort part with the signal’s reason. Reasoning deltas are reported as reasoning-delta chunks and surface as reasoning.* events (see Reasoning).

​

Where each provider runs