AgentScope 2.0 Frequently Asked Questions (FAQ)
Updated September 10, 2026 for AgentScope 2.x. Start with the stable documentation, and select the documentation version that matches your installed package when following API examples.
Getting Started
Q1: What is AgentScope 2.0, and when should I use it?
AgentScope 2.0 is an open-source framework for building tool-using agents and running them as applications. It combines a Python SDK with model integrations, tools, context management, permissions, and an optional Agent Service with a web UI.
Use the SDK to build a single agent or compose your own application. Use Agent Service when you need managed users, sessions, agent teams, and a frontend. See the framework overview.
Q2: How do I create my first agent?
The Python SDK requires Python 3.11 or later. Configure a model and its credentials, create an Agent, and call reply for a final response or reply_stream for incremental events. Add a Toolkit when the agent needs tools.
Follow the Quickstart for installation and a complete example. The console provides a terminal interface for trying your agent interactively.
Q3: Do I have to use Qwen or DashScope?
No. AgentScope includes integrations for multiple model APIs, including OpenAI, Anthropic, Gemini, DashScope, and Ollama. Choose the model class and matching credentials for the API you use. Available modalities and features depend on the selected model and API.
See model configuration and chat models.
Q4: Is AgentScope 2.0 compatible with 1.x?
No. AgentScope 2.0 changes the agent abstraction, messages and events, tool integration, state management, and deployment APIs. Upgrading an existing application requires code changes; installing 2.x alone does not migrate it.
Use the migration guide to update your application. For an application that still runs 1.x, use its matching versioned documentation.
Building Agents
Q5: How do I add Python tools or connect MCP servers?
Use Toolkit to give an agent Python tools and tools exposed by MCP servers. MCP stands for Model Context Protocol. AgentScope supports STDIO and HTTP connections, with connection lifecycle requirements depending on whether the client is stateful or stateless.
See Python tools and MCP integration for registration and connection examples.
Q6: How do Skills work in AgentScope 2.0?
A skill is a directory containing a SKILL.md file with metadata and instructions. Register skill sources with the toolkit or manage them through a workspace. The agent can read a skill's instructions and follow them using its available tools; a skill is not itself a callable tool.
See the Skills guide for supported sources and loading behavior.
Q7: Can I request structured output?
Yes. Pass a Pydantic model through structured_schema when calling reply or reply_stream. AgentScope validates the generated data, and the final message exposes it through structured_output.
See structured output for examples and behavior when a reply pauses for human input.
Q8: How do I build a multi-agent application?
You can compose agents in your own Python application. For service-based collaboration, Agent Team lets a leader create worker agents and exchange messages with them. Each worker runs in its own session, and the example web UI displays the team and its activity.
Use Agent Team when you want managed leader-worker collaboration. A single agent remains sufficient when one model and toolkit can complete the task without delegation.
Q9: Does 2.0 support RAG and long-term memory?
Yes. RAG provides document parsing, chunking, embedding, vector storage, and retrieval. Agent Service also provides an optional knowledge-base service. Long-term memory integrations include file-based agentic memory, ReMe, and Mem0.
Use RAG to retrieve information from a knowledge collection and long-term memory to retain useful information across conversations. They can be used together. See RAG, RAG Service, and long-term memory.
Q10: How can I customize agent behavior?
Use agent middleware to add behavior at lifecycle points such as model calls, tool execution, and context compression. Implement the relevant framework interfaces when adding a custom model, tool, or workspace backend.
See middleware and the Agent interface. These extension points let you customize an application without editing the framework's agent loop.
Control and Deployment
Q11: Can a person approve tool calls or interrupt an agent?
Yes. The permission system can allow, deny, or request confirmation for a tool call. Human-in-the-loop events let your application present an approval request and return the user's decision. You can also interrupt a running agent through the supported interruption flow.
See permissions, human-in-the-loop, and interruption.
Q12: What is a workspace? Does it always provide a sandbox?
A workspace supplies the agent's execution environment and manages resources such as tools, MCP servers, skills, and offloaded context. A local workspace operates on the host; it does not provide container isolation. Supported sandbox backends include Docker, Bubblewrap, Apple Container, Kubernetes, E2B, Daytona, and OpenSandbox, among others.
Choose a backend and configure mounts, credentials, and permissions for your application. See workspaces for supported backends and their lifecycle.
Q13: Do I still need the standalone Runtime or Studio to build a web application?
For a new 2.x application, start with the SDK's Agent Service and bundled web UI. Agent Service is a FastAPI-based hosting layer for agents, with session management, persistence, scheduling, and workspace management. You do not need to assemble the old standalone Runtime and Studio stack to run the supplied web application.
You can also use the SDK inside your own backend. See the Agent Service guide for the bundled backend and frontend setup.
Q14: Does Agent Service handle users, sessions, and authentication?
Agent Service manages user-owned resources and multiple sessions, with configurable storage and workspace allocation. Authentication still belongs to your application: the example user-header dependency must be replaced with your own authenticated identity integration before exposing the service to users.
See Agent Service and workspace management. Separate conversation state and execution-environment isolation are distinct configuration choices.
Q15: How do I deploy an AgentScope agent as a service?
AgentScope includes Agent Service and a matching web UI. Start with the backend example in examples/agent_service and the frontend example in examples/web_ui to run a complete application, then configure your models, tools, and workspaces.
Follow the Agent Service setup guide for prerequisites and startup commands. Use examples from the same checkout as the SDK you install.
Q16: How do I build a multi-tenant agent service with AgentScope?
The built-in service under agentscope.app manages multiple tenants and sessions, with shared storage and a message bus for distributed operation. Its modular interfaces let you run it as a standalone service, embed it in an existing application, or compose it into a microservice architecture. Serverless deployment requires adapting the application to the hosting platform's request lifecycle, streaming support, and background execution model.
Storage backends are replaceable: use Redis or SQLAlchemy-backed databases such as SQLite, PostgreSQL, and MySQL. Configure shared persistence and messaging for multiple service instances, connect the bundled web UI, and integrate your own authentication. See Agent Service, storage backends, and workspace management.
Q17: Does AgentScope support the A2A protocol?
Yes. AgentScope 2.0.8 and later support A2A (Agent2Agent). Use A2AAgent to connect to a remote A2A agent and consume its responses through AgentScope's message and event interfaces.
The A2A example includes both a server built from an AgentScope agent and a client connecting to it. Install the a2a extra to use this integration. Model configuration, tools, and execution policies of a remote agent are managed by that remote service.
Ecosystem and Development
Q18: Can I use AgentScope from Java?
Yes. AgentScope Java is maintained in a separate repository with its own releases and documentation. Use its Java APIs and version-specific guides rather than translating Python snippets directly or assuming matching version numbers imply identical APIs.
Start with the AgentScope Java repository and Java documentation.
Q19: How should I use an AI coding assistant with AgentScope?
We provide agentscope-skill in the official skills repository for vibe coding with AgentScope. It gives your coding assistant AgentScope-specific guidance, API references, and examples. Follow the repository instructions to make the skill available to your assistant.
Give it your installed AgentScope version and the corresponding documentation links. The documentation site publishes an AI-readable index; individual documentation pages are also available as Markdown by appending .md to the page URL.
Ask the assistant to check API names against that version and run the resulting example. Use stable documentation for new applications, and development documentation only when your code uses the matching development source.
Resources
Use these official entry points for setup, API details, and examples: