AgentScope: A Flexible yet Robust Multi-Agent Platform

1.0.18 · active · verified Wed Apr 15

AgentScope is an open-source Python framework for building and running large language model (LLM) based multi-agent systems. It emphasizes clear abstractions, modular design, and efficient communication between agents, enabling structured, scalable, and production-ready AI applications. The library is actively developed with frequent releases, currently at version 1.0.18, and supports Python 3.10 and higher.

Common errors

```
ModuleNotFoundError: No module named 'agentscope'
```
cause The 'agentscope' package is not installed or not available in the current Python environment.

fix Install the package using 'pip install agentscope'.
```
ImportError: cannot import name 'ReActAgent' from 'agentscope.agent'
```
cause The 'ReActAgent' class is not found in the 'agentscope.agent' module, possibly due to a version mismatch or incorrect import.

fix Ensure you are using the correct import statement: 'from agentscope.agent import ReActAgent'.
```
TimeoutError: Runtime service did not start within the specified timeout.
```
cause The AgentScope runtime service failed to start within the expected time, possibly due to configuration issues or resource constraints.

fix Check the runtime logs for errors and ensure all required services are properly configured and running.
```
docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
```
cause The Docker Python SDK cannot connect to the Docker service, often due to misconfigured Docker host settings.

fix Set the 'DOCKER_HOST' environment variable to point to the correct Docker socket, e.g., 'export DOCKER_HOST=unix://$HOME/.colima/docker.sock'.
```
Error: 'No AgentApp found in agent.py'
```
cause The 'agent.py' file does not export an 'AgentApp' instance or the required function.

fix Ensure your 'agent.py' file exports an 'agent_app' or 'app' variable, or a 'create_app()' function.

Warnings

breaking AgentScope v1.0.0 introduced a significant refactoring. Model configuration via `agentscope.init(model_configs=...)` is deprecated. Users must now instantiate model objects (e.g., `OpenAIChatModel`) explicitly and pass them to agents. Similarly, `DialogAgent` and `DictDialogAgent` are deprecated; use `ReActAgent` or inherit from `AgentBase`.
Fix: Remove `agentscope.init(model_configs=...)`. Create model instances directly (e.g., `model = OpenAIChatModel(...)`) and pass them as arguments to agent constructors. Replace `DialogAgent` with `ReActAgent` or a custom agent inheriting from `AgentBase`.
gotcha Many advanced features, such as specific model integrations (e.g., DashScope, Anthropic, Ollama), RAG capabilities (e.g., Milvus, MongoDB), or Redis memory, require installing optional dependencies using `pip install agentscope[feature]` or `pip install agentscope[full]`.
Fix: Consult the official documentation for the specific feature you intend to use and install the corresponding extra dependency, or use `pip install agentscope[full]` to cover common optional requirements.
gotcha AgentScope v1.0+ is designed around asynchronous execution. Most agent and model interactions are `await`-able. Users familiar with synchronous Python might encounter `TypeError: 'coroutine' object is not awaited` if they don't use `async/await` correctly.
Fix: Ensure that agent `reply` methods and other asynchronous calls are prefixed with `await`, and that your application runs within an `asyncio` event loop (e.g., `asyncio.run(main())`).
gotcha API keys for LLMs (e.g., OpenAI, DashScope) are typically expected to be set as environment variables (e.g., `OPENAI_API_KEY`, `DASHSCOPE_API_KEY`). Failing to set these will result in authentication errors when models attempt to make API calls.
Fix: Set the appropriate API key environment variable before running your AgentScope application, or pass the API key directly to the model constructor if supported and preferred.
gotcha When using streaming models and tools, specific parsing behaviors can be controlled. For instance, in v1.0.14, the `stream_tool_parsing=False` option was introduced to disable tool use input parsing in streaming mode, which might be necessary for certain scenarios or to fix unexpected behavior.
Fix: If encountering unexpected tool parsing behavior during streaming, investigate model or agent constructor parameters for options like `stream_tool_parsing` to fine-tune parsing logic.
gotcha Memory management and session persistence in AgentScope (e.g., using Redis, relational databases, or Mem0 for long-term memory) can have specific setup requirements and potential bug fixes across versions. Inconsistent memory configurations or outdated dependencies for memory backends can lead to data loss or runtime errors.
Fix: Regularly check release notes and documentation for updates regarding memory module fixes and best practices. Ensure all necessary database drivers or client libraries are installed and configured correctly for your chosen memory backend.

Install

pip install agentscope Basic Installation
pip install agentscope[full] Installation with common dependencies (models, tools)

Imports

ReActAgent
```
from agentscope.agent import ReActAgent
```
UserAgent
```
from agentscope.agent import UserAgent
```

DashScopeChatModel

from agentscope.model import DashScopeChatModel

OpenAIChatModel

from agentscope.model import OpenAIChatModel

DashScopeChatFormatter

from agentscope.formatter import DashScopeChatFormatter

OpenAIChatFormatter

from agentscope.formatter import OpenAIChatFormatter

Msg
```
from agentscope.message import Msg
```

InMemoryMemory

from agentscope.memory import InMemoryMemory

init
wrong:
```
agentscope.init(model_configs=...)
```
correct:
```
import agentscope; agentscope.init()
```
As of v1.0.0, model configuration via `init` is deprecated; instantiate model objects directly.
DialogAgent
wrong:
```
from agentscope.agents import DialogAgent
```
correct:
```
Use ReActAgent or inherit from AgentBase
```
Deprecated in v1.0.0; use `ReActAgent` or `AgentBase` for custom agents.

Quickstart

This example demonstrates a basic conversation between a `UserAgent` and a `ReActAgent` using an OpenAI model. It showcases how to initialize a model with an API key (from an environment variable) and instantiate agents directly, then run an asynchronous conversation loop. The example assumes `OPENAI_API_KEY` is set.

import os
import asyncio
from agentscope.agent import ReActAgent, UserAgent
from agentscope.model import OpenAIChatModel
from agentscope.formatter import OpenAIChatFormatter
from agentscope.message import Msg

async def main():
    # Set your OpenAI API key as an environment variable
    # export OPENAI_API_KEY="your_api_key_here"
    if not os.environ.get("OPENAI_API_KEY"):
        print("Please set the OPENAI_API_KEY environment variable.")
        return

    # Initialize the model
    model = OpenAIChatModel(
        model_name="gpt-4o", # or "gpt-3.5-turbo"
        api_key=os.environ.get("OPENAI_API_KEY", ""),
        formatter=OpenAIChatFormatter()
    )

    # Create a ReAct agent and a User agent
    # Note: As of v1.0.0, agentscope.init(model_configs=...) is deprecated.
    # Instantiate models and pass them directly to agents.
    assistant = ReActAgent(
        name="Assistant",
        model=model,
        sys_prompt="You are a helpful AI assistant. Always be polite."
    )
    user = UserAgent(name="User")

    print("\n--- Start Conversation ---")
    x = None
    while True:
        x = await assistant.reply(x)
        x = await user.reply(x)
        if x.content.lower() == "exit":
            break
    print("--- End Conversation ---")

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

view raw JSON →