# aws300/a2a-scaffold architecture

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

- Interactive diagram: https://gitdiagram.com/aws300/a2a-scaffold
- Repository: https://github.com/aws300/a2a-scaffold

## Overview

A2A Scaffold is a standalone agent server with a built-in chat interface and a protocol endpoint for other agents. Its main workflow runs from chat input or an A2A request through the streaming service to an LLM-backed agent, then streams text and AG-UI events back. The README also documents agent configuration, skill discovery, MCP tools, document access, image/file uploads, and agent-card discovery. The source excerpts are partial, so links for unsampled routes and integrations follow README documentation and are omitted where their wiring is unclear.

Main entry points: [`src/agentx/services/a2a_service.py`](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/services/a2a_service.py) (Strands agent), [`frontend/src/components/chat/ChatPanel.tsx`](https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/components/chat/ChatPanel.tsx) (Chat panel), [`src/agentx/server/main.py`](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/server/main.py) (HTTP server), [`frontend/src/a2a-scaffold.tsx`](https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/a2a-scaffold.tsx) (Chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_chat_ui["Chat UI<br/>[a2a-scaffold.tsx]"]
  node_chat_panel["Chat panel<br/>[ChatPanel.tsx]"]
  node_markdown["Markdown rendering<br/>[index.ts]"]
  node_api_client["RPC client<br/>[client.ts]"]
  node_stream_hook["Stream state hook<br/>[useAgentStream.ts]"]
end

subgraph group_server["A2A server"]
  node_server_main["HTTP server<br/>[main.py]"]
  node_a2a_service["A2A streaming service<br/>[a2a_service.py]"]
  node_agent_card["Agent card<br/>[a2a_service.py]"]
  node_upload["Workspace upload<br/>[main.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agui_adapter["AG-UI adapter<br/>[agui_adapter.py]"]
  node_agent_config["Agent configuration"]
  node_agent_runtime["Strands agent<br/>[a2a_service.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_skills["Skills<br/>[skill_loader.py]"]
  node_mcp_loader["MCP loader<br/>[mcp_loader.py]"]
  node_agent_tools["Agent tools"]
  node_doc_tool["Document access<br/>[doc_tool.py]"]
end

node_person(("Chat user"))
node_a2a_client(("A2A client"))
node_llm{{"LLM provider"}}
node_mcp_services{{"MCP services"}}
node_library_service{{"Library service"}}

node_person -->|"uses"| node_chat_ui
node_chat_ui -->|"renders"| node_chat_panel
node_chat_ui -->|"loads config"| node_api_client
node_chat_panel -->|"streams chat"| node_server_main
node_chat_panel -->|"renders replies"| node_markdown
node_chat_panel -->|"uploads files"| node_upload
node_upload -->|"provides workspace files"| node_agent_runtime
node_a2a_client -->|"sends A2A requests"| node_server_main
node_a2a_client -->|"discovers agent"| node_agent_card
node_server_main -->|"dispatches protocol"| node_a2a_service
node_server_main -->|"reads and saves"| node_agent_config
node_a2a_service -->|"runs inference"| node_agent_runtime
node_agent_runtime -->|"requests completions"| node_llm
node_a2a_service -->|"encodes stream events"| node_agui_adapter
node_chat_panel -->|"processes stream"| node_stream_hook
node_stream_hook -->|"parses AG-UI events"| node_agui_adapter
node_agent_runtime -->|"loads skills"| node_skills
node_agent_runtime -->|"loads MCP tools"| node_mcp_loader
node_mcp_loader -.->|"connects tools"| node_mcp_services
node_agent_runtime -->|"invokes tools"| node_agent_tools
node_agent_tools -->|"uses document access"| node_doc_tool
node_doc_tool -->|"fetches documents"| node_library_service

click node_chat_ui "https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/a2a-scaffold.tsx"
click node_chat_panel "https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/components/chat/ChatPanel.tsx"
click node_markdown "https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/components/markdown/index.ts"
click node_api_client "https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/api/client.ts"
click node_server_main "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/server/main.py"
click node_a2a_service "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/services/a2a_service.py"
click node_agent_card "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/services/a2a_service.py"
click node_agui_adapter "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/agui_adapter.py"
click node_stream_hook "https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/lib/useAgentStream.ts"
click node_agent_runtime "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/services/a2a_service.py"
click node_skills "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/tools/skill_loader.py"
click node_mcp_loader "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/tools/mcp_loader.py"
click node_agent_tools "https://github.com/aws300/a2a-scaffold/tree/main/src/agentx/tools"
click node_doc_tool "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/tools/doc_tool.py"
click node_upload "https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/server/main.py"

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_chat_ui,node_chat_panel,node_markdown,node_api_client,node_stream_hook,node_person,node_a2a_client toneBlue
class node_server_main,node_a2a_service,node_agent_card,node_upload toneAmber
class node_agui_adapter,node_agent_config,node_agent_runtime toneMint
class node_skills,node_mcp_loader,node_agent_tools,node_doc_tool toneRose
class node_llm,node_mcp_services,node_library_service toneIndigo
```

## Components

### Chat experience

- [Chat UI](https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/a2a-scaffold.tsx): `frontend/src/a2a-scaffold.tsx`
- [Chat panel](https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/components/chat/ChatPanel.tsx): `frontend/src/components/chat/ChatPanel.tsx`
- [Markdown rendering](https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/components/markdown/index.ts): `frontend/src/components/markdown/index.ts`
- [RPC client](https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Stream state hook](https://github.com/aws300/a2a-scaffold/blob/main/frontend/src/lib/useAgentStream.ts): `frontend/src/lib/useAgentStream.ts`

### A2A server

- [HTTP server](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/server/main.py): `src/agentx/server/main.py`
- [A2A streaming service](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/services/a2a_service.py): `src/agentx/services/a2a_service.py`
- [Agent card](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/services/a2a_service.py): `src/agentx/services/a2a_service.py`
- [Workspace upload](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/server/main.py): `src/agentx/server/main.py`

### Agent runtime

- [AG-UI adapter](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/agui_adapter.py): `src/agentx/agui_adapter.py`
- **Agent configuration**
- [Strands agent](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/services/a2a_service.py): `src/agentx/services/a2a_service.py`

### Agent capabilities

- [Skills](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/tools/skill_loader.py): `src/agentx/tools/skill_loader.py`
- [MCP loader](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/tools/mcp_loader.py): `src/agentx/tools/mcp_loader.py`
- [Agent tools](https://github.com/aws300/a2a-scaffold/tree/main/src/agentx/tools): `src/agentx/tools`
- [Document access](https://github.com/aws300/a2a-scaffold/blob/main/src/agentx/tools/doc_tool.py): `src/agentx/tools/doc_tool.py`

### Other components

- **Chat user**
- **A2A client**
- **LLM provider**
- **MCP services**
- **Library service**

## Connections

- Chat user → Chat UI: uses
- Chat UI → Chat panel: renders
- Chat UI → RPC client: loads config
- Chat panel → HTTP server: streams chat
- Chat panel → Markdown rendering: renders replies
- Chat panel → Workspace upload: uploads files
- Workspace upload → Strands agent: provides workspace files
- A2A client → HTTP server: sends A2A requests
- A2A client → Agent card: discovers agent
- HTTP server → A2A streaming service: dispatches protocol
- HTTP server → Agent configuration: reads and saves
- A2A streaming service → Strands agent: runs inference
- Strands agent → LLM provider: requests completions
- A2A streaming service → AG-UI adapter: encodes stream events
- Chat panel → Stream state hook: processes stream
- Stream state hook → AG-UI adapter: parses AG-UI events
- Strands agent → Skills: loads skills
- Strands agent → MCP loader: loads MCP tools
- MCP loader → MCP services: connects tools
- Strands agent → Agent tools: invokes tools
- Agent tools → Document access: uses document access
- Document access → Library service: fetches documents