AgentScope: 멀티 에이전트 실험을 넘어 운영 환경까지 가져가는 Python 에이전트 프레임워크

AI Agent를 만들기 시작하면 금방 비슷한 벽에 부딪힙니다.
“툴 호출은 되는데 구조가 금방 꼬인다”, “멀티 에이전트 데모는 되는데 운영 환경으로 옮기기 어렵다”, “메모리, 추적, 평가를 붙이려니 프레임워크 바깥 일이 더 많다.”

AgentScope는 바로 그 지점에서 등장한 프로젝트입니다. 단순히 “에이전트를 하나 띄우는 라이브러리”가 아니라, ReAct 에이전트, 툴, 메모리, MCP, A2A, RAG, tracing, evaluation, realtime voice까지 하나의 개발 경험으로 묶으려는 방향이 매우 분명합니다. 저장소 README는 AgentScope를 “production-ready, easy-to-use agent framework”로 소개하고, 실제 패키지 구조도 agent, tool, memory, rag, tracing, realtime, a2a, pipeline, tuner처럼 운영에 필요한 축으로 나뉘어 있습니다. 2026년 3월 26일 기준 최신 릴리스는 v1.0.18이고, GitHub 저장소는 약 2만 스타 규모입니다. (GitHub)

프로젝트 소개

AgentScope는 Python 3.10+ 기반의 에이전트 프레임워크입니다. 저장소 기준 설치는 pip install agentscope로 시작할 수 있고, 핵심 패키지 외에 A2A, realtime, memory, RAG, evaluation, tuner 같은 기능을 optional dependency 형태로 확장하도록 설계되어 있습니다. 기본 의존성에는 openai, anthropic, dashscope, mcp, sqlalchemy, opentelemetry 등이 포함되어 있어, 모델 연결부터 도구 실행, 상태 저장, 관측성까지 한 프레임 안에서 다루려는 의도가 드러납니다. 저자는 패키지 메타데이터상 Alibaba Tongyi Lab의 SysML team으로 표시되어 있습니다. (GitHub)

문서 구조를 보면 이 프로젝트가 어떤 개발자를 겨냥하는지도 선명합니다.
튜토리얼은 설치 후 바로 ReActAgent를 만드는 흐름으로 시작하고, 그 다음에 Conversation, Multi-Agent Debate, Routing, Handoffs, Memory, MCP, Realtime Agent, Tracing, Evaluation, RAG로 이어집니다. 즉, “LLM 호출 래퍼”가 아니라 에이전트 애플리케이션 전체 수명주기를 염두에 둔 프레임워크입니다. (AgentScope)

README의 가장 중요한 메시지는 이것입니다.
AgentScope는 모델을 지나치게 강한 오케스트레이션으로 묶기보다, 모델의 reasoning과 tool use 능력을 적극 활용하는 방향으로 설계되었습니다. 이 문장은 요즘 에이전트 프레임워크들의 분기점을 잘 보여줍니다. 어떤 프레임워크는 노드를 강하게 정의하고 흐름을 정적으로 짜는 데 강하고, AgentScope는 상대적으로 에이전트가 스스로 판단하는 여지를 남긴 쪽에 가깝습니다. (GitHub)

 

GitHub - agentscope-ai/agentscope: Build and run agents you can see, understand and trust.

 

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

에이전트 프레임워크를 조금만 써보면 두 가지 방향이 갈립니다.

첫 번째는 워크플로를 아주 명확하게 그래프나 상태 머신으로 정의하는 접근입니다. 이 방식은 예측 가능성이 높지만, 모델이 스스로 판단하고 툴을 조합하는 유연성은 줄어들 수 있습니다.

두 번째는 LLM에게 더 많은 자율성을 주는 접근입니다. 문제는 이 경우 운영에서 필요한 기능, 예를 들면 메모리 관리, 툴 스키마 관리, 중단 처리, 상태 복원, 추적, 평가, 멀티 에이전트 통신이 금방 복잡해진다는 점입니다.

AgentScope는 이 둘 사이에서 꽤 실용적인 절충을 택합니다.

