AgentScope: A Flexible yet Robust Multi-Agent Platform
raw JSON → 1.0.18 verified Wed Apr 15 auth: no python
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.
pip install agentscope Common errors
error 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'.
error 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'.
error 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.
error 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 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[full] 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=...)correctimport agentscope; agentscope.init() - DialogAgent wrong
from agentscope.agents import DialogAgentcorrectUse ReActAgent or inherit from AgentBase
Quickstart
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())