SWE-agent 配置系统完全指南从 YAML 基础到多模态实战【免费下载链接】SWE-agentSWE-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]项目地址: https://gitcode.com/GitHub_Trending/sw/SWE-agent导读SWE-agent 是一款接收 GitHub Issue 并自动修复代码的 AI 编程智能体其行为高度可定制一切交互能力都由.yaml配置文件驱动。本文以 docs/config/index.md 为骨架系统讲解 SWE-agent 配置文件的组织方式、--config命令行用法、默认配置详解、五大可配置领域工具、提示词模板、演示轨迹、模型行为、输入输出接口并深入多模态配置与 Docker 环境配置。读完本文你将能独立编写、合并、调试自己的配置文件把 SWE-agent 接入任意模型、任意代码库与任意任务类型。一、配置系统的核心概念在 SWE-agent 中配置Configuration由一个或多个.yaml文件表示通过命令行界面的--config标志指定详见 命令行教程。配置文件决定了一台智能体如何与SWEEnv环境交互具体可以控制以下五件事定义 Agent 可用于遍历和修改代码库的工具tools详见 工具配置编写在单条轨迹trajectory过程中确定性/条件性展示给 Agent 的提示词prompts详见 模板配置使用演示轨迹demonstrations引导 Agent 行为详见 演示配置改变 Agent 的模型行为model behavior详见 模型配置控制Agent 与环境之间的输入/输出接口。这种设计将智能体策略与环境执行彻底解耦同一份环境代码可以搭配完全不同的工具集、提示词与模型快速做策略对比实验。官方默认配置文件位于仓库根目录的config/目录下。仓库自带的 config/README.md 给出了分类说明sweagent_0_7/是论文时代0.7 版本的配置、exotic/是各种特殊场景配置、human/是不依赖 LM 的调试配置、demo/用于演示讲解。二、如何使用配置文件--config 标志与多配置合并基本用法在 命令行教程 描述的 CLI 中通过--config标志指定配置文件# 单次运行解决一个任务实例 sweagent run --config config/your_config.yaml # 批量运行在 benchmark 数据集上跑批 sweagent run-batch --config config/your_config.yaml多个配置文件的合并也可以一次性传入多个配置文件注意--config需要重复书写sweagent run --config config/default.yaml --config my_config.yaml多个配置文件按嵌套方式nested way合并后一个文件中的键值会覆盖前一个文件中对应位置的键值而未冲突的部分则逐层叠加。这意味着你可以在基础配置之上叠加增量补丁式的定制配置而无需复制整份文件。默认配置 default.yaml当不提供任何--config标志时SWE-agent 会加载默认配置config/default.yaml。其完整内容如下该文件已注明灵感源自 Anthropic 的 computer use 演示但可搭配任意 LM 使用agent: templates: system_template: |- You are a helpful assistant that can interact with a computer to solve tasks. instance_template: |- uploaded_files {{working_dir}} /uploaded_files Ive uploaded a python code repository in the directory {{working_dir}}. Consider the following PR description: pr_description {{problem_statement}} /pr_description Can you help me implement the necessary changes to the repository so that the requirements specified in the pr_description are met? Ive already taken care of all changes to any of the test files described in the pr_description. This means you DONT have to modify the testing logic or any of the tests in any way! Your task is to make the minimal changes to non-tests files in the {{working_dir}} directory to ensure the pr_description is satisfied. Follow these steps to resolve the issue: 1. As a first step, it might be a good idea to find and read code relevant to the pr_description 2. Create a script to reproduce the error and execute it with python filename.py using the bash tool, to confirm the error 3. Edit the sourcecode of the repo to resolve the issue 4. Rerun your reproduce script and confirm that the error is fixed! 5. Think about edgecases and make sure your fix handles them as well Your thinking should be thorough and so its fine if its very long. next_step_template: |- OBSERVATION: {{observation}} next_step_no_output_template: |- Your command ran successfully and did not produce any output. tools: env_variables: PAGER: cat MANPAGER: cat LESS: -R PIP_PROGRESS_BAR: off TQDM_DISABLE: 1 GIT_PAGER: cat bundles: - path: tools/registry - path: tools/edit_anthropic - path: tools/review_on_submit_m registry_variables: USE_FILEMAP: true SUBMIT_REVIEW_MESSAGES: - | Thank you for your work on this issue. Please carefully follow the steps below to help review your changes. 1. If you made any changes to your code after running the reproduction script, please run the reproduction script again. If the reproduction script is failing, please revisit your changes and make sure they are correct. If you have already removed your reproduction script, please ignore this step. 2. Remove your reproduction script (if you havent done so already). 3. If you have modified any TEST files, please revert them to the state they had before you started fixing the issue. You can do this with git checkout -- /path/to/test/file.py. Use below diff to find the files you need to revert. 4. Run the submit command again to confirm. Here is a list of all of your changes: diff {{diff}} /diff enable_bash_tool: true parse_function: type: function_calling history_processors: - type: cache_control last_n_messages: 2相对路径的解析规则配置文件中的相对路径会按以下优先级解析先尝试SWE_AGENT_CONFIG_ROOT环境变量若已设置否则回退到 SWE-agent 仓库根目录。例如tools下的 bundle 路径tools/edit_anthropic在设置SWE_AGENT_CONFIG_ROOT/a/b/c后会解析为/a/b/c/tools/edit_anthropic详见 环境变量文档。三、配置的五大能力领域1. 工具配置Tool Bundles 机制工具是配置和扩展 Agent 能力最直接的方式。典型的工具集包括让 Agent 执行 shell 命令的bash 工具可调用 python 脚本、用于检查代码的文件查看器、以及基于查找替换或行号范围的代码编辑器。SWE-agent 将工具组织为工具包tool bundle。每个 bundle 是一个文件夹标准结构如下bundle/ ├── bin/ │ └── tool executable │ └── state executable ├── config.yaml ├── install.sh ├── README.md └── pyproject.tomlbin/目录存放工具的实际可执行实现。仓库中 tools/image_tools/config.yaml 是一个简洁的 bundle 配置示例tools: view_image: signature: view_image image_file docstring: view an image file arguments: - name: image_file type: string description: the path to the image file to view required: true每个工具配置包含signature调用签名、docstring注入提示词的功能描述与arguments参数定义。另一个重要概念是state命令它在每次 action 执行后运行返回一段 JSON 字符串供解析得到的字典可用于格式化提示词模板。例如经典的 SWE-agent 工具通过state提取工作目录与当前打开文件见仓库中 tools/windowed/bin/_state#!/usr/bin/env python3 import json import os from pathlib import Path from registry import registry # type: ignore def main(): current_file registry.get(CURRENT_FILE) open_file n/a if not current_file else str(Path(current_file).resolve()) state {open_file: open_file, working_dir: os.getcwd()} print(json.dumps(state))对应的配置键为tools.state_command: _state。state命令的完整规范见 bundle 配置参考如何编写一个全新工具可参考 添加自定义工具教程。2. 模板配置三种每轮模板模板配置定义了在解决单个任务实例的一次 episode 中每一轮该向模型展示什么。下图展示了各模板在一条轨迹中的位置每轮会从以下三种模板中选择一种展示Next Stepnext_step_template当模型的 action 成功执行后展示包含执行输出并提示下一步动作Next Step (No Output)next_step_no_output_template当 action 成功执行但没有标准输出时展示例如rm、cd这类命令Format Errorformat_error_template当模型响应格式错误时展示。之后的两轮处理逻辑是若下一轮响应正确则该 Format Error 轮次会从消息历史中移除episode 继续若连续两轮响应均格式错误则 episode 终止。全部模板选项见 模板配置参考。模板中大量使用{{working_dir}}、{{problem_statement}}、{{observation}}、{{diff}}这类 Jinja2 变量它们分别由环境状态、任务描述与 state 命令提供。3. 演示配置用轨迹引导行为演示demonstration本质是一条已完成的轨迹LM 可从中学习如何使用命令与环境交互。SWE-agent 只接收轨迹文件形式的演示但轨迹通常是 JSON可用sweagent traj-to-demo命令转换为更易读、易编辑的 YAML默认存放于demos/目录。生成演示的两条路径手动创建以--agent.model.namehuman_thought运行 Agent每轮手动输入 thought以END_THOUGHT结尾与 action单条命令再把轨迹转换为演示。若只想调试不想每轮输入 thought可用--agent.model.namehuman。在human_thought模式下用传统行号编辑器编辑文本时运行edit edit_start_line:edit_end_line写入多行文本回车后写end_of_edit再回车提交。从已有轨迹转换先找到满意的.traj文件例如本仓库 tests/test_data/trajectories/ 下的示例轨迹运行路径会打印在底部执行sweagent traj-to-demo path to trajectory file.traj转换为demos/目录下的 YAML再手工编辑适配自己的用例与配置可用sweagent run-replay --traj_path path to demo回放演示、由系统生成执行输出来验证其可运行性最后把演示路径写进配置文件。4. 模型配置缓存、成本与多 Key模型行为是配置的另一大重点入门请先阅读 安装指南中的模型章节完整参数见 模型配置参考动作提取方式见 解析器参考。本地模型需要取消花费限制spending limits并在不支持 function calling 时配置对应的 action parser。若想为本地模型保留成本追踪可在配置中提供自定义litellm_model_registry文件定义本地模型的自定义定价信息而非完全禁用成本限制。Anthropic Claude 的 prompt caching与gpt-4o等自动做缓存的模型不同Claude 需要手动设置缓存断点在配置中加入如下 history processor即 config/default.yaml 末尾所用机制其实现见 sweagent/agent/history_processors.py 的CacheControlHistoryProcessoragent: history_processors: - type: cache_control last_n_messages: 2注意其他 history processor 若不小心可能干扰 prompt caching但如果你的处理器只修改最后一条 observation则仍可与缓存组合使用。由于 Anthropic Claude 每个 key 只给 4 个缓存断点、单次 agent run 需要 2 个读取与设置缓存各占一个每个 key 只能并行跑两个run-batch实例需要更多并行度时应配置多个 key见下文。检查缓存命中率可直接在轨迹目录 grepgrep -o cached_tokens[0-9]* django__django-11299.debug.log。此外从仓库历史看Claude 3.7/4 的最大输出 token 数可借助额外 headers 扩展也可在配置中手动设置最大输出 token 以覆盖 litellm 信息。启用扩展思考extended thinking的配置示例agent: name: claude-sonnet-4-20250514 model: temperature: 1. completion_kwargs: reasoning_effort: higho1 模型必须显式设置top_p: null与temperature: 1.因为其他取值不被 o1 支持agent: model: top_p: null temperature: 1.多 Key 轮换run-batch支持在多个 key 间轮换将多个 key 用:::连接后通过--agent.model.api_key传入。每个线程即每个并行处理一个任务实例的 Agent在整个运行期间固定使用同一个 key因此不会破坏 prompt caching。自定义成本追踪为 litellm 默认注册表中不存在的模型新模型、本地模型、需覆盖旧定价的模型创建 JSON 注册表文件{ ollama/llama2: { max_tokens: 8192, input_cost_per_token: 0.00002, output_cost_per_token: 0.00006, litellm_provider: ollama, mode: chat }, my-custom-provider/my-new-model: { max_tokens: 8192, max_input_tokens: 8192, max_output_tokens: 8192, input_cost_per_token: 0.000001, output_cost_per_token: 0.000002, litellm_provider: openai, mode: chat } }然后在配置中指定agent: model: litellm_model_registry: my_model_registry.json # Path to your custom registry ...如需修改计算成本所用的 tokenizer可设置 模型配置参考 中的custom_tokenizer。测试用模型仓库还提供HumanModel/HumanThoughtModel用户输入代替 LM 输出用于创建演示、ReplayModel回放轨迹、InstantEmptySubmitTestModel创建空reproduce.py后直接提交可在不花费任何额度的情况下测试 SWE-agent。5. 环境变量与 I/O 接口所有 API keyLM 与 GitHub都可通过环境变量设置见 keys 文档。除SWE_AGENT_CONFIG_ROOT外还有一批只能通过环境变量设置不能在配置文件中写的变量SWE_AGENT_CONFIG_DIR默认PACKAGE/configSWE_AGENT_TOOLS_DIR默认PACKAGE/toolsSWE_AGENT_TRAJECTORY_DIR默认PACKAGE/trajectories以非--editable方式安装swe-agent时必须设置以上三个变量。日志相关环境变量SWE_AGENT_LOG_TIME为日志添加时间戳、SWE_AGENT_LOG_STREAM_LEVEL控制 CLI 上显示的日志级别TRACE是低于DEBUG的自定义级别对run-batch无效。大多数环境变量也可写入.env文件持久化。四、多模态配置让 Agent看得见对于需要处理图像GitHub Issue 中的截图、UI 设计稿、示意图、报错截图等和视觉模型vision-capable的场景SWE-agent 提供了专门的多模态配置最佳示范是 config/default_mm_with_images.yaml。该配置启用完整的图像处理能力SWE-bench Multimodal 图像处理下载 GitHub Issue 图片并转换为 base64 格式供 SWE-bench Multimodal 实例使用扩展观察长度提高 observation token 上限以容纳图像内容图像工具引入image_toolsbundle 用于查看图像网页浏览工具引入web_browserbundle 用于浏览器自动化历史处理启用image_parsinghistory processor 解析图像输出。关键多模态配置项agent: templates: disable_image_processing: false # enable/disable image processing max_observation_length: 10_000_000 # increased for images tools: bundles: - path: tools/image_tools # image viewing capabilities - path: tools/web_browser # browser automation tools history_processors: - type: image_parsing # process image tools outputs (required for tools to work)default_mm_with_images.yaml 完整剖析完整的 config/default_mm_with_images.yaml 在默认配置基础上做了以下扩展值得逐项对照理解agent: templates: disable_image_processing: false system_template: |- You are a helpful assistant that can interact with a computer to solve tasks. instance_template: |- # ...与 default.yaml 相同的任务指令... Note: You can use the view_image command to display images as embedded base64 data when relevant. Youll also be given access browser tools to interact with the web or a local server. In the browser, your mouse is shown as a red crosshair. If you need to start a command that has long-running output (e.g. a web server), you should _always_ use the following pattern: server_command my_server_log.txt next_step_template: |- OBSERVATION: {{observation}} next_step_no_output_template: |- Your command ran successfully and did not produce any output. max_observation_length: 10_000_000 # need longer for images tools: execution_timeout: 300 # need longer for builds bundles: - path: tools/registry - path: tools/edit_anthropic - path: tools/image_tools # lets models view image files - path: tools/web_browser # browser tool for interacting with web servers - path: tools/review_on_submit_m registry_variables: USE_FILEMAP: true SUBMIT_REVIEW_MESSAGES: # ...与 default.yaml 相同的提交审查提示词... enable_bash_tool: true parse_function: type: function_calling history_processors: - type: image_parsing # parses base64 encoded images in the observation # - type: cache_control # enable for claude # last_n_messages: 2 # enable for claude instances: type: swe_bench subset: multimodal split: dev shuffle: true # filter: processing__p5.js-6069需要注意的增量点max_observation_length提升到10_000_000因为图像转 base64 后会显著拉长 observationtools.execution_timeout提高到300秒为构建类命令留出更长时间新增image_tools提供view_image命令定义见 tools/image_tools/config.yaml与web_browser提供open_site、screenshot_site、click_mouse、type_text、scroll_on_page、execute_script_on_page等约 17 个浏览器自动化工具history processor 换成image_parsing实现位于 sweagent/agent/history_processors.py 的ImageParsingHistoryProcessor用于解析 observation 中的 base64 图像由于图像解析与 prompt caching 可能冲突cache_control被注释掉Claude 场景可按需启用文件底部还示范了instances段type: swe_bench、subset: multimodal、split: dev可通过filter字段精确过滤单个实例。多模态运行与编程式使用启动多模态批量运行sweagent run-batch \ --config config/default_mm_with_images.yaml \ --instances.type swe_bench \ --instances.subset multimodal \ --instances.split dev多模态处理由 sweagent/agent/problem_statement.py 中的SWEBenchMultimodalProblemStatement支撑它自动完成实例检测、GitHub issue 图片下载、base64 markdown 转换与错误回退失败时退回纯文本。设计上只处理problem_statement类别的图片提供理解任务所需的视觉上下文而patch与test_patch类别的图片可能包含解题提示因此不处理以保留 Agent 自主性。支持 PNG、JPEG、WebP 格式单张上限 10MB。视觉能力由模型自动检测Claude Sonnet 4、o3/o4-mini、Gemini 2.5 等视觉模型均可直接使用。更完整的多模态配置细节见 多模态指南。五、环境配置让 Agent 跑在正确的容器里SWE-agent 默认运行在 docker 镜像python:3.11中SWE-Bench 场景下每个实例会从 dockerhub 拉取对应镜像。以下是 环境配置文档 给出的自定义 docker 环境示例FROM python:3.11.10-bullseye # (1)! ARG DEBIAN_FRONTENDnoninteractive # (2)! ENV TZEtc/UTC WORKDIR / # Install swe-rex for faster startup RUN pip install pipx RUN pipx install swe-rex RUN pipx ensurepath ENV PATH$PATH:/root/.local/bin/ # Install any extra dependencies RUN pip install flake8 SHELL [/bin/bash, -c]基础镜像起点安装依赖时务必禁用交互式提示构建并运行docker build -f tiny.Dockerfile -t swe-agent-tiny . sweagent run --env.deployment.image swe-agent-tiny ...六、实战从零组合一份自己的配置综合以上内容编写自定义配置的推荐流程是从默认配置起步复制 config/default.yaml保证基础能力完整按需叠加能力需要图像时引入image_tools/web_browserbundle 并切换image_parsing需要 Claude 缓存时追加cache_controlhistory processor定制提示词改写instance_template中的任务步骤如补充先复现错误再修改的强制流程利用{{working_dir}}、{{problem_statement}}、{{observation}}等变量配置模型根据模型类型设置temperature/top_p/completion_kwargsClaude 场景启用cache_control增量合并用--config base.yaml --config override.yaml的方式让覆盖文件只写差异项保持基础配置可复用验证先用测试模型如HumanThoughtModel或run-replay回放已有轨迹确认配置可解析、可执行再投入真实运行。注意路径解析配置内所有相对路径bundle 路径、演示路径、注册表文件路径都受SWE_AGENT_CONFIG_ROOT或仓库根目录解析规则约束若使用非 editable 安装还需按 环境变量文档 设置SWE_AGENT_CONFIG_DIR、SWE_AGENT_TOOLS_DIR、SWE_AGENT_TRAJECTORY_DIR三个目录变量。总结SWE-agent 的配置系统以.yaml为唯一事实来源通过--config注入、嵌套合并、SWE_AGENT_CONFIG_ROOT路径解析三大机制把工具、提示词、演示、模型与环境五类能力统一管理起来。默认配置default.yaml提供了开箱即用的完整基线default_mm_with_images.yaml则展示了图像处理、浏览器自动化与长上下文场景的扩展范式。掌握这套配置语言就等于掌握了驾驭 SWE-agent 的完整控制面板——无论是复现 benchmark、接入私有模型还是为特定代码库定制专属智能体都可以在不动一行核心代码的前提下完成。【免费下载链接】SWE-agentSWE-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]项目地址: https://gitcode.com/GitHub_Trending/sw/SWE-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考