Skip to content

feat: add ANTHROPIC_BASE_URL support #1886

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dongjiang1989 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: add ANTHROPIC_BASE_URL support #1886

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
752f4fa
add anthropic base url
dongjiang1989 May 18, 2026
f0cc8b9
Merge branch 'main' into add-env
EItanya May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions go/core/internal/controller/translator/agent/adk_api_translator.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -434,6 +434,12 @@ func (a *adkApiTranslator) translateModel(ctx context.Context, namespace, modelC

if model.Spec.Anthropic != nil {
anthropic.BaseUrl = model.Spec.Anthropic.BaseURL
if model.Spec.Anthropic.BaseURL != "" {
modelDeploymentData.EnvVars = append(modelDeploymentData.EnvVars, corev1.EnvVar{
Name: env.AnthropicAPIBaseURL.Name(),
Value: model.Spec.Anthropic.BaseURL,
})
}
}
return anthropic, modelDeploymentData, secretHashBytes, nil
case v1alpha2.ModelProviderAzureOpenAI:
Expand Down
99 changes: 99 additions & 0 deletions go/core/internal/controller/translator/agent/adk_api_translator_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1413,3 +1413,102 @@ func Test_AdkApiTranslator_SandboxAgent_BYOEmitsSandbox(t *testing.T) {
require.False(t, sawDeploy)
require.False(t, sawService, "sandbox runtime must not include Service; agent-sandbox owns it")
}

func Test_AdkApiTranslator_AnthropicBaseURLEnvVar(t *testing.T) {
scheme := schemev1.Scheme
require.NoError(t, v1alpha2.AddToScheme(scheme))

namespace := "test-ns"

tests := []struct {
name string
baseURL string
wantEnvVar bool
wantEnvVarValue string
}{
{
name: "empty baseURL does not inject env var",
baseURL: "",
wantEnvVar: false,
},
{
name: "custom baseURL injects ANTHROPIC_BASE_URL env var",
baseURL: "https://proxy.internal/anthropic/v1",
wantEnvVar: true,
wantEnvVarValue: "https://proxy.internal/anthropic/v1",
},
{
name: "default Anthropic URL still injects env var",
baseURL: "https://api.anthropic.com",
wantEnvVar: true,
wantEnvVarValue: "https://api.anthropic.com",
},
}

for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
ns := &corev1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: namespace}}

modelConfig := &v1alpha2.ModelConfig{
ObjectMeta: metav1.ObjectMeta{Name: "anthropic-model", Namespace: namespace},
Spec: v1alpha2.ModelConfigSpec{
Provider: v1alpha2.ModelProviderAnthropic,
Model: "claude-3-sonnet-20240229",
APIKeySecret: "anthropic-secret",
Anthropic: &v1alpha2.AnthropicConfig{
BaseURL: tt.baseURL,
},
},
}

agent := &v1alpha2.Agent{
ObjectMeta: metav1.ObjectMeta{Name: "test-agent", Namespace: namespace},
Spec: v1alpha2.AgentSpec{
Type: v1alpha2.AgentType_Declarative,
Description: "Test Agent",
Declarative: &v1alpha2.DeclarativeAgentSpec{
SystemMessage: "You are a test agent",
ModelConfig: "anthropic-model",
},
},
}

kubeClient := fake.NewClientBuilder().
WithScheme(scheme).
WithObjects(ns, modelConfig, agent).
Build()

defaultModel := types.NamespacedName{Namespace: namespace, Name: "anthropic-model"}
trans := translator.NewAdkApiTranslator(kubeClient, defaultModel, nil, "", nil)

outputs, err := translator.TranslateAgent(context.Background(), trans, agent)
require.NoError(t, err)
require.NotNil(t, outputs)

// Find the deployment and check env vars
var deployment *appsv1.Deployment
for _, obj := range outputs.Manifest {
if d, ok := obj.(*appsv1.Deployment); ok {
deployment = d
break
}
}
require.NotNil(t, deployment)

var found bool
for _, envVar := range deployment.Spec.Template.Spec.Containers[0].Env {
if envVar.Name == "ANTHROPIC_BASE_URL" {
found = true
assert.Equal(t, tt.wantEnvVarValue, envVar.Value)
break
}
}

if tt.wantEnvVar {
assert.True(t, found, "expected ANTHROPIC_BASE_URL env var to be injected")
} else {
assert.False(t, found, "did not expect ANTHROPIC_BASE_URL env var")
}
})
}
}
7 changes: 7 additions & 0 deletions go/core/pkg/env/providers.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,13 @@ var (
"API key for Anthropic.",
ComponentAgentRuntime,
)

AnthropicAPIBaseURL = RegisterStringVar(
"ANTHROPIC_BASE_URL",
"",
"Custom base URL for the Anthropic API.",
ComponentAgentRuntime,
)
)

// Azure OpenAI
Expand Down
15 changes: 15 additions & 0 deletions python/packages/kagent-adk/src/kagent/adk/_a2a.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,19 @@ def thread_dump(request: Request) -> PlainTextResponse:
kagent_url_override = os.getenv("KAGENT_URL")


def _configure_anthropic_client() -> None:
"""
Configure the Anthropic client to use ANTHROPIC_BASE_URL.

Reads ANTHROPIC_BASE_URL from the environment (matching the Go-side
env.AnthropicAPIBaseURL registration) and logs its presence. The Anthropic
SDK natively reads ANTHROPIC_BASE_URL, so no explicit remapping is needed.
Comment thread
dongjiang1989 marked this conversation as resolved.
"""
anthropic_api_base = os.getenv("ANTHROPIC_BASE_URL")
if anthropic_api_base:
logger.info(f"Configured Anthropic client with base URL: {anthropic_api_base}")


