# themanojdesai/python-a2a architecture

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

- Interactive diagram: https://gitdiagram.com/themanojdesai/python-a2a
- Repository: https://github.com/themanojdesai/python-a2a

## Overview

##### Project Type and Purpose
- Python A2A is an open-source Python library implementing Google’s Agent-to-Agent (A2A) protocol with Model Context Protocol (MCP) integration, plus CLI tools, discovery registry, workflow engine, LangChain bridges, and a visual UI for building agent networks.
- It’s not a monolithic web app but a modular SDK + microservice-style framework. It can be embedded in Python apps, run as standalone servers, or orchestrated via CLI/UI.

##### Key Architectural Components (nine modules from README & file tree)
A. Models
- Data classes for messages, tasks, agent cards (python_a2a/models).
B. Client
- HTTP/streaming clients for talking to A2A servers, building agent networks, routing (python_a2a/client + StreamingClient + A2AClient).
C. Server
- Base A2A servers that expose skills as REST/SSE endpoints (python_a2a/server, A2AServer, HTTP handlers, LLM providers).
D. Discovery
- Agent registry and discovery microservice (python_a2a/discovery, AgentRegistry, DiscoveryClient).
E. MCP
- MCP server/client tool framework for tool-using agents (python_a2a/mcp).
F. LangChain Integration
- Bridges to convert between LangChain tools/agents and A2A/MCP servers (python_a2a/langchain).
G. Workflow Engine
- Fluent API to orchestrate multi-agent workflows with branching/parallelism (python_a2a/workflow, python_a2a/agent_flow/engine).
H. Agent Flow UI
- Frontend (JS/CSS) + backend for visual workflow editor (python_a2a/agent_flow/server + static assets).
I. CLI
- Command-line entry points for sending messages, launching servers, running workflows, and starting UI (python_a2a/cli.py, start_ui.py).

##### Relationships & Interactions
- Clients → call → Servers (HTTP/SSE).
- Servers ↔ Discovery Registry (register and query capabilities).
- Servers → invoke → MCP tools (if configured).
- Workflow Engine & Agent Network orchestrate calls to multiple servers.
- CLI & UI → use → Client modules / Workflow Engine to drive interactions.
- LangChain bridges can sit between Client/Server and LangChain pipelines.
- All components share common Models and Utils.

