Qwen-Agent: 알리바바의 오픈소스 에이전트 프레임워크 완전 정복

Qwen-Agent Framework

Qwen Chat의 백엔드로 사용되며, 14,000개 이상의 GitHub 스타를 받은 알리바바의 오픈소스 에이전트 프레임워크. Function Calling부터 MCP, Code Interpreter, RAG까지 — Qwen-Agent는 현대적 AI 에이전트 개발에 필요한 거의 모든 것을 담고 있다.

왜 Qwen-Agent인가

AI 에이전트 프레임워크 시장은 이미 포화 상태다. LangChain, AutoGPT, CrewAI… 선택지는 넘쳐난다. 그런데 왜 굳이 Qwen-Agent를 주목해야 할까?

세 가지 이유:

실전 검증: Qwen Chat의 실제 백엔드로 운영 중인 프로덕션급 프레임워크다. 연구용 데모가 아니다.
모델 특화: Qwen 시리즈(Qwen3, Qwen3.5, QwQ)의 Function Calling, 추론 능력을 최대한 활용하도록 설계됐다.
올인원: 도구 호출, RAG, 코드 실행, MCP 지원까지 별도 라이브러리 없이 한 프레임워크에서 해결된다.

AI Agent Concept

핵심 기능 딥다이브

1. Function Calling (도구 호출)

Qwen-Agent의 Function Calling은 Parallel Function Calls를 기본 지원한다. 여러 도구를 동시에 호출하고 결과를 종합하는 패턴이 자연스럽게 구현된다.

from qwen_agent.agents import Assistant

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    'generate_cfg': {
        'top_p': 0.8,
        # Qwen3 추천 템플릿
        'fncall_prompt_type': 'nous'
    }
}

bot = Assistant(
    llm=llm_cfg,
    system_message="도움이 필요하면 도구를 사용하세요.",
    function_list=['my_custom_tool', 'code_interpreter']
)

vLLM/Ollama와도 호환된다. OpenAI API 호환 서버면 어디든 연결 가능하다.

2. MCP (Model Context Protocol) 지원

2025년 5월부터 MCP를 정식 지원한다. MCP 서버의 도구를 Qwen-Agent에서 바로 호출할 수 있다.

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  }
}

MCP 덕분에 파일시스템, 메모리, 데이터베이스 등 외부 리소스를 표준화된 방식으로 연결할 수 있다.

3. Code Interpreter (코드 실행)

Docker 기반 샌드박스에서 안전하게 코드를 실행한다. 에이전트가 직접 Python 코드를 작성하고 실행한 뒤 결과를 반환하는 패턴이 가능하다.

# code_interpreter는 내장 툴
tools = ['code_interpreter']
bot = Assistant(llm=llm_cfg, function_list=tools)

⚠️ 주의: Docker 설치가 필수다. 프로덕션용이 아닌 로컬 테스트용으로 권장된다.

4. RAG (검색 증강 생성)

PDF, 웹페이지 등 외부 문서를 읽고 질문에 답할 수 있다. files 파라미터로 문서를 전달하면 된다.

bot = Assistant(
    llm=llm_cfg,
    files=['./examples/resource/doc.pdf']
)

5. 커스텀 툴 등록

BaseTool을 상속받아 커스텀 도구를 쉽게 만들 수 있다.

from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    description = 'AI 이미지 생성 서비스'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': '이미지 설명',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        # 구현
        return result

DeepPlanning: 에이전트 계획 능력 벤치마크

Qwen-Agent 팀은 2026년 1월, DeepPlanning 벤치마크를 공개했다. 장기 계획 수립 능력을 평가하는 도전적인 벤치마크다.

두 가지 도메인

영역	여행 계획	쇼핑 계획
작업 수	120개 (한/영)	120개 (영문)
도구	9개 API	15개 API
목표	분 단위 일정	최적화된 장바구니

평가 핵심 역량

능동적 정보 수집: 환경 상태를 직접 조회 (폐업 여부, 재고 확인)
국소 제약 추론: 브랜드, 사이즈, 편의시설 등 세부 조건 충족
전역 제약 최적화: 예산, 시간 등 전체 계획의 타당성

이 벤치마크에서 GPT-4, Claude 같은 프론티어 모델도 어려움을 겪는다고 한다. 장기 계획은 여전히 AI에게 도전적인 영역이다.

실전 활용 예시

Qwen3.5로 에이전트 만들기

from qwen_agent.agents import Assistant

llm_cfg = {
    'model': 'qwen3.5-72b-instruct',
    'model_type': 'qwen_dashscope',
}

bot = Assistant(
    llm=llm_cfg,
    system_message="당신은 도움이 되는 어시스턴트입니다.",
    function_list=['code_interpreter']
)

# Gradio UI로 실행
from qwen_agent.gui import WebUI
WebUI(bot).run()

QwQ-32B로 추론 에이전트

llm_cfg = {
    'model': 'qwq-32b',
    'model_type': 'qwen_dashscope',
    'generate_cfg': {
        'thought_in_content': False,  # reasoning_content 분리
    }
}

QwQ는 다단계, 병렬, 멀티턴 도구 호출을 지원한다. 복잡한 추론이 필요한 작업에 적합하다.

설치 및 시작하기

# 전체 설치 (GUI, RAG, Code Interpreter, MCP 포함)
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"

# 최소 설치
pip install -U qwen-agent

API 키 설정:

DashScope 사용: DASHSCOPE_API_KEY 환경변수
vLLM/Ollama 사용: model_server 파라미터로 base_url 지정

마치며: Qwen 생태계의 완성

Qwen-Agent는 단순한 프레임워크가 아니다. Qwen 모델 생태계의 완성이다.

Qwen2.5, Qwen3, Qwen3.5, QwQ — 강력한 모델군
Qwen-Agent — 모델을 에이전트로 만드는 프레임워크
Qwen Chat — 프로덕션 서비스
DeepPlanning — 평가 벤치마크

알리바바는 모델만 공개하는 게 아니라, 전체 스택을 오픈소스로 풀고 있다. 중국 AI 생태계의 성장세가 무섭다.

Qwen 모델을 사용 중이라면, Qwen-Agent는 선택이 아닌 필수다.

🔗 관련 정보

GitHub: QwenLM/Qwen-Agent
문서: Qwen-Agent Documentation
벤치마크: DeepPlanning Benchmark
Qwen Chat: chat.qwen.ai