# ag2ai/ag2 architecture

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

- Interactive diagram: https://gitdiagram.com/ag2ai/ag2
- Repository: https://github.com/ag2ai/ag2

## Overview

##### Project type and purpose
- This is a library/framework (AG2, formerly AutoGen) for building and orchestrating AI agents in Python. It is not a web or mobile app but an open-source AgentOS providing core agent abstractions, multi-agent orchestration patterns (conversable agents, group chat, swarms), tool registration/execution, LLM client integrations, RAG, caching, code execution environments, and extensive documentation/notebooks.

##### High-level analysis of the file structure
- Top-level directories:
- autogen/     → Main Python package: core, agentchat, tools, interop, cache, coding, events, oai (LLM clients), mcp (FastAPI proxy), io, logger, etc.
- test/        → Automated tests for every submodule.
- notebook/    → Jupyter notebooks demonstrating use cases.
- website/     → Documentation site source (MkDocs, Docusaurus, scripts).
- scripts/     → Build, test, lint, devcontainer utilities.
- Key patterns:
- Core agent abstractions under autogen/agentchat and autogen/agents.
- Tooling modules for external APIs and code execution under autogen/tools and autogen/coding.
- LLM client abstractions under autogen/oai and autogen/interop.
- Caching layer (disk, Redis, Cosmos, in-memory) under autogen/cache.
- Orchestration patterns (GroupChat, Swarm) under autogen/agentchat/group.
- Event and message pipelines under autogen/events and autogen/messages.
- Configuration/CI: devcontainer, GitHub Actions workflows, pre-commit config, pyproject.toml.

##### Insights from the README
- Project goal: streamline building single and multi-agent workflows, integrate human-in-the-loop, various LLM providers, tools, RAG, and advanced patterns.
- Core concepts: ConversableAgent, UserProxyAgent, GroupChat, Swarm, tool registration, structured outputs, retrieval, code execution.
- External dependencies: Python ≥3.9, LLM provider APIs (OpenAI, Anthropic, Gemini, etc.), vector stores (Chroma, Qdrant, MongoDB), Docker for code execution.

