AgentScope Overview

AgentScope v2 is a production-ready, high-performance multi-agent framework designed to leverage the reasoning and tool-calling capabilities of modern Large Language Models (LLMs). Unlike frameworks that rely on rigid prompt templates, AgentScope focuses on flexible abstractions that allow agents to operate autonomously while providing developers with robust control through a two-layer architecture README.md64-70

The current version of the framework is 2.0.6 src/agentscope/_version.py4 For a quick setup, see Getting Started & Installation.

Two-Layer Architecture

AgentScope is structured into two primary layers: the SDK Layer for local development and agent logic, and the Agent Service Layer for production deployment and multi-agent orchestration README.md124-142

SDK Layer (Core Logic)

The SDK provides the building blocks for creating individual agents. It revolves around the Agent class and the ReAct (Reasoning-Acting) loop, which handles structured outputs, real-time interruptions, and tool execution README.md128

• Models: Support for LLM, Embedding, and TTS providers including OpenAI, Anthropic, Gemini, DashScope, DeepSeek, and Ollama README.md130
• Middleware: A hook-based system (e.g., RAGMiddleware, TTSMiddleware, AgenticMemoryMiddleware) that wraps agent actions to handle context compression, memory, and tracing README.md134 examples/console/main.py23
• Tool System: Managed via Toolkit, supporting Python functions, MCP (Model Context Protocol), and specialized skills README.md129

Agent Service Layer (Backend & Deployment)

The Service layer facilitates scaling agents into multi-user, multi-session applications. It utilizes a FastAPI-based backend to manage agent lifecycles, persistence, and communication README.md77-80

• Persistence: Standardized storage for SQL and Redis backends README.md84-85
• Workspaces: Sandboxed environments for safe tool execution (Docker, K8s, Daytona, E2B, OpenSandbox) README.md81-82
• Channels: Integration with IM platforms like Feishu (Lark) and Discord README.md77

AgentScope Architecture Overview

Sources: README.md124-142 src/agentscope/console/_console.py95-131 examples/console/main.py55-84

Key Design Principles

AgentScope is built on several core principles to ensure maintainability and performance:

1. Reasoning over Constraints: The framework prioritizes the model's innate reasoning and tool-use abilities over opinionated orchestrations README.md68-70
2. Lazy Loading: To keep the core package lightweight, third-party dependencies are imported only when needed at the function level .github/copilot-instructions.md10-19
3. Strict Encapsulation: Internal framework components are prefixed with _ to distinguish them from the public API, with exposure controlled through __init__.py src/agentscope/__init__.py5-10 .github/copilot-instructions.md27-30
4. Extensibility: Features like Long-term Memory are implemented as swappable middlewares, such as ReMe long-term memory or AgenticMemoryMiddleware README.md83-84 examples/console/main.py75-79
5. Event-Driven Interaction: Real-time feedback is provided via a stream of AgentEvent objects, which are rendered by components like ConsoleRenderer or the Web UI src/agentscope/console/_renderer.py6-15 tests/console_renderer_test.py9-27

Bridging NL and Code Entities

Sources: .github/copilot-instructions.md10-30 README.md77-84 src/agentscope/console/__init__.py1-20 tests/console_renderer_test.py9-27

Wiki Navigation

This wiki is organized to take you from basic setup to deep architectural dives:

• Getting Started & Installation: Environment setup, API key configuration, and running your first agent.
• Contributing & Development Standards: Guidelines for PRs, lazy-loading rules, testing, and coding style.
• Core SDK Architecture: Deep dive into the Agent class, message system, and middleware hooks.
• Model Layer: Details on LLM adapters (OpenAI, Anthropic, etc.), embedding models, and TTS integration.
• Tool System: How to build skills, use built-in tools (Bash, Filesystem), and integrate with MCP servers.
• Workspace & Execution Environments: Managing local and sandboxed environments (Docker, K8s, Daytona).
• RAG (Retrieval-Augmented Generation): Implementing document pipelines, vector stores, and long-term memory.
• Agent Service (Backend): Building and deploying the FastAPI backend, session management, and multi-agent teams.
• Web UI Frontend: Exploring the React-based frontend components and SSE streaming.
• Testing Infrastructure: Overview of unit tests, integration tests, and model example scripts.
• Glossary: Definitions of codebase-specific terms and code pointers.

Sources: README.md124-150 src/agentscope/_version.py4 .github/copilot-instructions.md1-97