• 에이전트의 기본 추상화는 단순합니다. reply, observe, print 중심입니다.
• 하지만 ReAct 에이전트로 올라가면 _reasoning과 _acting이 분리됩니다.
• 메모리는 저장소 역할에 집중하고, 압축 같은 알고리즘은 에이전트 계층에서 처리합니다.
• 라우팅은 structured output이나 tool call처럼 단순한 패턴으로 구현합니다.
• tracing은 OpenTelemetry 기반으로 붙여 운영 가시성을 확보합니다. (AgentScope)

이 설계가 좋은 이유는 명확합니다.
프레임워크가 모든 판단을 대신하지 않고, 개발자가 필요한 수준에서 제어할 수 있게 한다는 점입니다. 초중급 개발자 입장에서는 시작이 쉽고, 중급 이상 개발자 입장에서는 확장 포인트가 많습니다.

핵심 기능

1. 바로 쓸 수 있는 ReActAgent

문서에서 ReActAgent는 AgentScope의 중심 클래스입니다. 훅, structured output, 실시간 인터럽트, sync/async 툴, streaming tool response, stateful toolkit, parallel tool calls, MCP server, 장기 메모리 관리까지 한 에이전트에 통합되어 있습니다. 생성자 파라미터만 봐도 toolkit, memory, long_term_memory, parallel_tool_calls, plan_notebook 등이 노출되어 있어 “간단한 챗봇”보다 훨씬 넓은 범위를 커버합니다. (AgentScope)

아래처럼 아주 빠르게 시작할 수 있습니다.

import os
import asyncio

from agentscope.agent import ReActAgent, UserAgent
from agentscope.model import DashScopeChatModel
from agentscope.formatter import DashScopeChatFormatter
from agentscope.memory import InMemoryMemory
from agentscope.tool import Toolkit, execute_python_code, execute_shell_command

async def main():
    toolkit = Toolkit()
    toolkit.register_tool_function(execute_python_code)
    toolkit.register_tool_function(execute_shell_command)

    agent = ReActAgent(
        name="Friday",
        sys_prompt="You're a helpful assistant named Friday.",
        model=DashScopeChatModel(
            model_name="qwen-max",
            api_key=os.environ["DASHSCOPE_API_KEY"],
            stream=True,
        ),
        memory=InMemoryMemory(),
        formatter=DashScopeChatFormatter(),
        toolkit=toolkit,
    )

    user = UserAgent(name="user")
    msg = None

    while True:
        msg = await agent(msg)
        msg = await user(msg)
        if msg.get_text_content() == "exit":
            break

asyncio.run(main())

이 예제가 좋은 이유는 단순합니다.
AgentScope의 기본 단위가 모델 + 포매터 + 메모리 + 툴킷 + 에이전트라는 점을 한 번에 보여주기 때문입니다. README의 quickstart도 이 흐름을 그대로 사용합니다. (GitHub)

2. 툴 호출을 “함수 중심”으로 다룬다

AgentScope의 Toolkit은 꽤 실용적입니다. Python 함수와 docstring에서 툴 스키마를 자동 파싱하고, sync/async 함수, generator 기반 streaming response, JSON Schema 확장, signal handling 기반 인터럽트, 에이전트의 자율적 툴 관리까지 지원합니다. (AgentScope)

즉, 툴을 프레임워크 전용 DSL로 다시 작성하기보다 기존 Python 함수를 최대한 그대로 자산화하는 쪽입니다.

from agentscope.tool import ToolResponse

def get_weather(city: str) -> ToolResponse:
    """Get weather information for a city.

    Args:
        city (str):
            City name to query.
    """
    # 실제 구현에서는 외부 API 호출
    return ToolResponse(content=f"{city} is sunny, 22C")

이런 함수들을 Toolkit에 등록하면 에이전트가 reasoning 단계에서 툴 호출을 계획하고, acting 단계에서 실제 실행하는 구조를 만들 수 있습니다.

3. 메모리를 저장 계층과 에이전트 로직으로 분리한다

