# summerpunch/langmanus architecture

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

- Interactive diagram: https://gitdiagram.com/summerpunch/langmanus
- Repository: https://github.com/summerpunch/langmanus

## Overview

Based on your project’s file tree and README, LangManus is a community‐driven AI automation framework that orchestrates a multi‐agent system built around language models and specialized tools. The purpose is to enable academic exploration in advanced multi-agent coordination, deep research, and workflow automation where distinct agents (like Coordinator, Planner, Supervisor, Researcher, Coder, Browser, and Reporter) work together to solve complex tasks and generate comprehensive responses.

##### Main Components
- Agent System: Highlight the hierarchical multi-agent setup with a Supervisor coordinating specialized agents. Label components for each major agent role – Coordinator (entry point), Planner, Supervisor, Researcher, Coder, Browser, and Reporter. Also note the agent prompting subsystem from the “src/prompts” directory.
- API Server: Show the FastAPI-based API server (see server.py and endpoints described in the README) which exposes endpoints such as /api/chat/stream with Server-Sent Events for streaming responses.
- Configuration and Tooling: Include configuration modules (under src/config) that manage settings (LLM APIs, environment variables from .env and conf.yaml). Also represent the use of a template engine (src/prompts/template.py) for dynamic agent prompts.
- External Integrations: Represent integrations with external services – for LLMs (via litellm integration), web crawling tools, TAVILY search API, and Jina for neural search. Also include the browser component that uses Chromium (configurable via environment variables).

##### Relationships and Data Flow
- API to Agent Subsystem: Illustrate how incoming API requests from clients (through FastAPI endpoints) trigger workflows in the agent system, eventually invoking tools or external integrations.
- Configuration Management: Indicate how configuration files (like conf.yaml and .env) are used by various modules (in src/config) to initialise LLM parameters and tool settings.

##### Architectural Patterns and Design Principles
- Multi-Agent & Hierarchical Orchestration: Emphasize the multi-tier system where each agent has a clear responsibility and can be swapped or extended via its markdown-based prompt system.
- Modularity: Illustrate how the project is modular – separate directories for API, agents, configuration, and tools help ensure separation of concerns.
- Extensibility: Highlight the ease of adding new agent roles or integration tools given the structure (prompt templates, configuration overrides, and plugin-like tool modules).

##### Technologies, Frameworks, and Libraries
- Python 3.12+ is the main runtime.
- uv as the package manager provides virtual environment and dependency management.
- FastAPI is used for the API server.
- Docker and Docker Compose for containerized deployments.
- External libraries such as litellm, Jina, and browser-use integrated within the system.
- GitHub Actions (under .github/workflows) are used for CI/CD processes (build, lint, test).

