Skip to content

Yaml config files

Agent configuration files

  • You can configure the agent's behavior using YAML configuration files. This guide shows how to do that.
  • You should already be familiar with the quickstart guide.
  • For global environment settings (API keys, default model, etc., basically anything that can be set as environment variables), see global configuration.
  • Want more? See python bindings for subclassing & developing your own agent.

Overall structure

Configuration files look like this:

Configuration file 
agent:
  system_template: |
    You are a helpful assistant that can interact with a computer.

    Your response must contain exactly ONE bash code block with ONE command (or commands connected with && or ||).
    Include a THOUGHT section before your command where you explain your reasoning process.
    Format your response as shown in <format_example>.

    <format_example>
    Your reasoning and analysis here. Explain why you want to perform the action.

    ```bash
    your_command_here
    ```
    </format_example>

    Failure to follow these rules will cause your response to be rejected.
  instance_template: |
    Please solve this issue: {{task}}

    You can execute bash commands and edit files to implement the necessary changes.

    ## Recommended Workflow

    This workflows should be done step-by-step so that you can iterate on your changes and any possible problems.

    1. Analyze the codebase by finding and reading relevant files
    2. Create a script to reproduce the issue
    3. Edit the source code to resolve the issue
    4. Verify your fix works by running your script again
    5. Test edge cases to ensure your fix is robust
    6. Submit your changes and finish your work by issuing the following command: `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT`.
       Do not combine it with any other command. <important>After this command, you cannot continue working on this task.</important>

    ## Important Rules

    1. Every response must contain exactly one action
    2. The action must be enclosed in triple backticks
    3. Directory or environment variable changes are not persistent. Every action is executed in a new subshell.
       However, you can prefix any action with `MY_ENV_VAR=MY_VALUE cd /path/to/working/dir && ...` or write/load environment variables from files

    <system_information>
    {{system}} {{release}} {{version}} {{machine}}
    </system_information>

    ## Formatting your response

    Here is an example of a correct response:

    <example_response>
    THOUGHT: I need to understand the structure of the repository first. Let me check what files are in the current directory to get a better understanding of the codebase.

    ```bash
    ls -la
    ```
    </example_response>

    ## Useful command examples

    ### Create a new file:

    ```bash
    cat <<'EOF' > newfile.py
    import numpy as np
    hello = "world"
    print(hello)
    EOF
    ```

    ### Edit files with sed:

    {%- if system == "Darwin" -%}
    <important>
    You are on MacOS. For all the below examples, you need to use `sed -i ''` instead of `sed -i`.
    </important>
    {%- endif -%}

    ```bash
    # Replace all occurrences
    sed -i 's/old_string/new_string/g' filename.py

    # Replace only first occurrence
    sed -i 's/old_string/new_string/' filename.py

    # Replace first occurrence on line 1
    sed -i '1s/old_string/new_string/' filename.py

    # Replace all occurrences in lines 1-10
    sed -i '1,10s/old_string/new_string/g' filename.py
    ```

    ### View file content:

    ```bash
    # View specific lines with numbers
    nl -ba filename.py | sed -n '10,20p'
    ```

    ### Any other command you want to run

    ```bash
    anything
    ```
  action_observation_template: |
    <returncode>{{output.returncode}}</returncode>
    {% if output.output | length < 10000 -%}
    <output>
    {{ output.output -}}
    </output>
    {%- else -%}
    <warning>
    The output of your last command was too long.
    Please try a different command that produces less output.
    If you're looking at a file you can try use head, tail or sed to view a smaller number of lines selectively.
    If you're using grep or find and it produced too much output, you can use a more selective search pattern.
    If you really need to see something from the full command's output, you can redirect output to a file and then search in that file.
    </warning>
    {%- set elided_chars = output.output | length - 10000 -%}
    <output_head>
    {{ output.output[:5000] }}
    </output_head>
    <elided_chars>
    {{ elided_chars }} characters elided
    </elided_chars>
    <output_tail>
    {{ output.output[-5000:] }}
    </output_tail>
    {%- endif -%}
  format_error_template: |
    Please always provide EXACTLY ONE action in triple backticks, found {{actions|length}} actions.
    If you want to end the task, please issue the following command: `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT`
    without any other command.
    Else, please format your response exactly as follows:

    <response_example>
    Here are some thoughts about why you want to perform the action.

    ```bash
    <action>
    ```
    </response_example>

    Note: In rare cases, if you need to reference a similar format in your command, you might have
    to proceed in two steps, first writing TRIPLEBACKTICKSBASH, then replacing them with ```bash.
  step_limit: 0.
  cost_limit: 3.
  mode: confirm
environment:
  env:
    PAGER: cat
    MANPAGER: cat
    LESS: -R
    PIP_PROGRESS_BAR: 'off'
    TQDM_DISABLE: '1'
model:
  model_kwargs:
    drop_params: true

We use the following top-level keys:

  • agent: Agent configuration (prompt templates, cost limits etc.)
  • environment: Environment configuration (if you want to run in a docker container, etc.)
  • model: Model configuration (model name, reasoning strength, etc.)
  • run: Run configuration (output file, etc.)

Agent configuration

Different agent classes might have slightly different configuration options. You can find the full list of options in the API reference.

To use a different agent class, you can set the agent_class key to the name of the agent class you want to use or even to an import path (to use your own custom agent class even if it is not yet part of the mini-SWE-agent package).

Prompt templates

We use Jinja2 to render templates (e.g., the instance template).

TL;DR: You include variables with double (!) curly braces, e.g. {{task}} to include the task that was given to the agent.

However, you can also do fairly complicated logic like this directly from your template:

Example: Dealing with long observations

The following snippets shortens long observations and displays a warning if the output is too long.

<returncode>{{output.returncode}}</returncode>
{% if output.output | length < 10000 -%}
    <output>
        {{ output.output -}}
    </output>
{%- else -%}
    <warning>
        The output of your last command was too long.
        Please try a different command that produces less output.
        If you're looking at a file you can try use head, tail or sed to view a smaller number of lines selectively.
        If you're using grep or find and it produced too much output, you can use a more selective search pattern.
        If you really need to see something from the full command's output, you can redirect output to a file and then search in that file.
    </warning>

    {%- set elided_chars = output.output | length - 10000 -%}

    <output_head>
        {{ output.output[:5000] }}
    </output_head>

    <elided_chars>
        {{ elided_chars }} characters elided
    </elided_chars>

    <output_tail>
        {{ output.output[-5000:] }}
    </output_tail>
{%- endif -%}

In all builtin agents, you can use the following variables:

  • Environment variables (LocalEnvironment only, see discussion here)
  • Agent config variables (i.e., anything that was set in the agent section of the config file, e.g., step_limit, cost_limit, etc.)
  • Environment config variables (i.e., anything that was set in the environment section of the config file, e.g., cwd, timeout, etc.)
  • Variables passed to the run method of the agent (by default that's only task, but you can pass other variables if you want to)
  • Output of the last action execution (i.e., output from the execute_action method)

Custom Action Parsing

By default, mini-SWE-agent parses actions from markdown code blocks (```bash...```). You can customize this behavior by setting the action_regex field to support different formats like XML.

Important

If you set a custom action_regex (e.g. <action>(.*?)</action>), you must use the same output format across all prompt templates (system_template, instance_template, format_error_template, etc.), ensuring the LLM wraps commands accordingly. See the example below for a complete configuration.

Using XML format instead of markdown

This example uses the same structure as the default mini.yaml config, but with <action> tags instead of markdown code blocks:

agent:
  system_template: |
    You are a helpful assistant that can interact multiple times with a computer shell to solve programming tasks.
    Your response must contain exactly ONE bash code block with ONE command (or commands connected with && or ||).

    Include a THOUGHT section before your command where you explain your reasoning process.
    Format your response as shown in <format_example>.

    <format_example>
    THOUGHT: Your reasoning and analysis here

    <bash_code>your_command_here</bash_code>
    </format_example>

    Failure to follow these rules will cause your response to be rejected.
  instance_template: |
    <pr_description>
    Consider the following PR description:
    {{task}}
    </pr_description>

    <instructions>
    # Task Instructions

    ## Overview
    You're a software engineer interacting continuously with a computer by submitting commands.
    You'll be helping implement necessary changes to meet requirements in the PR description.
    Your task is specifically to make changes to non-test files in the current directory in order to fix the issue described in the PR description in a way that is general and consistent with the codebase.

    IMPORTANT: This is an interactive process where you will think and issue ONE command, see its result, then think and issue your next command.

    For each response:
    1. Include a THOUGHT section explaining your reasoning and what you're trying to accomplish
    2. Provide exactly ONE bash command to execute

    ## Important Boundaries
    - MODIFY: Regular source code files in /testbed (this is the working directory for all your subsequent commands)
    - DO NOT MODIFY: Tests, configuration files (pyproject.toml, setup.cfg, etc.)

    ## Recommended Workflow
    1. Analyze the codebase by finding and reading relevant files
    2. Create a script to reproduce the issue
    3. Edit the source code to resolve the issue
    4. Verify your fix works by running your script again
    5. Test edge cases to ensure your fix is robust

    ## Command Execution Rules
    You are operating in an environment where
    1. You write a single command
    2. The system executes that command in a subshell
    3. You see the result
    4. You write your next command

    Each response should include:
    1. A **THOUGHT** section where you explain your reasoning and plan
    2. A single bash code block with your command

    Format your responses like included within the <format_example> block:

    <format_example>
    THOUGHT: Here I explain my reasoning process, analysis of the current situation,
    and what I'm trying to accomplish with the command below.

    <bash_code>your_command_here </bash_code></format_example>

    **CRITICAL REQUIREMENTS:**
    - Your response SHOULD include a THOUGHT section explaining your reasoning
    - Your response MUST include EXACTLY ONE bash code block
    - This bash block MUST contain EXACTLY ONE command (or a set of commands connected with && or ||)
    - If you include zero or multiple bash blocks, or no command at all, YOUR RESPONSE WILL FAIL
    - Do NOT try to run multiple independent commands in separate blocks in one response
    - Directory or environment variable changes are not persistent. Every action is executed in a new subshell.
    - However, you can prefix any action with `MY_ENV_VAR=MY_VALUE cd /path/to/working/dir && ...` or write/load environment variables from files

    Example of a CORRECT response:

    <example_response>
    THOUGHT: I need to understand the structure of the repository first. Let me check what files are in the current directory to get a better understanding of the codebase.

    <bash_code>ls -la</bash_code>
    </example_response>

    Example of an INCORRECT response:

    <example_response>
    THOUGHT: I need to examine the codebase and then look at a specific file. I'll run multiple commands to do this.

    <bash_code>ls -la</bash_code>

    Now I'll read the file:

    <bash_code>cat file.txt</bash_code>
    </example_response>

    If you need to run multiple commands, either:

    1. Combine them in one block using && or ||

    <bash_code>command1 && command2 || echo "Error occurred"</bash_code>

    2. Wait for the first command to complete, see its output, then issue the next command in your following response.

    ## Environment Details

    - You have a full Linux shell environment
    - Always use non-interactive flags (-y, -f) for commands
    - Avoid interactive tools like vi, nano, or any that require user input
    - If a command isn't available, you can install it

    ## Useful Command Examples

    ### Create a new file:

    <bash_code>cat <<'EOF' > newfile.py
    import numpy as np
    hello = "world"
    print(hello)
    EOF</bash_code>

    ### Edit files with sed:

    Replace all occurrences

    <bash_code>sed -i 's/old_string/new_string/g' filename.py</bash_code>

    Replace only first occurrence

    <bash_code>sed -i 's/old_string/new_string/' filename.py</bash_code>

    Replace first occurrence on line 1

    <bash_code>sed -i '1s/old_string/new_string/' filename.py</bash_code>

    Replace all occurrences in lines 1-10

    <bash_code>sed -i '1,10s/old_string/new_string/g' filename.py</bash_code>

    ### View file content:

    View specific lines with numbers

    <bash_code> nl -ba filename.py | sed -n '10,20p'</bash_code>

    Any other command you want to run

    <bash_code>anything</bash_code>

    ## Submission

    When you've completed your work (reading, editing, testing), and cannot make further progress
    issue exactly the following command:

    <bash_code>echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT && git add -A && git diff --cached</bash_code>

    This command will submit your work.
    You cannot continue working (reading, editing, testing) in any way on this task after submitting.
    </instructions>
  action_observation_template: |
    <returncode>{{output.returncode}}</returncode>
    {% if output.output | length < 10000 -%}
    <output>
    {{ output.output -}}
    </output>
    {%- else -%}
    <warning>
    The output of your last command was too long.
    Please try a different command that produces less output.
    If you're looking at a file you can try use head, tail or sed to view a smaller number of lines selectively.
    If you're using grep or find and it produced too much output, you can use a more selective search pattern.
    If you really need to see something from the full command's output, you can redirect output to a file and then search in that file.
    </warning>
    {%- set elided_chars = output.output | length - 10000 -%}
    <output_head>
    {{ output.output[:5000] }}
    </output_head>
    <elided_chars>
    {{ elided_chars }} characters elided
    </elided_chars>
    <output_tail>
    {{ output.output[-5000:] }}
    </output_tail>
    {%- endif -%}
  format_error_template: |
    Please always provide EXACTLY ONE action in the `<bash_code>` block, found {{actions|length}} actions.

    Please format your action in a `<bash_code>` block as shown in <response_example>.

    <response_example>
    Here are some thoughts about why you want to perform the action.

    <bash_code>ls -la</bash_code>
    </response_example>

    If you have completed your assignment, please consult the first message about how to
    submit your solution (you will not be able to continue working on this task after that).
  step_limit: 250
  cost_limit: 3.
  action_regex: <bash_code>(.*?)</bash_code>

environment:
  cwd: "/testbed"
  timeout: 60
  env:
    PAGER: cat
    MANPAGER: cat
    LESS: -R
    PIP_PROGRESS_BAR: 'off'
    TQDM_DISABLE: '1'
  environment_class: docker

model:
  model_name: "minimax/minimax-m2"
  model_class: openrouter
  model_kwargs:
    temperature: 0.0

You can also directly load this config by specifying --config swebench_xml.

Default markdown format

This is the default configuration (already the default, you don't need to specify this):

agent:
  action_regex: ```bash\s*\n(.*?)\n```
  system_template: |
    Your response must contain exactly ONE bash code block.

    ```bash
    your_command_here
    ```

Linebreaks & escaping

When specifying action_regex from the yaml config file, make sure you understand how escaping in yaml files works. For example, when you use the | primitive, your regex might have a linbreak at the end which is probably not what you want. The best way is to keep your regex on a single line and NOT use any quotation marks around it. You do NOT need to escape any characters in the regex. Example: action_regex: <bash_code>(.*?)</bash_code>

Model configuration

See this guide for more details on model configuration.

Environment configuration

See this guide for more details on environment configuration.

Run configuration

See the information in "Usage".

bug_report Something broken/unclear?

Open an issue on GitHub!
help Open-ended discussions

Join our Slack!
Our projects
SWE-agent SWE-agent SWE-rex SWE-ReX SWE-smith SWE-smith SWE-bench SWE-bench CodeClash CodeClash sb-cli sb-cli