feat: add litellm.agent() to run claude code, codex, opencode and deep agents through the ai gateway

.circleci/scripts/unit_selection.sh

@@ -77,6 +77,7 @@ legacy_paths() {
       echo tests/unit/embeddings
       echo tests/unit/endpoints
       echo tests/unit/files
+      echo tests/unit/harness
       echo tests/unit/images
       echo tests/unit/interactions
       echo tests/unit/messages

.github/ci-coverage-allowlist.yml

@@ -4,6 +4,14 @@ description: >-
   by a job nor listed here, so every entry below is a decision on the record.
 
 test_paths:
+  - reason: >-
+      litellm.agent() end-to-end suite. It drives the real claude, codex and opencode CLIs and
+      deepagents against a live LiteLLM AI Gateway, so it needs those binaries on PATH plus
+      LITELLM_PROXY_API_BASE / LITELLM_PROXY_API_KEY, and skips without them. Run manually
+      before changing litellm/harness; the mocked coverage runs in tests/unit/harness and
+      tests/unit/llms/*/harness
+    paths:
+      - tests/harness_e2e
   - reason: >-
       The Rust/Python parity harness is run manually through its local CLI. Recorded replay,
       fixture generation, and harness checks are intentionally outside pull request CI

README.md

@@ -268,6 +268,31 @@ For MCP OAuth, an upstream may advertise dynamic client registration but refuse
 
 </details>
 
+<details>
+<summary><b>Agents</b> - Run Claude Code, Codex, OpenCode or Deep Agents on any model (Python SDK)</summary>
+
+### Python SDK - Agents
+
+```python
+import litellm
+from litellm import Harness, sandbox
+
+result = litellm.agent(
+    Harness.CLAUDE_CODE,  # or Harness.CODEX, Harness.OPENCODE, Harness.DEEPAGENTS
+    "Find why tests/test_router.py is flaky and fix it.",
+    sandbox=sandbox.local("./repo"),
+    model="litellm_proxy/claude-sonnet-4-5",  # a model group on your AI Gateway
+)
+
+print(result.text, result.cost, [f.path for f in result.files])
+```
+
+Set `LITELLM_PROXY_API_BASE` and `LITELLM_PROXY_API_KEY` and every model call the agent makes goes through your AI Gateway, tagged `harness,claude_code`. Drop the `litellm_proxy/` prefix to call a provider directly. Install `starlette uvicorn` plus the agent's CLI (`claude`, `codex` or `opencode`), or `deepagents langchain-litellm` for Deep Agents.
+
+[**Docs: Agent Harnesses**](https://docs.litellm.ai/docs/harness)
+
+</details>
+
 ### Supported Providers ([Website Supported Models](https://models.litellm.ai/) | [Docs](https://docs.litellm.ai/docs/providers))
 
 | Provider                                                                            | `/chat/completions` | `/messages` | `/responses` | `/embeddings` | `/image/generations` | `/audio/transcriptions` | `/audio/speech` | `/moderations` | `/batches` | `/rerank` |

litellm/__init__.py

@@ -2281,6 +2281,24 @@ def set_global_gitlab_config(config: Dict[str, Any]) -> None:
 # Track if async client cleanup has been registered (for lazy loading)
 _async_client_cleanup_registered = False
 
+# litellm.agent() entrypoints, resolved lazily from litellm.harness by __getattr__.
+_AGENT_EXPORTS: Final = frozenset(
+    {
+        "agent",
+        "aagent",
+        "agent_session",
+        "aagent_session",
+        "agent_resume",
+        "aagent_resume",
+        "agent_capabilities",
+        "Harness",
+        "ClaudeCodeOptions",
+        "CodexOptions",
+        "OpenCodeOptions",
+        "DeepAgentsOptions",
+    }
+)
+
 # Eager loading for backwards compatibility with VCR and other HTTP recording tools
 # When LITELLM_DISABLE_LAZY_LOADING is set, lazy-loaded attributes are loaded at import time
 # For now, this only affects encoding (tiktoken) as it was the only reported issue
@@ -2314,6 +2332,13 @@ def __getattr__(name: str) -> Any:
         handler_func: Final = registry[name]
         return handler_func(name)
 
+    # litellm.agent() and friends: imported on first access (not needed for completion calls)
+    if name == "harness" or name in _AGENT_EXPORTS:
+        import importlib
+
+        harness_module = importlib.import_module("litellm.harness")
+        return harness_module if name == "harness" else getattr(harness_module, name)
+
     # Lazy load encoding from main.py to avoid heavy tiktoken import
     if name == "encoding":
         from ._lazy_imports import get_litellm_globals

litellm/constants.py

@@ -2184,3 +2184,26 @@
 
 # API endpoint for breached password k-anonymity search
 HIBP_RANGE_API_BASE: Final = "https://api.pwnedpasswords.com/range"
+
+# litellm.harness defaults
+HARNESS_ENDPOINT_HOST: Final = "127.0.0.1"
+HARNESS_ENDPOINT_STARTUP_TIMEOUT_SECONDS: Final = 10.0
+HARNESS_ENDPOINT_REQUEST_TIMEOUT_SECONDS: Final = 600.0
+HARNESS_SESSION_TOKEN_BYTES: Final = 32
+HARNESS_MAX_DIFF_BYTES: Final = 256 * 1024
+HARNESS_STDERR_TAIL_LINES: Final = 40
+HARNESS_STREAM_READ_CHUNK_BYTES: Final = 64 * 1024
+HARNESS_EVENT_QUEUE_MAX_SIZE: Final = 1024
+HARNESS_PROCESS_KILL_GRACE_SECONDS: Final = 5.0
+HARNESS_SNAPSHOT_SKIP_DIRS: Final = frozenset(
+    {
+        ".git",
+        "node_modules",
+        ".venv",
+        "venv",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+    }
+)

litellm/harness/__init__.py

@@ -0,0 +1,98 @@
+"""Agent harnesses: run Claude Code, Codex, OpenCode or Deep Agents on any LiteLLM model.
+
+The entrypoints live on the top-level package:
+
+    import litellm
+    from litellm import Harness, sandbox
+
+    result = litellm.agent(
+        Harness.CLAUDE_CODE,
+        "fix the failing test",
+        sandbox=sandbox.local("."),
+        model="litellm_proxy/claude-sonnet-4-5",  # a model group on your AI Gateway
+    )
+
+This module holds the types you get back: events, Result, State, errors.
+"""
+
+from litellm.harness.errors import (
+    CapabilityUnsupported,
+    HarnessError,
+    HarnessInstallFailed,
+    OptionsMismatch,
+    OutputInvalid,
+    SandboxError,
+    SessionClosed,
+    StateIncompatible,
+)
+from litellm.harness.options import (
+    ClaudeCodeOptions,
+    CodexOptions,
+    DeepAgentsOptions,
+    OpenCodeOptions,
+)
+from litellm.harness.runtime import (
+    AsyncEventStream,
+    AsyncSession,
+    aagent,
+    aagent_resume,
+    aagent_session,
+    agent_capabilities,
+)
+from litellm.harness.sync import EventStream, Session, agent, agent_resume, agent_session
+from litellm.harness.types import (
+    Approval,
+    Capabilities,
+    Compaction,
+    Done,
+    Event,
+    FileChange,
+    Harness,
+    Reasoning,
+    Result,
+    State,
+    Text,
+    ToolCall,
+    ToolResult,
+    Usage,
+)
+
+__all__ = (
+    "Approval",
+    "AsyncEventStream",
+    "AsyncSession",
+    "Capabilities",
+    "CapabilityUnsupported",
+    "ClaudeCodeOptions",
+    "CodexOptions",
+    "Compaction",
+    "DeepAgentsOptions",
+    "Done",
+    "Event",
+    "EventStream",
+    "FileChange",
+    "Harness",
+    "HarnessError",
+    "HarnessInstallFailed",
+    "OpenCodeOptions",
+    "OptionsMismatch",
+    "OutputInvalid",
+    "Reasoning",
+    "Result",
+    "SandboxError",
+    "Session",
+    "SessionClosed",
+    "State",
+    "StateIncompatible",
+    "Text",
+    "ToolCall",
+    "ToolResult",
+    "Usage",
+    "aagent",
+    "aagent_resume",
+    "aagent_session",
+    "agent",
+    "agent_capabilities",
+    "agent_resume",
+    "agent_session",
+)

litellm/harness/context.py

@@ -0,0 +1,62 @@
+"""Per-session state shared by the runtime, handlers and harness configs."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+from pydantic import BaseModel
+
+from litellm.harness.options import HarnessOptions
+from litellm.harness.sandbox.base import Sandbox
+from litellm.harness.types import Approval, Harness, PermissionMode
+
+if TYPE_CHECKING:
+    from litellm.harness.endpoint import ModelEndpoint
+
+ApprovalHandler: TypeAlias = Callable[
+    [Approval], bool | Awaitable[bool]  # mutable-ok: Callable parameter list in a type alias, not a runtime collection
+]
+
+
+@dataclass(frozen=True)
+class GatewayTarget:
+    """Resolved LiteLLM AI Gateway for `litellm_proxy/` models. Internal, not exported."""
+
+    api_base: str
+    api_key: str
+
+
+@dataclass
+class SessionContext:
+    """Everything a handler and config need for a session. Owned by the runtime."""
+
+    harness: Harness
+    sandbox: Sandbox
+    session_id: str
+    # Model name as sent to the runtime (litellm_proxy/ prefix already stripped).
+    model: str | None = None
+    gateway: GatewayTarget | None = None
+    api_key: str | None = None
+    api_base: str | None = None
+    endpoint: ModelEndpoint | None = None
+    instructions: str | None = None
+    tools: Sequence[Callable[..., Any]] = ()
+    skills: Sequence[str] = ()
+    disable_tools: Sequence[str] = ()
+    permissions: PermissionMode = "full"
+    on_approval: ApprovalHandler | None = None
+    output: type[BaseModel] | None = None
+    max_turns: int | None = None
+    timeout: float | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    options: HarnessOptions | None = None
+    # Set by the handler after each turn.
+    final_text: str = ""
+    output_json: str | None = None
+    # Usage for in-process harnesses that call LiteLLM directly (no model endpoint).
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost: float = 0.0
+    calls: int = 0