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");

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.

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.2");

Anthropic:

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

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

Gemini:

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

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

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.

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.