Getting Started with AgentScope: Build Your First Multi-Agent App

If you’ve been searching for a structured way to get started with AgentScope and build your first multi-agent app, this guide walks you through everything from installation to a working conversation loop. AgentScope is a Python framework designed to simplify the development of multi-agent systems — applications where multiple AI agents collaborate, communicate, and reason together to solve complex tasks. Whether you’re building a research assistant, a coding helper, or an orchestrated workflow, AgentScope gives you the primitives to wire it all up cleanly.

What is AgentScope?

AgentScope is an open-source agent framework built around a fully asynchronous runtime. Unlike simpler LLM wrappers, it treats agents as first-class citizens with their own memory, toolkits, and communication channels.

Its key design goals are:

• Agent-centric architecture — each agent is an independent actor with a model, memory, and tool access
• Multi-agent orchestration — a built-in MsgHub handles message routing between agents
• Tool extensibility — agents can call Python functions, external APIs, or MCP-based services
• Async-first — the entire framework is asynchronous since v1.0.0, enabling efficient parallel execution

If you want to understand the broader landscape of agent reasoning patterns, the ReAct: Reasoning and Acting — The Paper Behind Agent Frameworks article covers the conceptual foundation that AgentScope’s ReActAgent builds on.

AgentScope is particularly well-suited for scenarios where you need agents to pass messages back and forth, share context, and delegate subtasks — which maps directly to real-world workflows like code review pipelines, research summarizers, or conversational assistants with tool use.

Setting Up Your Environment

Prerequisites

Before installing AgentScope, make sure you have Python 3.10 or higher installed. You can verify your version with:

python --version

It is strongly recommended to use a virtual environment to isolate your project dependencies:

python -m venv agentscope-env
source agentscope-env/bin/activate  # On Windows: agentscope-env\Scripts\activate

Installing AgentScope

Install the package using pip:

pip install agentscope

That’s the only required installation step. All core components — agents, memory, toolkits, and message hubs — are bundled in the agentscope package.

Configuring API Keys

AgentScope supports multiple model backends. This guide uses DashScope (Alibaba Cloud’s LLM API), which requires the DASHSCOPE_API_KEY environment variable. Set it in your shell before running any scripts:

export DASHSCOPE_API_KEY="your-api-key-here"

On Windows (PowerShell):

$env:DASHSCOPE_API_KEY = "your-api-key-here"

If you’re using a different model provider, AgentScope’s model layer is abstracted, so you can swap in other backends by instantiating a different model class.

Core Concepts of AgentScope

Understanding AgentScope’s building blocks will make your code much easier to reason about before you start wiring things together.

Agents

Agents are the fundamental actors in AgentScope. Each agent encapsulates a model, optional memory, and an optional toolkit. The two most important built-in agent types are:

• ReActAgent — an agent that uses the ReAct pattern (Reason + Act) to decide when to call tools and when to respond directly. It is the go-to choice for tool-using agents.
• UserAgent — a thin wrapper that reads input from the human user, making it easy to interleave human and AI turns in a conversation.

Toolkit and Tools

A Toolkit is a container that manages the functions an agent is allowed to call. You register tool functions into the toolkit, and the agent’s model decides when and how to invoke them.

AgentScope provides built-in tools like execute_python_code, which allows agents to write and run Python code dynamically — similar to how tools work in AutoGen Code Execution: Build Agents That Write and Run Code.

Memory

Memory gives agents persistence within a session. InMemoryMemory stores the conversation history in RAM for the duration of the process. For production use cases that need persistence across restarts, LongTermMemoryBase provides the interface to extend into database-backed storage.

MsgHub

The MsgHub is the orchestration layer for multi-agent communication. Instead of manually passing messages between agents, you register all participants in a MsgHub, and it manages routing, ordering, and broadcast semantics. This is essential when you have more than two agents and need structured coordination.

For a deeper look at how multi-agent topologies differ architecturally, see Multi-Agent Architecture Topologies: Centralized vs Distributed.

Building a Multi-Agent Application

Now let’s put it all together. The following example builds a minimal but complete multi-agent application: a human user interacts with a ReActAgent that has access to a Python code execution tool.

Step 1 — Imports

import asyncio
from agentscope.agent import ReActAgent, UserAgent
from agentscope.model import DashScopeChatModel
from agentscope.memory import InMemoryMemory
from agentscope.tool import Toolkit, execute_python_code

Step 2 — Configure the Model, Toolkit, and Memory

