# modelscope/agentscope architecture

> Architecture diagram of the GitHub repository modelscope/agentscope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/modelscope/agentscope
- Repository: https://github.com/modelscope/agentscope

## Overview

##### Project Type and Purpose
- AgentScope is a Python-based multi-agent platform and SDK for building LLM-powered applications.
- It provides a core library (`src/agentscope/…`) with abstractions for agents, messages, memory, pipelines, RPC/server, and UI (Studio).
- It also supplies example applications (e.g., `applications/multisource_rag_app`), deployment scripts (`scripts/`), documentation (`docs/`), and tests (`tests/`).

##### Top-Level Architecture Components
- Core Library (Python package under `src/agentscope`):
- Agents: dialog, RAG, React, user, dictionary agents
- Message & Memory: `message/`, `memory/`
- Models: wrappers for OpenAI, DashScope, Gemini, Zhipu, Ollama, LiteLLM, Yi, PostAPI, Anthropic
- Service Layer: retrieval, web search, code execution, file I/O, SQL queries, multi-modality, web browser control
- Manager & RPC: actor-based distribution (`manager/`), gRPC definitions (`rpc/`), server launcher and servicer
- Pipelines & Strategy: composite workflows (`pipelines/`, `strategy/`)
- Prompt: generation, optimization, formatting
- Studio UI: backend (`studio/`), frontend assets (HTML/CSS/JS under `studio/static`), Gradio integration
- Example Multi-Source RAG Application (`applications/multisource_rag_app`):
- Agents and utilities for context management, retrieval, summarization, reranking, query rewrite
- Knowledge stores: local files and Elasticsearch
- Async model orchestration (`async_model/`)
- Gradio frontend (`studio/gradio_with_feedback.py`), server entrypoint (`copilot_server.py`)
- Deployment & Service Scripts (`scripts/`): setups for Ollama, FastChat, vLLM, Flask+Transformers/Mo delScope
- Documentation & Testing: Sphinx tutorial docs under `docs/tutorial`, unit tests under `tests/`

##### Component Interactions and Data Flows
- An application instantiates one or more Agent objects. Messages (`Msg`) flow between agents over in-process calls or via RPC for distributed mode.
- ModelWrapper components abstract LLM API calls; these may be local (Flask, FastChat, vLLM) or remote (OpenAI, DashScope, etc.).
- The service layer is invoked by agents to fetch external data (web search, SQL, file ops, code execution).
- Pipelines chain multiple agents or services in series/parallel with conditionals and loops.
- The Manager/Launcher handles actor lifecycles and scheduling; gRPC (`rpc_agent.proto`) is used for inter-process communication.
- Studio UI communicates with the backend via WebSocket or HTTP to render dialogues, pipelines, and multi-modal outputs in the browser/Gradio.

