# AgentScope: features, protocols, quickstart

## TL;DR

AgentScope is an Apache-2.0 Python agent framework from the agentscope-ai organization. Version 2.0 centers on a ReAct agent with a permission system, pause-and-resume human confirmation, sandboxed workspaces and leader-member team pipelines, plus an optional multi-tenant agent service. It suits Python teams building supervised, long-running agents that speak MCP, A2A and AG-UI.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python, TypeScript, Java |
| License | Apache-2.0 |
| Pricing model | Open source, free |
| Orchestration pattern | Supervisor |
| GitHub stars | 32,598 (as of 2026-09-30) |
| GitHub forks | 3,590 |
| Last push | 2026-09-30 |
| Latest release | v2.0.9 |
| Repository | [agentscope-ai/agentscope](https://github.com/agentscope-ai/agentscope) |
| Website | [agentscope.io](https://agentscope.io) |
| Documentation | [docs.agentscope.io](https://docs.agentscope.io/) |
| Last verified | 2026-09-30 |

## Key features

- ReAct Agent with a Toolkit that combines Python tools, MCP servers and skills, including built-in shell, file and search tools. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/agent/overview))
- TeamPipeline: a leader assigns tasks to member agents through a TeamAssign tool and receives only their final replies (experimental). ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/pipeline/team))
- GoalPipeline keeps an executor agent working until a verifier agent accepts the result. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/pipeline/goal))
- Permission system that allows, denies or asks per tool call, using rules, global modes and tool-level safety checks. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/permission-system/overview))
- Human-in-the-loop events: the agent parks on RequireUserConfirmEvent or external-execution tools and resumes when a result event is sent back. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/agent/human-in-the-loop))
- Workspaces run tools locally or in Bubblewrap, Docker, E2B, Daytona, Kubernetes or OpenSandbox behind one interface. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/workspace/overview))
- Long-term memory as middleware: file-based agentic memory, ReMe or Mem0. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/long-term-memory))
- Agent service: FastAPI backend with multi-tenant sessions, a web UI, IM channels and protocol middleware such as AG-UI. ([source](https://docs.agentscope.io/en/versions/2.0.9/deploy/agent-service))

## Architecture and orchestration pattern

Pattern: Supervisor.

The core is a stateless reasoning-acting loop in `Agent`: the model reasons, calls tools from a `Toolkit`, and every step is published on one event stream (text deltas, tool calls, results). Middleware hooks wrap reasoning, acting, model calls, permission checks and context compression, and a workspace decides where tools actually execute.

Multi-agent work goes through pipelines that expose several agents behind a single `reply_stream`. `TeamPipeline` gives a leader a `TeamAssign` tool; members run in their own contexts, concurrently when assigned in the same round, and never talk to each other. `GoalPipeline` loops an executor against a verifier, and the agent service adds a leader-worker Agent Team with task planning. Remote agents can join through `A2AAgent`.

Working memory is managed by context middleware (compaction, tool-result offload). Long-term memory is middleware backed by Markdown files, ReMe or Mem0. The agent service persists session state in SQL or NoSQL backends.

### Human in the loop

Every tool call passes the permission system, which returns allow, deny or ask. On ask, the agent emits `RequireUserConfirmEvent` with the pending calls and suggested rules and parks the reply; the app sends a confirmation result back through `reply` / `reply_stream` to resume, and accepted rules can be persisted. Tools marked for external execution pause the same way. Running agents can be interrupted and resumed from a consistent state, and in `TeamPipeline` a member's confirmation request is routed back to that member by `reply_id`. `A2AAgent` proxies do not support these controls.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/tool/mcp) | Client: MCPClient instances (stateful STDIO/HTTP or stateless HTTP) are passed to Toolkit(mcps=[...]) and their tools are namespaced mcp__server__tool. |
| A2A | Yes (checked 2026-09-30) | [link](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/a2a) | Client: A2AAgent proxies a remote A2A (1.0+) agent through the official SDK (agentscope[a2a]); the repo's examples/a2a also builds an A2A server from an AgentScope agent. |
| AG-UI | Yes (checked 2026-09-30) | [link](https://docs.agentscope.io/en/versions/2.0.9/deploy/agent-service) | Server-side adapter: the agent service ships AGUIProtocolMiddleware, which rewrites its SSE session stream into AG-UI events; it applies to the service, not the bare Agent loop. |

## Best for

- Agents that run shell and file tools under explicit allow/deny/ask permission rules.
- Leader-member teams where a coordinator assigns work to specialist agents.
- Coding-style agents that execute in isolated workspaces such as Docker, E2B or Kubernetes.
- Self-hosted multi-tenant agent services with a web UI and IM channels.

## Not for

- Projects that must stay on AgentScope 1.x APIs; the docs warn not to mix 1.x and 2.x.
- Teams that need stable multi-agent interfaces today (pipelines and SOP are marked experimental).
- Python versions below 3.11.

## Quickstart

```sh
uv pip install agentscope
```

Install not yet verified by this site.

```python
import asyncio, os
from agentscope.agent import Agent
from agentscope.console import launch_console
from agentscope.credential import OpenAICredential
from agentscope.model import OpenAIChatModel
from agentscope.pipeline import TeamMember, TeamPipeline
from agentscope.tool import Toolkit, Read, Grep

async def main() -> None:
    model = OpenAIChatModel(credential=OpenAICredential(api_key=os.environ["OPENAI_API_KEY"]), model="gpt-4o-mini")
    lead = Agent(name="Lead", system_prompt="Split the task and assign parts.", model=model, toolkit=Toolkit())
    reader = Agent(name="Reader", system_prompt="Read files and summarize them.", model=model,
                   toolkit=Toolkit(tools=[Read(), Grep()]))
    team = TeamPipeline(leader=lead, members=[TeamMember(agent=reader, description="Reads and summarizes local files.")])
    await launch_console(agent=team)  # terminal chat with tool-call confirmation

asyncio.run(main())
```

### Common pitfalls

- Requires Python 3.11 or higher; the docs recommend installing with uv.
- Use the documentation version that matches the installed package; `/latest/` is development docs, and 1.x and 2.x APIs must not be mixed.
- The leader in a TeamPipeline needs a toolkit (the pipeline registers `TeamAssign` there), and member names must be unique and differ from the leader's.
- A2A needs `pip install "agentscope[a2a]"`; the agent service and AG-UI middleware come with the `service` extra.
- Set the provider key (for example `DASHSCOPE_API_KEY` in the official quickstart, or `OPENAI_API_KEY` with OpenAICredential).

Official quickstart: https://docs.agentscope.io/en/versions/2.0.9/quickstart

## Pros

- Fine-grained tool governance: rules, modes and per-tool checks, with suggested rules a user can accept during a prompt. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/permission-system/overview))
- Agents can be interrupted and resumed from a consistent state. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/agent/interrupt-agent))
- Seven workspace backends share one interface, so the same agent code can move from local to container or cloud sandboxes. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/workspace/overview))
- The bundled agent service adds multi-tenant sessions, a web UI, IM channels, scheduling and SQL/NoSQL persistence on top of the SDK. ([source](https://github.com/agentscope-ai/agentscope))
- Separate TypeScript and Java implementations exist for teams outside Python, per the FAQ. ([source](https://docs.agentscope.io/en/versions/2.0.9/others/faq))

## Cons

- AgentScope 2.0 APIs differ from 1.x, and the docs tell readers not to mix the two versions. ([source](https://docs.agentscope.io/llms.txt))
- The pipeline module (including TeamPipeline) is marked experimental and may change. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/pipeline/team))
- An open bug reports that a stale HITL confirmation can resume a reply that was already resolved. ([source](https://github.com/agentscope-ai/agentscope/issues/2778))
- An open bug reports the agent service's POST /chat accepting client-supplied system and assistant roles. ([source](https://github.com/agentscope-ai/agentscope/issues/2813))
- A2AAgent is only a proxy: tools, permissions, interruption and human-in-the-loop are not available for remote agents. ([source](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/a2a))

## Alternatives

- [AutoGen](https://multiagentguide.top/tools/autogen.md)
- [Microsoft Agent Framework](https://multiagentguide.top/tools/microsoft-agent-framework.md)
- [Google ADK (Python)](https://multiagentguide.top/tools/google-adk.md)
- [CrewAI](https://multiagentguide.top/tools/crewai.md)
- [CAMEL](https://multiagentguide.top/tools/camel.md)

## FAQ

### Does AgentScope support MCP, A2A and AG-UI?

Yes. Agents load MCP servers through MCPClient in the Toolkit, A2AAgent talks to remote A2A agents, and the agent service includes an AG-UI protocol middleware.

### Is AgentScope free?

Yes. It is Apache-2.0 and no paid tier is documented; you pay for the model provider you connect.

### How do multiple AgentScope agents work together?

Most directly through TeamPipeline: a leader agent assigns tasks to members with a TeamAssign tool and gets back only their final replies. GoalPipeline and the service-level Agent Team are other options.

### Which language is AgentScope written in?

This repository is the Python SDK (Python 3.11+). The FAQ lists separate TypeScript and Java implementations with their own APIs and releases.

### Can a human approve tool calls?

Yes. When the permission system returns ask, the agent emits RequireUserConfirmEvent and waits; sending the user's answer back resumes it.

## Sources

- [agentscope-ai/agentscope repository (README)](https://github.com/agentscope-ai/agentscope)
- [AgentScope documentation](https://docs.agentscope.io/)
- [Docs llms.txt (version guidance)](https://docs.agentscope.io/llms.txt)
- [Quickstart (2.0.9)](https://docs.agentscope.io/en/versions/2.0.9/quickstart)
- [Agent overview](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/agent/overview)
- [A2A protocol](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/a2a)
- [MCP](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/tool/mcp)
- [Human-in-the-loop](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/agent/human-in-the-loop)
- [Interrupt agent](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/agent/interrupt-agent)
- [Team pipeline](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/pipeline/team)
- [Goal pipeline](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/pipeline/goal)
- [Long-term memory](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/long-term-memory)
- [Permission system overview](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/permission-system/overview)
- [Workspace overview](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/workspace/overview)
- [Agent service architecture](https://docs.agentscope.io/en/versions/2.0.9/deploy/agent-service)
- [Agent team (service)](https://docs.agentscope.io/en/versions/2.0.9/deploy/agent-team)
- [Standard operating procedure (experimental)](https://docs.agentscope.io/en/versions/2.0.9/building-blocks/sop)
- [FAQ](https://docs.agentscope.io/en/versions/2.0.9/others/faq)
- [Issue #2778: stale HITL confirmation](https://github.com/agentscope-ai/agentscope/issues/2778)
- [Issue #2813: POST /chat accepts client-supplied roles](https://github.com/agentscope-ai/agentscope/issues/2813)

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/agentscope