Yaml config files

Agent configuration files

This guide shows how to configure agent behavior using YAML configuration files.
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 the cookbook 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}} {{processor}}
    </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:
    temperature: 0.0
    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}}, but you can also do fairly complicated logic like this:

Example: Dealing with long observations

<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
Environment config variables
Explicitly passed variables (observation, task etc.) depending on the template

bug_report Something broken/unclear?

Open an issue on GitHub!

help Open-ended discussions

Join our Slack!

Our projects