mini-swe-agent: 최소한의 AI 에이전트 구축을 위한 새로운 튜토리얼

📣 최소한의 AI 에이전트 구축에 관한 새로운 튜토리얼

📣 Gemini 3 Pro가 mini-swe-agent를 통해 SWE-bench verified에서 74%를 달성했습니다!

📣 새로운 블로그 포스트: GPT-5와 Sonnet 4 사이를 무작위로 전환하면 성능이 향상됩니다

경고

이것은 mini-swe-agent v2입니다. 마이그레이션 가이드 (migration guide)를 읽어주세요. 이전 버전은 v1 브랜치를 확인하시기 바랍니다.

2024년에 저희는 SWE-bench와 SWE-agent를 구축하여 코딩 에이전트 (coding agent) 혁명의 시작을 도왔습니다.

이제 저희는 질문합니다: 만약 우리의 에이전트가 100배 더 단순해지면서도, 여전히 거의 비슷하게 잘 작동한다면 어떨까요?

mini는

널리 채택됨: Meta, NVIDIA, Essential AI, IBM, Nebius, Anyscale, Princeton University, Stanford University 및 기타 여러 곳에서 사용됩니다. 최소화됨: 에이전트 클래스를 위한 단 100줄 정도의 Python 코드 (그리고 환경, 모델, 실행 스크립트를 위한 약간의 코드) — 화려한 의존성 (dependencies)이 없습니다! 성능 우수: SWE-bench verified 벤치마크에서 74% 이상의 점수를 기록하며, Claude Code보다 훨씬 빠르게 시작합니다. 배포 가능: 로컬 환경 (local environments), docker/podman, singularity/apptainer, bublewrap, contree 등을 지원합니다. 호환성: litellm, openrouter, portkey 등을 통해 모든 모델을 지원합니다. /completion 및 /response 엔드포인트, 인터리브드 씽킹 (interleaved thinking) 등을 지원합니다. - SWE-bench, SWE-agent 등을 만든 Princeton 및 Stanford 팀이 구축했습니다. 테스트 완료:

더 많은 동기 부여 (연구용)

SWE-agent는 2024년에 AI 에이전트 개발의 기폭제 역할을 했습니다. 당시 저희는 에이전트를 위한 도구와 특수 인터페이스에 많은 강조를 두었습니다.
하지만 1년이 지난 지금, 언어 모델 (LMs)의 능력이 향상됨에 따라 유용한 에이전트를 구축하는 데 이러한 것들이 전혀 필요하지 않은 경우가 많습니다!
실제로, mini 에이전트는

bash 외에는 어떠한 도구도 가지고 있지 않습니다— 심지어 언어 모델(LM)의 도구 호출(tool-calling) 인터페이스를 사용할 필요조차 없습니다. 이는 말 그대로 어떤 모델로도 실행할 수 있음을 의미합니다. 샌드박스(sandboxed) 환경에서 실행할 때도 단 하나의 패키지를 설치하는 것조차 신경 쓸 필요가 없습니다 — 오직 bash만 있으면 됩니다. 완전히 선형적인 히스토리(linear history)를 가집니다— 에이전트의 모든 단계는 단순히 메시지에 추가될 뿐입니다. 따라서 궤적(trajectory)과 LM에 전달하는 메시지 사이에 차이가 없습니다. 디버깅(debugging) 및 미세 조정(fine-tuning)에 매우 유용합니다. 다음과 함께 동작을 실행합니다— 모든 동작은 완전히 독립적입니다(상태를 유지하는 셸 세션(stateful shell session)을 계속 실행하는 것과 대조적임). 덕분에 샌드박스에서 동작을 실행하는 것이 매우 간단하며(말 그대로 subprocess.run을 docker exec로 교체하기만 하면 됩니다), 손쉽게 확장할 수 있습니다. 진심으로, 이것은 매우 중요한 부분입니다. 저를 믿으세요.

이러한 특징 덕분에 mini는 베이스라인 시스템(baseline system)으로서, 그리고 (에이전트 스캐폴드(agent scaffold)보다는) 언어 모델을 우리 주의의 중심에 두는 시스템으로서 완벽합니다. mini를 사용하여 다양한 언어 모델(LM)의 성능을 평가하는 SWE-bench (bash only) 리더보드에서 그 결과를 확인할 수 있습니다.

추가적인 동기 (도구로서의 측면)

어떤 에이전트들은 과적합(overfitted)된 연구 산물입니다. 다른 것들은 UI가 비대해진 프론트엔드 괴물들입니다.

