How-to

Add a model provider

Connect a model backend through explicit provider, transport, model, reasoning, and authentication settings.

Quick answer

A Buffaly model provider is not just a model name in a prompt. Provider selection is catalog-driven and separates provider family, transport, provider-specific model name, optional reasoning level, and authentication state.

Provider

Family token such as openai, anthropic, xai, or gemini.

Transport

Execution path such as codex_backend, responses_api, or provider_native.

Model

Provider-specific model name exposed by the catalog.

Reasoning and auth

Optional reasoning token plus credentials owned by built-in features or provider-specific settings.

When to add a provider module

Add a model provider when Buffaly must select and call a different model backend. Provider modules are for model selection and completion execution, not a generic tool mechanism.

Need	Better fit
Repeatable text/checklist workflow	Prompt skill
Buffaly-native typed operation	ProtoScript skill/action
Deterministic SDK/protocol logic	C# DLL tool
Configured system with lifecycle and identity	Service
Model backend in selector/runtime	Model provider module

What source shows about provider defaults

The verified default path is OpenAI through the Codex-backed path. Optional provider-native providers such as Anthropic, xAI, Gemini, or another backend are configured routes, not automatic defaults.

ProviderCatalogSourceRegistry starts with OpenAiCodexProviderCatalogSource as the built-in catalog source.
ProviderCatalogDefaults defines openai, codex_backend, responses_api, provider_native, and default transport behavior.
ProviderCatalogService.ResolveDefaultSelection(...) falls back to provider openai, transport codex_backend, and reasoning medium when no session-specific selection exists.

Do not call Anthropic, xAI, Gemini, or another provider default just because a module example exists. Verify the manifest, feature/settings row, credentials, and web/worker assemblies for the running instance.

Provider module anatomy

The implementation supports a catalog surface and an execution surface. A provider module usually implements IProviderCatalogSource to build the provider catalog row and IProviderNativeCompletionExecutor to execute provider-native completions.

Catalog source

Returns provider token, transports, models, default model, enabled/configured state, and reasoning options.

Completion executor

Handles provider API calls and returns Buffaly canonical completion output.

{
  "Enabled": true,
  "Provider": "anthropic",
  "DisplayName": "Anthropic",
  "AssemblyPath": "Buffaly.Provider.Anthropic/Buffaly.Provider.Anthropic.dll",
  "CatalogSourceTypeName": "Buffaly.Provider.Anthropic.AnthropicProviderCatalogSource",
  "CompletionExecutorTypeName": "Buffaly.Provider.Anthropic.AnthropicCompletionExecutor",
  "LoadOrder": 500
}

Manifest rules: Enabled=false leaves a module installed but undiscovered; Provider must be stable and unique; AssemblyPath resolves relative to the manifest directory; source/executor type names must implement the expected interfaces. Missing assemblies or invalid types are skipped with provider-module diagnostics.

Authentication and secrets

Provider credentials belong in configuration or secret-backed feature settings, not in implementation files, wiki pages, prompt files, or provider manifests.

FeatureName = Anthropic Feature
Settings = {
  "ApiKey": "...",
  "ModelNames": ["claude-sonnet-4-5"],
  "SupportedReasoningLevels": ["low", "medium", "high"],
  "DefaultReasoningLevel": "medium",
  "BaseUrl": "https://api.anthropic.com",
  "Version": "2023-06-01",
  "MaxTokens": 4096
}

Use placeholder values in docs and never commit real API keys. Verify that the web and worker runtime read the same configuration source for the target instance.

The easiest way: ask Buffaly to create or update it

Ask the Buffaly agent to inspect source first, then make the provider change with explicit validation and no secrets in source.

Add a provider-native Anthropic provider module. Inspect the provider catalog and dynamic provider module loader source first. Create or update the provider module, manifest entry, feature settings documentation, and validation steps. Do not store API keys in source.

Diagnose why provider anthropic does not appear in the provider selector. Check ProviderModules.json, module DLL path, catalog source type, feature row, logs, and the provider catalog endpoint.

Manual workflow

Pick a stable lowercase provider token such as anthropic; do not reuse an existing token.
Choose the transport: provider_native for provider-specific executors, or OpenAI transports only for supported OpenAI paths.
Implement or install the provider catalog source and provider-native executor.
Copy provider assemblies into the install-root provider module folder and keep web/worker folders aligned.
Add or update ProviderModules.json.
Configure credentials and model settings without putting secrets in the manifest.
Recycle or reload only the target instance as needed; do not kill shared Buffaly or dotnet processes for routine registration.
Verify catalog discovery, selection persistence, and a safe completion round trip.
Commit only intentional source/docs changes and keep deployment secrets out of git.

How Buffaly validates provider choices

Provider selection is validated against the authoritative provider catalog. ProviderCatalogService resolves provider row, transport row, model row, and supported reasoning level in order. Missing or disabled values throw explicit errors instead of silently falling back.

POST /api/buffaly.agent.host/provider-catalog-service/get-provider-catalog

Provider row appears with expected token, IsEnabled=true, and IsConfigured=true when credentials/settings are valid.
Default transport and at least one model row exist for the transport you plan to use.
Supported reasoning levels match what the test session will select.
A safe smoke prompt such as Reply with exactly: provider smoke ok returns the expected canonical output shape.

Common failures

Provider does not appear

Check ProviderModules.json, Enabled, DLL path, catalog source type, unique provider token, dependency loading, and provider-module diagnostics.

Provider appears but is not configured

Check feature/settings row, credential store, settings JSON contract, and feature name alignment.

Selection fails

Check provider token spelling/casing, selected transport, model row, and reasoning level support.

Completion fails

Check worker-side executor loading, web/worker folder alignment, external credentials, model name validity, and canonical output mapping.

Providers and authentication Self-discoverable providers Add a C# DLL tool Adding skills, services, and tools Buffaly services Troubleshooting and validation