# heywhyayo/a2a_multi_agent architecture

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

- Interactive diagram: https://gitdiagram.com/heywhyayo/a2a_multi_agent
- Repository: https://github.com/heywhyayo/a2a_multi_agent

## Overview

This repository implements a NestJS crypto-research multi-agent service: clients submit A2A JSON-RPC tasks to an orchestrator, which delegates research and report formatting to specialist agents and returns task results or streamed updates. The researcher and formatter also expose task and agent-card endpoints. Shared A2A types and utilities define the protocol and task-building helpers. The README is a generic NestJS starter and does not document these product capabilities; some delegation and LLM interactions are only partially sampled, so those links are marked unverified.

Main entry points: [`src/shared/a2a.types.ts`](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/shared/a2a.types.ts) (A2A contracts), [`src/shared/a2a.utils.ts`](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/shared/a2a.utils.ts) (Task utilities), [`src/orchestrator/tasks.controller.ts`](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/tasks.controller.ts) (Orchestrator tasks), [`src/orchestrator/orchestrator.service.ts`](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/orchestrator.service.ts) (Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Task coordination"]
  node_orchestrator_tasks["Orchestrator tasks"]
  node_orchestrator_service["Orchestrator"]
  node_a2a_client["A2A HTTP client"]
  node_orchestrator_card["Orchestrator card"]
end

subgraph group_specialists["Specialist agents"]
  node_researcher_tasks["Research tasks"]
  node_researcher_service["Crypto researcher"]
  node_researcher_card["Researcher card"]
  node_formatter_tasks["Formatter tasks"]
  node_formatter_service["Report formatter"]
  node_formatter_card["Formatter card"]
end

subgraph group_protocol["A2A protocol"]
  node_a2a_types["A2A contracts<br/>[a2a.types.ts]"]
  node_a2a_utils["Task utilities<br/>[a2a.utils.ts]"]
end

subgraph group_runtime["Application runtime"]
  node_app_controller["Status endpoint<br/>[app.controller.ts]"]
  node_app_service["Status service<br/>[app.service.ts]"]
end

node_client(("API client"))
node_anthropic{{"Anthropic API"}}

node_client -->|"submits tasks"| node_orchestrator_tasks
node_client -->|"queries capabilities"| node_orchestrator_card
node_orchestrator_tasks -->|"dispatches methods"| node_orchestrator_service
node_orchestrator_service -->|"delegates requests"| node_a2a_client
node_a2a_client -.->|"sends A2A tasks"| node_researcher_tasks
node_a2a_client -.->|"sends A2A tasks"| node_formatter_tasks
node_researcher_tasks -->|"dispatches methods"| node_researcher_service
node_formatter_tasks -->|"dispatches methods"| node_formatter_service
node_researcher_service -.->|"requests research"| node_anthropic
node_formatter_service -.->|"generates report"| node_anthropic
node_orchestrator_service -->|"uses task contracts"| node_a2a_types
node_researcher_service -->|"uses task contracts"| node_a2a_types
node_formatter_service -->|"uses task contracts"| node_a2a_types
node_a2a_client -->|"uses task contracts"| node_a2a_types
node_orchestrator_tasks -->|"accepts task shapes"| node_a2a_types
node_researcher_tasks -->|"accepts task shapes"| node_a2a_types
node_formatter_tasks -->|"accepts task shapes"| node_a2a_types
node_orchestrator_tasks -->|"builds RPC replies"| node_a2a_utils
node_researcher_tasks -->|"builds RPC replies"| node_a2a_utils
node_formatter_tasks -->|"builds RPC replies"| node_a2a_utils
node_orchestrator_service -->|"builds task messages"| node_a2a_utils
node_researcher_service -->|"builds task artifacts"| node_a2a_utils
node_formatter_service -->|"builds task artifacts"| node_a2a_utils
node_a2a_utils -->|"constructs protocol data"| node_a2a_types
node_client -->|"checks availability"| node_app_controller
node_app_controller -->|"gets status"| node_app_service

click node_orchestrator_tasks "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/tasks.controller.ts"
click node_orchestrator_service "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/orchestrator.service.ts"
click node_a2a_client "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/a2a-client.service.ts"
click node_orchestrator_card "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/agent-card.controller.ts"
click node_researcher_tasks "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/researcher/tasks.controller.ts"
click node_researcher_service "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/researcher/researcher.service.ts"
click node_researcher_card "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/researcher/agent-card.controller.ts"
click node_formatter_tasks "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/formatter/tasks.controller.ts"
click node_formatter_service "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/formatter/formatter.service.ts"
click node_formatter_card "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/formatter/agent-card.controller.ts"
click node_a2a_types "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/shared/a2a.types.ts"
click node_a2a_utils "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/shared/a2a.utils.ts"
click node_app_controller "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/app.controller.ts"
click node_app_service "https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/app.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_orchestrator_tasks,node_orchestrator_service,node_a2a_client,node_orchestrator_card,node_client toneBlue
class node_researcher_tasks,node_researcher_service,node_researcher_card,node_formatter_tasks,node_formatter_service,node_formatter_card toneAmber
class node_a2a_types,node_a2a_utils,node_anthropic toneMint
class node_app_controller,node_app_service toneRose
```

## Components

### Task coordination

- [Orchestrator tasks](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/tasks.controller.ts): `src/orchestrator/tasks.controller.ts`
- [Orchestrator](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/orchestrator.service.ts): `src/orchestrator/orchestrator.service.ts`
- [A2A HTTP client](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/a2a-client.service.ts): `src/orchestrator/a2a-client.service.ts`
- [Orchestrator card](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/orchestrator/agent-card.controller.ts): `src/orchestrator/agent-card.controller.ts`

### Specialist agents

- [Research tasks](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/researcher/tasks.controller.ts): `src/researcher/tasks.controller.ts`
- [Crypto researcher](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/researcher/researcher.service.ts): `src/researcher/researcher.service.ts`
- [Researcher card](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/researcher/agent-card.controller.ts): `src/researcher/agent-card.controller.ts`
- [Formatter tasks](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/formatter/tasks.controller.ts): `src/formatter/tasks.controller.ts`
- [Report formatter](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/formatter/formatter.service.ts): `src/formatter/formatter.service.ts`
- [Formatter card](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/formatter/agent-card.controller.ts): `src/formatter/agent-card.controller.ts`

### A2A protocol

- [A2A contracts](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/shared/a2a.types.ts): `src/shared/a2a.types.ts`
- [Task utilities](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/shared/a2a.utils.ts): `src/shared/a2a.utils.ts`

### Application runtime

- [Status endpoint](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/app.controller.ts): `src/app.controller.ts`
- [Status service](https://github.com/heywhyayo/a2a_multi_agent/blob/main/src/app.service.ts): `src/app.service.ts`

### Other components

- **API client**
- **Anthropic API**

## Connections

- API client → Orchestrator tasks: submits tasks (evidence: `src/orchestrator/tasks.controller.ts`)
- API client → Orchestrator card: queries capabilities (evidence: `src/orchestrator/agent-card.controller.ts`)
- Orchestrator tasks → Orchestrator: dispatches methods (evidence: `src/orchestrator/tasks.controller.ts`)
- Orchestrator → A2A HTTP client: delegates requests (evidence: `src/orchestrator/orchestrator.service.ts`)
- A2A HTTP client → Research tasks: sends A2A tasks
- A2A HTTP client → Formatter tasks: sends A2A tasks
- Research tasks → Crypto researcher: dispatches methods (evidence: `src/researcher/tasks.controller.ts`)
- Formatter tasks → Report formatter: dispatches methods (evidence: `src/formatter/tasks.controller.ts`)
- Crypto researcher → Anthropic API: requests research
- Report formatter → Anthropic API: generates report
- Orchestrator → A2A contracts: uses task contracts (evidence: `src/orchestrator/orchestrator.service.ts`)
- Crypto researcher → A2A contracts: uses task contracts (evidence: `src/researcher/researcher.service.ts`)
- Report formatter → A2A contracts: uses task contracts (evidence: `src/formatter/formatter.service.ts`)
- A2A HTTP client → A2A contracts: uses task contracts (evidence: `src/orchestrator/a2a-client.service.ts`)
- Orchestrator tasks → A2A contracts: accepts task shapes (evidence: `src/orchestrator/tasks.controller.ts`)
- Research tasks → A2A contracts: accepts task shapes (evidence: `src/researcher/tasks.controller.ts`)
- Formatter tasks → A2A contracts: accepts task shapes (evidence: `src/formatter/tasks.controller.ts`)
- Orchestrator tasks → Task utilities: builds RPC replies (evidence: `src/orchestrator/tasks.controller.ts`)
- Research tasks → Task utilities: builds RPC replies (evidence: `src/researcher/tasks.controller.ts`)
- Formatter tasks → Task utilities: builds RPC replies (evidence: `src/formatter/tasks.controller.ts`)
- Orchestrator → Task utilities: builds task messages (evidence: `src/orchestrator/orchestrator.service.ts`)
- Crypto researcher → Task utilities: builds task artifacts (evidence: `src/researcher/researcher.service.ts`)
- Report formatter → Task utilities: builds task artifacts (evidence: `src/formatter/formatter.service.ts`)
- Task utilities → A2A contracts: constructs protocol data (evidence: `src/shared/a2a.utils.ts`)
- API client → Status endpoint: checks availability (evidence: `src/app.controller.ts`)
- Status endpoint → Status service: gets status (evidence: `src/app.controller.ts`)
