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

> Architecture diagram of the GitHub repository aws-solutions-library-samples/guidance-for-multi-agent-orchestration-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-on-aws
- Repository: https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws

## Overview

This is a customer-support chatbot demo built around a Bedrock supervisor and specialized agents, with a React chat and agent-trace interface. The principal workflow is a customer inquiry, streamed through the web app and backend to the supervisor for specialist handling, then rendered as an answer. The README documents the agents’ Athena and knowledge-base capabilities; sampled backend files show agent construction and storage setup, but not the full runtime resolver or action execution. Those connections are therefore limited to documented relationships.

Main entry points: [`src/backend/lib/stacks/backend/multi-agent/index.ts`](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/index.ts) (Supervisor Agent), [`src/backend/lib/stacks/backend/multi-agent/product_recommendation/index.ts`](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/product_recommendation/index.ts) (Recommendation Agent), [`src/backend/lib/stacks/backend/multi-agent/personalization/index.ts`](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/personalization/index.ts) (Personalization Agent), [`src/frontend/src/pages/Home/Chat/index.tsx`](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/pages/Home/Chat/index.tsx) (Chat Interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Customer Web App"]
  node_chat["Chat Interface<br/>[index.tsx]"]
  node_chat_api["Chat API Client<br/>[api.ts]"]
  node_trace_parser["Trace Parser<br/>[traceParser.ts]"]
  node_trace_storage[("Trace Storage")]
  node_agent_flow["Agent Flow View<br/>[AgentFlowPanel.tsx]"]
end

subgraph group_backend["Agent Backend"]
  node_streaming["Streaming API<br/>[index.ts]"]
  node_resolver["Stream Resolver<br/>[index.ts]"]
  node_supervisor["Supervisor Agent<br/>[index.ts]"]
  node_order["Order Agent<br/>[index.ts]"]
  node_recommend["Recommendation Agent<br/>[index.ts]"]
  node_troubleshoot["Troubleshooting Agent<br/>[index.ts]"]
  node_personalize["Personalization Agent<br/>[index.ts]"]
  node_action["Action Executor<br/>[index.py]"]
end

subgraph group_data["Data and Knowledge"]
  node_storage[("Athena and Glue Data<br/>[index.ts]")]
  node_knowledge[("Knowledge Bases")]
  node_s3_data["S3 Data Services<br/>[s3DataService.ts]"]
end

subgraph group_identity["Access and Hosting"]
  node_auth["Cognito Auth<br/>[auth.ts]"]
  node_frontend_hosting["Web Hosting<br/>[index.ts]"]
end

node_customer(("Customer"))

node_customer -->|"submits inquiry"| node_chat
node_chat -.->|"sends messages"| node_chat_api
node_chat_api -.->|"opens stream"| node_streaming
node_streaming -->|"routes requests"| node_resolver
node_resolver -.->|"invokes agent"| node_supervisor
node_supervisor -->|"delegates orders"| node_order
node_supervisor -->|"delegates recommendations"| node_recommend
node_supervisor -->|"delegates troubleshooting"| node_troubleshoot
node_supervisor -->|"delegates personalization"| node_personalize
node_order -.->|"uses action group"| node_action
node_recommend -.->|"uses action group"| node_action
node_personalize -.->|"uses action group"| node_action
node_order -.->|"queries Athena"| node_storage
node_recommend -.->|"queries Athena"| node_storage
node_personalize -.->|"queries Athena"| node_storage
node_recommend -.->|"retrieves feedback"| node_knowledge
node_troubleshoot -.->|"searches guides"| node_knowledge
node_personalize -.->|"uses browsing history"| node_knowledge
node_chat -.->|"parses agent traces"| node_trace_parser
node_trace_parser -->|"updates traces"| node_trace_storage
node_agent_flow -->|"renders parsed traces"| node_trace_parser
node_agent_flow -->|"reads trace state"| node_trace_storage
node_customer -->|"authenticates"| node_auth
node_frontend_hosting -.->|"hosts app"| node_chat
node_s3_data -.->|"loads data"| node_storage

click node_chat "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/pages/Home/Chat/index.tsx"
click node_chat_api "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/pages/Home/Chat/api.ts"
click node_streaming "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/streaming-api/index.ts"
click node_resolver "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/streaming-api/resolver-function/index.ts"
click node_supervisor "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/index.ts"
click node_order "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/order_management/index.ts"
click node_recommend "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/product_recommendation/index.ts"
click node_troubleshoot "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/troubleshoot/index.ts"
click node_personalize "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/personalization/index.ts"
click node_action "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/action-group/executor-function/index.py"
click node_trace_parser "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/utilities/traceParser.ts"
click node_trace_storage "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/utilities/agentTraceStorage.ts"
click node_agent_flow "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/common/components/react_flow/AgentFlowPanel.tsx"
click node_auth "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/auth.ts"
click node_storage "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/storage/index.ts"
click node_knowledge "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/tree/main/src/backend/lib/stacks/backend/multi-agent"
click node_s3_data "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/pages/Home/Data/s3DataService.ts"
click node_frontend_hosting "https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/frontend/index.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_chat,node_chat_api,node_trace_parser,node_trace_storage,node_agent_flow toneBlue
class node_streaming,node_resolver,node_supervisor,node_order,node_recommend,node_troubleshoot,node_personalize,node_action toneAmber
class node_storage,node_knowledge,node_s3_data toneMint
class node_auth,node_frontend_hosting toneRose
class node_customer toneIndigo
```

## Components

### Customer Web App

- [Chat Interface](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/pages/Home/Chat/index.tsx): `src/frontend/src/pages/Home/Chat/index.tsx`
- [Chat API Client](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/pages/Home/Chat/api.ts): `src/frontend/src/pages/Home/Chat/api.ts`
- [Trace Parser](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/utilities/traceParser.ts): `src/frontend/src/utilities/traceParser.ts`
- [Trace Storage](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/utilities/agentTraceStorage.ts): `src/frontend/src/utilities/agentTraceStorage.ts`
- [Agent Flow View](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/common/components/react_flow/AgentFlowPanel.tsx): `src/frontend/src/common/components/react_flow/AgentFlowPanel.tsx`

### Agent Backend

- [Streaming API](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/streaming-api/index.ts): `src/backend/lib/stacks/backend/streaming-api/index.ts`
- [Stream Resolver](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/streaming-api/resolver-function/index.ts): `src/backend/lib/stacks/backend/streaming-api/resolver-function/index.ts`
- [Supervisor Agent](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/index.ts): `src/backend/lib/stacks/backend/multi-agent/index.ts`
- [Order Agent](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/order_management/index.ts): `src/backend/lib/stacks/backend/multi-agent/order_management/index.ts`
- [Recommendation Agent](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/product_recommendation/index.ts): `src/backend/lib/stacks/backend/multi-agent/product_recommendation/index.ts`
- [Troubleshooting Agent](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/troubleshoot/index.ts): `src/backend/lib/stacks/backend/multi-agent/troubleshoot/index.ts`
- [Personalization Agent](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/personalization/index.ts): `src/backend/lib/stacks/backend/multi-agent/personalization/index.ts`
- [Action Executor](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/multi-agent/action-group/executor-function/index.py): `src/backend/lib/stacks/backend/multi-agent/action-group/executor-function/index.py`

### Data and Knowledge

- [Athena and Glue Data](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/storage/index.ts): `src/backend/lib/stacks/backend/storage/index.ts`
- [Knowledge Bases](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/tree/main/src/backend/lib/stacks/backend/multi-agent): `src/backend/lib/stacks/backend/multi-agent`
- [S3 Data Services](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/frontend/src/pages/Home/Data/s3DataService.ts): `src/frontend/src/pages/Home/Data/s3DataService.ts`

### Access and Hosting

- [Cognito Auth](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/backend/auth.ts): `src/backend/lib/stacks/backend/auth.ts`
- [Web Hosting](https://github.com/aws-solutions-library-samples/guidance-for-multi-agent-orchestration-on-aws/blob/main/src/backend/lib/stacks/frontend/index.ts): `src/backend/lib/stacks/frontend/index.ts`

### Other components

- **Customer**

## Connections

- Customer → Chat Interface: submits inquiry
- Chat Interface → Chat API Client: sends messages
- Chat API Client → Streaming API: opens stream
- Streaming API → Stream Resolver: routes requests (evidence: `src/backend/lib/stacks/backend/streaming-api/index.ts`)
- Stream Resolver → Supervisor Agent: invokes agent
- Supervisor Agent → Order Agent: delegates orders (evidence: `src/backend/lib/stacks/backend/multi-agent/index.ts`)
- Supervisor Agent → Recommendation Agent: delegates recommendations (evidence: `src/backend/lib/stacks/backend/multi-agent/index.ts`)
- Supervisor Agent → Troubleshooting Agent: delegates troubleshooting (evidence: `src/backend/lib/stacks/backend/multi-agent/index.ts`)
- Supervisor Agent → Personalization Agent: delegates personalization (evidence: `src/backend/lib/stacks/backend/multi-agent/index.ts`)
- Order Agent → Action Executor: uses action group
- Recommendation Agent → Action Executor: uses action group
- Personalization Agent → Action Executor: uses action group
- Order Agent → Athena and Glue Data: queries Athena
- Recommendation Agent → Athena and Glue Data: queries Athena
- Personalization Agent → Athena and Glue Data: queries Athena
- Recommendation Agent → Knowledge Bases: retrieves feedback (evidence: `src/backend/lib/stacks/backend/multi-agent/product_recommendation/index.ts`)
- Troubleshooting Agent → Knowledge Bases: searches guides (evidence: `src/backend/lib/stacks/backend/multi-agent/troubleshoot/index.ts`)
- Personalization Agent → Knowledge Bases: uses browsing history (evidence: `src/backend/lib/stacks/backend/multi-agent/personalization/index.ts`)
- Chat Interface → Trace Parser: parses agent traces
- Trace Parser → Trace Storage: updates traces (evidence: `src/frontend/src/utilities/traceParser.ts`)
- Agent Flow View → Trace Parser: renders parsed traces (evidence: `src/frontend/src/common/components/react_flow/AgentFlowPanel.tsx`)
- Agent Flow View → Trace Storage: reads trace state (evidence: `src/frontend/src/common/components/react_flow/AgentFlowPanel.tsx`)
- Customer → Cognito Auth: authenticates
- Web Hosting → Chat Interface: hosts app
- S3 Data Services → Athena and Glue Data: loads data
