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 ships two agent classes that share a common foundation. DefaultAgent implements the fully-automated run loop — it initialises the conversation, calls the model in a loop, executes shell actions, and saves a trajectory file when done. InteractiveAgent extends DefaultAgent with a human-in-the-loop layer: it can confirm actions before running them, accept direct user commands, and let you steer the session at any point without restarting. Both classes accept the same constructor signature. All configuration fields are passed as keyword arguments and validated by the underlying Pydantic config model.

​
DefaultAgent

from minisweagent.agents.default import DefaultAgent, AgentConfig

​
Constructor

DefaultAgent(model: Model, env: Environment, *, config_class: type = AgentConfig, **kwargs)
model and env are required positional arguments. All remaining keyword arguments are forwarded to config_class for validation. You can supply a custom config class (a AgentConfig subclass) via config_class if you need extra fields.

​
AgentConfig fields

AgentConfig is a Pydantic BaseModel. All fields may be set via keyword arguments to the constructor or through a YAML config file.
​
system_template
str
required
Jinja2 template string for the system message — the very first message in the conversation. Template variables are populated via get_template_vars(), which merges config, environment, model, and runtime state (step count, cost, elapsed time).
​
instance_template
str
required
Jinja2 template string for the first user message, which presents the task to the model. The task variable is available here (passed to run()).
​
step_limit
int
default:"0"
Maximum number of model calls the agent is allowed to make. 0 means no limit. When the limit is reached the agent raises LimitsExceeded and exits with exit_status: "LimitsExceeded".
​
cost_limit
float
default:"3.0"
Stop the agent after its accumulated API cost exceeds this value (in USD). Checked before every model call. Set to 0 to disable.
​
wall_time_limit_seconds
int
default:"0"
Stop the agent after this many seconds of wall-clock time. 0 means no limit. When exceeded the agent raises TimeExceeded and exits with exit_status: "TimeExceeded".
​
output_path
Path | None
default:"None"
If set, the full trajectory (messages, config, cost stats) is written to this path as JSON after every step. Parent directories are created automatically.

​
Public methods

MethodSignatureDescription
runrun(task: str = "", **kwargs) -> dictInitialise messages, then call step() in a loop until the last message has role == "exit". Returns the extra dict of that final message.
stepstep() -> list[dict]Single agent step: calls query() then execute_actions(). Returns the list of new observation messages.
queryquery() -> dictCheck limits, call model.query(), accumulate cost. Returns the model’s message dict.
execute_actionsexecute_actions(message: dict) -> list[dict]Run every action in message["extra"]["actions"] through the environment, format observations, and append them to self.messages.
serializeserialize(*extra_dicts) -> dictReturn a JSON-serialisable dict with messages, config, cost stats, and trajectory format version. Additional dicts are recursively merged in.
savesave(path: Path | None, *extra_dicts) -> dictSerialise and, if path is given, write to disk. Returns the serialised data.

​
Return value of run()

run() returns the extra dict attached to the final exit message. It always contains at least: 
{
    "exit_status": str,   # e.g. "Submitted", "LimitsExceeded", "TimeExceeded", or an exception class name
    "submission": str,    # the agent's final answer / patch (empty string if not submitted cleanly)
}

​
Example usage

from minisweagent.agents.default import DefaultAgent
from minisweagent.models import get_model
from minisweagent.environments.local import LocalEnvironment

model = get_model("anthropic/claude-opus-4-5")
env = LocalEnvironment(cwd="/repo")
agent = DefaultAgent(
    model,
    env,
    system_template="You are a helpful coding agent...",
    instance_template="Please fix the following issue:\n{{ task }}",
    cost_limit=2.0,
    step_limit=30,
    output_path="trajectory.json",
)
result = agent.run(task="Fix the failing test in tests/test_foo.py")
print(result["exit_status"])   # "Submitted"
print(result["submission"])    # the model's final answer

​
InteractiveAgent

from minisweagent.agents.interactive import InteractiveAgent, InteractiveAgentConfig
InteractiveAgent is a direct subclass of DefaultAgent. It overrides add_messages, query, step, and execute_actions to print agent output to the terminal, optionally prompt the user before executing commands, and handle keyboard interruptions gracefully.

​
InteractiveAgentConfig fields

InteractiveAgentConfig extends AgentConfig with the following additional fields:
​
mode
Literal['human', 'confirm', 'yolo']
default:"\"confirm\""
Controls how the agent handles action execution:
  • "confirm" — prompt the user before running any LM-issued command that is not on the whitelist.
  • "yolo" — run all LM-issued commands immediately without confirmation.
  • "human" — the user types commands directly; the LM does not issue its own commands until the mode is switched.
The mode can be changed at runtime using the /c, /y, /u slash commands in the terminal prompt.
​
whitelist_actions
list[str]
default:"[]"
List of regular expression strings. Commands that match any pattern are executed without prompting, even in "confirm" mode.
​
confirm_exit
bool
default:"true"
When true, the agent asks the user for confirmation before submitting and exiting. The user can type a follow-up task to continue the session instead of quitting.

​
Slash commands (runtime)

While the agent is running, the following slash commands are accepted at any prompt:
CommandEffect
/ySwitch to yolo mode
/cSwitch to confirm mode
/uSwitch to human mode
/mEnter a multiline comment
/hPrint available commands

​
Example usage

from minisweagent.agents.interactive import InteractiveAgent
from minisweagent.models import get_model
from minisweagent.environments.local import LocalEnvironment

model = get_model("anthropic/claude-opus-4-5")
env = LocalEnvironment(cwd="/repo")
agent = InteractiveAgent(
    model,
    env,
    system_template="You are a helpful coding agent...",
    instance_template="Please fix: {{ task }}",
    mode="confirm",
    whitelist_actions=[r"^cat\s", r"^ls\s"],
    confirm_exit=True,
)
result = agent.run(task="Investigate the failing CI job")

Build docs developers (and LLMs) love

Get started for freeTalk to us