Skip to content

SWE-agent takes a GitHub issue and tries to automatically fix it, using your LM of choice. It can also be employed for offensive cybersecurity or competitive coding challenges. [NeurIPS 2024]

Doc: Add tutorial on adding new tools (#1226)

Kilian Lieretd747e5360432
diff --git a/docs/index.md b/docs/index.md
index 3a1fe9c3..9a4bcb4b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -76,5 +76,6 @@ SWE-agent is built and maintained by researchers from Princeton University and S
## ✍️ Doc updates
+* June 26: [Adding custom tools](usage/adding_custom_tools.md)
* Apr 8: [Running SWE-agent competitively](usage/competitive_runs.md)
* Mar 7: [Updated SWE-agent architecture diagram of 1.0](background/architecture.md)
\ No newline at end of file
diff --git a/docs/usage/adding_custom_tools.md b/docs/usage/adding_custom_tools.md
new file mode 100644
index 00000000..0b47e54e
--- /dev/null
+++ b/docs/usage/adding_custom_tools.md
@@ -0,0 +1,306 @@
+# Adding Custom Tools
+
+!!! abstract "Adding custom tools to SWE-agent"
+ This tutorial walks you through creating and integrating custom tools into SWE-agent.
+ We'll create a fun `print_cat` command that prints ASCII art of a cat for morale boost!
+
+ Please read our [hello world](hello_world.md) and [command line basics](cl_tutorial.md) tutorials before proceeding.
+
+## Understanding Tool Structure
+
+Every SWE-agent tool is organized as a "bundle" - a directory containing:
+
+1. **`config.yaml`** - Defines the tool's interface and documentation
+2. **`bin/`** directory - Contains the executable scripts
+3. **`install.sh`** (optional) - Sets up dependencies
+4. **`lib/`** (optional) - Contains shared libraries or utilities
+
+Let's look at the simple `submit` tool structure:
+
+```
+tools/submit/
+├── config.yaml
+└── bin/
+ └── submit
+```
+
+## Step 1: Write the Command Script
+
+First, let's create our `morale_boost` tool bundle:
+
+```bash
+mkdir -p tools/morale_boost/bin
+```
+
+Create the executable script that will be called when the agent runs your command:
+
+```bash title="tools/morale_boost/bin/print_cat"
+#!/bin/bash
+
+# print_cat - A morale-boosting ASCII cat printer!
+
+echo "🐱 Here's a cat to boost your morale! 🐱"
+echo ""
+cat << 'EOF'
+ /\_/\
+( o.o )
+ > ^ <
+ _) (_
+(_____)
+EOF
+echo ""
+echo "You're doing great! Keep coding! 💪"
+```
+
+If you're wondering about the strange `EOF` construct, those are called
+[heredocs](https://linuxize.com/post/bash-heredoc/) and enable multiline
+arguments in bash.
+
+## Step 2: Define the Tool Configuration
+
+Create the `config.yaml` file that tells SWE-agent about your tool:
+
+```yaml title="tools/morale_boost/config.yaml"
+tools:
+ print_cat:
+ signature: "print_cat"
+ docstring: "Prints an ASCII art cat for morale boost. Use when you need encouragement!"
+ arguments: []
+```
+
+!!! tip "Tool Configuration Options"
+
+ The `config.yaml` supports various options:
+
+ - **`signature`**: How the command should be called (including arguments)
+ - **`docstring`**: Description that helps the AI understand when to use this tool
+ - **`arguments`**: List of arguments with types, descriptions, and whether they're required
+
+For a tool with arguments, it would look like this:
+
+```yaml title="Example with arguments"
+tools:
+ print_animal:
+ signature: "print_animal <animal_type> [--size=<size>]"
+ docstring: "Prints ASCII art of the specified animal"
+ arguments:
+ - name: animal_type
+ type: string
+ description: "Type of animal to print (cat, dog, elephant)"
+ required: true
+ - name: size
+ type: string
+ description: "Size of the art (small, medium, large)"
+ required: false
+```
+
+## Step 3: Tell the agent to use the new tool
+
+Now you need to tell SWE-agent to use your new tool. Copy `config/default.yaml` to `config/my_custom_config.yaml`
+and make the following modification
+
+```yaml title="config/my_custom_config.yaml"
+agent:
+ templates:
+ instance_template: |-
+ (...)
+
+ Don't forget to use `print_cat` when you need encouragement!
+
+ Your thinking should be thorough and so it's fine if it's very long.
+ bundles:
+ - path: tools/registry
+ - path: tools/edit_anthropic
+ - path: tools/review_on_submit_m
+ - path: tools/morale_boost # Add our custom tool bundle!
+ # everything else stays the same
+```
+
+## Step 4: Let's test it
+
+Now you can test your tool by running SWE-agent with your custom configuration:
+
+```bash
+sweagent run \
+ --config config/my_custom_config.yaml \
+ --agent.model.name=gpt-4o \
+ --env.repo.github_url=https://github.com/SWE-agent/test-repo \
+ --problem_statement.text="Add a simple hello world function to the repository. Feel free to use print_cat for morale!"
+```
+
+The agent should now have access to your `print_cat` command and may use it during execution!
+
+## Advanced Tool Features
+
+### Multiple Commands in One Bundle
+
+You can define multiple commands in a single tool bundle:
+
+```yaml title="tools/morale_boost/config.yaml - Extended version"
+tools:
+ print_cat:
+ signature: "print_cat"
+ docstring: "Prints an ASCII art cat for morale boost"
+ arguments: []
+ print_dog:
+ signature: "print_dog"
+ docstring: "Prints an ASCII art dog for variety"
+ arguments: []
+ motivate:
+ signature: "motivate <message>"
+ docstring: "Prints a motivational message with ASCII art"
+ arguments:
+ - name: message
+ type: string
+ description: "The motivational message to display"
+ required: true
+```
+
+Don't forget to create the corresponding scripts in the `bin/` directory!
+
+### Using Python Libraries
+
+If you prefer Python, you can create Python-based tools:
+
+```python title="tools/morale_boost/bin/print_cat"
+#!/usr/bin/env python3
+"""
+A morale-boosting cat printer in Python!
+"""
+
+print("🐱 Here's a cat to boost your morale! 🐱")
+```
+
+If your Python tool needs additional dependencies, create an `install.sh` script:
+
+```bash title="tools/morale_boost/install.sh"
+#!/bin/bash
+# This script runs when the tool bundle is installed
+
+# Example: Install Python packages
+pip install cowsay
+pip install colorama
+
+echo "Morale boost tools installed! Ready to spread joy! 🎉"
+```
+
+### Environment Variables and Context
+
+Your tools can access environment variables and the current working context:
+
+```bash title="Example using environment variables"
+#!/bin/bash
+
+echo "Current working directory: $PWD"
+echo "Repository root: $ROOT"
+echo "My custom variable: $MY_CUSTOM_VAR"
+```
+
+Adding environment variables in your config file can be a simple way of customizing your tools
+
+```yaml title="config/my_custom_config.yaml"
+agent:
+ tools:
+ env_variables:
+ PAGER: cat
+ MY_CUSTOM_VAR: "Hello from config!"
+ DEBUG_MODE: "true"
+ # ... rest of config
+```
+
+For sensitive data like API keys, you can propagate environment variables from your host system:
+
+```yaml title="config/my_custom_config.yaml"
+agent:
+ tools:
+ propagate_env_variables:
+ - "OPENAI_API_KEY"
+ - "GITHUB_TOKEN"
+ - "MY_SECRET_KEY"
+ # ... rest of config
+```
+
+Your tools can then access these variables:
+
+```bash title="tools/morale_boost/bin/print_cat_with_api"
+#!/bin/bash
+
+if [ -n "$GITHUB_TOKEN" ]; then
+ echo "🐱 Connected to GitHub! Ready to boost morale across repos!"
+else
+ echo "🐱 Just a local morale booster today!"
+fi
+```
+
+However, we mostly recommend to use the python bindings of the `registry` bundle for keeping internal
+state (instead of using environment variables).
+
+### Using the Registry Bundle
+
+The registry bundle provides a persistent key-value store that survives across tool calls. This is better than environment variables because
+you can store complex data structures (lists, dictionaries) as JSON.
+
+**Setting registry variables in your config:**
+
+```yaml title="config/my_custom_config.yaml"
+agent:
+ tools:
+ registry_variables:
+ MY_CUSTOM_SETTING: "hello world"
+ MORALE_MESSAGES:
+ - "You're doing great!"
+ - "Keep up the good work!"
+ - "Almost there!"
+ DEBUG_MODE: true
+ bundles:
+ - path: tools/registry # Always include this first!
+ - path: tools/morale_boost
+```
+
+**Accessing registry variables in your Python tools:**
+
+```python title="tools/morale_boost/bin/print_motivational_cat"
+#!/usr/bin/env python3
+
+from registry import registry
+
+def main():
+ # Get a simple value with a fallback
+ setting = registry.get("MY_CUSTOM_SETTING", "default value")
+ print(f"Setting: {setting}")
+
+ # Get a list of messages
+ messages = registry.get("MORALE_MESSAGES", [])
+ if messages:
+ import random
+ message = random.choice(messages)
+ print(f"🐱 {message}")
+
+ # Set a value (persists across tool calls)
+ registry["LAST_MORALE_BOOST"] = "2024-01-15 10:30:00"
+
+ print("Morale boosted! 🚀")
+
+if __name__ == "__main__":
+ main()
+```
+
+**Accessing registry variables in bash tools:**
+
+```bash title="tools/morale_boost/bin/print_simple_cat"
+#!/bin/bash
+
+# Read from registry using the _read_env helper
+CUSTOM_SETTING=$(_read_env "MY_CUSTOM_SETTING" "default value")
+DEBUG_MODE=$(_read_env "DEBUG_MODE" "false")
+
+echo "🐱 Custom setting: $CUSTOM_SETTING"
+
+if [ "$DEBUG_MODE" = "true" ]; then
+ echo "Debug mode is enabled!"
+fi
+```
+
+The registry is particularly useful for complex tools that need to maintain state across multiple invocations, like the `review_on_submit_m` tool that tracks submission stages.
+
+{% include-markdown "../_footer.md" %}
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index d8b1e4d6..fc9b996c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -72,6 +72,7 @@ nav:
- "Trajectory inspector": "usage/inspector.md"
- "Batch mode": "usage/batch_mode.md"
- "Competitive runs": "usage/competitive_runs.md"
+ - "Adding custom tools": "usage/adding_custom_tools.md"
- "What's next?": "usage/whats_next.md"
- "FAQ": "faq.md"
- User Guides:
diff --git a/mlc_config.json b/mlc_config.json
index ed2d628c..4573f97e 100644
--- a/mlc_config.json
+++ b/mlc_config.json
@@ -17,6 +17,9 @@
},
{
"pattern": "https?://(.*\\.)?x\\.com/.*"
+ },
+ {
+ "pattern": "https://linuxize.com/post/bash-heredoc/"
}
]
}