##### Architectural Patterns and Principles
- Actor Model: Each agent or service runs as an independent actor (possibly remote).
- Adapter/Wrapper Pattern: `ModelWrapper` and `Service` classes abstract differences among LLM APIs and services.
- Pipeline Composition: Functional and class-based pipelines allow conditional and sequential execution.
- Layered Separation:
- API Layer (ModelWrapper, Service)
- Business Logic (Agents, Pipelines, Strategies)
- Orchestration Layer (Manager, RPC, Studio server)
- Presentation Layer (Studio frontend, Gradio)
- Configuration-Driven: JSON/YAML configs under `configs/` drive agent and knowledge behaviors.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library" 
        direction TB
        Agents["Agents"]:::core
        Msg["Msg (message/msg.py)"]:::core
        Block["Block (message/block.py)"]:::core
        Memory["Memory (memory/memory.py)"]:::core
        TempMem["TemporaryMemory (memory/temporary_memory.py)"]:::core
        Models["Model Wrappers"]:::core
        Service["Service Layer"]:::core
        Manager["Manager"]:::core
        RPC["RPC Definitions & Client"]:::core
        Server["Server Launcher & Servicer"]:::core
        Pipelines["Pipelines & Strategy"]:::core
        Prompt["Prompt (generation/optimization)"]:::core
        StudioBack["Studio UI Backend"]:::core
        StudioStatic["Studio Static Assets"]:::core
    end

    %% Example Application
    subgraph "Example Multi-Source RAG App" 
        direction TB
        Knowledge["Knowledge Sources"]:::example
        RetrievalAgent["RetrievalAgent"]:::example
        ContextMgr["ContextManager"]:::example
        Summarizer["Summarizer/Reranker"]:::example
        CopilotServer["CopilotServer"]:::example
        GradioApp["Gradio UI"]:::example
    end

    %% Deployment & Scripts
    subgraph "Deployment & Scripts"
        direction TB
        Scripts["scripts/"]:::deployment
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        LLMs["LLM APIs (OpenAI, DashScope, etc.)"]:::external
        Elasticsearch["Elasticsearch"]:::external
        WebServices["Web Services"]:::external
    end

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        StudioUI["Studio UI (Browser/WebSocket)"]:::ui
    end

    %% Connections
    Agents -->|"uses"| Msg
    Agents -->|"uses"| Block
    Agents -->|"uses"| Memory
    Agents -->|"uses"| TempMem
    Agents -->|"calls"| Models
    Agents -->|"invokes"| Service
    Agents -->|"managed by"| Manager
    Agents -->|-- RPC -->| RPC
    RPC -.->|async| Server
    Agents -->|"calls"| Pipelines
    Pipelines -->|"uses"| Prompt
    StudioUI -->|HTTP/WebSocket| StudioBack
    StudioBack -->|loads| Agents
    StudioBack -->|uses| RPC
    Scripts -->|deploy| Models
    Scripts -->|deploy| Service
    Knowledge -->|provides| RetrievalAgent
    RetrievalAgent -->|calls| Service
    RetrievalAgent -->|manages| ContextMgr
    ContextMgr -->|calls| Summarizer
    Summarizer -->|responds| CopilotServer
    CopilotServer -->|serves| GradioApp
    GradioApp -->|renders| UI
    Models -->|wraps| LLMs
    Service -->|queries| Elasticsearch
    Service -->|calls| WebServices
    Manager -->|orchestrates| Agents
    Manager -->|orchestrates| RPC

    %% Legend
    subgraph Legend
        direction LR
        C[Core Library]:::core
        E[External Systems]:::external
        X[Example App]:::example
        U[UI Layer]:::ui
        D[Deployment]:::deployment
    end

    %% Click Events
    click Agents "https://github.com/modelscope/agentscope/tree/main/src/agentscope/agents"
    click Msg "https://github.com/modelscope/agentscope/blob/main/src/agentscope/message/msg.py"
    click Block "https://github.com/modelscope/agentscope/blob/main/src/agentscope/message/block.py"
    click Memory "https://github.com/modelscope/agentscope/blob/main/src/agentscope/memory/memory.py"
    click TempMem "https://github.com/modelscope/agentscope/blob/main/src/agentscope/memory/temporary_memory.py"
    click Service "https://github.com/modelscope/agentscope/tree/main/src/agentscope/service"
    click StudioBack "https://github.com/modelscope/agentscope/blob/main/src/agentscope/studio/_app.py"
    click StudioStatic "https://github.com/modelscope/agentscope/tree/main/src/agentscope/studio/static"
    click RPC "https://github.com/modelscope/agentscope/blob/main/src/agentscope/rpc/rpc_agent.proto"
    click Pipelines "https://github.com/modelscope/agentscope/tree/main/src/agentscope/pipelines"
    click Scripts "https://github.com/modelscope/agentscope/tree/main/scripts/"
    
    %% Styles
    classDef core fill:#D0E6FF,stroke:#0284C7,color:#000;
    classDef external fill:#D4F8D4,stroke:#33A02C,color:#000;
    classDef example fill:#FFE8CC,stroke:#FF7F00,color:#000;
    classDef ui fill:#F3D4F4,stroke:#A33EA1,color:#000;
    classDef deployment fill:#F0F0F0,stroke:#888888,color:#000;
```
