The AgentScope backend is built as a FastAPI application, organized into modular routers that expose the SDK's capabilities via a RESTful API. This layer handles request validation using Pydantic schemas, manages resource access control, and facilitates real-time communication through Server-Sent Events (SSE).
The application factory create_app registers all built-in routers automatically src/agentscope/app/_app.py108-109 Each router is responsible for a specific domain of the AgentScope ecosystem, from agent lifecycle management to real-time chat streaming.
| Router | Responsibility | Key Endpoints |
|---|---|---|
agent_router | Agent definition & discovery | GET /, POST /, GET /schema/v2 |
session_router | Chat session lifecycle & history | POST /, GET /{id}/messages, GET /{id}/stream |
chat_router | Message injection & HITL response | POST /{session_id} |
credential_router | API key & provider management | GET /, POST /, GET /schemas |
knowledge_base_router | RAG management & document ingestion | POST /, POST /{id}/upload, POST /{id}/search |
workspace_router | Filesystem, MCP, and Skill management | GET /mcp, GET /skill, GET /list |
hub_router | Global MCP & Skill discovery | GET /mcp, GET /skill |
health_router | System status & connectivity check | GET / |
channel_router | External platform (Discord/Feishu) bindings | GET /, POST /, POST /{id}/actions |
schedule_router | Cron-based task scheduling | GET /, POST /, GET /{id}/sessions |
The following diagram illustrates how the create_app factory wires the routers and their dependencies.
System to Code Entity Mapping: Router Initialization
Sources: src/agentscope/app/_app.py81-104 src/agentscope/app/_router/__init__.py3-17 src/agentscope/app/_router/_workspace.py20-25
The session_router is the most complex endpoint, managing the intersection of persisted state and live execution. It uses SessionView to bundle session records with their active status and team details src/agentscope/app/_router/_schema/_session.py82-85
The SessionService provides a unified SessionStatus enum src/agentscope/app/_service/_session.py61-96 It collapses cluster liveness (from the MessageBus run-lock) and durable parking state (from persisted AgentState.context) into a single value for the UI:
RUNNING: A worker holds the distributed lease src/agentscope/app/_service/_session.py92AWAITING_PERMISSION: Parked on a Human-in-the-loop (HITL) confirm src/agentscope/app/_service/_session.py83-86AWAITING_EXTERNAL_RESULT: Parked on an external tool execution src/agentscope/app/_service/_session.py87-90IDLE: No active run or pending tool calls src/agentscope/app/_service/_session.py93Real-time interaction is achieved via the stream_events endpoint, which returns a StreamingResponse src/agentscope/app/_router/_session.py8-9 The frontend consumes this via a fetch-based SSE generator to handle custom headers like X-User-ID examples/web_ui/frontend/src/api/client.ts1-20
Data Flow: Agent to Frontend SSE
Sources: src/agentscope/app/_service/_session.py98-141 src/agentscope/app/_router/_schema/_session.py80-82 examples/web_ui/frontend/src/api/types.ts137-152
The workspace_router manages the dynamic environment of a session, specifically handling the installation of MCP clients and skills into a WorkspaceBase instance src/agentscope/app/_router/_workspace.py2-3
The router provides endpoints to list live MCP tools and their health status by resolving the workspace via WorkspaceService src/agentscope/app/_router/_workspace.py53-65 When an MCP is added manually, it is also persisted in the user's library src/agentscope/app/_router/_workspace.py129-135
Skills can be uploaded directly or added from a library. The upload_skill endpoint handles multi-part form data, validating the skill manifest and storing the code within the workspace's local storage src/agentscope/app/_router/_workspace.py263-280 The WorkspaceService uses an UploadManifest to track successful and failed uploads src/agentscope/app/_service/_workspace.py28
System to Code Entity Mapping: Workspace Tool Assembly
Sources: src/agentscope/app/_router/_workspace.py45-59 src/agentscope/app/_service/_toolkit.py40-56 src/agentscope/app/_service/_workspace.py14-28
AgentScope uses Pydantic for all API schemas, ensuring strict type safety and automatic documentation generation. These schemas are mirrored in TypeScript for the Web UI examples/web_ui/frontend/src/api/types.ts1-50
AgentData: Core agent identity, system prompts, and ReActConfig examples/web_ui/frontend/src/api/types.ts43-50SessionConfig: Binds an agent to specific ChatModelConfig, TTSModelConfig, and SessionKnowledgeConfig examples/web_ui/frontend/src/api/types.ts116-132POST and PATCH operations.
CreateAgentRequest: Fields required to instantiate an agent src/agentscope/app/_router/_schema/_agent.py46-49UpdateSessionRequest: Supports partial updates for parameters like cwd or permission_mode src/agentscope/app/_router/_schema/_session.py77-78AgentView: Includes an editable flag based on ownership examples/web_ui/frontend/src/api/types.ts52-60TeamDetailResponse: Resolves a team's leader and member agents into a single object src/agentscope/app/_router/_schema/_session.py83-85Sources: src/agentscope/app/_router/_schema/__init__.py4-85 examples/web_ui/frontend/src/api/types.ts3-110
The deps.py module provides the bridge between the FastAPI request context and the underlying service layer.
get_current_user_id: Extracts the user identity from the X-User-ID header src/agentscope/app/_router/_workspace.py21get_storage: Provides access to the persistence backend (SQL/Redis) src/agentscope/app/_router/_workspace.py23get_resource_access_service: Enforces the ResourceAccessPolicyBase, determining if a user can view or edit a specific agent, credential, or knowledge base src/agentscope/app/_service/_toolkit.py34get_workspace_service: Resolves the execution environment (local or sandboxed) for a specific user/agent/session triplet src/agentscope/app/_router/_workspace.py24Routers perform proactive validation using these dependencies. For example, the workspace_router calls workspace_service.resolve to ensure the caller has access to the requested workspace before performing file or tool operations src/agentscope/app/_router/_workspace.py61-65
Sources: src/agentscope/app/_router/_workspace.py20-27 src/agentscope/app/_service/_toolkit.py52
The health_router provides a critical endpoint for monitoring the operational state of the backend components.
GET /health)It returns a HealthResponse containing the status of various system components src/agentscope/app/_router/_schema/_health.py10-15:
Sources: src/agentscope/app/_router/_health.py1-20 src/agentscope/app/_router/_schema/_health.py1-15
Refresh this wiki