##### Architectural Patterns
- Modular design: each major feature is a subpackage.
- Microservice style: servers (A2A, MCP, registry) communicate over REST/SSE.
- pluggable protocol layers: A2A core, MCP, LangChain.
- MVC for UI: backend API + static frontend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library Modules
    subgraph "Core Library" 
        Models["Models\n(python_a2a/models)"]:::core
        Utils["Utilities\n(python_a2a/utils)"]:::core
    end

    %% Client Layer
    subgraph "Client Layer" 
        A2AClient["A2AClient\n(python_a2a/client/base.py)"]:::client
        StreamingClient["StreamingClient\n(python_a2a/client/streaming.py)"]:::client
        Router["Router\n(python_a2a/client/router.py)"]:::client
    end

    %% Server Layer
    subgraph "Server Layer"
        A2AServer["A2AServer\n(python_a2a/server/a2a_server.py)"]:::server
        HTTPServer["HTTP Handlers\n(python_a2a/server/http.py)"]:::server
        LLMProviders["LLM Providers\n(python_a2a/server/llm)"]:::server
    end

    %% Discovery Registry
    subgraph "Discovery Registry"
        AgentRegistry["AgentRegistry\n(python_a2a/discovery/registry.py)"]:::server
    end

    %% MCP Framework
    subgraph "MCP Framework"
        MCPServer["MCP Server\n(python_a2a/mcp/fastmcp.py)"]:::integration
        MCPTransport["Transport\n(python_a2a/mcp/transport/fastapi.py)"]:::integration
    end

    %% LangChain Integration
    subgraph "LangChain Integration"
        LCBridge["A2A Bridge\n(python_a2a/langchain/a2a.py)"]:::integration
    end

    %% Workflow Engine
    subgraph "Workflow Engine"
        FlowCore["Flow API\n(python_a2a/workflow/flow.py)"]:::client
        EngineExecutor["Engine Executor\n(python_a2a/agent_flow/engine/executor.py)"]:::client
    end

    %% Agent Flow UI Backend
    subgraph "Agent Flow UI Backend"
        UIFeAPI["API Endpoints\n(python_a2a/agent_flow/server/api.py)"]:::server
        StaticAssets["Static Assets\n(python_a2a/agent_flow/server/static)"]:::ui
    end

    %% UI Frontend
    AgentUI["Agent Flow UI\n(React/JS)"]:::ui

    %% CLI
    subgraph "CLI Tools"
        MainCLI["Main CLI\n(python_a2a/cli.py)"]:::client
        StartUI["UI Starter\n(start_ui.py)"]:::client
    end

    %% External LLM
    ExternalLLM["LLM Providers\n(Anthropic, OpenAI, Bedrock)"]:::external

    %% Relationships
    Models -->|uses| A2AClient
    Utils -->|shared by| A2AClient
    A2AClient -->|HTTP/SSE| A2AServer
    StreamingClient -->|SSE| A2AServer
    Router -->|routes| A2AClient
    A2AServer -->|register/discover| AgentRegistry
    A2AServer -->|invoke tools| MCPServer
    MCPServer -->|transport| MCPTransport
    LCBridge -->|integrates| A2AClient
    FlowCore -->|orchestrates| A2AClient
    EngineExecutor -->|executes| FlowCore
    MainCLI -->|calls| FlowCore
    AgentUI -->|drives| UIFeAPI
    UIFeAPI -->|uses| EngineExecutor
    UIFeAPI -->|serves| StaticAssets
    StartUI -->|starts| UIFeAPI
    A2AServer -->|calls| ExternalLLM

    %% Click Events
    click Models "https://github.com/themanojdesai/python-a2a/tree/main/python_a2a/models"
    click Utils "https://github.com/themanojdesai/python-a2a/tree/main/python_a2a/utils"
    click A2AClient "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/client/base.py"
    click StreamingClient "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/client/streaming.py"
    click Router "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/client/router.py"
    click A2AServer "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/server/a2a_server.py"
    click HTTPServer "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/server/http.py"
    click LLMProviders "https://github.com/themanojdesai/python-a2a/tree/main/python_a2a/server/llm"
    click AgentRegistry "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/discovery/registry.py"
    click MCPServer "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/mcp/fastmcp.py"
    click MCPTransport "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/mcp/transport/fastapi.py"
    click LCBridge "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/langchain/a2a.py"
    click FlowCore "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/workflow/flow.py"
    click EngineExecutor "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/agent_flow/engine/executor.py"
    click UIFeAPI "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/agent_flow/server/api.py"
    click StaticAssets "https://github.com/themanojdesai/python-a2a/tree/main/python_a2a/agent_flow/server/static"
    click MainCLI "https://github.com/themanojdesai/python-a2a/blob/main/python_a2a/cli.py"
    click StartUI "https://github.com/themanojdesai/python-a2a/blob/main/start_ui.py"

    %% Styles
    classDef core fill:#cccccc,stroke:#333,stroke-width:1px;
    classDef client fill:#a0c4ff,stroke:#0366d6,stroke-width:1px;
    classDef server fill:#caffbf,stroke:#2d6a4f,stroke-width:1px,stroke-dasharray: 5 5;
    classDef ui fill:#ffd6a5,stroke:#f06543,stroke-width:1px;
    classDef integration fill:#d0bfff,stroke:#6f42c1,stroke-width:1px;
    classDef external fill:#e0e0e0,stroke:#555,stroke-width:1px,stroke-dasharray: 2 2;
```
