Provider Clients and Models

Anvia separates provider setup from model usage.

A client knows how to talk to a provider. A model is the reusable capability you pass into agents, extractors, pipelines, and retrieval code.

1. Create a Client

Use the provider client that matches your runtime.

import { OpenAIClient } from "@anvia/openai";

const client = new OpenAIClient({ apiKey });

Provider clients only use the values you pass to their constructors. Your app owns whether those values come from environment variables, a secret manager, user input, or test fixtures.

const client = new OpenAIClient({
  apiKey,
});

2. Create a Completion Model

const model = client.completionModel("gpt-5.5");

The completion model implements Anvia's normalized CompletionModel interface. That means the rest of the SDK can use it without depending on one provider's request format.

Every completion model also exposes required metadata:

model.provider;
model.defaultModel;
model.capabilities;

Capabilities describe what the Anvia adapter supports, such as tools, streaming, image input, document file input, and output schemas. Core validates requests against those capabilities before calling the provider SDK, so unsupported requests fail early with an Anvia CompletionCapabilityError. For example, OpenAI and Gemini adapters expose image and document input, while Mistral currently rejects those attachment types.

3. Pass the Model Into an Agent

import { AgentBuilder } from "@anvia/core";

const agent = new AgentBuilder("triage", model)
  .instructions("Classify incoming support messages.")
  .build();

Models are reusable. One model can power several agents:

const supportAgent = new AgentBuilder("support", model).build();
const billingAgent = new AgentBuilder("billing", model).build();

4. Use Provider-Specific Or Compatible Clients When Needed

OpenAI-compatible APIs:

import { OpenAIClient } from "@anvia/openai";

const client = new OpenAIClient({
  baseUrl: "https://openrouter.ai/api/v1",
  apiKey,
});
const model = client.completionModel("openai/gpt-5.5");

Anthropic:

import { AnthropicClient } from "@anvia/anthropic";

const client = new AnthropicClient({ apiKey });
const model = client.completionModel("claude-opus-4-6");

Gemini:

import { GeminiClient } from "@anvia/gemini";

const client = new GeminiClient({ apiKey });
const model = client.completionModel("gemini-3.1-flash-lite-preview");

Mistral:

import { MistralClient } from "@anvia/mistral";

const client = new MistralClient({ apiKey });
const model = client.completionModel("mistral-large-latest");

Vertex AI:

const client = new GeminiClient({
  vertexai: true,
  project,
  location,
});

5. Use Embedding Models For Retrieval

Some provider clients can also create embedding models:

const embeddings = client.embeddingModel("text-embedding-3-small");

Embedding models are used by retrieval and vector store workflows. Completion models answer prompts. Keep those capabilities separate so each workflow can swap providers independently.

Capability Validation

Swapping providers works best when your request only uses features supported by both adapters. For example, a plain text prompt can move between OpenAI, Anthropic, Gemini, and Mistral. A prompt with image input can use adapters that expose image input, such as OpenAI and Gemini, but cannot use the current Mistral adapter.

When you build agents, extractors, or direct completion requests, Anvia checks the selected model's capabilities before transport. Provider-specific options passed through additionalParams are still your responsibility; they may make a request non-portable even when the core capability check passes.

Choosing Where To Store Models

Create clients and models once per process, request handler module, or dependency container. Then pass the model into builders where needed.

Avoid creating a new provider client for every prompt unless your application specifically needs per-request credentials or base URLs.

Next

Read Prompt Requests to see how agents turn prompts, history, context, tools, and runtime options into normalized model requests.