메모리 문서를 보면 AgentScope는 메모리를 “메시지 저장과 mark 기반 관리”에 집중시킵니다. mark는 힌트, 요약, 일반 대화 같은 분류 라벨 역할을 하며, memory compression 같은 알고리즘은 메모리 클래스가 아니라 에이전트 계층에서 처리합니다. 기본 구현으로는 InMemoryMemory, AsyncSQLAlchemyMemory, RedisMemory가 제공됩니다. (AgentScope)

이 방식이 중요한 이유는, 많은 프레임워크가 메모리라는 이름 아래 저장소와 정책을 섞어버리기 때문입니다. AgentScope는 둘을 분리해서 다음 같은 이점을 줍니다.

• 저장소 교체가 쉽다
• 메모리 압축 정책을 에이전트 수준에서 바꾸기 쉽다
• 세션 복원이나 상태 저장과 연결하기 좋다

from agentscope.memory import InMemoryMemory
from agentscope.message import Msg

memory = InMemoryMemory()

await memory.add(Msg("user", "지난주 회의 내용을 요약해줘", "user"), mark="dialog")
await memory.add(Msg("system", "핵심 TODO 3개", "assistant"), mark="hint")

이 mark 설계는 실무에서 꽤 유용합니다. 단순 “최근 N개 대화”보다 훨씬 풍부한 제어가 가능하기 때문입니다.

4. 멀티 에이전트 오케스트레이션이 생각보다 단순하다

문서의 Multi-Agent Debate 예제는 AgentScope의 멀티 에이전트 철학을 잘 보여줍니다. MsgHub를 사용해 참여자들의 메시지를 브로드캐스트하고, moderator/aggregator가 structured output으로 종료 여부와 정답을 판단합니다. (AgentScope)

핵심은 “멀티 에이전트 = 거대한 프레임워크 기능”으로 보지 않는다는 점입니다.
메시지라는 공통 데이터 구조와 포매터, 그리고 허브를 조합해 구현합니다.

from agentscope.pipeline import MsgHub

async with MsgHub(participants=[alice, bob, moderator]):
    await alice(Msg("user", "찬성 측 입장을 말해줘", "user"))
    await bob(Msg("user", "반대 측 입장을 말해줘", "user"))

이 설계는 학습 곡선이 낮습니다.
“에이전트끼리 어떻게 연결되지?”라는 질문에 대해, 복잡한 런타임 대신 메시지 흐름 중심 모델로 답합니다.

5. Routing, Handoff, MCP, A2A까지 운영형 기능이 이미 들어 있다

Routing 문서는 structured output 기반 라우팅과 tool call 기반 라우팅 두 방식을 제시합니다. Handoffs 문서는 Orchestrator-Workers 패턴을 tool calls로 간단히 구현하는 예를 보여줍니다. MCP 문서는 HTTP/SSE/StdIO 기반 MCP 서버와 stateful/stateless client를 다루고, A2A Agent 문서는 원격 에이전트와의 상호운용을 위한 A2A 프로토콜 지원을 설명합니다. (AgentScope)

이건 꽤 큰 장점입니다.
보통 에이전트 프로젝트는 “로컬 함수 호출”까지만 잘 되고, 외부 에코시스템과 연결되는 순간 구조가 무너집니다. AgentScope는 그 경계를 패키지 차원에서 미리 열어 둡니다.

6. Tracing과 Evaluation이 기본 세계관 안에 있다

Tracing은 OpenTelemetry 기반입니다. LLM, tool, agent, formatter에 대한 built-in tracing과 에러 추적을 제공하고, Studio에서 네이티브 시각화를 지원하며, 외부 플랫폼 연동도 염두에 두고 있습니다. Evaluation은 Ray 기반 병렬/분산 평가, interruption 후 재개, 결과 시각화를 제공합니다. (AgentScope)

에이전트 프레임워크에서 이 부분은 의외로 더 중요합니다.
데모 단계에서는 답변 하나 잘 나오면 끝이지만, 서비스 단계에서는 결국 다음 질문으로 넘어갑니다.

• 어떤 단계에서 실패했나?
• 어떤 툴 호출이 병목인가?
• 프롬프트 변경 후 성능이 나아졌나?
• 특정 벤치마크에서 회귀가 생겼나?

