# aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws architecture

> Architecture diagram of the GitHub repository aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws
- Repository: https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws

## Overview

This repository implements an AWS-hosted customer-support chat application. A customer signs in, sends a message through the React interface, and receives streamed responses coordinated by a LangGraph supervisor. The supervisor delegates to specialist agents for order management, recommendations, personalization, and troubleshooting, then returns a response. The graph also shows the application’s data, knowledge-base, and streaming layers. The README documents the overall AWS architecture; source excerpts confirm several frontend and supervisor call paths, but much of the specialist-agent and infrastructure wiring was not sampled.

Main entry points: [`infra/lib/ecs-stack.ts`](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/ecs-stack.ts) (ECS agent services), [`agents/supervisor-agent/src/client.py`](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/client.py) (Agent HTTP client), [`agents/personalization-agent/src/agent.py`](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/personalization-agent/src/agent.py) (Personalization), [`agents/order-management-agent/src/agent.py`](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/order-management-agent/src/agent.py) (Order management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Customer interface"]
  node_web_app["React chat app<br/>[App.tsx]"]
  node_chat_ui["WebSocket chat"]
  node_auth["Authentication"]
  node_event_hook["Supervisor events"]
end

subgraph group_orchestration["Agent orchestration"]
  node_supervisor_api["Supervisor API<br/>[main.py]"]
  node_supervisor["LangGraph supervisor<br/>[agent.py]"]
  node_agent_client["Agent HTTP client<br/>[client.py]"]
end

subgraph group_specialists["Specialist agents"]
  node_order_agent["Order management<br/>[agent.py]"]
  node_recommend_agent["Product recommendations<br/>[agent.py]"]
  node_personal_agent["Personalization<br/>[agent.py]"]
  node_trouble_agent["Troubleshooting<br/>[agent.py]"]
  node_order_data["Order data tools"]
  node_recommend_data["Recommendation data<br/>[database.py]"]
  node_personal_data["Customer profile data<br/>[database.py]"]
end

subgraph group_services["Data and AI services"]
  node_aurora[("Aurora PostgreSQL<br/>[database-stack.ts]")]
  node_bedrock_kb[("Bedrock knowledge bases")]
  node_bedrock["Amazon Bedrock"]
  node_session_store[("Session checkpoints")]
end

subgraph group_platform["AWS application platform"]
  node_appsync["AppSync streaming"]
  node_ecs["ECS agent services<br/>[ecs-stack.ts]"]
  node_monitoring["CloudWatch monitoring"]
end

node_customer(("Customer"))

node_customer -->|"uses"| node_web_app
node_web_app -->|"requires sign-in"| node_auth
node_web_app -->|"routes to"| node_chat_ui
node_chat_ui -->|"uses events"| node_event_hook
node_event_hook -->|"publishes request"| node_appsync
node_appsync -.->|"streams chat"| node_supervisor_api
node_supervisor_api -->|"processes requests"| node_supervisor
node_supervisor -->|"calls agents"| node_agent_client
node_agent_client -->|"HTTP dispatch"| node_order_agent
node_agent_client -->|"HTTP dispatch"| node_recommend_agent
node_agent_client -->|"HTTP dispatch"| node_personal_agent
node_agent_client -.->|"HTTP dispatch"| node_trouble_agent
node_order_agent -.->|"uses tools"| node_order_data
node_recommend_agent -.->|"uses data"| node_recommend_data
node_personal_agent -.->|"uses data"| node_personal_data
node_order_data -.->|"queries"| node_aurora
node_recommend_data -.->|"queries"| node_aurora
node_personal_data -.->|"stores profiles"| node_aurora
node_supervisor -->|"checkpoints sessions"| node_session_store
node_order_agent -.->|"uses AI"| node_bedrock
node_recommend_agent -.->|"uses AI"| node_bedrock
node_personal_agent -.->|"uses AI"| node_bedrock
node_trouble_agent -.->|"uses AI"| node_bedrock
node_trouble_agent -.->|"retrieves guidance"| node_bedrock_kb
node_personal_agent -.->|"retrieves knowledge"| node_bedrock_kb
node_ecs -.->|"hosts service"| node_supervisor_api
node_ecs -.->|"hosts service"| node_order_agent
node_ecs -.->|"hosts service"| node_recommend_agent
node_ecs -.->|"hosts service"| node_personal_agent
node_ecs -.->|"hosts service"| node_trouble_agent
node_monitoring -.->|"observes services"| node_ecs

click node_web_app "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/frontend/src/App.tsx"
click node_chat_ui "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/frontend/src/components/Chat/WebSocketChatInterface.tsx"
click node_auth "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/frontend/src/components/auth/AuthenticatorWrapper.tsx"
click node_event_hook "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/frontend/src/hooks/useSupervisorAgentEvents.ts"
click node_appsync "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/streaming-api-stack.ts"
click node_supervisor_api "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/main.py"
click node_supervisor "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/agent.py"
click node_agent_client "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/client.py"
click node_order_agent "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/order-management-agent/src/agent.py"
click node_recommend_agent "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/product-recommendation-agent/src/agent.py"
click node_personal_agent "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/personalization-agent/src/agent.py"
click node_trouble_agent "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/troubleshooting-agent/src/agent.py"
click node_order_data "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/order-management-agent/src/postgresql_tools.py"
click node_recommend_data "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/product-recommendation-agent/src/database.py"
click node_personal_data "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/personalization-agent/src/database.py"
click node_aurora "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/database-stack.ts"
click node_bedrock_kb "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/bedrock-knowledge-base-stack.ts"
click node_session_store "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/dynamodb_session_saver.py"
click node_ecs "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/ecs-stack.ts"
click node_monitoring "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/monitoring-stack.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_web_app,node_chat_ui,node_auth,node_event_hook toneBlue
class node_supervisor_api,node_supervisor,node_agent_client toneAmber
class node_order_agent,node_recommend_agent,node_personal_agent,node_trouble_agent,node_order_data,node_recommend_data,node_personal_data toneMint
class node_aurora,node_bedrock_kb,node_bedrock,node_session_store toneRose
class node_appsync,node_ecs,node_monitoring,node_customer toneIndigo
```

## Components

### Customer interface

- [React chat app](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [WebSocket chat](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/frontend/src/components/Chat/WebSocketChatInterface.tsx): `frontend/src/components/Chat/WebSocketChatInterface.tsx`
- [Authentication](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/frontend/src/components/auth/AuthenticatorWrapper.tsx): `frontend/src/components/auth/AuthenticatorWrapper.tsx`
- [Supervisor events](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/frontend/src/hooks/useSupervisorAgentEvents.ts): `frontend/src/hooks/useSupervisorAgentEvents.ts`

### Agent orchestration

- [Supervisor API](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/main.py): `agents/supervisor-agent/src/main.py`
- [LangGraph supervisor](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/agent.py): `agents/supervisor-agent/src/agent.py`
- [Agent HTTP client](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/client.py): `agents/supervisor-agent/src/client.py`

### Specialist agents

- [Order management](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/order-management-agent/src/agent.py): `agents/order-management-agent/src/agent.py`
- [Product recommendations](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/product-recommendation-agent/src/agent.py): `agents/product-recommendation-agent/src/agent.py`
- [Personalization](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/personalization-agent/src/agent.py): `agents/personalization-agent/src/agent.py`
- [Troubleshooting](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/troubleshooting-agent/src/agent.py): `agents/troubleshooting-agent/src/agent.py`
- [Order data tools](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/order-management-agent/src/postgresql_tools.py): `agents/order-management-agent/src/postgresql_tools.py`
- [Recommendation data](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/product-recommendation-agent/src/database.py): `agents/product-recommendation-agent/src/database.py`
- [Customer profile data](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/personalization-agent/src/database.py): `agents/personalization-agent/src/database.py`

### Data and AI services

- [Aurora PostgreSQL](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/database-stack.ts): `infra/lib/database-stack.ts`
- [Bedrock knowledge bases](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/bedrock-knowledge-base-stack.ts): `infra/lib/bedrock-knowledge-base-stack.ts`
- **Amazon Bedrock**
- [Session checkpoints](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/agents/supervisor-agent/src/dynamodb_session_saver.py): `agents/supervisor-agent/src/dynamodb_session_saver.py`

### AWS application platform

- [AppSync streaming](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/streaming-api-stack.ts): `infra/lib/streaming-api-stack.ts`
- [ECS agent services](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/ecs-stack.ts): `infra/lib/ecs-stack.ts`
- [CloudWatch monitoring](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-langgraph-on-aws/blob/main/infra/lib/monitoring-stack.ts): `infra/lib/monitoring-stack.ts`

### Other components

- **Customer**

## Connections

- Customer → React chat app: uses (evidence: `README.md`)
- React chat app → Authentication: requires sign-in (evidence: `frontend/src/App.tsx`)
- React chat app → WebSocket chat: routes to (evidence: `frontend/src/App.tsx`)
- WebSocket chat → Supervisor events: uses events (evidence: `frontend/src/components/Chat/WebSocketChatInterface.tsx`)
- Supervisor events → AppSync streaming: publishes request (evidence: `frontend/src/hooks/useSupervisorAgentEvents.ts`)
- AppSync streaming → Supervisor API: streams chat (evidence: `README.md`)
- Supervisor API → LangGraph supervisor: processes requests (evidence: `agents/supervisor-agent/src/main.py`)
- LangGraph supervisor → Agent HTTP client: calls agents (evidence: `agents/supervisor-agent/src/agent.py`)
- Agent HTTP client → Order management: HTTP dispatch (evidence: `agents/supervisor-agent/src/client.py`)
- Agent HTTP client → Product recommendations: HTTP dispatch (evidence: `agents/supervisor-agent/src/client.py`)
- Agent HTTP client → Personalization: HTTP dispatch (evidence: `agents/supervisor-agent/src/client.py`)
- Agent HTTP client → Troubleshooting: HTTP dispatch (evidence: `README.md`)
- Order management → Order data tools: uses tools
- Product recommendations → Recommendation data: uses data
- Personalization → Customer profile data: uses data
- Order data tools → Aurora PostgreSQL: queries (evidence: `README.md`)
- Recommendation data → Aurora PostgreSQL: queries (evidence: `README.md`)
- Customer profile data → Aurora PostgreSQL: stores profiles
- LangGraph supervisor → Session checkpoints: checkpoints sessions (evidence: `agents/supervisor-agent/src/agent.py`)
- Order management → Amazon Bedrock: uses AI (evidence: `README.md`)
- Product recommendations → Amazon Bedrock: uses AI (evidence: `README.md`)
- Personalization → Amazon Bedrock: uses AI (evidence: `README.md`)
- Troubleshooting → Amazon Bedrock: uses AI (evidence: `README.md`)
- Troubleshooting → Bedrock knowledge bases: retrieves guidance (evidence: `README.md`)
- Personalization → Bedrock knowledge bases: retrieves knowledge (evidence: `README.md`)
- ECS agent services → Supervisor API: hosts service (evidence: `README.md`)
- ECS agent services → Order management: hosts service (evidence: `README.md`)
- ECS agent services → Product recommendations: hosts service (evidence: `README.md`)
- ECS agent services → Personalization: hosts service (evidence: `README.md`)
- ECS agent services → Troubleshooting: hosts service (evidence: `README.md`)
- CloudWatch monitoring → ECS agent services: observes services (evidence: `README.md`)
