# aws-samples/sample-voice-ai-agent-studio architecture

> Architecture diagram of the GitHub repository aws-samples/sample-voice-ai-agent-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-voice-ai-agent-studio
- Repository: https://github.com/aws-samples/sample-voice-ai-agent-studio

## Overview

Conversational AI Agent Studio guides users from agent setup—template, speech pipeline, voice, prompt, workflow, and integrations—to browser testing and deployment on Bedrock AgentCore; agents can also be reached by PSTN or SIP relays. Separate product branches manage RAG and tools, agent history, and evaluation suites, including simulated conversations and judge scoring. The graph combines documented capabilities with evidenced source references; several API routes and frontend flows are represented at subsystem level because their implementation excerpts were not provided.

Main entry points: [`source/agent/main.py`](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/main.py) (AgentCore voice runtime), [`source/frontend/src/App.tsx`](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/App.tsx) (Studio UI), [`source/eval-runner/nova-sonic-eval-harness/main.py`](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/main.py) (Conversation evaluator), [`source/frontend/src/services/apiClient.ts`](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/services/apiClient.ts) (Authenticated API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_studio["Agent Studio"]
  node_ui["Studio UI<br/>[App.tsx]"]
  node_wizard["Agent wizard<br/>[WizardContext.tsx]"]
  node_wizard_steps["Pipeline selection"]
  node_agent_admin["Agent management<br/>[AgentDetail.tsx]"]
  node_api_client["Authenticated API client<br/>[apiClient.ts]"]
  node_api["Studio API handlers"]
  node_demo_api["Agent configuration API<br/>[demos_stack.py]"]
end

subgraph group_runtime["Voice Runtime"]
  node_agent["AgentCore voice runtime<br/>[main.py]"]
  node_agent_framework["Strands BidiAgent<br/>[strands_agent.py]"]
  node_history[("Call history")]
end

subgraph group_integrations["Agent Integrations"]
  node_tool_config["Tool integrations<br/>[registry.py]"]
  node_rag_runtime["RAG runtime<br/>[rag_tools.py]"]
  node_rag_api["RAG management API<br/>[rag_handler.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_ui["Evaluation suite UI"]
  node_eval_api["Evaluation APIs<br/>[eval_handler.py]"]
  node_eval_runner["Conversation evaluator<br/>[main.py]"]
  node_stream["Nova Sonic streaming"]
  node_judge["LLM judge"]
  node_results[("Evaluation results<br/>[results_manager.py]")]
end

subgraph group_channels["Voice Channels"]
  node_pstn["PSTN relay<br/>[tac_server.py]"]
  node_sip["SIP relay<br/>[index.js]"]
end

node_user(("Studio user"))
node_caller(("Voice caller"))
node_aws{{"AWS Bedrock"}}
node_phone_network{{"Phone network"}}

node_user -->|"configures agents"| node_ui
node_ui -->|"routes wizard"| node_wizard_steps
node_wizard_steps -->|"updates pipeline"| node_wizard
node_ui -->|"routes management"| node_agent_admin
node_agent_admin -.->|"requests API"| node_api_client
node_api_client -->|"sends authenticated requests"| node_api
node_api_client -.->|"loads agent configurations"| node_demo_api
node_ui -->|"configures knowledge sources"| node_rag_api
node_rag_api -->|"uses requests"| node_api_client
node_api -.->|"provides agent configuration"| node_agent
node_agent -->|"creates agent"| node_agent_framework
node_agent -->|"logs conversations"| node_history
node_agent -->|"loads tools"| node_tool_config
node_agent -->|"loads RAG tools"| node_rag_runtime
node_agent -->|"runs on AgentCore"| node_aws
node_user -->|"defines evaluation suites"| node_eval_ui
node_eval_ui -.->|"manages evaluations"| node_eval_api
node_eval_api -.->|"starts evaluations"| node_eval_runner
node_eval_runner -->|"streams test sessions"| node_stream
node_eval_runner -->|"scores conversations"| node_judge
node_eval_runner -.->|"records results"| node_results
node_caller -->|"calls phone number"| node_pstn
node_pstn -.->|"bridges voice session"| node_agent
node_caller -->|"starts SIP call"| node_sip
node_sip -.->|"bridges voice session"| node_agent
node_phone_network -->|"carries calls"| node_pstn
node_phone_network -->|"carries SIP media"| node_sip

click node_ui "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/App.tsx"
click node_wizard "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/context/WizardContext.tsx"
click node_wizard_steps "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/pages/PipelineSelection.tsx"
click node_agent_admin "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/pages/AgentDetail.tsx"
click node_api_client "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/services/apiClient.ts"
click node_api "https://github.com/aws-samples/sample-voice-ai-agent-studio/tree/main/source/api"
click node_demo_api "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/deployment/demos_stack/demos_stack.py"
click node_agent "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/main.py"
click node_agent_framework "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/strands_agent.py"
click node_history "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/call_history_logger.py"
click node_tool_config "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/tools/registry.py"
click node_rag_runtime "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/rag_tools.py"
click node_rag_api "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/api/rag_handler.py"
click node_eval_ui "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/pages/EvalSuiteDetail.tsx"
click node_eval_api "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/api/eval_handler.py"
click node_eval_runner "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/main.py"
click node_stream "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/core/sonic_stream_manager.py"
click node_judge "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/evaluation/llm_judge_binary.py"
click node_results "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/logging_/results_manager.py"
click node_pstn "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/telephony/pstn/tac_server.py"
click node_sip "https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/telephony/sip/bridge/index.js"

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_ui,node_wizard,node_wizard_steps,node_agent_admin,node_api_client,node_api,node_demo_api,node_user toneBlue
class node_agent,node_agent_framework,node_history toneAmber
class node_tool_config,node_rag_runtime,node_rag_api toneMint
class node_eval_ui,node_eval_api,node_eval_runner,node_stream,node_judge,node_results toneRose
class node_pstn,node_sip,node_caller,node_aws,node_phone_network toneIndigo
```

## Components

### Agent Studio

- [Studio UI](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/App.tsx): `source/frontend/src/App.tsx`
- [Agent wizard](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/context/WizardContext.tsx): `source/frontend/src/context/WizardContext.tsx`
- [Pipeline selection](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/pages/PipelineSelection.tsx): `source/frontend/src/pages/PipelineSelection.tsx`
- [Agent management](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/pages/AgentDetail.tsx): `source/frontend/src/pages/AgentDetail.tsx`
- [Authenticated API client](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/services/apiClient.ts): `source/frontend/src/services/apiClient.ts`
- [Studio API handlers](https://github.com/aws-samples/sample-voice-ai-agent-studio/tree/main/source/api): `source/api`
- [Agent configuration API](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/deployment/demos_stack/demos_stack.py): `deployment/demos_stack/demos_stack.py`

### Voice Runtime

- [AgentCore voice runtime](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/main.py): `source/agent/main.py`
- [Strands BidiAgent](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/strands_agent.py): `source/agent/strands_agent.py`
- [Call history](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/call_history_logger.py): `source/agent/call_history_logger.py`

### Agent Integrations

- [Tool integrations](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/tools/registry.py): `source/agent/tools/registry.py`
- [RAG runtime](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/agent/rag_tools.py): `source/agent/rag_tools.py`
- [RAG management API](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/api/rag_handler.py): `source/api/rag_handler.py`

### Evaluation

- [Evaluation suite UI](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/frontend/src/pages/EvalSuiteDetail.tsx): `source/frontend/src/pages/EvalSuiteDetail.tsx`
- [Evaluation APIs](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/api/eval_handler.py): `source/api/eval_handler.py`
- [Conversation evaluator](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/main.py): `source/eval-runner/nova-sonic-eval-harness/main.py`
- [Nova Sonic streaming](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/core/sonic_stream_manager.py): `source/eval-runner/nova-sonic-eval-harness/core/sonic_stream_manager.py`
- [LLM judge](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/evaluation/llm_judge_binary.py): `source/eval-runner/nova-sonic-eval-harness/evaluation/llm_judge_binary.py`
- [Evaluation results](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/source/eval-runner/nova-sonic-eval-harness/logging_/results_manager.py): `source/eval-runner/nova-sonic-eval-harness/logging_/results_manager.py`

### Voice Channels

- [PSTN relay](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/telephony/pstn/tac_server.py): `telephony/pstn/tac_server.py`
- [SIP relay](https://github.com/aws-samples/sample-voice-ai-agent-studio/blob/main/telephony/sip/bridge/index.js): `telephony/sip/bridge/index.js`

### Other components

- **Studio user**
- **Voice caller**
- **AWS Bedrock**
- **Phone network**

## Connections

- Studio user → Studio UI: configures agents (evidence: `README.md`)
- Studio UI → Pipeline selection: routes wizard (evidence: `source/frontend/src/App.tsx`)
- Pipeline selection → Agent wizard: updates pipeline (evidence: `source/frontend/src/pages/PipelineSelection.tsx`)
- Studio UI → Agent management: routes management (evidence: `source/frontend/src/App.tsx`)
- Agent management → Authenticated API client: requests API
- Authenticated API client → Studio API handlers: sends authenticated requests (evidence: `README.md`)
- Authenticated API client → Agent configuration API: loads agent configurations
- Studio UI → RAG management API: configures knowledge sources
- RAG management API → Authenticated API client: uses requests
- Studio API handlers → AgentCore voice runtime: provides agent configuration
- AgentCore voice runtime → Strands BidiAgent: creates agent (evidence: `source/agent/main.py`)
- AgentCore voice runtime → Call history: logs conversations (evidence: `source/agent/main.py`)
- AgentCore voice runtime → Tool integrations: loads tools (evidence: `source/agent/main.py`)
- AgentCore voice runtime → RAG runtime: loads RAG tools (evidence: `source/agent/main.py`)
- AgentCore voice runtime → AWS Bedrock: runs on AgentCore (evidence: `README.md`)
- Studio user → Evaluation suite UI: defines evaluation suites (evidence: `README.md`)
- Evaluation suite UI → Evaluation APIs: manages evaluations
- Evaluation APIs → Conversation evaluator: starts evaluations
- Conversation evaluator → Nova Sonic streaming: streams test sessions (evidence: `source/eval-runner/nova-sonic-eval-harness/main.py`)
- Conversation evaluator → LLM judge: scores conversations (evidence: `source/eval-runner/nova-sonic-eval-harness/main.py`)
- Conversation evaluator → Evaluation results: records results (evidence: `source/eval-runner/nova-sonic-eval-harness/main.py`)
- Voice caller → PSTN relay: calls phone number (evidence: `README.md`)
- PSTN relay → AgentCore voice runtime: bridges voice session
- Voice caller → SIP relay: starts SIP call (evidence: `README.md`)
- SIP relay → AgentCore voice runtime: bridges voice session
- Phone network → PSTN relay: carries calls (evidence: `README.md`)
- Phone network → SIP relay: carries SIP media (evidence: `README.md`)
