Dependencies

Manage optional packages in the Python environment that runs AgentCompass.

AgentCompass dependency management covers only the host Python environment that runs the agentcompass process. It can inspect or install packages imported by benchmark loaders, host-side evaluators, and local SDK integrations.

Packages used inside Docker, Daytona, Modal, or another execution environment are outside this dependency manager’s scope. Their images, snapshots, recipes, and harness setup own those packages. System prerequisites such as the Docker daemon, GPUs, and provider credentials are also outside Python dependency management.

Default Installation

Install the default profile from a source checkout:

uv pip install -e .

The default profile contains:

Category	Packages or capabilities
Runtime	Async file and HTTP utilities, configuration, logging, result rendering, validation, and retry support, etc
Model clients	OpenAI, Anthropic, and LiteLLM
Shared benchmark data	datasets
Harbor framework	harbor
Remote sandbox environments	Daytona and Modal SDKs
Common media support	pillow

Docker still requires its external service and system tools. Its runtime is not downloaded by the optional dependency installer.

Optional Extras

The extras below are installed into the host environment that runs AgentCompass. They never install packages inside a Docker container or a remote sandbox.

Extra	Required in the host Python environment when	How it is checked
swebench	Running swebench_verified or swebench_multilingual	Generic dependency check before task loading
scicode	Running the host-side SciCode evaluator	Generic dependency check before task loading
gdpval	Loading GDPVal references or producing host-side workbooks	Generic dependency check before task loading
wildclawbench	Decrypting WildClawBench ground truth on the host	Generic dependency check before task loading
mini-swe-agent	Running mini_swe_agent with launch_mode=local	Local harness preflight before the session starts
frontier-engineering	Running openevolve through host_process	OpenEvolve checks the Python selected by the harness
taubench	Running TauBench through host_process	TauBench runs its execution-environment doctor before inference

Install one or more extras ahead of time:

uv pip install -e ".[swebench,mini-swe-agent]"

For an installed release instead of a source checkout:

python -m pip install "agentcompass[swebench,mini-swe-agent]"

Automatic Installation

auto-install-dependencies is disabled by default, so a run does not modify the host user environment without an explicit opt-in. When a selected component declares a DependencySpec, AgentCompass checks its declared import modules in the current interpreter. If one is missing, the run raises OptionalDependencyError and prints complete uv and pip commands for manual installation.

After installing the suggested extra, run the same command again. Alternatively, explicitly opt in to automatic installation for trusted built-in components:

export MODEL_NAME=""

agentcompass run <benchmark> <harness> "$MODEL_NAME" --auto-install-dependencies

For a multi-request orchestration, apply the same explicit opt-in once at the shared runtime:

agentcompass launch orchestration.yaml --auto-install-dependencies

The same opt-in is available through configuration, environment variables, and the Python SDK:

runtime:
  auto_install_dependencies: true

export AGENTCOMPASS_AUTO_INSTALL_DEPENDENCIES=true

import os

from agentcompass import run_evaluation

run_evaluation(
    benchmark="swebench_verified",
    harness="mini_swe_agent",
    model=os.environ["MODEL_NAME"],
    auto_install_dependencies=True,
)

Explicit CLI or SDK values take precedence over the environment variable, which takes precedence over configuration. When enabled, installation runs in the AgentCompass host Python environment before task loading. It never installs packages in an execution environment and is independent of sandbox setup and network policy.

The check covers the import names declared by the selected component; it does not recursively inspect every transitive package or validate a complete Python environment. uv or pip resolves transitive dependencies when it installs the extra.

When Dependency Checks Run

AgentCompass does not scan or install every optional extra when a component is selected. A dependency check runs only on an execution path that declares or performs that check, and a satisfied check produces no installation message.

Select components
  |
  v
Does the active execution path declare a dependency check?
  |-- No  --> Continue without checking or prompting
  |
  `-- Yes --> Check the environment that will consume the dependency
                |-- Available --> Continue silently
                `-- Missing   --> Report the relevant installation or provisioning action

The generic Host Python checks follow the same rule: they first inspect the declared imports and return silently when all are available. Manual uv and pip commands are generated only after a missing import is detected.

Some benchmark dependencies remain host requirements regardless of --env. swebench_verified and swebench_multilingual use swebench in host-side evaluation; SciCode evaluates with its scientific Python stack on the host; GDPVal loads references and produces workbooks on the host; and WildClawBench decrypts ground truth on the host. Selecting Docker, Daytona, or Modal for task execution does not move those operations into the sandbox.

Execution Environment Boundary

--auto-install-dependencies has no effect inside Docker, Daytona, Modal, or other sandboxes. A harness may perform its own environment-specific preflight or setup, but that behavior is separate from the generic dependency manager and is documented on the corresponding harness or environment page.

For example, the Frontier-Engineering Docker recipe selects an image whose runner Python already provides OpenEvolve 0.2.26. The OpenEvolve harness validates that sandbox Python directly; it does not inspect or modify the host Python environment. With host_process, install the frontier-engineering extra into the Python selected by the harness.

See Environments for image and provider setup, and Installation for operating-system prerequisites.

Special Case and Potential Dependency Conflicts

TauBench

The official tau2 package constrains shared packages differently from AgentCompass. To avoid downgrading the host Python environment’s LiteLLM or Tenacity installation, AgentCompass first installs the taubench extra and then installs the pinned tau2 source without its transitive dependencies:

uv pip install -e ".[taubench]"
uv pip install --python "$(command -v python)" --no-deps \
  "tau2 @ git+https://github.com/sierra-research/tau2-bench@v1.0.1"

The banking knowledge variants additionally require the external sandbox runtime and retrieval tools:

npm install -g @anthropic-ai/sandbox-runtime@0.0.23
sudo apt-get install -y ripgrep bubblewrap socat