class KAgentApp:
def __init__(
self,
Expand Down Expand Up @@ -86,6 +99,8 @@ def __init__(
self.agent_config = agent_config

def build(self, local=False) -> FastAPI:
_configure_anthropic_client()

session_service = InMemorySessionService()
token_service = None
http_client: Optional[httpx.AsyncClient] = None
Expand Down
5 changes: 3 additions & 2 deletions python/packages/kagent-adk/src/kagent/adk/models/_anthropic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,12 @@ def _create_http_client(self):
@cached_property
def _anthropic_client(self) -> AsyncAnthropic:
api_key = self._api_key or os.environ.get("ANTHROPIC_API_KEY")
base_url = self.base_url or os.environ.get("ANTHROPIC_BASE_URL")
kwargs = {}
if api_key:
kwargs["api_key"] = api_key
if self.base_url:
kwargs["base_url"] = self.base_url
if base_url:
Copy link
Copy Markdown
Contributor

@supreme-gg-gg supreme-gg-gg May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would be a use case to inject the ANTHROPIC_BASE_URL env var? As shown here we already set the base_url kwarg on the anthropic client (which has a higher order of precedence than the env var), so if you specify a base url in the modelconfig for anthropic models it already works.

Copy link
Copy Markdown
Contributor Author

@dongjiang1989 dongjiang1989 May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @supreme-gg-gg

Totally agree. The explicit base_url passed into the Anthropic client has higher precedence and fully covers all custom endpoint requirements defined in ModelConfig.

We keep supporting the ANTHROPIC_BASE_URL environment variable mainly for native SDK convention compliance, convenient local debugging, unified global proxy configuration, and compatibility with external tooling that only respects official Anthropic environment variables.

Additionally, it provides a smooth out-of-the-box experience for new users: when first installing kagent, they can simply set ANTHROPIC_BASE_URL(with a proxy URL) and ANTHROPIC_API_KEY at the system level to get a working default setup immediately, without needing to configure ModelConfig upfront.

Copy link
Copy Markdown
Contributor

@EItanya EItanya May 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additionally, it provides a smooth out-of-the-box experience for new users: when first installing kagent, they can simply set ANTHROPIC_BASE_URL(with a proxy URL) and ANTHROPIC_API_KEY at the system level to get a working default setup immediately, without needing to configure ModelConfig upfront.

Specifically here you mean when running the agent locally? If so why do we need this code in the controller. I think this is a lot of added code with complexity to optimize for a small local use case.

Copy link
Copy Markdown
Contributor Author

@dongjiang1989 dongjiang1989 May 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @EItanya

To clarify the use case: in certain regions (e.g. China), the Anthropic API is not directly accessible. Users need to configure third-party providers that implement the Anthropic Messages API protocol, such as https://help.aliyun.com/zh/model-studio/anthropic-api-messages#ac2a3b4c5d6f7. They set this via ModelConfig.Spec.Anthropic.BaseURL.

However, since the controller already passes base_url from ModelConfig to the Python ADK explicitly (via KAgentAnthropicLlm(base_url=...)), injecting ANTHROPIC_BASE_URL as an env var into the pod is indeed redundant for the K8s deployment path. The env var fallback on the Python side is still valuable for local development, but that doesn't require controller involvement.

I'll remove the controller-side changes (adk_api_translator.go, providers.go, and the corresponding Go test) and keep only the Python ADK changes. Will push shortly.

kwargs["base_url"] = base_url
Comment thread
dongjiang1989 marked this conversation as resolved.
if self.extra_headers:
kwargs["default_headers"] = self.extra_headers

Expand Down
17 changes: 17 additions & 0 deletions python/packages/kagent-adk/tests/unittests/models/test_anthropic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,23 @@ def test_client_uses_base_url(self):
_ = llm._anthropic_client
assert mock_anthropic.call_args.kwargs["base_url"] == "https://proxy.internal/anthropic"

def test_client_falls_back_to_env_base_url(self):
llm = KAgentAnthropicLlm(model="claude-3-sonnet-20240229")
with mock.patch.dict("os.environ", {"ANTHROPIC_BASE_URL": "https://env-proxy.internal/anthropic"}):
with mock.patch("kagent.adk.models._anthropic.AsyncAnthropic") as mock_anthropic:
mock_anthropic.return_value = mock.MagicMock(spec=AsyncAnthropic)
_ = llm._anthropic_client
assert mock_anthropic.call_args.kwargs["base_url"] == "https://env-proxy.internal/anthropic"

def test_explicit_base_url_takes_precedence_over_env(self):
llm = KAgentAnthropicLlm(model="claude-3-sonnet-20240229", base_url="https://explicit.internal/anthropic")
with mock.patch.dict("os.environ", {"ANTHROPIC_BASE_URL": "https://env.internal/anthropic"}):
with mock.patch("kagent.adk.models._anthropic.AsyncAnthropic") as mock_anthropic:
mock_anthropic.return_value = mock.MagicMock(spec=AsyncAnthropic)
_ = llm._anthropic_client
# Explicit base_url wins over env
assert mock_anthropic.call_args.kwargs["base_url"] == "https://explicit.internal/anthropic"

def test_client_uses_extra_headers(self):
llm = KAgentAnthropicLlm(model="claude-3-sonnet-20240229", extra_headers={"X-Org": "test-org"})
with mock.patch("kagent.adk.models._anthropic.AsyncAnthropic") as mock_anthropic:
Expand Down
Loading