Execution Agent

An LLM-powered agent that automatically sets up, builds, and runs test suites for software projects inside Docker containers. Given a Git repository, it analyzes the project, creates a Dockerfile, installs dependencies, and executes the test suite — all autonomously.

Installation

pip install execution-agent

Requires Python 3.10+ and Docker installed on the host.

Quick Start

# 1. Set your API key
export OPENAI_API_KEY="your-api-key"

# 2. Create a project metadata file
cat > project_meta_data.json << 'EOF'
{
  "project_path": "my_project",
  "project_url": "https://github.com/username/my_project",
  "language": "Python",
  "budget": 40
}
EOF

# 3. Run the agent
execution-agent --experiment-file project_meta_data.json

How It Works

1. Context gathering — Clones the repository, inspects CI configs, README, and dependency files
2. Dockerfile generation — Creates a Docker environment tailored to the project
3. Build & test — Iteratively runs commands inside the container to install, build, and test
4. Retry with learning — If the budget is exhausted, retries with lessons from previous attempts
5. Forced exit — As a last resort, a knowledge model synthesizes a final solution from all context

The task is considered successful when ~80%+ of tests pass.

Command-Line Options

execution-agent --experiment-file META.json [OPTIONS]

You can also run it as a module:

python -m execution_agent --experiment-file project_meta_data.json

Project Metadata Format

{
  "project_path": "scipy",
  "project_name": "SciPy",
  "project_url": "https://github.com/scipy/scipy",
  "language": "Python",
  "budget": 40
}

Agent Tools

The agent can use these tools during execution:

Output Structure

execution_agent_workspace/
├── _run_logs/<project>/<timestamp>/
│   ├── run.log                    # Human-readable log
│   ├── run.jsonl                  # Structured JSON log
│   ├── messages.json              # Full LLM conversation history
│   ├── replay_trace.sh            # Bash script to replay all commands
│   ├── tool_metrics.json          # Tool execution statistics
│   ├── cycles_chats/              # Per-cycle LLM prompts
│   ├── success_artifacts/         # On success: Dockerfile, commands.sh, launch.sh
│   └── forced_exit_cycle/         # On budget exhaustion: final attempt artifacts
└── <project>/                     # Cloned repository

Reproducing a Successful Run

cd execution_agent_workspace/_run_logs/<project>/<timestamp>/success_artifacts/
./launch.sh

Retry Mechanism

1. Attempt 1: Initial run with full budget
2. Attempts 2–N: Retries informed by lessons from previous attempts
3. Forced exit cycle: If all retries fail, a knowledge model generates a final Dockerfile and test script based on everything learned

Each attempt produces a summary with problems encountered, progress made, and suggestions for the next attempt.

Language Support

Built-in guidelines are included for: Python, Java, JavaScript/TypeScript, C, C++, and Rust.

Environment Variables

License

MIT — see LICENSE.md for details.

Based on mini-swe-agent by Kilian Lieret and Carlos E. Jimenez.