execution-agent 0.1.2

Automated project building and test execution inside Docker containers

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]

Option	Description	Default
--experiment-file	Path to project metadata JSON (required)	—
--task	Custom task string	Auto-generated
--task-file	File containing custom task instructions	—
--model	LLM model for the agent	gpt-5-nano
--knowledge-model	LLM model for context analysis	gpt-5-mini
--api-key	OpenAI API key	$OPENAI_API_KEY
--workspace-root	Output directory	execution_agent_workspace
--prompt-files	Custom prompt templates directory	Bundled defaults
--log-level	DEBUG / INFO / WARNING / ERROR	INFO
--run-log-dir	Custom directory for run logs	Auto-generated
--max-retries	Retries after budget exhaustion	2

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
}

Field	Description
project_path	Directory name for the project
project_name	Human-readable name (optional)
project_url	Git repository URL
language	Primary language: Python, Java, Javascript, C, C++, Rust
budget	Maximum execution cycles (steps)

Agent Tools

The agent can use these tools during execution:

Tool	Description
linux_terminal	Execute bash commands inside the Docker container
read_file	Read file contents
write_to_file	Write files (Dockerfiles, scripts, etc.)
search_docker_image	Search Docker Hub for base images
goals_accomplished	Signal successful task completion

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

Variable	Description
OPENAI_API_KEY	API key for LLM access (required)
OPENAI_MODEL	Default model (fallback for --model)
KNOWLEDGE_MODEL	Default knowledge model (fallback for --knowledge-model)

License

MIT — see LICENSE.md for details.

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