Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/swe-agent/mini-swe-agent/llms.txt

Use this file to discover all available pages before exploring further.

mini-swe-agent v2.0 brings native tool calling, multimodal input support, and a cleaner architecture where models own action parsing and observation formatting. Most of these improvements required breaking changes to the config format, Python APIs, and trajectory structure. This guide covers every change you need to make.
If you want to stay on v1.x, pin your dependency: mini-swe-agent~=1.0. The v1 documentation and v1 branch on GitHub remain available.

​
What changed at a glance

AreaImpact
CLI with default configsNo changes needed
Custom YAML configsConfig keys moved; see Config changes
Trajectory parsingSome metadata moved to extra; see Trajectory format
Python bindings / subclassesRefactoring required; see Architecture changes

​
Config changes

If you only customised system_template and instance_template, no changes are needed.
Several config keys have moved from the agent section to the model section.
Keys moved from agent to model:
  • observation_template (also renamed from action_observation_template)
  • format_error_template
  • action_regex (text-based parsing only)
Key removed:
  • timeout_template
New config structure: 
# v2
agent:
  system_template: "..."
  instance_template: "..."
  step_limit: 0
  cost_limit: 3.0
environment:
  cwd: "..."
  timeout: 30
model:
  model_name: "..."
  observation_template: "..."
  format_error_template: "..."
Code block language tag changed: The default action regex changed from ```bash to ```mswea_bash_command to avoid false matches against bash examples in prompts. Update any custom prompt templates or action_regex values accordingly. Completion signal changed:
The magic string the agent uses to detect task completion has changed. Update any custom environment scripts or prompt templates.
# v1
echo MINI_SWE_AGENT_FINAL_OUTPUT

# v2
echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT
Multiple configs and key-value overrides via CLI: 
mini -c mini.yaml -c model.model_kwargs.temperature=0.5
mini -c swebench.yaml -c agent.step_limit=100
mini -c mini.yaml -c /path/to/model.yaml
When you pass -c, the full default config is not loaded automatically. Always specify your base config file alongside any overrides.

​
Migration steps

1

Update your config files

Move observation_template, format_error_template, and action_regex from the agent section to the model section. Remove timeout_template. Rename action_observation_template to observation_template.
2

Update the completion signal

Replace every occurrence of MINI_SWE_AGENT_FINAL_OUTPUT with COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT in your prompt templates and custom environment scripts.
3

Update the action code block tag

If you use text-based parsing, update any action_regex patterns and prompt templates that expect ```bash to use ```mswea_bash_command instead (or set action_regex explicitly).
4

Switch model class

Tool calling is now the default. If you were using the anthropic model class (removed in v2), switch to litellm. If you were using litellm_response_api or portkey_response_api, rename them — see the table in Removed & renamed.
5

Update Python imports for exceptions

Move all exception imports from minisweagent.agents.default to minisweagent.exceptions.
# v1
from minisweagent.agents.default import Submitted, FormatError

# v2
from minisweagent.exceptions import Submitted, FormatError
6

Update Agent.run() call sites

run() now returns a dict instead of a tuple[str, str].
# v1
submission, exit_status = agent.run(task)

# v2
result = agent.run(task)
submission = result["submission"]
exit_status = result["exit_status"]
7

Update trajectory parsing code

Metadata fields that were top-level message attributes in v1 have moved into the extra field in v2. The exact message structure now mirrors the model’s native output. See Trajectory format for details.
8

Refactor custom Model / Environment / Agent subclasses

Review the updated protocol signatures in Architecture changes and update method signatures, removed attributes, and new required methods.

​
Tool calling

v2.0 uses native tool calling by default instead of regex-based text parsing.
ModeHow it works
Tool calling (default)Model invokes a native “bash” tool via the tool-calling API
Text-based (legacy)Model outputs commands in markdown code blocks; regex extracts them
# Default (tool calling)
mini
python -m minisweagent.run.benchmarks.swebench