a. Main components
1. Core Agent Framework (autogen/)
- Agent abstractions (ConversableAgent, AssistantAgent, UserProxyAgent)
- Multi-agent orchestrators (GroupChatManager, Swarm)
- Message/event pipeline
2. LLM Client Layer (autogen/oai + autogen/interop)
- OpenAI, Anthropic, Gemini, Bedrock, Cohere, Mistral, etc.
3. Tooling Layer
- Registered “tool” functions (autogen/tools)
- Code execution environments (Docker, local, Jupyter) under autogen/coding and autogen/environments
4. Retrieval & Caching
- Vector stores (ChromaDB, Qdrant, MongoDB) under autogen/agentchat/contrib/* and autogen/interop
- Cache backends (in-memory, disk, Redis, CosmosDB) under autogen/cache
5. Logging & Monitoring
- Logger factories (file, SQLite) under autogen/logger
- Runtime event logging (autogen/events, autogen/io/processors)
6. Application Entry Points
- CLI (`autogen mcp`, scripts)
- Jupyter notebooks (notebook/)
7. Documentation Website
- MkDocs, Docusaurus sources in website/
b. Relationships and interactions
- Agent initiates message → Core framework routes to orchestrator or directly to recipient.
- Core framework invokes LLM Client → returns model-generated response.
- If the response indicates a tool call → Tooling Layer executes code or external API.
- Retrieval Layer handles RAG: query vector store, retrieve docs, feed to LLM.
- Caching Layer intercepts LLM and retrieval calls to store/serve cached results.
- Logging & Event layers subscribe to agent events, emit logs or CLI output.
- Orchestrators decide which agent speaks next or parallelize (swarm).
c. Architectural patterns and design principles
- Modular layering: clear separation of agent core, LLM clients, tools, retrieval, caching.
- Dependency injection: tool registration, pluggable LLM backends, environment abstraction.
- Event-driven messaging: agents communicate via a message/event bus.
- Extensibility: add new agents, tools, backends without changing core.
d. Key technologies/frameworks
- Python 3.9+
- FastAPI (mcp proxy)
- Docker (code execution environments)
- Vector DBs (Chroma, Qdrant, MongoDB)
- LLM SDKs (OpenAI, Anthropic, Gemini, etc.)
- MkDocs/Docusaurus (documentation)

##### Final advice
- Plugin points explicitly to show extensibility.
- Keep the focus on how messages traverse the system and how backends plug in.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entry Points
    subgraph "Application Entry Points"
        cli["CLI"]:::entry
        proxy["FastAPI Proxy"]:::entry
        notebooks["Jupyter Notebooks"]:::entry
    end

    %% Core Agent Framework
    subgraph "Core Agent Framework"
        conv["ConversableAgent"]:::core
        asst["AssistantAgent"]:::core
        proxyAgent["UserProxyAgent"]:::core
        orchestrators["Multi-Agent Orchestrators"]:::core
        messages["Message Pipeline"]:::core
        eventsPipeline["Event Pipeline"]:::core
    end

    %% LLM Client Layer
    subgraph "LLM Client Layer"
        oaiClient["OpenAI Client"]:::llm
        anthropic["Anthropic Client"]:::llm
        gemini["Gemini Client"]:::llm
        registry["Interop Registry"]:::llm
        langchainFactory["Langchain Factory"]:::llm
    end

    %% Tooling Layer
    subgraph "Tooling Layer"
        toolReg["Tool Registration"]:::tool
        toolContrib["Tools Contrib"]:::tool
        toolExp["Tools Experimental"]:::tool
        codeFactory["Coding Factory"]:::tool
        dockerExec["Docker Executor"]:::tool
        jupyterExec["Jupyter Executor"]:::tool
        dockerEnv["Docker Python Env"]:::tool
    end

    %% Retrieval & Caching
    subgraph "Retrieval & Caching"
        cacheFactory["Cache Factory"]:::retrieval
        inMem["In-Memory Cache"]:::retrieval
        redisCache["Redis Cache"]:::retrieval
        cosmosCache["CosmosDB Cache"]:::retrieval
        diskCache["Disk Cache"]:::retrieval
        ragChroma["ChromaDB Query Engine"]:::retrieval
        ragMongo["MongoDB Query Engine"]:::retrieval
        ragFalkor["Falkor Graph Query Engine"]:::retrieval
        ragQdrant["Qdrant Engine"]:::retrieval
    end

    %% Logging & Events
    subgraph "Logging & Events"
        loggerFactory["Logger Factory"]:::log
        fileLogger["File Logger"]:::log
        sqliteLogger["SQLite Logger"]:::log
        consoleProcessor["Console Event Processor"]:::log
    end

    %% Documentation Website
    subgraph "Documentation Website"
        scriptsAPI["API & MkDocs Scripts"]:::docs
        mkdocsScript["Generate MkDocs"]:::docs
        sourceAPI["Site Source (docs/)"]:::docs
        sourceMkdocs["Site Source (mkdocs/)"]:::docs
    end

    %% Data Flows
    cli -->|"start"| conv
    proxy -->|"start"| conv
    notebooks -->|"start"| conv

    conv --> orchestrators
    asst --> orchestrators
    proxyAgent --> orchestrators

    orchestrators --> messages
    messages --> eventsPipeline
    eventsPipeline --> oaiClient
    eventsPipeline --> anthropic
    eventsPipeline --> gemini
    eventsPipeline --> registry
    eventsPipeline --> langchainFactory

    messages --> toolReg
    toolReg --> toolContrib
    toolReg --> toolExp
    toolReg --> codeFactory
    codeFactory --> dockerExec
    codeFactory --> jupyterExec
    codeFactory --> dockerEnv

    messages --> cacheFactory
    cacheFactory --> inMem
    cacheFactory --> redisCache
    cacheFactory --> cosmosCache
    cacheFactory --> diskCache

    messages --> ragChroma
    messages --> ragMongo
    messages --> ragFalkor
    messages --> ragQdrant

    messages --> loggerFactory
    messages --> fileLogger
    messages --> sqliteLogger
    messages --> consoleProcessor

    %% Click Events
    click conv "https://github.com/ag2ai/ag2/blob/main/autogen/agentchat/conversable_agent.py"
    click asst "https://github.com/ag2ai/ag2/blob/main/autogen/agentchat/assistant_agent.py"
    click proxyAgent "https://github.com/ag2ai/ag2/blob/main/autogen/agentchat/user_proxy_agent.py"
    click orchestrators "https://github.com/ag2ai/ag2/blob/main/autogen/agentchat/group/multi_agent_chat.py"
    click messages "https://github.com/ag2ai/ag2/blob/main/autogen/messages/base_message.py"
    click eventsPipeline "https://github.com/ag2ai/ag2/blob/main/autogen/events/agent_events.py"
    click oaiClient "https://github.com/ag2ai/ag2/blob/main/autogen/oai/client.py"
    click anthropic "https://github.com/ag2ai/ag2/blob/main/autogen/oai/anthropic.py"
    click gemini "https://github.com/ag2ai/ag2/blob/main/autogen/oai/gemini.py"
    click registry "https://github.com/ag2ai/ag2/blob/main/autogen/interop/registry.py"
    click langchainFactory "https://github.com/ag2ai/ag2/blob/main/autogen/interop/langchain/langchain_chat_model_factory.py"
    click toolReg "https://github.com/ag2ai/ag2/blob/main/autogen/tools/tool.py"
    click toolContrib "https://github.com/ag2ai/ag2/tree/main/autogen/tools/contrib"
    click toolExp "https://github.com/ag2ai/ag2/tree/main/autogen/tools/experimental"
    click codeFactory "https://github.com/ag2ai/ag2/blob/main/autogen/coding/factory.py"
    click dockerExec "https://github.com/ag2ai/ag2/blob/main/autogen/coding/docker_commandline_code_executor.py"
    click jupyterExec "https://github.com/ag2ai/ag2/blob/main/autogen/coding/jupyter/jupyter_code_executor.py"
    click dockerEnv "https://github.com/ag2ai/ag2/blob/main/autogen/environments/docker_python_environment.py"
    click cacheFactory "https://github.com/ag2ai/ag2/blob/main/autogen/cache/cache_factory.py"
    click inMem "https://github.com/ag2ai/ag2/blob/main/autogen/cache/in_memory_cache.py"
    click redisCache "https://github.com/ag2ai/ag2/blob/main/autogen/cache/redis_cache.py"
    click cosmosCache "https://github.com/ag2ai/ag2/blob/main/autogen/cache/cosmos_db_cache.py"
    click diskCache "https://github.com/ag2ai/ag2/blob/main/autogen/cache/disk_cache.py"
    click ragChroma "https://github.com/ag2ai/ag2/blob/main/autogen/agentchat/contrib/rag/chromadb_query_engine.py"
    click ragMongo "https://github.com/ag2ai/ag2/blob/main/autogen/agentchat/contrib/rag/mongodb_query_engine.py"
    click ragFalkor "https://github.com/ag2ai/ag2/blob/main/autogen/agentchat/contrib/graph_rag/falkor_graph_query_engine.py"
    click ragQdrant "https://github.com/ag2ai/ag2/blob/main/autogen/agentchat/contrib/vectordb/qdrant.py"
    click loggerFactory "https://github.com/ag2ai/ag2/blob/main/autogen/logger/logger_factory.py"
    click fileLogger "https://github.com/ag2ai/ag2/blob/main/autogen/logger/file_logger.py"
    click sqliteLogger "https://github.com/ag2ai/ag2/blob/main/autogen/logger/sqlite_logger.py"
    click consoleProcessor "https://github.com/ag2ai/ag2/blob/main/autogen/io/processors/console_event_processor.py"
    click cli "https://github.com/ag2ai/ag2/blob/main/autogen/mcp/__main__.py"
    click proxy "https://github.com/ag2ai/ag2/blob/main/autogen/mcp/mcp_proxy/mcp_proxy.py"
    click notebooks "https://github.com/ag2ai/ag2/blob/main/notebook/agentchat_quickstart_examples.ipynb"
    click scriptsAPI "https://github.com/ag2ai/ag2/blob/main/autogen/_website/generate_api_references.py"
    click mkdocsScript "https://github.com/ag2ai/ag2/blob/main/autogen/_website/generate_mkdocs.py"
    click sourceAPI "https://github.com/ag2ai/ag2/tree/main/website/docs/"
    click sourceMkdocs "https://github.com/ag2ai/ag2/tree/main/website/mkdocs/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef llm fill:#E2F8D2,stroke:#28a745,color:#28a745
    classDef tool fill:#FFE8C2,stroke:#d58214,color:#d58214
    classDef retrieval fill:#F0E6FF,stroke:#6f42c1,color:#6f42c1
    classDef log fill:#EDEDED,stroke:#6c757d,color:#6c757d
    classDef entry fill:#D1ECF1,stroke:#17a2b8,color:#17a2b8
    classDef docs fill:#D6EAF8,stroke:#3498db,color:#3498db
```
