# v2.0 Migration Guide

!!! danger "Breaking Changes"

    **mini-swe-agent v2.0** brings major improvements but requires migration.

    To stay with v1.x, pin your dependency: `mini-swe-agent~=1.0`.

    See the [v1 documentation](https://mini-swe-agent.com/v1/) or the [v1 branch on GitHub](https://github.com/SWE-agent/mini-swe-agent/tree/v1).

## What's new

- **Tool calls**: Native tool calling API support (now the default)

- **Multimodal input**: Support for images and other content types

## What do I need to change?

> I only use the mini CLI with default configs

No changes needed.

> I use custom configs

You might need to move some config keys. See [Config changes](#config-changes).

> I parse/analyze trajectories

Some metadata fields moved to `extra`. See [Trajectory format](#trajectory-format).

> I use the python bindings or built custom subclasses

You will need to refactor. An agent can refactor your code based on the instructions below.

## Config changes

If you only changed `system_template` and `instance_template`, no changes needed.

**Move from `agent` to `model`:**

- `observation_template` (renamed from `action_observation_template`)

- `format_error_template`

- `action_regex` (only for text-based parsing)

**Removed:**

- `timeout_template`

**Code block format changed:**

Default action regex changed from `` ```bash `` to `` ```mswea_bash_command `` to avoid conflicts with bash examples in prompts.

**Completion signal changed:**

From `echo MINI_SWE_AGENT_FINAL_OUTPUT` to `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT`.

**New structure:**

```yaml

agent:

  system_template: "..."

  instance_template: "..."

  step_limit: 0

  cost_limit: 3.

environment:

  cwd: "..."

  timeout: 30

model:

  model_name: "..."

  observation_template: "..."

  format_error_template: "..."

```

**CLI now supports multiple configs and key-value overrides:**

```bash

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

```

!!! warning

    If you use `-c`, you will not load the full default config, so make sure to always specify your config file in addition to any overrides/updates.

## Tool calling

v2.0 uses native tool calling by default (instead of regex-based text parsing).

**What's the difference?**

- Tool calling (default): Model uses native tool calling API to invoke a "bash" tool

- Text-based (legacy): Model outputs commands in markdown code blocks (or similar), regex extracts them

**How to use it:**

Tool calling is the default. The CLI uses `mini.yaml` and `swebench.yaml` which are configured for tool calling.

```bash

# Default (tool calling)

mini

python -m minisweagent.run.benchmarks.swebench

mini-extra swebench

# Text-based parsing

mini-extra swebench -c swebench_backticks.yaml

mini -c mini_textbased.yaml

```

**For custom configs:**

```yaml

model:

  model_class: litellm  # tool calling (default)

  model_name: anthropic/claude-sonnet-4-5-20250929

# or for text-based:

model:

  model_class: litellm_textbased

  action_regex: "```mswea_bash_command\\s*\\n(.*?)\\n```"

```

## Trajectory format

- In v1, all messages in the trajectory's `messages` field were "hand-formatted", i.e., had a `content: str` and `role: str` field.

- **In v2, we use the model's native output as the basis for the message and only add the `extra` field to it**.

If you use a model that uses the standard `/completion` endpoint, then you will still always have a `content: str` and `role: str` field.

However, if you use the [`/response`](https://platform.openai.com/docs/api-reference/responses) endpoint, then things might look different.

In other words: the exact message structure depends on the model you use.

* Advantage: Any model message structure is supported

* Disadvantage: If you parse trajectories, you might need to adapt to the message structure of the model you use.

## Removed & renamed

**Removed features:**

- **"Visual" UI**: The `-v` flag for the alternate, textual based `mini -v` CLI is no longer supported. This was a tough decision to make, but in the end the visual mode didn't see the adoption we wanted and is significantly more complex to maintain than the default interface.

- **Rotating API keys**: `ANTHROPIC_API_KEYS` with `::` separator no longer supported. Use single `ANTHROPIC_API_KEY`.

- **`github_issue` run script**: The dedicated `github_issue.py` run script was removed. Use the `mini` CLI instead.

- **`MSWEA_MODEL_API_KEY` environment variable**: No longer used to override API keys.

**Removed model classes:**

- **`anthropic` model class**: Removed. Use `litellm` model class for Anthropic models (make sure that cache control is enabled).

**Renamed model classes:**

| v1 name | v2 name |

|---------|---------|

| `litellm_response_api` | `litellm_response` |

| `portkey_response_api` | `portkey_response` |

**New model classes:**

| Name | Description |

|------|-------------|

| `litellm_textbased` | Text-based parsing (regex) instead of tool calls |

| `openrouter_textbased` | Text-based parsing for OpenRouter |

| `openrouter_response` | OpenRouter with response API |

**New environment:**

- **`swerex_modal`**: Run environments on Modal (requires `pip install mini-swe-agent[modal]`)

## Architecture changes

1. **Responsibility shift**: Models now parse actions and format observations. This enables switching between tool calls and text parsing by changing model classes. The Agent class is now a simpler coordinator.

2. **Stateless models**: Cost tracking moved to Agent. The `cost` and `n_calls` attributes were removed from the Model protocol.

3. **Pydantic configs**: `AgentConfig` (and other configs) changed from `dataclass` to Pydantic `BaseModel`. This requires `pydantic >= 2.0`.

4. **New protocol methods**: All classes implement `get_template_vars()` and `serialize()` instead of requiring specific attributes.

### Protocol changes

If you want to write a custom Model, Environment or Agent compatible with `mini-swe-agent`, you don't need to subclass anything.

Rather, mini-swe-agent fully uses duck typing with [protocols](https://typing.python.org/en/latest/spec/protocol.html)

(tl;dr: as long as you implement the required methods, you can use any class as a Model, Environment or Agent).

Config options like `--config-class` also take full import classes, so you can put your classes wherever you want.

**Model protocol:**

```python

# 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:**

```python

# 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:**

```python

# Removed attributes (you don't need to implement these anymore, but you can)

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 changes

All flow control exceptions now inherit from `InterruptAgentFlow` and moved to `minisweagent.exceptions`:

```python

InterruptAgentFlow (base)

├── Submitted (task completed)

├── LimitsExceeded (cost/step limit)

├── FormatError (invalid model output)

└── UserInterruption (user cancelled)  # new

```

**Removed exception classes:**

- `NonTerminatingException` - use `InterruptAgentFlow` base class

- `TerminatingException` - use `InterruptAgentFlow` base class

- `ExecutionTimeoutError` - removed (no longer used)

```python

# Old

from minisweagent.agents.default import Submitted, FormatError

# New

from minisweagent.exceptions import Submitted, FormatError

```

### Agent.run() return value

```python

# Old (v1)

submission, exit_status = agent.run(task)  # tuple[str, str]

# New (v2)

result = agent.run(task)  # dict

submission = result["submission"]

exit_status = result["exit_status"]

```

The `run()` method returns the `extra` dict from the final exit message. For full trajectory data, use `agent.save(path)` or `agent.serialize()`.