Qwen-Agent: LLM을 실제로 “일하게” 만드는 에이전트 프레임워크

LLM은 이제 단순히 텍스트를 생성하는 도구를 넘어 도구를 사용하고, 작업을 수행하며, 여러 단계를 거쳐 문제를 해결하는 Agent로 발전하고 있습니다.

이번 글에서는 Alibaba의 Qwen 팀이 공개한 Qwen-Agent 프로젝트를 살펴보겠습니다.

이 프로젝트는 Qwen 모델을 기반으로 Tool 사용, 코드 실행, 웹 검색, 멀티 에이전트 협업 등을 구현할 수 있는 Agent 프레임워크입니다.

 

GitHub - QwenLM/Qwen-Agent: Agent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpr

 

---

프로젝트 소개

Qwen-Agent는 Alibaba의 Qwen LLM을 기반으로 AI Agent 시스템을 구축하기 위한 Python 프레임워크입니다.

핵심 목표는 다음과 같습니다.

• LLM이 도구(Tools)를 사용할 수 있도록 만들기
• 복잡한 작업을 여러 단계로 나누어 수행
• 멀티 에이전트 협업 시스템 구축
• 코드 실행, 검색, 브라우징 등 외부 환경과 상호작용

즉, 단순한 LLM 호출이 아니라 “작업을 수행하는 AI 시스템”을 만드는 것이 목적입니다.

대표적으로 다음과 같은 시스템을 만들 수 있습니다.

• 코드 작성 및 실행 Agent
• 자동 리서치 Agent
• 웹 검색 기반 QA Agent
• 멀티 Agent 협업 시스템
• 자동화 Assistant

---

왜 이 프로젝트가 등장했을까

기존 LLM은 대부분 단순한 질의응답 형태로 사용되었습니다.

User → LLM → Answer

하지만 실제 문제는 대부분 여러 단계의 작업을 요구합니다.

예를 들어 이런 작업입니다.

• 웹에서 정보 검색
• 데이터 분석
• 코드 실행
• 파일 생성
• 여러 Agent 협업

기존 LLM API만으로는 다음과 같은 문제가 있습니다.

1. Tool 사용이 어렵다

예를 들어 LLM이 이런 작업을 해야 한다고 가정합니다.

• 웹 검색
• 코드 실행
• DB 조회

LLM은 직접 실행할 수 없기 때문에 Tool 시스템이 필요합니다.

---

2. 복잡한 Workflow 관리

다음과 같은 작업을 생각해봅시다.

질문 → 검색 → 요약 → 코드 작성 → 실행 → 결과 정리

이런 멀티 스텝 작업을 관리하는 프레임워크가 필요합니다.

---

3. 멀티 에이전트 협업

최근 AI 시스템은 여러 Agent가 협업하는 구조로 발전하고 있습니다.

예

• Planner Agent
• Tool Agent
• Coding Agent
• Research Agent

Qwen-Agent는 이런 구조를 쉽게 만들 수 있도록 설계되었습니다.

---

핵심 기능

Qwen-Agent는 단순한 LLM wrapper가 아니라 Agent Runtime에 가까운 구조를 가지고 있습니다.

대표 기능들을 살펴보겠습니다.

---

1. Tool 사용 기능

Agent가 외부 Tool을 사용할 수 있습니다.

예를 들어

• 웹 검색
• 코드 실행
• 파일 읽기
• API 호출

Tool은 Python 클래스로 정의됩니다.

예시:

from qwen_agent.tools import BaseTool

class WeatherTool(BaseTool):
    name = "weather"

    description = "Get weather info"

    def call(self, params: dict):
        city = params.get("city")
        return f"The weather in {city} is sunny."

Agent는 LLM의 판단에 따라 이 Tool을 호출합니다.

---

2. Code Interpreter

Qwen-Agent는 코드 실행 기능을 제공합니다.

예를 들어

• 데이터 분석
• 그래프 생성
• 계산
• 자동 코드 작성

Agent 흐름 예

User 질문
↓
Agent 코드 생성
↓
Python 실행
↓
결과 반환

이 구조는 ChatGPT의 Code Interpreter와 유사한 방식입니다.

---

3. ReAct 기반 Agent

Qwen-Agent는 ReAct 패턴을 사용합니다.

ReAct는 다음 과정을 반복합니다.

