games-development-ai/.claude/skills/agentscope-skill/references/v2-overview.md

What's AgentScope 2.0?

More secure, more efficient, more flexible, and more complete agent development.

AgentScope 2.0 is a major update to our agent framework, with a focus on improving the developer experience and making it easier to build and run agents in production.

AgentScope 2.0 is a breaking change from 1.0, with significant improvements in the core abstractions, APIs and architecture. We recommend users to migrate to 2.0 to take advantage of the new features and improvements.

2.0 brings the following major changes and improvements:

• Event System: Every step the agent takes — text, thinking, tool call, tool result — is observable as a typed stream, so you can render rich, responsive UIs and integrate with AG-UI or A2A without writing adapters.
• Execution Security: Dangerous tool calls can be denied or held for review, and untrusted code can run inside a sandbox — the agent never silently touches the host or leaks credentials.
• Human-in-the-loop: Users can confirm or edit tool arguments mid-run, and sensitive actions can be handed off to your own backend instead of executed in-process, with the agent resuming exactly where it paused.
• More Efficient: Multi-tool steps finish faster through concurrent execution, long conversations stay within the context window automatically, oversized tool outputs no longer blow up the prompt, and transient provider failures fall back gracefully.
• Workspace System: Move an agent from your laptop to a Docker host or an E2B sandbox by changing one line, with working directory, MCP clients and skills cleanly isolated per user, agent or session.
• Agent Service: Host any agent over REST + SSE with multi-tenant, multi-session concurrency, resumable streams, durable sessions, scheduled runs and managed credentials — without writing the service plumbing yourself.

If you are still evaluating whether to migrate, check out the Changelog for a full breakdown of every change — it should give you everything you need to plan your migration to AgentScope 2.0.

Observe every step of the agent and stream it straight into your UI. Gate or sandbox dangerous tool calls before they touch the host. Let users review and edit tool arguments before execution, or delegate sensitive actions to your own backend entirely. Tool calls are auto-batched and run concurrently or sequentially based on each tool's properties. Swap Local, Docker or E2B without rewriting the agent. Ship agents over REST + SSE with multi-tenant, multi-session concurrency, sessions, schedules and credentials.

Quickstart

Get up and running with AgentScope 2.0 in minutes

Installation

AgentScope requires Python 3.11+, and you can install it from PyPI or from source.

It's recommended to install AgentScope by using uv.

From PyPI

uv pip install agentscope

From Source

git clone -b main https://github.com/agentscope-ai/agentscope
cd agentscope
uv pip install -e .

Verify Installation

To ensure AgentScope is installed successfully, check via executing the following code:

import agentscope

print(agentscope.__version__)

Your First Agent

The snippet below builds the minimal agent: a DashScope credential, the matching chat model, an empty toolkit, and an Agent. The agent exposes two entry points — reply returns the final message, while reply_stream yields incremental events as the agent reasons and acts.

import asyncio
import os

from agentscope.agent import Agent
from agentscope.credential import DashScopeCredential
from agentscope.event import EventType
from agentscope.message import UserMsg
from agentscope.model import DashScopeChatModel
from agentscope.tool import Toolkit, Bash, Read, Write, Edit


async def main() -> None:
    agent = Agent(
        name="Friday",
        system_prompt="You are a helpful assistant named Friday.",
        model=DashScopeChatModel(
            credential=DashScopeCredential(
                api_key=os.getenv("DASHSCOPE_API_KEY"),
            ),
            model="qwen-plus",
        ),
        toolkit=Toolkit(tools=[Bash(), Read(), Write(), Edit()]),
    )

    user_msg = UserMsg(name="user", content="Hello, who are you?")

    # Option 1: await the final assistant message.
    reply_msg = await agent.reply(user_msg)
    # `reply_msg` is an `AssistantMsg` whose `content` is a list of blocks.
    # Inspect text blocks, tool calls, etc. as needed.
    ...

    # Option 2: stream incremental events (text deltas, tool calls, ...).
    async for event in agent.reply_stream(user_msg):
        # Dispatch on `event.type` — each branch handles one event kind.
        match event.type:
            case EventType.TEXT_BLOCK_DELTA:
                # Streaming text chunk from the model — append to UI / stdout.
                ...
            case EventType.TOOL_CALL_START:
                # The agent is about to invoke a tool — surface the call.
                ...
            case _:
                # Other events: thinking blocks, tool results, reply end, ...
                ...


