Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
4 changes: 3 additions & 1 deletion src/agent_env/agents/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,9 @@ Use your own URI, not `urn:agentenv:*`. Reference: `packages/agentenv-protocol/e
`request.config.timeout_seconds` with `request.mcp_servers` connected, records the trajectory, and returns a
`TaskResult` with a `session_ref`. Replace `claude_bridge.py` with your runtime's bridge.
4. **Map the model endpoint**: read `LITELLM_BASE_URL`, `LITELLM_API_KEY` and `LITELLM_EXTRA_HEADERS` and hand them
to your runtime, as `claude_bridge.py` `cli_env` does.
to your runtime, as `claude_bridge.py` `cli_env` does. `LITELLM_BASE_URL` comes as configured and may end in `/v1`
or not: a client that appends its own versioned path (Anthropic's `/v1/messages`) strips one trailing `/v1` first,
and one that wants the `/v1` root adds it unless it's there.
5. **Add extensions** (Extensions): `mcp-config` and `trajectory` first, then every other one your runtime can
honour. Keep `AGENT_CARD = app.state.agentenv_a2a.card` at the end of `a2a_server.py`.
6. **Test it offline** with Starlette's `TestClient` and your runtime faked, as `tst/unit/agents/claude_code/` does:
Expand Down
11 changes: 10 additions & 1 deletion src/agent_env/agents/agents/browser-use/agent.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
import re
import sys
from pathlib import Path
from urllib.parse import urlsplit, urlunsplit

import httpx2
from anthropic import AsyncAnthropic
Expand All @@ -38,12 +39,20 @@
_CHECKPOINT = TypeAdapter(ModelRequest | None)


def _api_root(url: str) -> str:
"""``LITELLM_BASE_URL`` without a trailing ``/`` and one trailing ``/v1``: it may be configured either way, and
Anthropic's client appends its own ``/v1/messages``. Core's ``api_root``, copied since this image can't import
core; a unit test keeps the copies equal."""
parts = urlsplit(url.strip())
return urlunsplit(parts._replace(path=parts.path.rstrip("/").removesuffix("/v1").rstrip("/")))


def model(turn: dict):
"""The turn's model on agent-env's endpoint, with the endpoint's headers."""
name, base_url, key = turn["model"], os.environ["LITELLM_BASE_URL"], os.environ["LITELLM_API_KEY"]
headers = json.loads(os.environ.get("LITELLM_EXTRA_HEADERS") or "{}")
if "claude" in name.lower():
client = AsyncAnthropic(auth_token=key, base_url=base_url, default_headers=headers)
client = AsyncAnthropic(auth_token=key, base_url=_api_root(base_url), default_headers=headers)
return AnthropicModel(name, provider=AnthropicProvider(anthropic_client=client),
profile=anthropic_model_profile(name.rsplit("/", 1)[-1]))
client = AsyncOpenAI(api_key=key, base_url=base_url, default_headers=headers)
Expand Down
11 changes: 10 additions & 1 deletion src/agent_env/agents/agents/claude-code/claude_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
from functools import partial
from pathlib import Path
from typing import Literal
from urllib.parse import urlsplit, urlunsplit

from pydantic import BaseModel, ConfigDict, model_validator

Expand Down Expand Up @@ -174,6 +175,14 @@ def _model_headers(raw: str | None) -> dict[str, str]:
return {str(name): str(value) for name, value in headers.items()}


def _api_root(url: str) -> str:
"""``LITELLM_BASE_URL`` without a trailing ``/`` and one trailing ``/v1``: it may be configured either way, and
the CLI appends its own ``/v1/messages``. Core's ``api_root``, copied since this image can't import core; a unit
test keeps the copies equal."""
parts = urlsplit(url.strip())
return urlunsplit(parts._replace(path=parts.path.rstrip("/").removesuffix("/v1").rstrip("/")))


def cli_env(environ: Mapping[str, str], *, model: str | None = None, project_id: str | None = None,
task_id: str | None = None, max_thinking_tokens: int | None = None,
clock_armed: bool = False, mcp_urls: Iterable[str] = ()) -> dict[str, str]:
Expand All @@ -185,7 +194,7 @@ def cli_env(environ: Mapping[str, str], *, model: str | None = None, project_id:
if not env.get("ANTHROPIC_AUTH_TOKEN") and env.get("LITELLM_API_KEY"):
env["ANTHROPIC_AUTH_TOKEN"] = env["LITELLM_API_KEY"]
if not env.get("ANTHROPIC_BASE_URL") and env.get("LITELLM_BASE_URL"):
env["ANTHROPIC_BASE_URL"] = env["LITELLM_BASE_URL"]
env["ANTHROPIC_BASE_URL"] = _api_root(env["LITELLM_BASE_URL"])
if env.get("ANTHROPIC_AUTH_TOKEN"):
env["ANTHROPIC_API_KEY"] = ""
if model and env.get("ANTHROPIC_BASE_URL"):
Expand Down
11 changes: 10 additions & 1 deletion src/agent_env/agents/agents/codex/codex_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
from collections.abc import Mapping
from pathlib import Path
from typing import Any, Literal
from urllib.parse import urlsplit, urlunsplit

import tomli_w
from pydantic import BaseModel, ConfigDict, model_validator
Expand Down Expand Up @@ -194,6 +195,14 @@ def model_headers(raw: str | None) -> dict[str, str]:
return {str(name): str(value) for name, value in headers.items()}


def _api_root(url: str) -> str:
"""``LITELLM_BASE_URL`` without a trailing ``/`` and one trailing ``/v1``: it may be configured either way, and
codex is given LiteLLM's ``/openai/v1`` route under it. Core's ``api_root``, copied since this image can't
import core; a unit test keeps the copies equal."""
parts = urlsplit(url.strip())
return urlunsplit(parts._replace(path=parts.path.rstrip("/").removesuffix("/v1").rstrip("/")))


def write_base_config(environ: Mapping[str, str]) -> None:
"""The settings every turn shares: the collaboration tools, and the model endpoint agent-env configured as a
Responses API provider, with its headers and the run's attribution on each call."""
Expand All @@ -206,7 +215,7 @@ def write_base_config(environ: Mapping[str, str]) -> None:
cfg["model_provider"] = "litellm"
provider = {
"name": "LiteLLM proxy",
"base_url": base_url.rstrip("/") + "/openai/v1",
"base_url": _api_root(base_url) + "/openai/v1",
"env_key": "LITELLM_API_KEY",
"wire_api": "responses",
# Bound codex retry/idle behavior so a hung stream fails fast
Expand Down
11 changes: 10 additions & 1 deletion src/agent_env/agents/agents/gemini/a2a_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
from datetime import datetime, timezone
from pathlib import Path
from typing import Any
from urllib.parse import urlsplit, urlunsplit

import httpx
from a2a.types import AgentSkill
Expand Down Expand Up @@ -144,6 +145,14 @@
_LITELLM_ROUTE_HEADERS = ("x-litellm-model-id", "x-litellm-model-api-base", "x-litellm-model-group")


def _api_root(url: str) -> str:
"""``LITELLM_BASE_URL`` without a trailing ``/`` and one trailing ``/v1``: it may be configured either way, and
the proxy appends LiteLLM's ``/gemini/...`` and ``/v1/chat/completions`` routes to it. Core's ``api_root``,
copied since this image can't import core; a unit test keeps the copies equal."""
parts = urlsplit(url.strip())
return urlunsplit(parts._replace(path=parts.path.rstrip("/").removesuffix("/v1").rstrip("/")))


def _describe_transport_error(exc: Exception) -> str:
"""Name the exception class: many httpx errors (ReadTimeout, RemoteProtocolError) stringify to ''."""
text = str(exc)
Expand Down Expand Up @@ -747,7 +756,7 @@ async def litellm_gemini_proxy(self, request: Request) -> Response:
if route is None:
raise HTTPException(status_code=404, detail="no running turn has this proxy route")
rest = request.path_params["rest"]
base = (os.environ.get("LITELLM_BASE_URL") or "").rstrip("/")
base = _api_root(os.environ.get("LITELLM_BASE_URL") or "")
if not base:
raise HTTPException(status_code=503, detail="LITELLM_BASE_URL not set; cannot forward gemini model calls")
# Provider-prefixed route models (vertex_ai/...) can't traverse the /gemini
Expand Down
2 changes: 1 addition & 1 deletion src/agent_env/agents/agents/hermes/hermes_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@


def _base_url(environ: Mapping[str, str]) -> str:
"""The endpoint's chat-completions root: agent-env's LITELLM_BASE_URL has no /v1 suffix."""
"""The endpoint's chat-completions root: LITELLM_BASE_URL may end in /v1 or not."""
base = (environ.get("LITELLM_BASE_URL") or "").rstrip("/")
return base if base.endswith("/v1") else f"{base}/v1"

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@


def _base_url(environ: Mapping[str, str]) -> str:
"""The endpoint's chat-completions root: agent-env's LITELLM_BASE_URL has no /v1 suffix."""
"""The endpoint's chat-completions root: LITELLM_BASE_URL may end in /v1 or not."""
base = (environ.get("LITELLM_BASE_URL") or "").rstrip("/")
return base if base.endswith("/v1") else f"{base}/v1"

Expand Down
2 changes: 1 addition & 1 deletion src/agent_env/agents/agents/opencode/opencode_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ def _one_of(self) -> OpenCodeTools:


def _base_url(environ: Mapping[str, str]) -> str:
"""The endpoint's chat-completions root: agent-env's LITELLM_BASE_URL has no /v1 suffix."""
"""The endpoint's chat-completions root: LITELLM_BASE_URL may end in /v1 or not."""
base = (environ.get("LITELLM_BASE_URL") or "").rstrip("/")
return base if base.endswith("/v1") else f"{base}/v1"

Expand Down
17 changes: 14 additions & 3 deletions src/agent_env/config/model.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
from dataclasses import dataclass, field, fields
from enum import StrEnum
from typing import Optional
from urllib.parse import urlsplit
from urllib.parse import urlsplit, urlunsplit

from agent_env.config.errors import ConfigError
from agent_env.config.loader import ENV_REF_PREFIX, SECRET_REF_PREFIX, SecretResolver, interpolate
Expand Down Expand Up @@ -284,15 +284,26 @@ def same_endpoint(a: Optional[str], b: Optional[str]) -> bool:
return bool(a and b) and _endpoint(a) == _endpoint(b)


def api_root(url: str) -> str:
"""``url`` without a trailing ``/`` and one trailing ``/v1``, for a client that appends its own versioned path
(Anthropic's ``/v1/messages``): the endpoint may be configured either way, and ``same_endpoint`` compares by the
same root."""
parts = urlsplit(url.strip())
return urlunsplit(parts._replace(path=_root_path(parts.path)))


def _root_path(path: str) -> str:
return path.rstrip("/").removesuffix("/v1").rstrip("/")


def _endpoint(url: str) -> tuple:
parts = urlsplit(url.strip())
scheme = parts.scheme.lower()
try:
port = parts.port
except ValueError:
return (url,)
path = parts.path.rstrip("/")
path = path.removesuffix("/v1").rstrip("/")
path = _root_path(parts.path)
return scheme, (parts.hostname or "").lower(), None if port == _DEFAULT_PORTS.get(scheme) else port, path, parts.query


Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,13 @@
from __future__ import annotations

import asyncio
import contextlib
import io
import json
import logging
import re
import uuid
from collections.abc import Mapping, Sequence
from collections.abc import Callable, Mapping, Sequence
from dataclasses import dataclass, field, replace
from typing import Any, ClassVar, Optional

Expand All @@ -20,7 +22,7 @@
from agent_env.a2a_agent.staging import transfer_store
from agent_env.config import get_config
from agent_env.config.errors import ConfigError
from agent_env.config.model import ModelParam, ModelRole, no_key_for
from agent_env.config.model import ModelParam, ModelRole, api_root, no_key_for
from agent_env.providers.sandbox_providers.sandbox import into_container
from agent_env.task_step.context import (
PromptResponse,
Expand Down Expand Up @@ -281,6 +283,29 @@ def _caches_prompts(model: str) -> bool:
return "claude" in model.lower()


def _judge_route(model: str, api_base: Optional[str], provider_of: Callable[..., Any],
custom_provider: Optional[str] = None) -> tuple[str, Optional[str]]:
"""The model name and base a direct judge call hands litellm; what it records stays ``model``. Through an
endpoint, a bare name goes by what litellm makes of it: an Anthropic one keeps that route, with the base's
trailing ``/v1`` dropped since its client appends ``/v1/messages``; an OpenAI one goes as configured; any other,
which litellm would send to that provider's own API (``gemini-*`` to Vertex), or one it can't place, goes
through the endpoint as ``openai/<name>``. A provider prefix in the name, or a ``custom_llm_provider`` among the
call's params, keeps the route it names. ``provider_of`` is litellm's ``get_llm_provider``, which prints a banner
before refusing a name it can't place."""
if api_base is None:
return model, None
try:
with contextlib.redirect_stdout(io.StringIO()):
provider = provider_of(model, custom_llm_provider=custom_provider)[1]
except Exception:
return f"openai/{model}", api_base
if provider == "anthropic":
return model, api_root(api_base)
if provider == "openai" or custom_provider or "/" in model:
return model, api_base
return f"openai/{model}", api_base


def _usage_and_cost(response: Any) -> dict:
"""A LiteLLM response's token counts and LiteLLM's price of it in USD, each None when it has none."""
usage = getattr(response, "usage", None)
Expand Down Expand Up @@ -1389,6 +1414,9 @@ async def _prompt_llm_judge(
if base and not api_key and not config.is_model_endpoint(base):
raise ConfigError(f"{self.type} '{self.id}': {no_key_for(base, _JUDGE_KEY_HOW)}")
call_config = config.resolve_model_call(model, default_api_key=api_key, base_override=base)
route_model, route_base = _judge_route(model, call_config.api_base, litellm.get_llm_provider,
call_config.params.get("custom_llm_provider"))
call_config = replace(call_config, api_base=route_base)
text_blocks: list[dict] = [{"type": "text", "text": eval_prompt}]
cached = bool(cached_prefix) and eval_prompt.startswith(cached_prefix or "") and _caches_prompts(model)
if cached:
Expand All @@ -1414,7 +1442,7 @@ async def _prompt_llm_judge(
for attempt in range(1, self.DEFAULT_MAX_RETRIES + 1):
try:
request_kwargs: dict = dict(
model=model,
model=route_model,
messages=messages,
timeout=self.judge_timeout_seconds,
**call_config.client_kwargs(),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
from typing import Any, ClassVar, Optional

from agent_env.config import ConfigError, get_config
from agent_env.config.model import MODEL_HEADERS_ENV, no_key_for
from agent_env.config.model import MODEL_HEADERS_ENV, api_root, no_key_for
from agent_env.entity.refs import EntityRef
from agent_env.env.env import require_sandbox
from agent_env.env.envs.computer.utils import inside
Expand Down Expand Up @@ -376,7 +376,7 @@ def _merged_env(self, config, sandbox_type: Optional[str], extra_env: dict[str,
try:
litellm_url = config.get_litellm_base_url()
merged_env["LITELLM_BASE_URL"] = litellm_url
merged_env["ANTHROPIC_BASE_URL"] = litellm_url
merged_env["ANTHROPIC_BASE_URL"] = api_root(litellm_url)
except (KeyError, ConfigError):
logger.warning("LITELLM_BASE_URL unavailable; verifier won't have LLM base URL")
merged_env.update(all_sandbox_container_env())
Expand Down
8 changes: 8 additions & 0 deletions tst/unit/agents/claude_code/test_cli_env.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,14 @@ def test_the_configured_endpoint_is_the_clis_with_its_key_as_a_bearer_token():
assert env["CLAUDE_CODE_ATTRIBUTION_HEADER"] == "0"


@pytest.mark.parametrize("base", ["https://gateway.example.com/v1", "https://gateway.example.com/v1/",
"https://gateway.example.com/"])
def test_the_endpoint_may_end_in_v1_since_the_cli_appends_its_own(base):
env = claude_bridge.cli_env({**GATEWAY, "LITELLM_BASE_URL": base})

assert (env["ANTHROPIC_BASE_URL"], env["LITELLM_BASE_URL"]) == ("https://gateway.example.com", base)


def test_a_script_the_model_runs_can_call_the_endpoint_with_the_litellm_variables():
headers = json.dumps({"X-Bill-To": "team-a"})

Expand Down
15 changes: 15 additions & 0 deletions tst/unit/agents/codex/test_config_and_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
from pathlib import Path

import httpx
import pytest

from tst.unit.agents.codex.agent import a2a_server, codex_bridge

Expand Down Expand Up @@ -271,3 +272,17 @@ def test_triggers_register_decide_and_state(codex):
decided = _call(codex, "POST", "/ext/triggers/decide", {"turn": 1, "solver_message": "x"}).json()
assert (decided["parts"], decided["done"], decided["fired"]) == ([{"kind": "text", "text": "hi"}], False, ["hello"])
assert _call(codex, "GET", "/ext/triggers").json()["firing_log"]


@pytest.mark.parametrize("base", ["https://llm.example.com/v1", "https://llm.example.com/v1/"])
def test_an_endpoint_ending_in_v1_gets_litellms_openai_route_once(codex, monkeypatch, base):
monkeypatch.setenv("LITELLM_BASE_URL", base)

async def exercise():
async with codex.app.router.lifespan_context(codex.app):
pass

asyncio.run(exercise())

config = tomllib.loads((Path(os.environ["CODEX_HOME"]) / "config.toml").read_text())
assert config["model_providers"]["litellm"]["base_url"] == "https://llm.example.com/openai/v1"
15 changes: 15 additions & 0 deletions tst/unit/agents/gemini/test_litellm_proxy.py
Original file line number Diff line number Diff line change
Expand Up @@ -322,3 +322,18 @@ def test_a_message_level_signature_goes_only_to_the_first_parallel_call(vertex,
parts = client.post(GENERATE, json=_GREQ).json()["candidates"][0]["content"]["parts"]

assert [p.get("thoughtSignature") for p in parts] == ["sig-a", None]


def test_an_endpoint_ending_in_v1_gets_litellms_routes_once(upstream, agent, client, monkeypatch):
monkeypatch.setenv("LITELLM_BASE_URL", BASE + "/v1/")
upstream.response = httpx.Response(200, json={"candidates": []})
_route(agent, model="gemini-2.5-flash", project_id="p-1")
client.post(GENERATE + "?alt=json", content=b'{"contents":[]}', headers={"content-type": "application/json"})
upstream.response = httpx.Response(200, json={
"model": "gemini-3.1-pro-preview", "choices": [{"message": {"content": "hi"}, "finish_reason": "stop"}],
"usage": {"prompt_tokens": 3, "completion_tokens": 1, "total_tokens": 4}})
_route(agent, model="vertex_ai/global/gemini-3.1-pro-preview", project_id="p-1")
client.post(GENERATE, json=_GREQ)

assert [str(request.url) for request in upstream.requests] == [
f"{BASE}/gemini/v1beta/models/gemini-3.1-pro-preview:generateContent?alt=json", f"{BASE}/v1/chat/completions"]
45 changes: 45 additions & 0 deletions tst/unit/agents/test_api_root_copies.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
"""Every agent's copy of core's ``api_root``, which an agent's image can't import, answers as core's does. Each copy is
read from its file's source, since some agents' modules import packages only their images install."""

import ast
from pathlib import Path
from urllib.parse import urlsplit, urlunsplit

import pytest

import agent_env
from agent_env.config.model import api_root

AGENTS = Path(agent_env.__file__).parent / "agents" / "agents"
URLS = [
"https://proxy.example", "https://proxy.example/", "https://proxy.example/v1", "https://proxy.example/v1/",
"https://proxy.example/v1/v1", "https://proxy.example/prefix", "https://proxy.example/prefix/v1",
"http://172.17.0.1:4000/v1", "https://proxy.example/v1?team=a", " https://proxy.example/v1 ",
"HTTPS://Proxy.Example/V1", "https://proxy.example/v10", "",
]


def _copies() -> dict[str, object]:
"""Each agent file's ``_api_root``, run from its source with only what it imports from ``urllib.parse``."""
copies = {}
for path in sorted(AGENTS.glob("*/*.py")):
tree = ast.parse(path.read_text())
for node in tree.body:
if isinstance(node, ast.FunctionDef) and node.name == "_api_root":
namespace = {"urlsplit": urlsplit, "urlunsplit": urlunsplit}
exec(compile(ast.Module([node], type_ignores=[]), str(path), "exec"), namespace)
copies[str(path.relative_to(AGENTS))] = namespace["_api_root"]
return copies


COPIES = _copies()


def test_the_agents_that_append_their_own_path_each_have_a_copy():
assert {"browser-use/agent.py", "claude-code/claude_bridge.py", "codex/codex_config.py",
"gemini/a2a_server.py"} <= set(COPIES)


@pytest.mark.parametrize("copy", sorted(COPIES))
def test_a_copy_answers_as_core_does(copy):
assert [COPIES[copy](url) for url in URLS] == [api_root(url) for url in URLS]
Loading
Loading