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.

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	✅	✅	✅	✅

See docs/reference/env_variables.yaml for the full catalog (including AWS/Vertex-compatible aliases) and machine-readable capability metadata.

Default selection logic

1. CLI flags – agents tell --provider openai --model gpt-4o and agents build accept per-command overrides. These always win.
2. Environment overrides – export CLEVERAGENTS_DEFAULT_PROVIDER and/or CLEVERAGENTS_DEFAULT_MODEL to set global defaults.
3. Settings object – Settings.default_provider / Settings.default_model (for example via Hatch profile) are next in line.
4. Auto fallback – when nothing is pinned, the registry chooses the first configured provider in this order: openai → anthropic → google → azure → openrouter → groq → together → cohere → gemini. The provider’s published default model is used automatically.

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

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.
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 – specify --model on the CLI or set CLEVERAGENTS_DEFAULT_MODEL to point at a supported ID for your provider.
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.