AgentScope는 이 질문에 대비한 구조를 이미 포함하고 있습니다.

7. Realtime Agent와 음성 인터랙션까지 확장된다

README와 realtime 문서 기준으로 AgentScope는 voice agent와 realtime voice agent를 적극적으로 밀고 있습니다. Realtime Agent는 OpenAI, DashScope, Gemini 계열 realtime 모델과 통합되며, 통합 이벤트 인터페이스, tool calling, multi-agent interaction을 지원합니다. supported model 예시에는 OpenAI gpt-4o-realtime-preview, Gemini gemini-2.5-flash-native-audio-preview-09-2025, DashScope qwen3-omni-flash-realtime 등이 언급됩니다. (GitHub)

이건 단순 부가기능이 아니라, AgentScope가 텍스트 챗봇만 보는 프레임워크가 아니라는 뜻입니다.
앞으로의 에이전트 인터페이스가 음성·실시간 상호작용으로 확장될 걸 감안한 설계라고 볼 수 있습니다.

프로젝트 아키텍처 분석

AgentScope 문서와 저장소 구조를 종합하면, 이 프레임워크의 중심은 Message 중심 아키텍처입니다.

• Agent는 입력 메시지를 받고 응답한다.
• Formatter는 메시지를 모델 API 포맷으로 바꾼다.
• Model은 reasoning을 수행한다.
• Toolkit은 tool call을 실행한다.
• Memory는 메시지를 저장하고 mark로 관리한다.
• Tracing은 각 단계의 실행을 관측한다.
• Pipeline/MsgHub는 멀티 에이전트 상호작용을 조정한다. (AgentScope)

이를 개발자 관점에서 다시 그리면 이런 구조에 가깝습니다.

이 구조에서 특히 눈에 띄는 점은 두 가지입니다.

첫째, ReAct 루프가 명확하게 분리되어 있습니다.
문서에서 AgentBase는 reply, observe, print를, ReActAgentBase는 _reasoning, _acting을 추가로 정의합니다. 즉, 에이전트 실행을 “생각”과 “행동”으로 나누어 훅과 추적을 걸기 좋은 구조입니다. (AgentScope)

둘째, 상태 관리가 중첩 가능하다는 점입니다.
문서의 key concepts는 agent, memory, long-term memory, toolkit 모두 stateful object라고 설명합니다. 이 말은 세션 저장, 복원, 사용자별 상태 분리에 꽤 유리하다는 뜻입니다. 실서비스에서 “사용자 A의 툴 상태”와 “사용자 B의 메모리 상태”를 따로 관리해야 할 때 도움이 됩니다. (AgentScope)

코드로 보는 사용 패턴

패턴 1: 단일 에이전트 + 툴 + 메모리

가장 먼저 추천하는 사용 방식입니다.

from agentscope.agent import ReActAgent
from agentscope.memory import InMemoryMemory
from agentscope.tool import Toolkit

toolkit = Toolkit()
toolkit.register_tool_function(get_weather)
toolkit.register_tool_function(search_docs)

agent = ReActAgent(
    name="DevAssistant",
    sys_prompt="너는 개발 문서 탐색을 도와주는 에이전트다.",
    model=model,
    formatter=formatter,
    memory=InMemoryMemory(),
    toolkit=toolkit,
    parallel_tool_calls=True,
)

문서 질의응답, 내부 운영 도구, Slack 보조 에이전트처럼 한 명의 유능한 작업자를 만들 때 적합합니다.

패턴 2: 라우터 + 전문 에이전트들

Routing 문서의 철학을 따라, 분기 판단은 structured output으로 두고 실제 작업은 각 전문 에이전트로 넘깁니다. (AgentScope)

class RouteDecision(BaseModel):
    target: Literal["code", "docs", "ops"]

decision = await router(
    Msg("user", user_query, "user"),
    structured_model=RouteDecision,
)

if decision.metadata["target"] == "code":
    result = await code_agent(Msg("user", user_query, "user"))
elif decision.metadata["target"] == "docs":
    result = await docs_agent(Msg("user", user_query, "user"))
