Install & Compatibility
Where this runs
tested against v1.0.21 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
473MB installed
● package 473MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ReActAgent
✓ from agentscope.agents import ReActAgent
✗ from agentscope import ReActAgent
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())
Debug
Known issues
breakingAgentScope 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`.fixRemove `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`.
affects: >=1.0.0 (from 0.x)
gotchaMany 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]`.fixConsult 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.
affects: All versions >=1.0.0
gotchaAgentScope 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.fixEnsure 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())`).
affects: All versions >=1.0.0
gotchaAPI 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.fixSet 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.
affects: All versions
gotchaWhen 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.fixIf encountering unexpected tool parsing behavior during streaming, investigate model or agent constructor parameters for options like `stream_tool_parsing` to fine-tune parsing logic.
affects: >=1.0.14
gotchaMemory 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.fixRegularly 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.
affects: All versions >=1.0.0
Upgrade
Version history
2.0.1latest on PyPI · released Jun 5, 2026
Audit
Dependencies
pythonrequiredRequired runtime environment
openaioptionalFor using OpenAI models (included in [full])
dashscopeoptionalFor using Alibaba Cloud DashScope models (included in [full])
anthropicoptionalFor using Anthropic models (included in [full])
ollamaoptionalFor using Ollama models (included in [full])
pymilvusoptionalFor Milvus vector database in RAG module
redisoptionalFor Redis-based session and memory management
agentscope-runtimeoptionalFor deploying agents as API services, secure sandboxing, and scalable deployment