6.3 Framework Two: AgentScope

If AutoGen's design philosophy is "driving collaboration through conversation," then AgentScope represents another technical path: engineering-first multi-agent platform. AgentScope, developed by Alibaba DAMO Academy, is specifically designed for building large-scale, highly reliable multi-agent applications. It not only provides an intuitive and easy-to-use programming interface but, more importantly, has built-in enterprise-level features such as distributed deployment, fault recovery, and observability, making it particularly suitable for building production environment applications that need to run stably for a long time.

6.3.1 Design of AgentScope

Compared with AutoGen, the core difference of AgentScope lies in its message-driven architectural design and industrial-grade engineering practices. If AutoGen is more like a flexible "conversation studio," then AgentScope is a complete "agent operating system," providing developers with full lifecycle support from development, testing to deployment. Unlike the inheritance-based design adopted by many frameworks, AgentScope chooses compositional architecture and message-driven mode. This design not only enhances the modularity of the system but also lays the foundation for its excellent concurrency performance and distributed capabilities.

(1) Layered Architecture System

As shown in Figure 6.2, AgentScope adopts a clear layered modular design, forming a complete agent development ecosystem from bottom-level basic components to top-level application orchestration.

Figure 6.2 AgentScope Architecture Diagram

In this architecture, the bottom layer is the Foundational Components layer, which provides core building blocks for the entire framework. The Message component defines a unified message format, supporting everything from simple text interaction to complex multimodal content; the Memory component provides short-term and long-term memory management; the Model API layer abstracts calls to different large language models; and the Tool component encapsulates the agent's ability to interact with the external world.

Above the basic components, the Agent-level Infrastructure layer provides higher-level abstractions. This layer not only includes various pre-built agents (such as browser-using agents, deep research agents) but also implements the classic ReAct paradigm, supporting advanced features such as agent hooks, parallel tool calling, and state management. Particularly noteworthy is that this layer natively supports asynchronous execution and real-time control, which is an important advantage of AgentScope compared to other frameworks.

The Multi-Agent Cooperation layer is where AgentScope's core innovation lies. MsgHub serves as the message center, responsible for message routing and state management between agents; while the Pipeline system provides flexible workflow orchestration capabilities, supporting various execution modes such as sequential and concurrent. This design allows developers to easily build complex multi-agent collaboration scenarios.

The top Deployment & Development layer reflects AgentScope's emphasis on engineering. AgentScope Runtime provides a production-grade runtime environment, while AgentScope Studio provides developers with a complete visual development toolchain.

(2) Message-Driven

AgentScope's core innovation lies in its message-driven architecture. In this architecture, all agent interactions are abstracted as the sending and receiving of messages, rather than traditional function calls.

from agentscope.message import Msg

# Standard structure of message
message = Msg(
    name="Alice",           # Sender name
    content="Hello, Bob!",  # Message content
    role="user",           # Role type
    metadata={             # Metadata information
        "timestamp": "2024-01-15T10:30:00Z",
        "message_type": "text",
        "priority": "normal"
    }
)

Using messages as the basic unit of interaction brings several key advantages:

• Asynchronous Decoupling: The sender and receiver of messages are decoupled in time, without needing to wait for each other, naturally supporting high-concurrency scenarios.
• Location Transparency: Agents do not need to care whether another agent is in a local process or on a remote server; the message system automatically handles routing.
• Observability: Every message can be logged, tracked, and analyzed, greatly simplifying debugging and monitoring of complex systems.
• Reliability: Messages can be persistently stored and retried. Even if the system fails, it can ensure the eventual consistency of interactions, improving the system's fault tolerance.

(3) Agent Lifecycle Management

In AgentScope, each agent has a clear lifecycle (initialization, running, pausing, destruction, etc.) and is implemented based on a unified base class AgentBase. Developers usually only need to focus on its core reply method.

from agentscope.agents import AgentBase

class CustomAgent(AgentBase):
    def __init__(self, name: str, **kwargs):
        super().__init__(name=name, **kwargs)
        # Agent initialization logic

    def reply(self, x: Msg) -> Msg:
        # Agent's core response logic
        response = self.model(x.content)
        return Msg(name=self.name, content=response, role="assistant")

    def observe(self, x: Msg) -> None:
        # Agent's observation logic (optional)
        self.memory.add(x)

This design pattern separates the agent's internal logic from external communication. Developers only need to define how the agent "thinks and responds" in the reply method.

(4) Message Passing Mechanism

AgentScope has a built-in Message Center (MsgHub), which is the hub of the entire message-driven architecture. MsgHub is not only responsible for message routing and distribution but also integrates advanced functions such as persistence and distributed communication. It has the following characteristics:

• Flexible Message Routing: Supports multiple communication modes such as point-to-point, broadcast, and multicast, and can build flexible and complex interaction networks.
• Message Persistence: Can automatically save all messages to databases (such as SQLite, MongoDB), ensuring that the state of long-running tasks can be recovered.
• Native Distributed Support: This is a signature feature of AgentScope. Agents can be deployed on different processes or servers, and MsgHub will automatically handle cross-node communication through RPC (Remote Procedure Call), completely transparent to developers.

These engineering capabilities provided by the underlying architecture make AgentScope more advantageous than traditional conversation-driven frameworks when handling complex application scenarios that require high concurrency and high reliability. Of course, this also requires developers to understand and adapt to the asynchronous programming paradigm of message-driven.

In the next section, we will deeply experience the capabilities of the AgentScope framework through a specific practical case, the Three Kingdoms Werewolf game, especially its advantages in handling concurrent interactions.

6.3.2 Three Kingdoms Werewolf Game

To deeply understand AgentScope's message-driven architecture and multi-agent collaboration capabilities, we will build a "Three Kingdoms Werewolf" game that integrates Chinese classical cultural elements. This case not only demonstrates AgentScope's advantages in handling complex multi-agent interactions but, more importantly, demonstrates how to fully leverage the power of message-driven architecture in a scenario that requires real-time collaboration, role-playing, and strategic gaming. Unlike traditional Werewolf, our "Three Kingdoms Werewolf" introduces classic characters such as Liu Bei, Guan Yu, and Zhuge Liang into the game. Each agent not only has to complete the basic tasks of Werewolf (such as werewolf killing, seer verification, villager reasoning) but also embodies the personality traits and behavior patterns of the corresponding Three Kingdoms characters. This design allows us to observe AgentScope's performance in handling multi-level role modeling.

(1) Architecture Design and Core Components

The system design of this case follows the principle of layered decoupling, dividing the game logic into three independent levels, each of which maps to one or more core components of AgentScope:

• Game Control Layer: A ThreeKingdomsWerewolfGame class serves as the main controller of the game, responsible for maintaining global state (such as player survival list, current game stage), advancing the game process (calling night phase, day phase), and judging victory or defeat.
• Agent Interaction Layer: Completely driven by MsgHub. All communication between agents, whether it's secret negotiations between werewolves or public debates during the day, is routed and distributed through the message center.
• Role Modeling Layer: Each player is an instance based on DialogAgent. Through carefully designed system prompts, we inject each agent with the dual identity of "game role" and "Three Kingdoms personality."

(2) Message-Driven Game Flow

The core design of this case is to use message-driven instead of state machine to manage the game flow. In traditional implementations, game phase transitions are usually controlled by a centralized state machine. In the AgentScope paradigm, the game flow is naturally modeled as a series of well-defined message interaction patterns.

For example, the implementation of the werewolf phase is not a simple function call but dynamically creates a temporary, private communication channel that only includes werewolf players through MsgHub:

async def werewolf_phase(self, round_num: int):
    """Werewolf phase - demonstrating message-driven collaboration mode"""
    if not self.werewolves:
        return None

    # Establish werewolf-exclusive communication channel through message center
    async with MsgHub(
        self.werewolves,
        enable_auto_broadcast=True,
        announcement=await self.moderator.announce(
            f"Werewolves, please discuss tonight's kill target. Surviving players: {format_player_list(self.alive_players)}"
        ),
    ) as werewolves_hub:
        # Discussion phase: werewolves exchange strategies through messages
        for _ in range(MAX_DISCUSSION_ROUND):
            for wolf in self.werewolves:
                await wolf(structured_model=DiscussionModelCN)

        # Voting phase: collect and count werewolves' kill decisions
        werewolves_hub.set_auto_broadcast(False)
        kill_votes = await fanout_pipeline(
            self.werewolves,
            msg=await self.moderator.announce("Please choose kill target"),
            structured_model=WerewolfKillModelCN,
            enable_gather=False,
        )

The advantage of this design is that game logic is clearly expressed as "in a specific context, what mode of message exchange to conduct," rather than a series of rigid state transitions. Day discussion (full broadcast), seer verification (point-to-point request), and other phases all follow the same design paradigm.

(3) Constraining Game Rules with Structured Output

A key challenge in Werewolf games is how to ensure that agent behavior conforms to game rules. AgentScope's structured output mechanism provides a solution to this problem. We define strict data models for different game behaviors:

class DiscussionModelCN(BaseModel):
    """Output format for discussion phase"""
    reach_agreement: bool = Field(
        description="Whether consensus has been reached",
        default=False
    )
    confidence_level: int = Field(
        description="Confidence level in current reasoning (1-10)",
        ge=1, le=10,
        default=5
    )
    key_evidence: Optional[str] = Field(
        description="Key evidence supporting your viewpoint",
        default=None
    )

class WitchActionModelCN(BaseModel):
    """Output format for witch action"""
    use_antidote: bool = Field(description="Whether to use antidote")
    use_poison: bool = Field(description="Whether to use poison")
    target_name: Optional[str] = Field(description="Poison target player name")

In this way, we not only ensure format consistency of agent output but, more importantly, achieve automated constraint of game rules. For example, the witch agent cannot use both antidote and poison on the same target at the same time, and the seer can only verify one player per night. These constraints are automatically executed through field definitions and validation logic of data models.

(4) Dual Challenge of Role Modeling

In this case, the most interesting technical challenge is how to make agents play two levels of roles well at the same time: game functional role (werewolf, seer, etc.) and cultural personality role (Liu Bei, Cao Cao, etc.). We solve this problem through prompt engineering:

def get_role_prompt(role: str, character: str) -> str:
    """Get role prompt - integrating game rules and character personality"""
    base_prompt = f"""You are {character}, playing {role} in this Three Kingdoms Werewolf game.

Important rules:
1. You can only participate in the game through dialogue and reasoning
2. Do not attempt to call any external tools or functions
3. Strictly reply in the required JSON format

Role characteristics:
"""

    if role == "Werewolf":
        return base_prompt + f"""
- You are in the werewolf camp, with the goal of eliminating all good people
- At night, you can negotiate with other werewolves on kill targets
- During the day, you must hide your identity and mislead good people
- Speak and act with {character}'s personality
"""

This design allows us to observe an interesting phenomenon: different Three Kingdoms characters, when playing the same game role, will exhibit completely different strategies and speech styles. For example, "Cao Cao" playing a werewolf may appear more cunning and good at disguise, while "Zhang Fei" playing a werewolf may appear more direct and impulsive.

(5) Concurrent Processing and Fault Tolerance Mechanism

AgentScope's asynchronous architecture plays an important role in this multi-agent game. The game often has scenarios that require simultaneously collecting decisions from multiple agents, such as the voting phase:

# Collect voting decisions from all players in parallel
vote_msgs = await fanout_pipeline(
    self.alive_players,
    await self.moderator.announce("Please vote to choose the player to eliminate"),
    structured_model=get_vote_model_cn(self.alive_players),
    enable_gather=False,
)

fanout_pipeline allows us to send the same message to all agents in parallel and asynchronously collect their responses. This not only improves the execution efficiency of the game but, more importantly, simulates the "simultaneous voting" scenario in real Werewolf games. At the same time, we add fault tolerance handling at key points:

try:
    response = await wolf(
        "Please analyze the current situation and express your viewpoint.",
        structured_model=DiscussionModelCN
    )
except Exception as e:
    print(f"⚠️ {wolf.name} error during discussion: {e}")
    # Create default response to ensure game continues
    default_response = DiscussionModelCN(
        reach_agreement=False,
        confidence_level=5,
        key_evidence="Unable to analyze temporarily"
    )

This design ensures that even if an agent encounters an exception, the entire game process can continue.

(6) Case Output and Summary

To more intuitively experience AgentScope's operating mechanism, the following is a real running log excerpt from the game's night phase, showing the process of two werewolf agents playing "Sun Quan" and "Zhou Yu" conducting secret negotiations and executing a kill.

🎮 Welcome to Three Kingdoms Werewolf!

=== Game Initialization ===
Game Moderator: 📢 【Sun Quan】You are playing a werewolf in this Three Kingdoms Werewolf game, your character is Sun Quan. You can kill a player at night
Game Moderator: 📢 【Zhou Yu】You are playing a werewolf in this Three Kingdoms Werewolf game, your character is Zhou Yu. You can kill a player at night
...

Game Moderator: 📢 Three Kingdoms Werewolf game begins! Participants: Sun Quan, Zhou Yu, Cao Cao, Zhang Fei, Sima Yi, Zhao Yun
✅ Game setup complete, 6 players in total

=== Round 1 ===
🌙 Night 1 falls, everyone close your eyes...

【Werewolf Phase】
Game Moderator: 📢 🐺 Werewolves please open your eyes, choose tonight's kill target...
Game Moderator: 📢 Werewolves, please discuss tonight's kill target. Surviving players: Sun Quan, Zhou Yu, Cao Cao, Zhang Fei, Sima Yi, Zhao Yun