else:
    result = await ops_agent(Msg("user", user_query, "user"))

고객지원, 사내 헬프데스크, 복합 SaaS 업무 자동화에 잘 맞습니다.

패턴 3: 오케스트레이터 + 워커

Handoffs 예제처럼, 상위 에이전트가 하위 워커를 생성하거나 호출하는 방식입니다. (AgentScope)

async def create_worker(task_description: str):
    worker = ReActAgent(
        name="Worker",
        sys_prompt=f"다음 작업만 정확히 수행해라: {task_description}",
        model=model,
        formatter=formatter,
        toolkit=toolkit,
    )
    return worker

이 패턴은 리서치, 코드 생성, 데이터 정리처럼 서브태스크 분해가 자연스러운 일에 강합니다.

이 프로젝트를 언제 쓰면 좋을까

AgentScope는 특히 다음 상황에서 강합니다.

첫째, 에이전트 데모가 아니라 에이전트 애플리케이션을 만들고 싶을 때입니다.
메모리, tracing, evaluation, studio, optional dependency 설계를 보면 애초에 운영을 고려하고 있습니다. (GitHub)

둘째, 멀티 에이전트 구조를 너무 무겁지 않게 가져가고 싶을 때입니다.
MsgHub, structured output routing, handoff 패턴은 학습 비용이 비교적 낮습니다. (AgentScope)

셋째, MCP나 A2A 같은 외부 프로토콜과 연결할 가능성이 있을 때입니다.
AgentScope는 이 부분을 “나중에 플러그인으로”가 아니라, 이미 프레임워크의 한 축으로 넣어 두었습니다. (AgentScope)

넷째, 음성/실시간 인터페이스까지 염두에 둘 때입니다.
요즘 많은 프레임워크가 여전히 텍스트 챗 중심인데, AgentScope는 realtime agent를 별도 모듈로 전개하고 있습니다. (GitHub)

아쉬운 점도 있다

좋은 점만 있는 건 아닙니다.

AgentScope는 범위가 넓습니다.
이 말은 곧 초기에 익혀야 할 개념도 많다는 뜻입니다. formatter, toolkit, memory mark, MsgHub, long_term_memory_mode, MCP client, A2AAgent 같은 용어가 한꺼번에 등장합니다. 문서가 잘 정리돼 있긴 하지만, 아주 작은 챗봇만 만들고 싶은 사람에게는 조금 무겁게 느껴질 수 있습니다. (AgentScope)

또 하나는, AgentScope의 철학이 모델의 자율성과 유연성 쪽에 있기 때문에, 워크플로를 매우 엄격하게 통제하고 싶다면 다른 방식의 프레임워크가 더 맞을 수도 있습니다. 반대로 말하면, AgentScope는 “모델이 꽤 잘해줄 것”을 전제로 설계된 영역이 분명히 있습니다. README도 rising model capability를 전제로 한 프레임워크라고 설명합니다. (GitHub)

정리

AgentScope를 한 문장으로 요약하면 이렇습니다.

“ReAct 중심의 에이전트 개발 경험을 유지하면서도, 멀티 에이전트·메모리·툴·프로토콜·관측성·평가까지 운영형 기능을 끌어안은 Python 프레임워크”

이 프로젝트가 흥미로운 이유는 단순히 기능이 많아서가 아닙니다.
기능들을 억지로 덕지덕지 붙인 것이 아니라, Message, Agent, Formatter, Toolkit, Memory라는 기본 추상화 위에 비교적 일관되게 쌓아 올렸기 때문입니다. 그 결과 “빠르게 시작”과 “깊게 확장” 사이의 균형이 꽤 좋습니다. (AgentScope)

에이전트 프로젝트를 이제 막 시작하는 팀이라면 단일 ReActAgent부터 시작해도 좋고, 이미 툴 체인과 멀티 에이전트 구조를 고민하는 팀이라면 Routing, Handoffs, MCP, Tracing까지 바로 이어갈 수 있습니다.

즉, AgentScope는 “장난감 데모를 넘어서는 순간”부터 진짜 매력이 보이는 프레임워크입니다.