asyncio.run(main())

Set `DASHSCOPE_API_KEY` in your environment before running the script. To use a different provider, swap `DashScopeCredential` and `DashScopeChatModel` for the matching pair (e.g. `OpenAICredential` and `OpenAIChatModel`).

Extra Dependencies

To satisfy the requirements of different functionalities, AgentScope provides extra dependencies that can be installed based on your needs.

• full: including extra dependencies for model APIs, tool functions and more.
• dev: development dependencies, including testing and documentation tools.

For example, when installing the full dependencies, the installation command varies depending on your operating system.

• For Windows users:

uv pip install agentscope[full]

• For Mac and Linux users:

uv pip install agentscope\[full\]

Changelog

Core differences between AgentScope 2.0 and 1.0

AgentScope 2.0 is a breaking release. The notes below summarize the differences against 1.0, grouped by module.

Agent

• Refactor ReActAgent into a new unified Agent class implementation.
• Replace the __call__ method in 1.0 with the reply_stream and reply public methods.
• Support yielding agent events from reply_stream for richer observability and control.
• Support permission checks and human-in-the-loop confirmations through the event stream.
• Support offloading the compressed context and oversized tool results via a new Offloader interface.
• Deprecate the hook mechanism and replace it with a new agent middleware system.
• Deprecate the state_dict and load_state_dict methods, moving towards explicit state management through the new AgentState type.
• Deprecate the print interface of the agent class, turning the agent into a pure producer.
• Deprecate the OpenTelemetry integration within the agent class and leave it to a new middleware implementation.

Event New

• Add event system for better frontend integration and human-in-the-loop support.

Message

Content blocks refactor:

• Refactor all content blocks by inheriting from the Pydantic BaseModel for better validation, serialization, and extensibility.
• Refactor ImageBlock, AudioBlock, VideoBlock into a unified DataBlock with a media_type field for extensibility.
• Add HintBlock for agent guidance and intermediate reasoning.
• Rename ToolUseBlock to ToolCallBlock.
• Add state and suggested_rules fields to ToolCallBlock for richer tool-call lifecycle modeling.
• Add state field to ToolResultBlock for richer tool-call lifecycle modeling.
• Add id field for all blocks for better traceability and referencing.

Msg class refactor:

• Refactor Msg to inherit from BaseModel and enforce content validation.
• Add created_at, finished_at, and usage fields to the Msg class for better observability and accounting.
• Add append_event method to Msg for yielding events from the agent's reply stream.
• Add factory methods UserMsg, AssistantMsg, and SystemMsg to create messages with the appropriate role.
• Add content field constraints with the specified role types.

Permission New

• Add a new permission system for gating tool execution, human-in-the-loop confirmation, and overall agent autonomy control.

Tool

• Add ToolBase abstraction for all tools.
• Refactor built-in tools:
  • Add Bash, Edit, Glob, Grep, Read, and Write with permission control.
  • Add TaskCreate, TaskGet, TaskList, and TaskUpdate for task management.

Toolkit refactor:

• Support tools, skills, MCPs, and tool groups as first-class citizens in the Toolkit abstraction.
• Add ToolGroup for on-demand activation, with the reserved basic group always active.
• Add the ResetTools meta-tool for the agent to switch tool groups at runtime.
• Add MCPTool and FunctionTool adapters for uniform tool registration.

MCP

• Refactor MCP implementation into a single MCPClient class for a unified client surface.
• Add StdioMCPConfig and HttpMCPConfig declarative configuration types for typed MCP setup.

