{"id":6503,"library":"agentscope","title":"AgentScope: A Flexible yet Robust Multi-Agent Platform","description":"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.","status":"active","version":"1.0.18","language":"en","source_language":"en","source_url":"https://github.com/agentscope-ai/agentscope","tags":["AI agents","multi-agent systems","LLM framework","agentic workflow","ReAct"],"install":[{"cmd":"pip install agentscope","lang":"bash","label":"Basic Installation"},{"cmd":"pip install agentscope[full]","lang":"bash","label":"Installation with common dependencies (models, tools)"}],"dependencies":[{"reason":"Required runtime environment","package":"python","optional":false},{"reason":"For using OpenAI models (included in [full])","package":"openai","optional":true},{"reason":"For using Alibaba Cloud DashScope models (included in [full])","package":"dashscope","optional":true},{"reason":"For using Anthropic models (included in [full])","package":"anthropic","optional":true},{"reason":"For using Ollama models (included in [full])","package":"ollama","optional":true},{"reason":"For Milvus vector database in RAG module","package":"pymilvus","optional":true},{"reason":"For Redis-based session and memory management","package":"redis","optional":true},{"reason":"For deploying agents as API services, secure sandboxing, and scalable deployment","package":"agentscope-runtime","optional":true}],"imports":[{"symbol":"ReActAgent","correct":"from agentscope.agent import ReActAgent"},{"symbol":"UserAgent","correct":"from agentscope.agent import UserAgent"},{"symbol":"DashScopeChatModel","correct":"from agentscope.model import DashScopeChatModel"},{"symbol":"OpenAIChatModel","correct":"from agentscope.model import OpenAIChatModel"},{"symbol":"DashScopeChatFormatter","correct":"from agentscope.formatter import DashScopeChatFormatter"},{"symbol":"OpenAIChatFormatter","correct":"from agentscope.formatter import OpenAIChatFormatter"},{"symbol":"Msg","correct":"from agentscope.message import Msg"},{"symbol":"InMemoryMemory","correct":"from agentscope.memory import InMemoryMemory"},{"note":"As of v1.0.0, model configuration via `init` is deprecated; instantiate model objects directly.","wrong":"agentscope.init(model_configs=...)","symbol":"init","correct":"import agentscope; agentscope.init()"},{"note":"Deprecated in v1.0.0; use `ReActAgent` or `AgentBase` for custom agents.","wrong":"from agentscope.agents import DialogAgent","symbol":"DialogAgent","correct":"Use ReActAgent or inherit from AgentBase"}],"quickstart":{"code":"import os\nimport asyncio\nfrom agentscope.agent import ReActAgent, UserAgent\nfrom agentscope.model import OpenAIChatModel\nfrom agentscope.formatter import OpenAIChatFormatter\nfrom agentscope.message import Msg\n\nasync def main():\n    # Set your OpenAI API key as an environment variable\n    # export OPENAI_API_KEY=\"your_api_key_here\"\n    if not os.environ.get(\"OPENAI_API_KEY\"):\n        print(\"Please set the OPENAI_API_KEY environment variable.\")\n        return\n\n    # Initialize the model\n    model = OpenAIChatModel(\n        model_name=\"gpt-4o\", # or \"gpt-3.5-turbo\"\n        api_key=os.environ.get(\"OPENAI_API_KEY\", \"\"),\n        formatter=OpenAIChatFormatter()\n    )\n\n    # Create a ReAct agent and a User agent\n    # Note: As of v1.0.0, agentscope.init(model_configs=...) is deprecated.\n    # Instantiate models and pass them directly to agents.\n    assistant = ReActAgent(\n        name=\"Assistant\",\n        model=model,\n        sys_prompt=\"You are a helpful AI assistant. Always be polite.\"\n    )\n    user = UserAgent(name=\"User\")\n\n    print(\"\\n--- Start Conversation ---\")\n    x = None\n    while True:\n        x = await assistant.reply(x)\n        x = await user.reply(x)\n        if x.content.lower() == \"exit\":\n            break\n    print(\"--- End Conversation ---\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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`.","severity":"breaking","affected_versions":">=1.0.0 (from 0.x)"},{"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.","message":"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]`.","severity":"gotcha","affected_versions":"All versions >=1.0.0"},{"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())`).","message":"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.","severity":"gotcha","affected_versions":"All versions >=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.14"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions >=1.0.0"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using 'pip install agentscope'.","cause":"The 'agentscope' package is not installed or not available in the current Python environment.","error":"ModuleNotFoundError: No module named 'agentscope'"},{"fix":"Ensure you are using the correct import statement: 'from agentscope.agent import ReActAgent'.","cause":"The 'ReActAgent' class is not found in the 'agentscope.agent' module, possibly due to a version mismatch or incorrect import.","error":"ImportError: cannot import name 'ReActAgent' from 'agentscope.agent'"},{"fix":"Check the runtime logs for errors and ensure all required services are properly configured and running.","cause":"The AgentScope runtime service failed to start within the expected time, possibly due to configuration issues or resource constraints.","error":"TimeoutError: Runtime service did not start within the specified timeout."},{"fix":"Set the 'DOCKER_HOST' environment variable to point to the correct Docker socket, e.g., 'export DOCKER_HOST=unix://$HOME/.colima/docker.sock'.","cause":"The Docker Python SDK cannot connect to the Docker service, often due to misconfigured Docker host settings.","error":"docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))"},{"fix":"Ensure your 'agent.py' file exports an 'agent_app' or 'app' variable, or a 'create_app()' function.","cause":"The 'agent.py' file does not export an 'AgentApp' instance or the required function.","error":"Error: 'No AgentApp found in agent.py'"}]}