Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)
Python
Add Agnes AI provider (#1176) (#1387)
Tanishq-1cddbaadf5e76
diff --git a/.env.example b/.env.exampleindex fd308270..eed486a5 100644--- a/.env.example+++ b/.env.example@@ -121,6 +121,10 @@ TOGETHER_API_KEY=""DEEPINFRA_API_KEY=""+# Agnes AI (OpenAI-compatible Chat Completions at apihub.agnes-ai.com/v1)+AGNES_API_KEY=""++# SambaNova Cloud (OpenAI-compatible Chat Completions at api.sambanova.ai/v1)SAMBANOVA_API_KEY=""@@ -151,7 +155,7 @@ OLLAMA_BASE_URL="http://localhost:11434"# All Claude model requests are mapped to these models, plain model is fallback# Format: provider_type/model/name-# Valid providers: "nvidia_nim" | "openai" | "azure_openai" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "xai" | "qwencloud" | "together" | "deepinfra" | "sambanova" | "kilo" | "fireworks" | "novita" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama" | "tokenrouter" | "nararoute"+# Valid providers: "nvidia_nim" | "openai" | "azure_openai" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "xai" | "qwencloud" | "together" | "deepinfra" | "agnes" | "sambanova" | "kilo" | "fireworks" | "novita" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama" | "tokenrouter" | "nararoute"MODEL_FABLE=MODEL_OPUS=MODEL_SONNET=@@ -196,6 +200,7 @@ FCC_SMOKE_MODEL_GROQ=FCC_SMOKE_MODEL_QWENCLOUD=FCC_SMOKE_MODEL_TOGETHER=FCC_SMOKE_MODEL_DEEPINFRA=+FCC_SMOKE_MODEL_AGNES=FCC_SMOKE_MODEL_SAMBANOVA=FCC_SMOKE_MODEL_KILO=FCC_SMOKE_MODEL_CEREBRAS=@@ -223,6 +228,7 @@ XAI_PROXY=""QWENCLOUD_PROXY=""TOGETHER_PROXY=""DEEPINFRA_PROXY=""+AGNES_PROXY=""AZURE_OPENAI_PROXY=""NVIDIA_NIM_PROXY=""OPENROUTER_PROXY=""diff --git a/README.md b/README.mdindex 6ee70f98..ae820ea1 100644--- a/README.md+++ b/README.md@@ -160,6 +160,7 @@ fcc-codex exec "hello"| [QwenCloud Token Plan](https://home.qwencloud.com/api-keys) | `QWENCLOUD_API_KEY` | `qwencloud/qwen3.7-plus` || [Together AI](https://api.together.ai/settings/api-keys) | `TOGETHER_API_KEY` | `together/zai-org/GLM-5.2` || [DeepInfra](https://deepinfra.com/dash/api_keys) | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V4-Flash` |+| [Agnes AI](https://agnes-ai.com/) | `AGNES_API_KEY` | `agnes/agnes-2.0-flash` || [Azure OpenAI](https://learn.microsoft.com/azure/foundry/openai/how-to/chatgpt) | `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_BASE_URL` | `azure_openai/<deployment-name>` || [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` || [Google Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai) | `VERTEX_PROJECT_ID` + ADC | `vertex/google/gemini-3.5-flash` |diff --git a/pyproject.toml b/pyproject.tomlindex 34866e1f..01983cbb 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "free-claude-code"-version = "4.24.0"+version = "4.25.0"description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"readme = "README.md"requires-python = ">=3.14.0"diff --git a/smoke/lib/config.py b/smoke/lib/config.pyindex 0e162f25..0783b80e 100644--- a/smoke/lib/config.py+++ b/smoke/lib/config.py@@ -81,6 +81,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {"cloudflare": "cloudflare/@cf/moonshotai/kimi-k2.6","tokenrouter": "tokenrouter/moonshotai/kimi-k3-free","nararoute": "nararoute/kimi-k3-free",+ "agnes": "agnes/agnes-2.0-flash",}MISTRAL_REASONING_SMOKE_DEFAULT_MODEL = "mistral/mistral-medium-3-5"diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.pyindex d296e4e9..b9d508a4 100644--- a/src/free_claude_code/config/admin/provider_manifest.py+++ b/src/free_claude_code/config/admin/provider_manifest.py@@ -210,6 +210,12 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {"Defaults to https://router.bynara.id/v1."),},+ "AGNES_API_KEY": {+ "label": "Agnes AI API Key",+ "description": (+ "Agnes AI OpenAI-compatible API key for apihub.agnes-ai.com/v1."+ ),+ },}diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.pyindex 6158a250..1852c8fc 100644--- a/src/free_claude_code/config/provider_catalog.py+++ b/src/free_claude_code/config/provider_catalog.py@@ -64,6 +64,8 @@ DEEPINFRA_DEFAULT_BASE = "https://api.deepinfra.com/v1/openai"TOKENROUTER_DEFAULT_BASE = "https://api.tokenrouter.com/v1"# NaraRoute OpenAI-compatible Chat Completions gateway.NARAROUTE_DEFAULT_BASE = "https://router.bynara.id/v1"+# Agnes AI OpenAI-compatible Chat Completions API.+AGNES_DEFAULT_BASE = "https://apihub.agnes-ai.com/v1"class ProviderAuthKind(StrEnum):@@ -172,6 +174,15 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {default_base_url=DEEPINFRA_DEFAULT_BASE,proxy_attr="deepinfra_proxy",),+ "agnes": ProviderDescriptor(+ provider_id="agnes",+ display_name="Agnes AI",+ credential_env="AGNES_API_KEY",+ credential_url="https://agnes-ai.com/",+ credential_attr="agnes_api_key",+ default_base_url=AGNES_DEFAULT_BASE,+ proxy_attr="agnes_proxy",+ ),"azure_openai": ProviderDescriptor(provider_id="azure_openai",display_name="Azure OpenAI",diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.pyindex 31be1520..ad0bebad 100644--- a/src/free_claude_code/config/settings.py+++ b/src/free_claude_code/config/settings.py@@ -143,6 +143,9 @@ class Settings(BaseSettings):# ==================== DeepInfra (OpenAI-compatible) ====================deepinfra_api_key: str = Field(default="", validation_alias="DEEPINFRA_API_KEY")+ # ==================== Agnes AI (OpenAI-compatible) ====================+ agnes_api_key: str = Field(default="", validation_alias="AGNES_API_KEY")+# ==================== Cerebras Inference (OpenAI-compatible) ====================cerebras_api_key: str = Field(default="", validation_alias="CEREBRAS_API_KEY")@@ -200,6 +203,7 @@ class Settings(BaseSettings):qwencloud_proxy: str = Field(default="", validation_alias="QWENCLOUD_PROXY")together_proxy: str = Field(default="", validation_alias="TOGETHER_PROXY")deepinfra_proxy: str = Field(default="", validation_alias="DEEPINFRA_PROXY")+ agnes_proxy: str = Field(default="", validation_alias="AGNES_PROXY")azure_openai_proxy: str = Field(default="", validation_alias="AZURE_OPENAI_PROXY")nvidia_nim_proxy: str = Field(default="", validation_alias="NVIDIA_NIM_PROXY")open_router_proxy: str = Field(default="", validation_alias="OPENROUTER_PROXY")diff --git a/src/free_claude_code/providers/openai_chat/profiles.py b/src/free_claude_code/providers/openai_chat/profiles.pyindex da8df8de..92863399 100644--- a/src/free_claude_code/providers/openai_chat/profiles.py+++ b/src/free_claude_code/providers/openai_chat/profiles.py@@ -20,6 +20,7 @@ from .reasoning import (LLAMACPP_REASONING,NO_REASONING,SPLIT_REASONING_OUTPUT,+ ChatTemplateReasoning,NamedEffortReasoning,ReasoningEncoder,ReasoningObject,@@ -214,6 +215,16 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {non_thinking_tag="non-reasoning",),),+ "agnes": OpenAIChatProfile(+ _policy(+ "AGNES",+ ReasoningReplayMode.THINK_TAGS,+ include_extra_body=True,+ extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,+ default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,+ ),+ ChatTemplateReasoning(field="enable_thinking"),+ ),"azure_openai": OpenAIChatProfile(_policy("AZURE_OPENAI",diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.pyindex 7e6cfebb..6edda527 100644--- a/tests/contracts/test_provider_catalog_order.py+++ b/tests/contracts/test_provider_catalog_order.py@@ -14,6 +14,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = ("qwencloud","together","deepinfra",+ "agnes","azure_openai","gemini","vertex",diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.pyindex db4c8efb..d917ff75 100644--- a/tests/contracts/test_smoke_config.py+++ b/tests/contracts/test_smoke_config.py@@ -223,6 +223,23 @@ def test_deepinfra_provider_smoke_uses_current_coding_model(monkeypatch) -> Noneassert models[0].source == "provider_default"+def test_agnes_provider_smoke_uses_documented_model(monkeypatch) -> None:+ monkeypatch.delenv("FCC_SMOKE_MODEL_AGNES", raising=False)+ config = _smoke_config(+ settings=_settings(+ model="ollama/llama3.1",+ ollama_base_url="",+ agnes_api_key="agnes-key",+ )+ )++ models = config.provider_smoke_models()++ assert [model.provider for model in models] == ["agnes"]+ assert models[0].full_model == "agnes/agnes-2.0-flash"+ assert models[0].source == "provider_default"++def test_connected_account_provider_smoke_requires_explicit_model(monkeypatch,) -> None:diff --git a/tests/providers/test_agnes.py b/tests/providers/test_agnes.pynew file mode 100644index 00000000..5c88648d--- /dev/null+++ b/tests/providers/test_agnes.py@@ -0,0 +1,227 @@+"""Tests for the Agnes AI OpenAI-chat provider profile."""++from typing import Any+from unittest.mock import patch++import httpx+import pytest+from openai import AsyncOpenAI++from free_claude_code.application.errors import InvalidRequestError+from free_claude_code.application.model_metadata import ProviderModelInfo+from free_claude_code.config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS+from free_claude_code.config.provider_catalog import AGNES_DEFAULT_BASE+from free_claude_code.core.anthropic.models import MessagesRequest+from free_claude_code.core.reasoning import ReasoningPolicy+from free_claude_code.providers.base import ProviderConfig+from free_claude_code.providers.openai_chat import OpenAIChatProvider+from tests.providers.support import (+ REASONING_OFF,+ REASONING_ON,+ immediate_admission,+ profiled_provider,+ reasoning_for,+)+++def agnes_provider() -> OpenAIChatProvider:+ return profiled_provider(+ "agnes",+ ProviderConfig(+ api_key="test-agnes-key",+ base_url=AGNES_DEFAULT_BASE,+ rate_limit=10,+ rate_window=60,+ ),+ admission=immediate_admission(provider_name="agnes"),+ )+++def _request(**overrides: Any) -> MessagesRequest:+ payload: dict[str, Any] = {+ "model": "agnes-2.0-flash",+ "messages": [{"role": "user", "content": "Hello"}],+ }+ payload.update(overrides)+ return MessagesRequest.model_validate(payload)+++def test_init_uses_documented_endpoint(+ agnes_provider: OpenAIChatProvider,+) -> None:+ assert agnes_provider._api_key == "test-agnes-key"+ assert agnes_provider._base_url == AGNES_DEFAULT_BASE+ assert agnes_provider._provider_name == "AGNES"+++def test_build_request_body_preserves_common_chat_tools_and_images(+ agnes_provider: OpenAIChatProvider,+) -> None:+ request = _request(+ system="Be concise.",+ messages=[+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "Inspect this image."},+ {+ "type": "image",+ "source": {+ "type": "base64",+ "media_type": "image/png",+ "data": "aW1hZ2U=",+ },+ },+ ],+ }+ ],+ tools=[+ {+ "name": "inspect_image",+ "description": "Inspect an image",+ "input_schema": {+ "type": "object",+ "properties": {"detail": {"type": "string"}},+ },+ }+ ],+ )++ body = agnes_provider._build_request_body(+ request,+ reasoning=reasoning_for(request),+ )++ assert body["model"] == "agnes-2.0-flash"+ assert body["max_tokens"] == ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS+ assert body["messages"][0] == {"role": "system", "content": "Be concise."}+ assert body["messages"][1]["content"] == [+ {"type": "text", "text": "Inspect this image."},+ {+ "type": "image_url",+ "image_url": {"url": "data:image/png;base64,aW1hZ2U="},+ },+ ]+ assert body["tools"][0]["function"]["name"] == "inspect_image"+++ ("reasoning", "enabled"),+ [(REASONING_OFF, False), (REASONING_ON, True)],+)+def test_build_request_body_encodes_documented_thinking_control(+ agnes_provider: OpenAIChatProvider,+ reasoning: ReasoningPolicy,+ enabled: bool,+) -> None:+ request = _request()++ body = agnes_provider._build_request_body(request, reasoning=reasoning)++ assert body["extra_body"] == {"chat_template_kwargs": {"enable_thinking": enabled}}+++def test_build_request_body_omits_thinking_control_for_provider_default(+ agnes_provider: OpenAIChatProvider,+) -> None:+ request = _request()++ body = agnes_provider._build_request_body(+ request,+ reasoning=ReasoningPolicy.provider_default(),+ )++ assert "extra_body" not in body+++def test_build_request_body_replays_reasoning_in_content_not_undocumented_field(+ agnes_provider: OpenAIChatProvider,+) -> None:+ request = _request(+ messages=[+ {"role": "user", "content": "Solve it."},+ {+ "role": "assistant",+ "content": [+ {"type": "thinking", "thinking": "Work through it."},+ {"type": "text", "text": "The answer is 42."},+ ],+ },+ {"role": "user", "content": "Continue."},+ ]+ )++ body = agnes_provider._build_request_body(+ request,+ reasoning=reasoning_for(request),+ )++ assistant = body["messages"][1]+ assert assistant == {+ "role": "assistant",+ "content": "<think>\nWork through it.\n</think>\n\nThe answer is 42.",+ }++[email protected]("field", ["reasoning", "reasoning_effort"])+def test_build_request_body_rejects_caller_reasoning_override(+ agnes_provider: OpenAIChatProvider,+ field: str,+) -> None:+ request = _request(extra_body={field: "caller-owned"})++ with pytest.raises(InvalidRequestError, match="must not override reasoning"):+ agnes_provider._build_request_body(request, reasoning=REASONING_ON)+++async def test_model_catalog_uses_documented_endpoint_and_auth() -> None:+ requests: list[httpx.Request] = []++ def handler(request: httpx.Request) -> httpx.Response:+ requests.append(request)+ return httpx.Response(+ 200,+ json={+ "object": "list",+ "data": [+ {+ "id": "agnes-2.0-flash",+ "object": "model",+ "created": 0,+ "owned_by": "agnes-ai",+ }+ ],+ },+ )++ http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))++ def build_client(*args: Any, **kwargs: Any) -> AsyncOpenAI:+ kwargs["http_client"] = http_client+ return AsyncOpenAI(*args, **kwargs)++ with patch(+ "free_claude_code.providers.openai_chat.provider.AsyncOpenAI",+ side_effect=build_client,+ ):+ provider = profiled_provider(+ "agnes",+ ProviderConfig(+ api_key="wire-agnes-key",+ base_url=AGNES_DEFAULT_BASE,+ rate_limit=10,+ rate_window=60,+ ),+ admission=immediate_admission(provider_name="agnes"),+ )+ try:+ model_infos = await provider.list_model_infos()+ finally:+ await provider.cleanup()++ assert model_infos == frozenset({ProviderModelInfo("agnes-2.0-flash")})+ assert len(requests) == 1+ assert str(requests[0].url) == "https://apihub.agnes-ai.com/v1/models"+ assert requests[0].headers["authorization"] == "Bearer wire-agnes-key"diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.pyindex 6250e0c3..0513262e 100644--- a/tests/providers/test_provider_runtime.py+++ b/tests/providers/test_provider_runtime.py@@ -11,6 +11,7 @@ from free_claude_code.application.errors import ()from free_claude_code.config.nim import NimSettingsfrom free_claude_code.config.provider_catalog import (+ AGNES_DEFAULT_BASE,BEDROCK_DEFAULT_BASE,COHERE_DEFAULT_BASE,DEEPINFRA_DEFAULT_BASE,@@ -85,6 +86,7 @@ def _make_settings(**overrides):mock.tokenrouter_base_url = TOKENROUTER_DEFAULT_BASEmock.nararoute_api_key = "test_nararoute_key"mock.nararoute_base_url = NARAROUTE_DEFAULT_BASE+ mock.agnes_api_key = "test_agnes_key"mock.lm_studio_base_url = "http://localhost:1234/v1"mock.llamacpp_base_url = "http://localhost:8080/v1"mock.ollama_base_url = "http://localhost:11434"@@ -111,6 +113,7 @@ def _make_settings(**overrides):mock.zai_proxy = ""mock.tokenrouter_proxy = ""mock.nararoute_proxy = ""+ mock.agnes_proxy = ""mock.fireworks_proxy = ""mock.fireworks_api_key = "test_fireworks_key"mock.novita_proxy = ""@@ -280,6 +283,26 @@ def test_deepinfra_provider_config_uses_key_base_and_proxy() -> None:assert isinstance(provider, OpenAIChatProvider)+def test_agnes_provider_config_uses_key_base_and_proxy() -> None:+ descriptor = PROVIDER_CATALOG["agnes"]+ settings = _make_settings(+ agnes_api_key="agnes-token",+ agnes_proxy="http://proxy.test:8080",+ )++ config = build_provider_config(descriptor, settings)+ with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):+ provider = create_provider("agnes", settings)++ assert descriptor.display_name == "Agnes AI"+ assert descriptor.credential_env == "AGNES_API_KEY"+ assert descriptor.base_url_attr is None+ assert config.api_key == "agnes-token"+ assert config.base_url == AGNES_DEFAULT_BASE+ assert config.proxy == "http://proxy.test:8080"+ assert isinstance(provider, OpenAIChatProvider)++def test_bedrock_provider_config_uses_regional_base_key_and_proxy() -> None:descriptor = PROVIDER_CATALOG["bedrock"]settings = _make_settings(@@ -601,6 +624,7 @@ def test_create_provider_instantiates_each_builtin():"zai": OpenAIChatProvider,"tokenrouter": OpenAIChatProvider,"nararoute": OpenAIChatProvider,+ "agnes": OpenAIChatProvider,"gemini": GeminiProvider,"vertex": VertexProvider,"groq": GroqProvider,diff --git a/uv.lock b/uv.lockindex 1043072f..c89c0448 100644--- a/uv.lock+++ b/uv.lock@@ -620,7 +620,7 @@ wheels = [[[package]]name = "free-claude-code"-version = "4.24.0"+version = "4.25.0"source = { editable = "." }dependencies = [{ name = "aiohttp" },