Thought → Action → Observation → Thought

예시

Thought: 웹 검색이 필요하다
Action: search_tool("Qwen Agent")
Observation: 검색 결과
Thought: 결과를 요약하자
Action: summarize()

이 방식은 Agent reasoning + tool usage를 동시에 구현합니다.

---

4. 멀티 에이전트 시스템

Qwen-Agent는 여러 Agent가 협력하는 구조도 지원합니다.

예를 들어

• Planner Agent
• Research Agent
• Coding Agent

각 Agent가 역할을 나눠서 작업합니다.

---

프로젝트 구조

Qwen-Agent는 Agent + Tool + LLM + Memory 구조를 기반으로 설계되어 있습니다.

구성 요소를 살펴보겠습니다.

---

Agent

Agent는 전체 Workflow를 관리합니다.

• reasoning
• tool selection
• task execution

---

Tools

Agent가 사용할 수 있는 외부 기능입니다.

예

• web search
• code execution
• API call
• file system

---

Memory

Agent의 대화 및 작업 상태를 관리합니다.

예

• 이전 대화
• 작업 히스토리
• tool 결과

---

LLM

Qwen 모델을 사용합니다.

예

• Qwen2
• Qwen2.5

---

기본 사용 예제

간단한 Agent를 만들어보겠습니다.

설치

pip install qwen-agent

---

기본 Agent 실행

from qwen_agent.agents import Assistant

llm_cfg = {
    "model": "qwen2",
}

agent = Assistant(llm=llm_cfg)

response = agent.run(
    messages=[{"role": "user", "content": "Explain what Qwen Agent is"}]
)

print(response)

---

Tool을 사용하는 Agent

Tool을 등록할 수도 있습니다.

from qwen_agent.agents import Assistant

tools = ["web_search"]

agent = Assistant(
    llm={"model": "qwen2"},
    tools=tools
)

agent.run(
    messages=[{"role": "user", "content": "Search latest AI news"}]
)

이 경우 Agent는 필요할 때 웹 검색 Tool을 호출합니다.

---

Code Interpreter 예제

코드 실행도 가능합니다.

agent = Assistant(
    llm={"model": "qwen2"},
    tools=["python"]
)

agent.run(
    messages=[{
        "role": "user",
        "content": "Calculate the mean of [1,2,3,4,5]"
    }]
)

Agent는 내부적으로 다음과 같은 흐름을 실행합니다.

LLM reasoning
↓
Python code 생성
↓
Code 실행
↓
결과 반환

---

Qwen-Agent의 장점

1. Agent 시스템에 최적화된 구조

단순 LLM wrapper가 아니라

• Tool
• Memory
• Reasoning

을 포함한 Agent runtime 구조입니다.

---

2. 멀티 Agent 지원

여러 Agent가 협업하는 시스템을 쉽게 만들 수 있습니다.

예

• Research Agent
• Coding Agent
• Planning Agent

---

3. Code Interpreter 내장

데이터 분석 및 자동 코드 실행이 가능합니다.

---

4. Qwen 모델 최적화

Alibaba의 Qwen LLM과 자연스럽게 통합됩니다.

---

이런 프로젝트에 활용할 수 있습니다

Qwen-Agent는 다음과 같은 시스템 구축에 매우 적합합니다.

예

AI 자동화 시스템

• 문서 분석
• 보고서 생성
• 데이터 처리

---

개발자 AI Assistant

• 코드 생성
• 코드 실행
• 디버깅

---

AI 리서치 Agent

• 웹 검색
• 논문 요약
• 데이터 수집

---

멀티 Agent 시스템

예

Planner → Researcher → Writer

---

마무리

Qwen-Agent는 단순한 LLM SDK가 아니라 Agent 시스템 구축을 위한 프레임워크입니다.

핵심 특징을 정리하면 다음과 같습니다.

• Tool 사용 가능한 LLM Agent
• ReAct 기반 Reasoning
• Code Interpreter
• 멀티 Agent 협업
• Qwen 모델 최적화

최근 AI 시스템은 “LLM + Tool + Workflow” 구조로 빠르게 발전하고 있습니다.

Qwen-Agent는 이러한 흐름 속에서 실제 작업을 수행하는 AI Agent 시스템을 쉽게 만들 수 있게 해주는 프레임워크라고 볼 수 있습니다.