Understanding AgentScope

What is AgentScope?

AgentScope is a production-ready, enterprise-grade open-source framework for building multi-agent applications with large language models. Its functionalities cover:

Development

ReAct agent, context compression, short/long-term memory, tool use, human-in-the-loop, multi-agent orchestration, agent hooks, structured output, planning, integration with MCP, agent skill, LLMs API, voice interaction (TTS/Realtime), RAG

Evaluation

Evaluate multistep agentic applications with statistical analysis

Training

Agentic reinforcement learning

Deployment

Session/state management, sandbox, local/serverless/Kubernetes deployment Installation pip install agentscope

or

uv pip

install

agentscope

Core Concepts

Message

The core abstraction for information exchange between agents. Supports heterogeneous content blocks (text, images, tool calls, tool results).

from

agentscope

.

message

import

Msg

,

TextBlock

,

ImageBlock

,

URLSource

msg

=

Msg

(

name

=

"user"

,

content

=

[

TextBlock

(

"Hello world"

)

,

ImageBlock

(

type

=

"image"

,

source

=

URLSource

(

type

=

"url"

,

url

=

"..."

)

)

]

,

role

=

"user"

)

Agent

LLM-empowered agent that can reason, use tools, and generate responses through iterative thinking and action loops.

Toolkit

Register and manage tools (Python functions, MCP, agent skills) that agents can call.

Memory

Store

Msg

objects as conversation history/context with a marking mechanism for advanced memory management (compression, retrieval).

ChatModel

Unified interface across different providers (OpenAI, Anthropic, DashScope, Ollama, etc.) with support for tool use and streaming.

Formatter

Convert Msg objects to LLM API-specific formats. Must be used with the corresponding ChatModel. Supports multi-agent conversations with different agent identifiers. Basic Usage Examples Example 1: Simple Chatbot 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 import os , asyncio async def main ( ) :

Initialize toolkit with tools

toolkit

Toolkit ( ) toolkit . register_tool_function ( execute_python_code ) toolkit . register_tool_function ( execute_shell_command )

Create ReActAgent with model, memory, formatter, and toolkit

agent

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

Create user agent for terminal input

user

UserAgent ( name = "user" )

Conversation loop

msg

None while True : msg = await agent ( msg )

Agent processes and replies

msg

await user ( msg )

User inputs next message

if msg . get_text_content ( ) == "exit" : break asyncio . run ( main ( ) ) Example 2: Multi-Agent Conversation AgentScope adopts explicit message passing for multi-agent conversations (PyTorch-like dynamic graph), allowing flexible information flow control. alice , bob , carol , david = ReActAgent ( . . . ) , ReActAgent ( . . . ) , ReActAgent ( . . . ) , ReActAgent ( . . . ) msg_alice = await alice ( ) msg_bob = await bob ( msg_alice )

Bob receives Alice's message and generate a reply. Alice doesn't receive Bob's message unless explicitly passed back.

msg_carol

await carol ( msg_alice )

Similarly, the agent cannot receive messages from other agents unless explicitly passed.

Broadcasting with MsgHub, a syntactic sugar for message broadcasting within a group of agents

from agentscope . pipeline import MsgHub async with MsgHub ( participants = [ alice , bob , carol ] , announcement = Msg ( "Host" , "Let's discuss" , "user" ) ) as hub : await alice ( )

Bob and Carol receive this

await bob ( )

Alice and Carol receive this

Manual broadcast

await hub . broadcast ( Msg ( "Host" , "New topic" , "user" ) )

Dynamic participant management

hub . add ( david ) hub . delete ( bob ) Example 3: Master-Worker Pattern Wrap worker agents as tools for the master agent. from agentscope . tool import ToolResponse , Toolkit async def create_worker ( task : str ) -

ToolResponse : """Create a worker agent for the given task. Args: task (str): The given task, which should be specific and concise. """ task_msg = Msg ( name = "master" , content = task , role = "user" )

Use the input task or wrap it into a more complex prompt

worker

ReActAgent ( . . . ) res = await worker ( task_msg ) return ToolResponse ( content = res . content )

Return the worker's response as the tool response

toolkit

Toolkit

(

)

toolkit

.

register_tool_function

(

create_worker

)

Working with AgentScope

This section provides guidance on how to effectively answer questions about AgentScope or coding with the framework.

Step 1: Clone the Repository First

CRITICAL

Before doing anything else, clone or update the AgentScope repository. The repository contains essential examples and references.

Clone into this skill directory so that you can refer to it across different sessions

cd /path/to/this/skill/directory git clone -b main https://github.com/agentscope-ai/agentscope.git

Or update if already cloned

cd

/path/to/this/skill/directory/agentscope

git

pull

Why this matters

The repository contains working examples, complete API documentation in source code, and implementation patterns that are more reliable than guessing.

Step 2: Understand the Repository Structure

The cloned repository is organized as follows. Note this may be outdated as the project evolves, you should always check the actual structure after cloning.

agentscope/

├── src/agentscope/ # Main library source code

│ ├── agent/ # Agent implementations (ReActAgent, etc.)

│ ├── model/ # LLM API wrappers (OpenAI, Anthropic, DashScope, etc.)

│ ├── formatter/ # Message formatters for different models

│ ├── memory/ # Memory implementations

│ ├── tool/ # Tool management and built-in tools

│ ├── message/ # Msg class and content blocks

│ ├── pipeline/ # Multi-agent orchestration (MsgHub, etc.)

│ ├── session/ # Session/state management

│ ├── mcp/ # MCP integration

│ ├── rag/ # RAG functionality

│ ├── realtime/ # Realtime voice interaction

│ ├── tts/ # Text-to-speech

│ ├── evaluate/ # Evaluation tools

│ └── ... # Other modules

│

├── examples/ # Working examples organized by category

│ ├── agent/ # Different agent types

│ │ └── ...

│ ├── workflows/ # Multi-agent workflows

│ │ └── ...

│ ├── functionality/ # Specific features

│ │ └── ...

│ ├── deployment/ # Deployment patterns

│ ├── integration/ # Third-party integrations

│ ├── evaluation/ # Evaluation examples

│ └── game/ # Game examples (e.g., werewolves)

│

├── docs/ # Documentation

│ ├── tutorial/ # Tutorial markdown files

│ ├── changelog.md # Version history

│ └── roadmap.md # Development roadmap

│

└── tests/ # Test files

Step 3: Browse Examples by Category

When looking for similar implementations,

browse the examples directory by category

rather than searching by keywords alone:

Start with the category

that matches your use case:

Building a specific agent type? →

examples/agent/

Multi-agent system? →

examples/workflows/

Need a specific feature (MCP, RAG, session)? →

examples/functionality/

Deployment patterns? →

examples/deployment/

List the subdirectories

to see what's available:

Use file listing tools to explore directory structure

Read directory names to understand what each example covers

Read example files

to understand implementation patterns:

Most examples contain a main script and supporting files

Look for README files in subdirectories for explanations

Combine with text search

when needed:

After identifying relevant directories, search within them for specific patterns

Search for class names, method calls, or specific functionality

Example workflow

:

User asks: "Build a FastAPI app with AgentScope"

→ Browse: List files in examples/deployment/

→ Check: Are there any web service examples?

→ Search: Look for "fastapi", "flask", "api", "server" in examples/

→ Read: Found examples and adapt to user's needs

Step 4: Verify Functionality Exists

Before implementing custom solutions, verify if AgentScope already provides the functionality:

List required functionalities

(e.g., session management, MCP integration, RAG)

Check if provided

:

Browse

examples

for examples

Search tutorial documentation in

docs/tutorial/

Use the provided scripts (see Part 3) to explore API structure

Read source code in

src/agentscope/

for implementation details

If not provided

Check how to customize by reading base classes and inheritance patterns in source code

Step 5: Make a Plan

Always create a plan before coding:

Identify what AgentScope components you'll use

Determine what needs custom implementation

Outline the architecture and data flow

Consider edge cases and error handling

Step 6: Code with API Reference

When writing code:

Check docstrings and arguments

before using any class/method

Read source code files to see signatures and documentation, or

Use the provided scripts to view module/class structures

NEVER

make up classes, methods, or arguments

Check parent classes

- A class's functionality includes inherited methods

Manage lifecycle

- Clean up resources when needed (close connections, release memory)

Common Pitfalls to Avoid

❌ Guessing API signatures without checking documentation

❌ Implementing features that already exist in AgentScope

❌ Mixing incompatible Model and Formatter (e.g., OpenAI model with DashScope formatter)

❌ Forgetting to await async agent calls

❌ Not checking parent class methods when searching for functionality

❌ Searching by keywords only without browsing the organized examples directory structure

Resources

This section lists all available resources for working with AgentScope.

Official Documentation

Tutorial

Comprehensive step-by-step guide covering most functionalities in detail. This is the primary resource for learning AgentScope.

GitHub Resources

Main Repository

Source code, examples, and documentation

Project Board

Official development roadmap and task tracking

Design Discussions

In-depth explanations about specific modules/functions/components

Repository Structure

When the repository is cloned locally, the following structure is available for reference:

src/agentscope/

Main library source code

Read this for API implementation details

Check docstrings for parameter descriptions

Understand inheritance hierarchies

examples/

Working examples demonstrating features

Start here when building similar applications

Examples cover: basic agents, multi-agent systems, tool usage, deployment patterns

docs/tutorial/

Tutorial documentation source files

Markdown files explaining concepts and usage

More detailed than README files

Scripts

Located in

scripts/

directory of this skill.

view_pypi_latest_version.sh

View the latest version of AgentScope on PyPI.

cd

/path/to/this/skill/directory/scripts/

bash

view_pypi_latest_version.sh

view_module_signature.py

Explore the structure of AgentScope modules, classes, and methods.

Search strategy

Use deep-first search - start broad, then narrow down: agentscope → see all submodules agentscope.agent → see agent-related classes agentscope.agent.ReActAgent → see specific class methods cd /path/to/this/skill/directory/scripts/

View top-level module

python view_module_signature.py --module agentscope

View specific submodule

python view_module_signature.py --module agentscope.agent

View specific class

python view_module_signature.py

--module

agentscope.agent.ReActAgent

Reference

Located in

references/

directory of this skill.

multi_agent_orchestration.md

Multi-agent orchestration concepts and implementation

deployment_guide.md

Deployment patterns and best practices