Sun Quan: Tonight we should eliminate Zhou Yu, this person is extremely intelligent and poses a great threat to us.
Zhou Yu: Sun Quan, you make a good point. But although Zhou Yu is intelligent, he may not be the biggest threat tonight. Cao Cao has great power, if we don't eliminate him early, it may be unfavorable to us.
Sun Quan: Cao Cao is indeed a threat, but if Zhou Yu lives, he can see through our schemes. Better to solve the immediate hidden danger first.
Zhou Yu: Sun Quan, your concern is not without reason. But if Cao Cao becomes our enemy, he can unite other forces to pose a greater threat to us.
Sun Quan: What you say also makes sense, Cao Cao's alliance is indeed troublesome. Then let's deal with Cao Cao first.
Zhou Yu: Very good, Sun Quan. Cao Cao is our primary target tonight.

Game Moderator: 📢 Please choose kill target
Sun Quan: I agree, Cao Cao must be eliminated.
Zhou Yu: I agree, Cao Cao is the target we need to solve tonight.

【Seer Phase】
Game Moderator: 📢 🔮 Seer please open your eyes, choose the player to verify...
Cao Cao: I want to verify Sun Quan.
Game Moderator: 📢 Verification result: Sun Quan is a werewolf

【Witch Phase】
Game Moderator: 📢 🧙‍♀️ Witch please open your eyes...
Game Moderator: 📢 Tonight Cao Cao was killed by werewolves
Zhang Fei: I used the antidote to save Cao Cao last night, now the antidote has been used up.
Game Moderator: 📢 You used the antidote to save Cao Cao

Game Moderator: 📢 Last night was peaceful, no one died.

【Day Discussion Phase】
Game Moderator: 📢 ☀️ Day 1 dawns, everyone please open your eyes...
Game Moderator: 📢 Now begin free discussion. Surviving players: Sun Quan, Zhou Yu, Cao Cao, Zhang Fei, Sima Yi, Zhao Yun

Sun Quan: Everyone, Cao Cao has great power and is a potential threat to us all. Tonight I suggest we concentrate our forces against him.
Zhou Yu: Sun Quan is absolutely right, Cao Cao is not only powerful himself but may also ally with other players, posing a greater threat to us.
Cao Cao: I verified Sun Quan last night, originally thought he was a good person, but the game moderator's result was werewolf. This means there's a werewolf lying.
Zhang Fei: I did save Cao Cao last night, indicating he was attacked by werewolves. But Cao Cao's verification result of Sun Quan is suspicious.
Sima Yi: There seems to be a contradiction between Cao Cao's verification result and Zhang Fei's saving action, we need more information to determine who is the werewolf.
Zhao Yun: The situation is indeed complex, we need to carefully analyze everyone's statements.

【Voting Phase】
Game Moderator: 📢 Please vote to choose the player to eliminate

Sun Quan: Cao Cao's threat is still great, I insist we should vote for him.
Zhou Yu: Based on last night's situation, I think we should vote for Cao Cao first, his threat is the greatest.
Cao Cao: I choose to vote for Sun Quan. According to the game moderator's feedback, Sun Quan is indeed a werewolf.
Zhang Fei: I insist on the fact that I saved Cao Cao last night, but the fact that Sun Quan was found to be a werewolf confuses me.
Sima Yi: We need more information to determine who is the werewolf.

[Game continues...]

6.3.3 Analysis of AgentScope's Advantages and Limitations

Through this "Three Kingdoms Werewolf" case, we deeply experienced the core advantages of the AgentScope framework. The framework, with its message-driven architecture as the core, elegantly maps complex game processes into a series of concurrent, asynchronous message passing events, thereby avoiding the rigidity and complexity of traditional state machines. Combined with its powerful structured output capability, we directly transform game rules into code-level constraints, greatly improving system stability and predictability. This design paradigm not only demonstrates its native concurrency advantages in performance but also ensures that even if a single agent encounters an exception, the overall process can run robustly in fault tolerance handling.

However, AgentScope's engineering advantages also bring a certain complexity cost. Although its message-driven architecture is powerful, it has high technical requirements for developers, requiring understanding of asynchronous programming, distributed communication, and other concepts. For simple multi-agent conversation scenarios, this architecture may seem overly complex, with the risk of "over-engineering." In addition, as a relatively new framework, its ecosystem and community resources still need further improvement. Therefore, AgentScope is more suitable for building large-scale, highly reliable production-level multi-agent systems, while for rapid prototype development or simple application scenarios, choosing a more lightweight framework may be more appropriate.