Implement a model provider

Implement ModelProvider when an existing provider adapter does not fit your API. An Agent calls this interface for generation and streaming; your adapter translates messages, options, responses, usage, and errors. Supporting the interface does not automatically add tool calling, structured output, multimodal input, or cancellation to an upstream service.

ModelProvider interface

Use the exported types as the contract:

import type {
  ChatMessage, ModelConfig, ModelResponse, StreamChunk, ToolDefinition,
} from "@agentium/core";

interface ModelProvider {
  readonly providerId: string;
  readonly modelId: string;
  generate(messages: ChatMessage[], options?: ModelConfig & { tools?: ToolDefinition[] }): Promise<ModelResponse>;
  stream(messages: ChatMessage[], options?: ModelConfig & { tools?: ToolDefinition[] }): AsyncGenerator<StreamChunk>;
}

ModelResponse.raw contains the adapter’s original response and is typed unknown. It is not copied to Agent.run()’s RunOutput. Normalize token usage into promptTokens, completionTokens, and totalTokens; preserve additional provider accounting in usage.providerMetrics when available.

Example skeleton

This host integration factory accepts a text-only request function owned by your application. It rejects features that this small adapter does not implement. The host function must validate its upstream response and pass signal to the upstream request.

import {
  getTextContent,
  type ModelConfig,
  type ModelProvider,
  type ToolDefinition,
} from "@agentium/core";

type RequestText = (input: {
  model: string;
  messages: Array<{ role: string; text: string }>;
  signal?: AbortSignal;
}) => Promise<{ text: string; promptTokens: number; completionTokens: number; raw: unknown }>;

export function textAdapter(modelId: string, request: RequestText): ModelProvider {
  function check(options?: ModelConfig & { tools?: ToolDefinition[] }) {
    options?.signal?.throwIfAborted();
    if (options?.tools?.length || options?.responseFormat && options.responseFormat !== "text") {
      throw new Error("This text-only adapter does not implement tools or structured output");
    }
    if (options && Object.entries(options).some(([key, value]) => value !== undefined && !["signal", "tools", "responseFormat"].includes(key))) {
      throw new Error("Add explicit upstream mapping for the requested model options");
    }
  }
  const provider: ModelProvider = {
    providerId: "company-text",
    modelId,
    async generate(messages, options) {
      check(options);
      if (messages.some((message) => typeof message.content !== "string" || message.toolCalls?.length || message.role === "tool")) {
        throw new Error("This adapter accepts text conversations without tool history");
      }
      const result = await request({
        model: modelId,
        messages: messages.map((message) => ({ role: message.role, text: getTextContent(message.content) })),
        signal: options?.signal,
      });
      options?.signal?.throwIfAborted();
      return {
        message: { role: "assistant", content: result.text },
        usage: {
          promptTokens: result.promptTokens,
          completionTokens: result.completionTokens,
          totalTokens: result.promptTokens + result.completionTokens,
        },
        finishReason: "stop",
        raw: result.raw,
      };
    },
    async *stream(messages, options) {
      // Buffered compatibility: one text chunk after the full response arrives.
      const response = await provider.generate(messages, options);
      yield { type: "text", text: getTextContent(response.message.content) };
      yield { type: "finish", finishReason: response.finishReason, usage: response.usage };
    },
  };
  return provider;
}

The stream above is explicitly buffered. For live token streaming, map the upstream event stream into the chunk contract below and cancel/close the upstream iterator when consumption ends. Report upstream failures as errors rather than yielding an empty successful answer.

Register with ModelRegistry

Pass a provider instance directly to new Agent({ model }) when only that Agent needs it. Register a factory with modelRegistry when another component, such as admin hydration, resolves a provider/model ID pair.

import { modelRegistry, type ModelProvider } from "@agentium/core";

export function registerCompanyProvider(
  factory: (modelId: string, config?: unknown) => ModelProvider,
) {
  modelRegistry.register("company", (modelId, config: unknown) => factory(modelId, config));
}

Your factory validates configuration before using it. Register it during application startup, before resolving a model or hydrating stored blueprints. Core’s separate registry holds live Agent/Team/Workflow instances; it is not the provider registry. Avoid replacing a built-in provider ID unintentionally.

StreamChunk types

Type	Payload	Meaning
`text`	`{ text }`	Text delta
`thinking`	`{ text }`	Provider-exposed reasoning summary delta
`tool_call_start`	`{ toolCall: { id, name } }`	Begin a tool call
`tool_call_delta`	`{ toolCallId, argumentsDelta }`	Tool argument JSON fragment
`tool_call_end`	`{ toolCallId }`	End the tool call
`finish`	`{ finishReason, usage?, providerExtras? }`	Final status, accounting, and optional replay metadata

Preserve tool-call IDs and provider replay metadata across turns. If you support function tools, test a complete model → tool → model exchange, not only a single text response. See the generated model contracts for exact types.

Full example

This complete local fixture verifies registry resolution, Agent execution, streaming, and cleanup. It echoes text; it is not an AI model or an upstream API integration. Use an ESM TypeScript project ("type": "module" in package.json) on a supported Node version.

npm install @agentium/core@4.0.0
npm install --save-dev tsx typescript @types/node

Save as provider-demo.ts:

import { Agent, getTextContent, modelRegistry, type ModelProvider } from "@agentium/core";

modelRegistry.register("local-demo", (modelId): ModelProvider => ({
  providerId: "local-demo",
  modelId,
  async generate(messages, options) {
    options?.signal?.throwIfAborted();
    const last = messages.at(-1);
    return {
      message: { role: "assistant", content: `Echo: ${last ? getTextContent(last.content) : ""}` },
      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
      finishReason: "stop",
      raw: null,
    };
  },
  async *stream(messages, options) {
    options?.signal?.throwIfAborted();
    const last = messages.at(-1);
    yield { type: "text", text: `Echo: ${last ? getTextContent(last.content) : ""}` };
    yield { type: "finish", finishReason: "stop", usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 } };
  },
}));

const agent = new Agent({ name: "provider-demo", model: modelRegistry.resolve("local-demo", "v1") });
try {
  const result = await agent.run("Hello");
  if (result.status !== "completed") throw new Error(`Run ended with ${result.status}`);
  console.log(result.text);
  for await (const chunk of agent.stream("Streaming")) {
    if (chunk.type === "text") console.log(chunk.text);
  }
} finally {
  await agent.close();
}

npx tsx provider-demo.ts

Expect Echo: Hello and Echo: Streaming. Adapt the request boundary to your upstream SDK, then add explicit checks for its usage mapping, cancellation, malformed responses, and every feature you enable. Use the built-in Cohere adapter for Cohere rather than duplicating its API normalization here.

Find an integration

Voice and call adapters

Sandbox and telemetry

Providers and services

Protocols and devices

Implement a model provider

ModelProvider interface

Example skeleton

Register with ModelRegistry

StreamChunk types

Full example

​ModelProvider interface

​Example skeleton

​Register with ModelRegistry

​StreamChunk types

​Full example

ModelProvider interface

Example skeleton

Register with ModelRegistry

StreamChunk types

Full example