# Initialize the language model
model = DashScopeChatModel(api_key="YOUR_API_KEY")

# Create a toolkit and register the code execution tool
toolkit = Toolkit()
toolkit.register_tool_function(execute_python_code)

# Initialize shared in-memory storage for the agent
memory = InMemoryMemory()

Replace "YOUR_API_KEY" with your actual DashScope API key, or load it from the environment variable:

import os
model = DashScopeChatModel(api_key=os.environ["DASHSCOPE_API_KEY"])

Step 3 — Initialize the Agents

# The AI assistant with reasoning and tool access
assistant_agent = ReActAgent(
    name="assistant",
    model=model,
    memory=memory,
    toolkit=toolkit
)

# The human-in-the-loop agent (reads from stdin)
user_agent = UserAgent()

The name parameter is used in message routing and logging, so give your agents meaningful identifiers when building larger systems.

Step 4 — Run the Conversation Loop

Because AgentScope v1.0.0 is fully asynchronous, the conversation loop must run inside an async function and be executed with asyncio.run():

async def main():
    msg = None

    while True:
        # Assistant processes the latest message and responds
        msg = await assistant_agent(msg)

        # User reads the assistant's reply and provides input
        msg = await user_agent(msg)

        # Exit condition: user types "exit"
        if msg.get_text_content().strip().lower() == "exit":
            print("Conversation ended.")
            break

if __name__ == "__main__":
    asyncio.run(main())

Full Working Example

Here is the complete script in one block, ready to copy and run:

import asyncio
import os

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


async def main():
    # Setup
    model = DashScopeChatModel(api_key=os.environ["DASHSCOPE_API_KEY"])
    toolkit = Toolkit()
    toolkit.register_tool_function(execute_python_code)
    memory = InMemoryMemory()

    # Agents
    assistant_agent = ReActAgent(
        name="assistant",
        model=model,
        memory=memory,
        toolkit=toolkit,
    )
    user_agent = UserAgent()

    # Conversation loop
    msg = None
    while True:
        msg = await assistant_agent(msg)
        msg = await user_agent(msg)
        if msg.get_text_content().strip().lower() == "exit":
            print("Session ended.")
            break


if __name__ == "__main__":
    asyncio.run(main())

Run the script with:

python main.py

You will see the assistant waiting for your first message. Type a coding question or ask it to compute something, and the agent will reason through it using the ReAct loop — deciding whether to call execute_python_code or respond directly.

Important Migration Notes (v1.0.0)

If you find older AgentScope tutorials online, be aware of these breaking changes introduced in v1.0.0:

• DialogAgent and DictDialogAgent are deprecated — use ReActAgent instead
• Model configuration files are deprecated — instantiate model objects directly (as shown above)
• All agent calls are now async and must be await-ed
• The RAG and Distribution modules are temporarily deprecated and being reworked
• The WebBrowser class is deprecated in favor of MCP-based tool integrations

Always check the installed version matches the documentation you’re reading:

pip show agentscope

Frequently Asked Questions

Does AgentScope work with models other than DashScope?

Yes. AgentScope abstracts the model layer, so you can instantiate different model classes for different providers. The DashScopeChatModel used in this guide is one option; other backends are available depending on your preferred API. Swap the model class while keeping the rest of your agent setup identical.

Why do I need await before every agent call?

Since v1.0.0, AgentScope is fully asynchronous. This design allows multiple agents to run concurrently without blocking each other, which is critical for performance in complex multi-agent pipelines. If you try to call an agent without await, the coroutine will not execute — you will get a coroutine object instead of a message response.

What is the difference between ReActAgent and UserAgent?

ReActAgent is an AI-powered agent that uses the ReAct reasoning loop to decide whether to call a tool or respond with text. UserAgent is a thin wrapper that collects input from a human via the terminal. In a typical setup, they alternate turns: the AI responds, the human replies, and so on.

Can I add my own custom tools to the Toolkit?

Yes. Any Python function can be registered as a tool using toolkit.register_tool_function(your_function). The function’s docstring and type annotations are used by the model to understand when and how to call it. Keep your functions focused and well-documented for best results.

What is MsgHub used for, and when do I need it?

MsgHub is AgentScope’s multi-agent orchestration layer. In the two-agent example above, you pass messages manually between agents in a loop. Once you add a third, fourth, or fifth agent, manual routing becomes error-prone. MsgHub manages the list of participants and handles message broadcasting and sequential routing automatically, making it the right tool for larger pipelines.