# Text-based parsing
mini -c mini_textbased.yaml
mini-extra swebench -c swebench_backticks.yaml
For custom configs: 
# Tool calling (default)
model:
  model_class: litellm
  model_name: anthropic/claude-sonnet-4-5-20250929

# Text-based parsing
model:
  model_class: litellm_textbased
  action_regex: "```mswea_bash_command\\s*\\n(.*?)\\n```"

​
Trajectory format

The trajectory message structure changed. v2 uses the model’s native output as the basis for each message and appends an extra field rather than reformatting everything into a uniform {role, content} shape.
  • v1: All messages had content: str and role: str.
  • v2: Messages reflect the model’s native output. For standard /completion endpoints this is still {role, content}, but for the OpenAI /response endpoint the shape may differ.
This means trajectory-parsing code that assumed a fixed message shape may need to be adapted per model.

​
Removed & renamed

Removed features:
The following features are gone in v2 with no direct replacement.
  • Visual UI (mini -v): The alternate textual UI has been removed.
  • Rotating API keys: ANTHROPIC_API_KEYS with :: separator is no longer supported. Use a single ANTHROPIC_API_KEY.
  • github_issue run script: Use the mini CLI instead.
  • MSWEA_MODEL_API_KEY environment variable: No longer used to override API keys.
Removed model classes:
  • anthropic — use litellm for Anthropic models (enable cache control in your config).
Renamed model classes:
v1 namev2 name
litellm_response_apilitellm_response
portkey_response_apiportkey_response
New model classes in v2:
NameDescription
litellm_textbasedText-based parsing (regex) instead of tool calls
openrouter_textbasedText-based parsing for OpenRouter
openrouter_responseOpenRouter with response API
New environment:
  • swerex_modal — run environments on Modal (requires pip install mini-swe-agent[modal]).
Removed exception classes:
v1v2 replacement
NonTerminatingExceptionInterruptAgentFlow base class
TerminatingExceptionInterruptAgentFlow base class
ExecutionTimeoutErrorRemoved (no longer used)

​
Architecture changes

​
Responsibility shift

In v2, models own action parsing and observation formatting. This is what enables switching between tool calling and text-based parsing simply by changing the model_class config value. The Agent class is now a simpler coordinator.

​
Pydantic configs

AgentConfig (and other config classes) changed from dataclass to Pydantic BaseModel. This requires pydantic >= 2.0.

​
Stateless models

Cost tracking moved from Model to Agent. The cost and n_calls attributes were removed from the Model protocol.

​
Protocol changes

mini-swe-agent uses duck typing with protocols — you do not need to subclass anything; you only need to implement the required methods. Model protocol — changes: 
# Removed attributes
cost: float      # moved to Agent
n_calls: int     # moved to Agent

# New methods
def format_message(self, **kwargs) -> dict: ...
def format_observation_messages(self, message: dict, outputs: list[dict], template_vars: dict | None = None) -> list[dict]: ...
def serialize(self) -> dict: ...
Environment protocol — changes: 
# Changed signature
def execute(self, action: dict, cwd: str = "") -> dict[str, Any]: ...
# was: (command: str) -> dict[str, str]

# New method
def serialize(self) -> dict: ...
Agent protocol — changes: 
# Removed attributes (optional to implement)
model: Model
env: Environment
messages: list[dict]

# Changed return type
def run(self, task: str, **kwargs) -> dict: ...
# was: tuple[str, str]

# New method
def save(self, path: Path | None, *extra_dicts) -> dict: ...

​
Exception hierarchy

All flow control exceptions now inherit from InterruptAgentFlow and live in minisweagent.exceptions: 
InterruptAgentFlow        # base
├── Submitted             # task completed successfully
├── LimitsExceeded        # cost or step limit hit
├── FormatError           # invalid model output
└── UserInterruption      # user cancelled (new in v2)

Build docs developers (and LLMs) love

Get started for freeTalk to us