Install & Compatibility
Where this runs
tested against v2.4.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DefaultAgent
✓ from minisweagent.agents.default import DefaultAgent
LitellmModel
✓ from minisweagent.models.litellm_model import LitellmModel
LocalEnvironment
✓ from minisweagent.environments.local import LocalEnvironment
This quickstart demonstrates how to initialize and run a `DefaultAgent` using a LiteLLM-compatible model (like OpenAI's GPT models) within a `LocalEnvironment`. The agent is tasked with writing a Python function and its tests. Ensure your LLM API key and preferred model name are set, either directly or via environment variables.
import os
from minisweagent.agents.default import DefaultAgent
from minisweagent.models.litellm_model import LitellmModel
from minisweagent.environments.local import LocalEnvironment
# Set your LLM API key and model name
os.environ["OPENAI_API_KEY"] = os.environ.get("MINI_SWE_AGENT_OPENAI_KEY", "sk-YOUR_OPENAI_KEY")
model_name = os.environ.get("MINI_SWE_AGENT_MODEL_NAME", "gpt-4o-mini") # Or "claude-3-sonnet", etc.
agent = DefaultAgent(
LitellmModel(model_name=model_name),
LocalEnvironment(),
)
task = "Write a Python function to calculate the nth Fibonacci number, with tests."
result = agent.run(task)
print(f"Agent finished with status: {result.get('exit_status')}")
print(f"Submission: {result.get('submission')}")
miniswe-agent --version
Debug
Known issues
breakingDependency `litellm` versions `1.82.7` and `1.82.8` were compromised. Update to a version that excludes these, or ensure your `litellm` installation is not one of these specific versions. The `mini-swe-agent` project has explicitly excluded these in its dependencies.fixUpgrade `mini-swe-agent` to `v2.2.8` or newer, which excludes compromised `litellm` versions. If managing `litellm` directly, ensure it's not `1.82.7` or `1.82.8`.
affects: litellm==1.82.7, litellm==1.82.8 (as a dependency)
gotchaThe `openai` dependency has specific versions (`1.100.0`, `1.100.1`) that are excluded due to known issues. Ensure your `openai` package is not one of these versions.fixUpgrade or downgrade `openai` to a version outside of `1.100.0` or `1.100.1`.
affects: openai==1.100.0, openai==1.100.1
gotchaOlder versions (pre-v2.2.5) could experience `FormatError`s, especially with weaker/smaller language models that make tool-calling mistakes, potentially hanging the agent.fixUpgrade to `mini-swe-agent` v2.2.5 or newer to benefit from bug fixes related to `FormatError` handling.
affects: <2.2.5
gotchaThe output format of trajectory files changed with v2.0 (from `trajectory_format: mini-swe-agent-1.0` to `mini-swe-agent-1.1`). If you have existing scripts or tools parsing v1 trajectory files, they will need updates.fixConsult the 'v2 migration guide' in the official documentation for details on the new output format, especially if parsing old trajectory files or comparing results across versions. Use the `inspector` for interactive browsing of new format files.
affects: >=2.0.0 (when interacting with v1 outputs)
gotchaIn versions prior to `v2.2.4`, invoking `mini` for the first time after installation and calling `setup` could lead to an exception due to a missing default model name, as the configuration wasn't reloaded correctly.fixUpgrade to `mini-swe-agent` v2.2.4 or newer to resolve the configuration reload issue after initial setup.
affects: <2.2.4
Errors
Common errors & fixes
AuthenticationError: litellm.AuthenticationError: geminiException - { "error": { "code": 400, "message": "API key not valid. Please pass a valid API key.", "status": "INVALID_ARGUMENT", ... } }
This error occurs when the API key provided for the language model (e.g., Gemini) is either incorrect, invalid, or missing, preventing successful authentication with the LiteLLM backend.
fixSet your API key using `mini-extra config set KEY VALUE` (e.g., `mini-extra config set GEMINI_API_KEY your_api_key_here`) or ensure the correct environment variable is set for your chosen model provider.
google.auth.exceptions.DefaultCredentialsError: Your default credentials were not found.
This issue typically arises when using a Google-provided model through LiteLLM without explicitly prefixing the model name with the provider (e.g., using `gemini-2.0-flash` instead of `gemini/gemini-2.0-flash`), causing LiteLLM to fall back to Google Cloud's default credentials which are often not configured.
fixEnsure you explicitly prefix your model name with the provider in your configuration (e.g., specify `gemini/gemini-2.0-flash` in your `model_name` field).
Exception: This model isn't mapped yet. model=... Add it here - https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json.
LiteLLM cannot calculate costs for the specified model because its pricing and context window information are not present in the LiteLLM model registry.
fixYou can either add the model's cost information to your local `litellm_model_registry` or configure LiteLLM to ignore cost calculation errors.
docker: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: ... permission denied.
The user attempting to run `mini-swe-agent` (or any Docker command) does not have sufficient permissions to access the Docker daemon socket, which is required for executing commands within Docker containers.
fixGrant the current user permission to access the Docker socket by running `sudo chmod 666 /var/run/docker.sock` or by adding your user to the `docker` Linux user group and restarting your session.
FormatError: LLM output wasn't properly formatted.
The language model's response did not adhere to the strict output format expected by `mini-swe-agent`, such as missing the `THOUGHT` section or providing an incorrect bash code block.
fixReview the prompt template and ensure the LLM is instructed to strictly follow the output format, including a `THOUGHT` section and exactly one bash code block in its response.
Upgrade
Version history
2.4.6latest on PyPI · released Jul 23, 2026
Audit
Dependencies
litellmrequiredUsed for model flexibility, supporting over 100 LLM providers. Specific versions (1.82.7, 1.82.8) were compromised and are excluded.
openairequiredDirect dependency, with specific problematic versions excluded.
pyyamlrequiredCore dependency for configuration.
richrequiredUsed for rich terminal output and interactive experience.