mini 에이전트는 블랙박스(black box)가 아닌, 해킹 가능한(hackable) 도구가 되고자 합니다.

한눈에 이해할 수 있을 만큼 단순하며
일상적인 워크플로우에서 사용할 수 있을 만큼 편리하고
확장하기에 유연합니다

다른 에이전트들(저희의 swe-agent를 포함하여)과 달리, mini는 다음과 같은 이유로 근본적으로 더 단순합니다:

bash 외에는 어떠한 도구도 없습니다— 심지어 언어 모델(LM)의 도구 호출(tool-calling) 인터페이스를 사용할 필요조차 없습니다. 에이전트가 수행하고자 하는 모든 특정 작업에 대해 커스텀 도구를 구현하는 대신, LM이 셸(shell)을 최대한 활용하는 데 온전히 집중합니다. PR(Pull Request)을 여는 것과 같은 특정 작업을 수행하고 싶나요? 에이전트에 이를 구현하는 데 시간을 쓰는 대신, 그냥 LM에게 스스로 방법을 찾아내라고 말하면 됩니다. subprocess.run을 통해 동작을 실행합니다— 모든 동작은 완전히 독립적입니다(상태를 유지하는(stateful) 셸 세션을 계속 실행하는 것과는 대조적입니다). 이는 에이전트의 안정성 측면에서 매우 중요한 부분입니다.

완전히 선형적인 히스토리를 가집니다— 에이전트의 모든 단계는 다음 단계에서 LM에 전달되는 메시지에 단순히 추가될 뿐입니다. 이는 디버깅을 수행하거나 LM에 어떤 프롬프트(prompt)가 제공되는지 이해하는 데 매우 유용합니다.

SWE-agent를 사용해야 할까요, 아니면 mini-SWE-agent를 사용해야 할까요?

mini-swe-agent를 기본 선택지로 고려해야 합니다.

특히, 다음과 같은 경우라면 mini-swe-agent를 사용해야 합니다:

• 로컬에서 작동하는 빠른 명령줄 도구(CLI tool)를 원하는 경우
• 매우 단순한 제어 흐름(control flow)을 가진 에이전트를 원하는 경우
• 훨씬 더 빠르고, 단순하며, 안정적인 샌드박싱(sandboxing) 및 벤치마크 평가를 원하는 경우
• 미세 조정(FT) 또는 강화학습(RL)을 수행 중이며, 특정 에이전트 스캐폴드(scaffold)에 과적합(overfit)되는 것을 원치 않는 경우

반면, 다음과 같은 경우에는 swe-agent를 사용해야 합니다:

• 각기 다른 인터페이스를 가진 다양한 도구 세트를 실험하고 싶은 경우
• 다양한 히스토리 프로세서(history processors)를 실험하고 싶은 경우

두 방식 모두에서 얻을 수 있는 것:

• SWE-Bench에서의 뛰어난 성능
• 궤적 브라우저(trajectory browser)

CLI (mini) | 배치 추론(Batch inference) | 궤적 브라우저 | Python 바인딩(Python bindings)

agent = DefaultAgent(
    LitellmModel(model_name=...),
    LocalEnvironment(),
    ...
)

옵션 1: 단순히 CLI를 사용해보고 싶은 경우 (익명 가상 환경에 패키지 설치)

pip install uv && uvx mini-swe-agent
# 또는
pip install pipx && pipx ensurepath && pipx run mini-swe-agent

옵션 2: 현재 환경에 CLI 및 Python 바인딩 설치

pip install mini-swe-agent
mini # CLI 실행

옵션 3: 소스에서 설치 (개발자 설정)

git clone https://github.com/SWE-agent/mini-swe-agent.git
cd mini-swe-agent && pip install -e .
mini # CLI 실행

문서에서 더 자세히 읽어보세요:

• 빠른 시작 가이드 (Quick start guide)
• mini CLI 사용법
• 전역 설정 (Global configuration)
• Yaml 설정 파일 (Yaml configuration files)
• 쿡북 (Cookbook)으로 기능 강화하기
• 자주 묻는 질문 (FAQ)
• 기여하기 (Contribute!)

이 작업이 도움이 되었다면, 귀하의 연구/작업에 SWE-agent 논문을 인용해 주시기 바랍니다:

@inproceedings{yang2024sweagent,
title={{SWE}-agent: Agent-Computer Interfaces Enable Automated Software Engineering},
author={John Yang and Carlos E Jimenez and Alexander Wettig and Kilian Lieret and Shunyu Yao and Karthik R Narasimhan and Ofir Press},
...

우리의 다른 프로젝트들: