How princeton-nlp/swe-agent works
Purpose and entry points
SWE-agent is a Python CLI framework that lets an LLM solve repository tasks through shell-backed tools: issue fixing, benchmarking, custom coding tasks, and legacy CTF workflows. The package entry point is sweagent/__main__.py; run orchestration is centered in sweagent/run/run.py, with single-instance, batch, replay, and shell modes in sweagent/run/run_single.py, sweagent/run/run_batch.py, and sweagent/run/run_replay.py.
Configuration-driven assembly
A YAML configuration selects the model, agent behavior, environment, prompts, tools, and run settings. Shared loading/serialization logic is in sweagent/utils/config.py; canonical and scenario-specific configurations live in config/default.yaml, config/benchmarks/, and config/sweagent_0_7/. This is the principal extension boundary: new experiments should compose configuration and existing abstractions rather than alter orchestration.
Agent control loop
The agent layer converts a problem and accumulated trajectory into model calls, parses model actions, executes them, and iterates until submission/termination. Core implementations and extension points are sweagent/agent/agents.py, sweagent/agent/action_sampler.py, and sweagent/agent/models.py. History reduction and multimodal/problem input handling sit at sweagent/agent/history_processors.py and sweagent/agent/problem_statement.py; hooks expose status/lifecycle observation under sweagent/agent/hooks/.
Model-provider boundary
sweagent/agent/models.py isolates LLM invocation and model configuration from the agent loop. It supports the README’s “language model of choice” model while preserving a common action-sampling interface. Credentials and runtime environment values are expected externally (for example .env.example), rather than embedded in task configs.
Sandboxed repository environment
The environment layer owns the target checkout and command-execution boundary: sweagent/environment/repo.py represents repository setup/state, while sweagent/environment/swe_env.py provides the agent-facing execution environment. Environment hooks in sweagent/environment/hooks/ report lifecycle/status. This boundary is where host/container isolation, repository mutation, installation, and test execution are controlled.
Tool protocol and executable bundles
Tool definitions are assembled from configured bundles, command metadata, and parsers in sweagent/tools/bundle.py, sweagent/tools/commands.py, and sweagent/tools/parsing.py. The actual agent-visible commands are external executable assets under tools/, such as tools/search/, tools/windowed_edit_replace/, and tools/submit/. This cleanly separates Python orchestration from shell/tool implementation and permits specialized capabilities including browser and image tools.
Runs, artifacts, and downstream integration
Run modules create trajectories and prediction/patch artifacts, support batch execution, replay, merging, comparison, and statistics. Key paths are sweagent/run/common.py, sweagent/run/batch_instances.py, and sweagent/run/hooks/. Run hooks can apply patches, invoke SWE-bench evaluation, or open GitHub pull requests via sweagent/run/hooks/apply_patch.py, sweagent/run/hooks/swe_bench_evaluate.py, and sweagent/run/hooks/open_pr.py; GitHub-specific utilities are in sweagent/utils/github.py.
Inspection and operational surfaces
A local trajectory inspector is provided by sweagent/inspector/server.py and its static UI in sweagent/inspector/index.html. The project runs on Python, uses shell commands and potentially containerized target environments, calls external LLM providers, integrates with GitHub, and optionally evaluates against SWE-bench. Documentation is built with MkDocs (mkdocs.yml), but it is separate from agent runtime architecture.
Main entry points: agents.py Agent loop · run_single.py Run modes · config.py Config loader · run.py Run orchestrator
Components 21
Configuration
YAML composition selects runtime components.
- Config loader · Loads and serializes composed runtime configuration.
sweagent/utils/config.py - Default config
config/default.yaml - Scenario configs · Benchmark and version-specific experiment configurations.
Agent Runtime
LLM-driven control loop and action protocol.
- Agent loop · Iterates model actions against problem state and trajectory.
sweagent/agent/agents.py - Action sampler · Parses and samples model actions through the common interface.
sweagent/agent/action_sampler.py - Model provider boundary · Isolates LLM invocation and model configuration.
sweagent/agent/models.py - History & problem input · Reduces history and handles problem or multimodal input.
sweagent/agent/history_processors.py - Agent hooks
Execution
Sandboxed repository mutation and run management.
- Run orchestrator · Assembles configured runs and dispatches execution modes.
sweagent/run/run.py - Run modes · Single, batch, replay, and shell workflows.
sweagent/run/run_single.py - Repository state · Owns target checkout setup and state.
sweagent/environment/repo.py - Sandbox environment · Runs agent-facing commands with controlled isolation.
sweagent/environment/swe_env.py - Tool protocol · Builds configured bundles, command metadata, and parsers.
sweagent/tools/bundle.py - Executable tool bundles · Agent-visible command implementations such as search, edit, and submit.
Outputs & Integrations
Artifacts, inspection, and optional downstream actions.
- Run artifacts · Creates predictions and patch outputs for runs.
sweagent/run/common.py - Run hooks · Applies patches, evaluates SWE-bench, or opens pull requests.
- Trajectory inspector · Serves the local trajectory inspection interface.
sweagent/inspector/server.py
Other components
- CLI entry point
sweagent/__main__.py - External LLM providers · Credentials and runtime values are supplied outside task configs.
- GitHub · Optional patch and pull-request destination.
- SWE-bench evaluation
Connections 21
- CLI entry point → Run orchestrator: starts
- Run orchestrator → Run modes: dispatches
- Run orchestrator → Config loader: loads
- Config loader → Default config: reads
- Config loader → Scenario configs: composes
- Run modes → Agent loop: executes
- Run modes → Repository state: creates
- Agent loop → History & problem input: uses
- Agent loop → Action sampler: samples actions
- Action sampler → Model provider boundary: requests completion
- Model provider boundary → External LLM providers: invokes
- Agent loop → Sandbox environment: executes actions
- Sandbox environment → Repository state: mutates checkout
- Sandbox environment → Tool protocol: exposes
- Tool protocol → Executable tool bundles: runs
- Agent loop → Agent hooks: emits lifecycle
- Run modes → Run artifacts: writes
- Run artifacts → Trajectory inspector: inspected by
- Run artifacts → Run hooks: triggers
- Run hooks → GitHub: opens PRs
- Run hooks → SWE-bench evaluation: evaluates