# bhancockio/agent2agent architecture

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

- Interactive diagram: https://gitdiagram.com/bhancockio/agent2agent
- Repository: https://github.com/bhancockio/agent2agent

## Overview

##### Project type and purpose
- This repository is a set of demo applications for Google’s Agent-to-Agent (A2A) SDK.
- It contains two self-contained Python projects:
- a2a_simple: a minimal single-agent example with a test client
- a2a_friend_scheduling: a multi-agent orchestration demo where a “host” agent coordinates multiple “friend” agents to schedule a meeting

##### File structure
- Top-level:
- a2a_simple/
- a2a_friend_scheduling/
- README.md
- a2a_simple:
- __main__.py: entry point for the single agent
- agent_executor.py: wraps the A2A SDK agent runtime
- test_client.py: invokes the agent via HTTP or SDK call
- a2a_friend_scheduling:
- host_agent_adk/: the host agent implementation (agent.py, pickleball_tools, remote_agent_connection)
- karley_agent_adk/, kaitlynn_agent_langgraph/, nate_agent_crewai/: three friend agent subprojects, each with its own agent.py and executor
- ai_docs/: planning and task definitions for each agent
- Each subproject has its own pyproject.toml and uv.lock indicating they run as separate Python services under Uvicorn (ASGI).

##### Key insights from README
- The friend scheduling demo showcases multi-agent orchestration.
- Each agent runs in its own process/container and communicates through the A2A SDK (typically HTTP/WebSocket).

##### Main components
a. For a2a_simple:
- Test Client
- Simple Agent Service
- A2A SDK library layer
b. For a2a_friend_scheduling:
- Host Agent Service
- Karley Agent Service
- Kaitlynn Agent Service
- Nate Agent Service
- ai_docs (conceptual planning layer, can be annotated but not a runtime component)
- Underlying A2A communication fabric (HTTP/WebSocket endpoints)

##### Relationships and data flow
- a2a_simple:
Test Client → HTTP POST → Simple Agent → A2A SDK → Agent logic → HTTP response → Test Client
- a2a_friend_scheduling:
1. Host Agent receives scheduling request (from a user or test harness).
2. Host Agent uses remote_agent_connection to invoke each friend agent’s HTTP endpoint.
3. Each friend agent processes its part (availability, preferences) and responds.
4. Host Agent aggregates responses, applies pickleball_tools or scheduling logic, and returns final plan.

##### Architectural patterns and design principles
- Microservices – each agent is its own service with isolation and independent deployment.
- Orchestration – Host Agent serves as the coordinator of multiple worker agents.
- SDK abstraction – A2A SDK provides uniform interface for agent-to-agent calls, hiding HTTP details.

##### Technologies and frameworks
- Python 3.x
- A2A Python SDK
- Uvicorn (ASGI server)
- pyproject.toml/poetry for dependency management

##### Elements
- From client to agent(s)
- Between Host Agent and each Friend Agent

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Simple A2A Demo
    subgraph "Simple A2A Demo"
        direction TB
        TestClient["Test Client"]:::external
        SimpleAgent["Simple Agent Service\n__main__.py\nagent_executor.py"]:::service
        A2ASDK["A2A SDK Layer"]:::sdk
        TestClient -->|"HTTP POST"| SimpleAgent
        SimpleAgent -->|"calls SDK"| A2ASDK
        A2ASDK -->|"executes agent logic"| SimpleAgent
        SimpleAgent -->|"HTTP response"| TestClient
    end

    %% Friend Scheduling Demo
    subgraph "Friend Scheduling Demo"
        direction TB
        ExternalClient2["User/Test Harness"]:::external
        HostAgent["Host Agent Service\nagent.py\npickleball_tools.py\nremote_agent_connection.py"]:::orchestration
        aiDocs["ai_docs\n(planning docs)"]:::concept

        ExternalClient2 -->|"HTTP POST scheduling request"| HostAgent

        %% Fan-out to friend agents
        subgraph "Friend Agents"
            direction TB
            KarleyAgent["Karley Agent Service\nagent.py\nagent_executor.py"]:::worker
            KaitlynnAgent["Kaitlynn Agent Service\nagent.py\nagent_executor.py"]:::worker
            NateAgent["Nate Agent Service\nagent.py\nagent_executor.py"]:::worker
        end

        HostAgent -->|"HTTP call"| KarleyAgent
        HostAgent -->|"HTTP call"| KaitlynnAgent
        HostAgent -->|"HTTP call"| NateAgent

        KarleyAgent -->|"response"| HostAgent
        KaitlynnAgent -->|"response"| HostAgent
        NateAgent -->|"response"| HostAgent

        HostAgent -->|"aggregate responses & return plan"| ExternalClient2
    end

    %% Click Events
    click TestClient "https://github.com/bhancockio/agent2agent/blob/main/a2a_simple/test_client.py"
    click SimpleAgent "https://github.com/bhancockio/agent2agent/blob/main/a2a_simple/__main__.py"
    click A2ASDK "https://github.com/bhancockio/agent2agent/blob/main/a2a_simple/agent_executor.py"

    click HostAgent "https://github.com/bhancockio/agent2agent/blob/main/a2a_friend_scheduling/host_agent_adk/host/agent.py"
    click KarleyAgent "https://github.com/bhancockio/agent2agent/blob/main/a2a_friend_scheduling/karley_agent_adk/agent.py"
    click KaitlynnAgent "https://github.com/bhancockio/agent2agent/blob/main/a2a_friend_scheduling/kaitlynn_agent_langgraph/app/agent.py"
    click NateAgent "https://github.com/bhancockio/agent2agent/blob/main/a2a_friend_scheduling/nate_agent_crewai/agent.py"
    click aiDocs "https://github.com/bhancockio/agent2agent/tree/main/a2a_friend_scheduling/ai_docs"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef service fill:#bbf,stroke:#333,stroke-width:1px
    classDef sdk fill:#ffb,stroke:#333,stroke-width:1px
    classDef orchestration fill:#bfb,stroke:#333,stroke-width:1px
    classDef worker fill:#fbf,stroke:#333,stroke-width:1px
    classDef concept fill:#eee,stroke:#999,stroke-dasharray: 5 5
```