Skill New

• Add skill loader abstraction to support in-time skill loading from the filesystem/sandbox/web.
• Add LocalSkillLoader class to support directory-based skill loading and monitoring.
• Support packaging skills into ToolGroups for on-demand activation and better organization.

Workspace New

• Add the workspace abstraction supplying tools, MCPs, skills, and context offloading through one unified interface.
• Add LocalWorkspace, DockerWorkspace, and E2BWorkspace implementations sharing the same agent-facing API for swappable execution backends.
• Add the Offloader protocol consumed by Agent for context compression and oversized tool-result handling.
• Add LocalWorkspaceManager, DockerWorkspaceManager, and E2BWorkspaceManager with agent-level isolation for multi-tenant services.
• Add an in-workspace MCP gateway so host-side agents can reach MCP servers running inside containers and sandboxes.

Model

• Decouple credential management from the model classes and centralize it in a new Credential module.
• Support credential-aware model listing and retrieval.
• Support Kimi, Moonshot, DeepSeek, XAI, and OpenAI Response API.
• Integrate formatter into the chat model abstraction and support default formatters for different model providers.
• Add the ModelCard schema describing model identity, capabilities, and parameter overrides.
• Add class method list_models for frontend model listing and selection.
• Deprecate the Trinity model wrapper.

Middleware New

• Refactor the hook mechanism into a more general agent middleware system.
• Add TracingMiddleware as the new entry point for OpenTelemetry tracing, replacing the in-agent integration.

Agent Service New

• Add a new FastAPI-based agent service and sandbox support in the app module.
• Add the create_app FastAPI factory exposing agent, chat, model, credential, session, schedule, workspace, and background-task routers.
• Add lifespan-scoped SessionManager, SchedulerManager, BackgroundTaskManager, and workspace managers for multi-tenant resource allocation.
• Add AGUIProtocolMiddleware for streaming and ToolOffloadMiddleware for oversized payloads.
• Add Redis-backed storage.

Memory

• Deprecate the memory module in 2.0 due to its tight coupling with agent logic.

RAG & Long-Term Memory

• Unify RAG and long-term memory into one module.
• Migration from 1.0 to 2.0 is in progress; the module — knowledge bases, document readers, and stores — will return on top of the 2.0 architecture in upcoming releases.

FAQ

Frequently asked questions about AgentScope v2.0

No. AgentScope 2.0 is a breaking release that introduces a redesigned agent abstraction, a new event system, the workspace and permission systems, and many other new features. APIs are not source-compatible with 1.0, and there is no automatic migration path.

We recommend upgrading to 2.0 for all new projects to benefit from the new capabilities. The 1.0 documentation remains available for existing users.

Yes. The **workspace** abstraction is AgentScope's execution environment for agents and ships three implementations — `LocalWorkspace` (host filesystem), `DockerWorkspace` (container), and `E2BWorkspace` (E2B cloud sandbox) — sharing the same interface so the same agent code runs against any backend. Workspaces also own MCP server lifecycles, skill management, and context offloading.

See [Workspace](/v2/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`.

Yes, on two layers:

* **TypeScript SDK** — install with `pnpm install @agentscope-ai/agentscope`. It mirrors the Python `Msg` and `Event` types so frontend code can consume agent streams without re-implementing the protocol.
* **Frontend UI** — a ready-to-use web app for [Agent Service](/v2/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code.

Yes. Both modules are being ported from 1.0 to the 2.0 architecture and will land in upcoming releases. Track the changelog and GitHub releases for availability. Yes. AgentScope is available in three languages, each with its own repository:

* **Python** — [`agentscope-ai/agentscope`](https://github.com/agentscope-ai/agentscope) (this documentation)
* **TypeScript** — [`agentscope-ai/agentscope-typescript`](https://github.com/agentscope-ai/agentscope-typescript)
* **Java** — [`agentscope-ai/agentscope-java`](https://github.com/agentscope-ai/agentscope-java)