##### Final Touches
- Incorporate annotations to point out key design patterns — such as “Hierarchical Multi-Agent Orchestration” and “Template-based Prompt System” — that underline the project's innovative structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interface
    subgraph "External Interface"
        API_Client["Client Request (API/Web UI)"]:::client
        API_Server["API Server"]:::api
        FastAPI["FastAPI App"]:::api
    end

    %% Agent System
    subgraph "Agent System"
        Coordinator["Coordinator Agent"]:::agent
        Planner["Planner Agent"]:::agent
        Supervisor["Supervisor Agent"]:::agent
        Researcher["Researcher Agent"]:::agent
        Coder["Coder Agent"]:::agent
        Browser["Browser Agent"]:::agent
        Reporter["Reporter Agent"]:::agent
        Prompt["Agent Prompt Templates"]:::prompt
        Workflow["Workflow Service"]:::service
    end

    %% Configuration and Integration
    subgraph "Configuration and Integration"
        Config["Configuration Module"]:::config
        TemplateEngine["Template Engine"]:::prompt
        ExternalLLM["External LLM (litellm)"]:::integration
        WebCrawler["Web Crawler Tools"]:::integration
        SearchAPI["Search Integration"]:::integration
        GraphGen["Graph Generation Module"]:::support
        AuxTools["Auxiliary Tools & Utilities"]:::support
        JSONUtils["JSON Utils"]:::support
        EnvConfig[".env.example"]:::config
        YAMLConfig["conf.yaml.example"]:::config
        CICD["CI/CD Pipelines"]:::config
    end

    %% Connections between layers
    API_Client -->|"sends_request"| API_Server
    API_Server -->|"triggers"| FastAPI
    FastAPI -->|"invokes_workflow"| Coordinator

    %% Agent system data flow
    Coordinator -->|"routes_to"| Planner
    Planner -->|"escalates_to"| Supervisor
    Supervisor -->|"coordinates_with"| Researcher
    Supervisor -->|"coordinates_with"| Coder
    Supervisor -->|"coordinates_with"| Browser
    Supervisor -->|"coordinates_with"| Reporter

    %% Prompt subsystem integration
    TemplateEngine -->|"generates"| Prompt
    Prompt -->|"used_by"| Coordinator
    Prompt -->|"used_by"| Planner
    Prompt -->|"used_by"| Supervisor
    Prompt -->|"used_by"| Researcher
    Prompt -->|"used_by"| Coder
    Prompt -->|"used_by"| Browser
    Prompt -->|"used_by"| Reporter

    %% Workflow orchestration
    Workflow -->|"orchestrates"| Supervisor

    %% Configuration influences agent system
    Config -->|"configures"| Coordinator
    Config -->|"configures"| Planner
    Config -->|"configures"| Supervisor
    Config -->|"configures"| Researcher
    Config -->|"configures"| Coder
    Config -->|"configures"| Browser
    Config -->|"configures"| Reporter
    Config -->|"feeds"| TemplateEngine

    %% External integrations from agents
    Researcher -->|"calls"| ExternalLLM
    Browser -->|"invokes"| WebCrawler
    Browser -->|"invokes"| SearchAPI

    %% Supporting components
    Config -->|"supports"| GraphGen
    Config -->|"supports"| AuxTools
    AuxTools -->|"includes"| JSONUtils

    %% Environment and CI/CD configurations
    Config -->|"includes"| EnvConfig
    Config -->|"includes"| YAMLConfig
    Config -->|"monitors"| CICD

    %% Click Events
    click Coordinator "https://github.com/summerpunch/langmanus/blob/main/src/agents/agents.py"
    click Prompt "https://github.com/summerpunch/langmanus/tree/main/src/prompts/"
    click Workflow "https://github.com/summerpunch/langmanus/blob/main/src/service/workflow_service.py"
    click API_Server "https://github.com/summerpunch/langmanus/blob/main/server.py"
    click FastAPI "https://github.com/summerpunch/langmanus/blob/main/src/api/app.py"
    click Config "https://github.com/summerpunch/langmanus/tree/main/src/config/"
    click TemplateEngine "https://github.com/summerpunch/langmanus/blob/main/src/prompts/template.py"
    click ExternalLLM "https://github.com/summerpunch/langmanus/blob/main/src/llms/litellm_v2.py"
    click WebCrawler "https://github.com/summerpunch/langmanus/tree/main/src/crawler/"
    click Browser "https://github.com/summerpunch/langmanus/blob/main/src/tools/browser.py"
    click SearchAPI "https://github.com/summerpunch/langmanus/blob/main/src/tools/search.py"
    click GraphGen "https://github.com/summerpunch/langmanus/tree/main/src/graph/"
    click AuxTools "https://github.com/summerpunch/langmanus/tree/main/src/tools/"
    click JSONUtils "https://github.com/summerpunch/langmanus/blob/main/src/utils/json_utils.py"
    click EnvConfig "https://github.com/summerpunch/langmanus/blob/main/.env.example"
    click YAMLConfig "https://github.com/summerpunch/langmanus/blob/main/conf.yaml.example"
    click CICD "https://github.com/summerpunch/langmanus/tree/main/.github/workflows"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef api fill:#ccf,stroke:#333,stroke-width:2px;
    classDef agent fill:#cfc,stroke:#333,stroke-width:2px;
    classDef prompt fill:#fc9,stroke:#333,stroke-width:2px;
    classDef service fill:#9cf,stroke:#333,stroke-width:2px;
    classDef config fill:#ffc,stroke:#333,stroke-width:2px;
    classDef integration fill:#cff,stroke:#333,stroke-width:2px;
    classDef support fill:#f99,stroke:#333,stroke-width:2px;
```
