cleveragents-core/docs/reference/providers.md

Provider Registry and Defaults

CleverAgents routes every LangGraph workflow through the provider registry defined in src/cleveragents/providers/registry.py. The registry inspects configured API keys, publishes capability metadata, and picks a sensible default provider/model whenever the CLI does not specify one. The CLI surface is actor-only—--provider/--model flags are removed in favor of selecting an actor (or using the configured default actor).

Supported providers

Provider	Required variables	Default model	Streaming	Tool Calls	Vision	JSON mode
OpenAI	OPENAI_API_KEY	gpt-4o	✅	✅	✅	✅
Anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-20250514	✅	✅	✅	❌
Google AI Studio	GOOGLE_API_KEY or GOOGLE_GENAI_API_KEY	gemini-2.0-flash	✅	✅	✅	✅
Azure OpenAI	AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT	gpt-4o	✅	✅	✅	✅
OpenRouter	OPENROUTER_API_KEY (+ optional CLEVERAGENTS_OPENROUTER_ORGANIZATION)	anthropic/claude-sonnet-4-20250514	✅	✅	✅	✅
Groq	GROQ_API_KEY	llama-3.1-70b-versatile	✅	✅	❌	✅
Together	TOGETHER_API_KEY	meta-llama/Llama-3.1-70B-Instruct-Turbo	✅	✅	❌	❌
Cohere	COHERE_API_KEY	command-r-plus	✅	✅	❌	❌
Gemini (standalone)	GEMINI_API_KEY or GOOGLE_GEMINI_API_KEY	gemini-2.0-flash	✅	✅	✅	✅

Keep this table in sync with provider capability metadata and required environment variables.

Default selection logic

1. Actor selection (required) – agents tell/build --actor <name> chooses the provider/model embedded in the actor config. If omitted, the default actor set via agents actor set-default is used; in test mode (CLEVERAGENTS_TESTING_USE_MOCK_AI=true), the mock actor is auto-provisioned.
2. Actor configuration – provider/model come from the actor’s stored config blob; these replace the removed --provider/--model overrides on CLI commands.
3. Settings defaults – Settings.default_provider / Settings.default_model still seed built-in actors, but the actor registry remains the source of truth.
4. Auto fallback – when a built-in actor is requested and no model is specified, the registry uses its published default; built-ins are created from the fallback order openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini.

The agents diagnostics command prints whether credentials were discovered along with the selected actor. Behave scenarios in features/provider_registry_coverage.feature cover every branch of this flow.

Actor CLI quick start

• agents actor add --name local/<id> --config <path> [--unsafe] [--set-default] stores the canonical actor blob (provider/model/options/graph_descriptor) and requires --unsafe when the config is marked unsafe. Example: agents actor add --name local/dev --config examples/actor.yaml --unsafe --set-default seeds a default custom actor.
• agents actor update --name <actor> [--config <path>] [--unsafe|--safe] [--set-default] [--option key=value] merges overrides into the stored blob; unsafe/safe are mutually exclusive. Example: agents actor update --name local/dev --option temperature=0.3 --set-default applies option overrides without touching provider/model metadata.
• agents actor set-default <name> sets the default actor used when --actor is omitted; defaults cannot be removed.
• agents actor list / agents actor show <name> display built-in <provider>/<model> actors plus custom local/<id> entries with unsafe/default/built-in markers and config hashes.
• agents actor remove local/<id> removes only custom actors that are not the default; built-ins are immutable. Removing the default actor raises an error until a new default is selected.
• Plan/Chat usage: agents tell --actor local/dev "add pagination" or rely on the configured default actor; runtime warns at verbosity ≥ warning when invoking unsafe actors, but does not require --unsafe during execution.

Actor configuration schema (v2-compatible)

Actor config files must remain in the original v2 format (no alternative schemas). Canonical fields:

• provider / model: required and stored as part of the actor blob; drive registry selection.
• graph_descriptor: optional graph metadata emitted by the actor package and injected into LangGraph execution.
• options: arbitrary option map merged from package defaults and CLI overrides; stored canonically in the blob.
• unsafe: boolean flag; CLI add/update requires --unsafe when true, and runtime emits a warning (verbosity ≥ warning) when invoking unsafe actors.

Configs are stored in the config DB as canonical JSON/YAML blobs with a content hash; built-ins are immutable <provider>/<model> entries and customs must use local/<id> naming.

OpenRouter header semantics

If CLEVERAGENTS_OPENROUTER_ORGANIZATION is set, the OpenRouter adapter mirrors that value into the HTTP-Referer and X-Title headers (see src/cleveragents/providers/llm/openrouter_provider.py). This keeps OpenRouter quotas segmented per organization without hard-coding branding elsewhere. Headers are sanitized (converted to strings, trimmed, and only added when non-empty).

Testing and safety levers

• Set CLEVERAGENTS_TESTING_USE_MOCK_AI=true (or 1/yes) to force the in-repository mock provider. The DI container injects it automatically, guaranteeing that local and CI test runs avoid accidental API calls.
• Use agents diagnostics after changing credentials to confirm that the registry sees your keys.
• Provider diagnostics surfaced by PlanService include environment hints when required keys are missing; the Behave coverage under features/plan_service.feature exercises these messages.

Troubleshooting checklist

1. "No AI provider configured" – export at least one API key above or enable the mock provider when testing; then select an actor that references it.
2. Azure errors – confirm AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT, and AZURE_OPENAI_API_VERSION (or their CLEVERAGENTS_ aliases) are set together. Validation will fail if any field is missing.
3. Model mismatch – select an actor whose config points at a supported model ID for the chosen provider (update the actor config if needed).
4. OpenRouter metadata issues – ensure any custom headers are passed via CLEVERAGENTS_OPENROUTER_ORGANIZATION; manual headers are sanitized before invoking LangChain’s ChatOpenAI shim.
5. Coverage gaps – run nox -s unit_tests -- features/provider_registry_coverage.feature to revalidate every scenario after updating credentials or defaults.