# microsoft/copilotstudiosamples architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/copilotstudiosamples
- Repository: https://github.com/microsoft/copilotstudiosamples

## Overview

#### Purpose and Entry Points
This is a multi-sample repository for Microsoft Copilot Studio, not one deployable application. It provides importable agent solutions, topic artifacts, integration code, UI embeds, infrastructure templates, and validation examples. Repository navigation is published as a Jekyll/GitHub Pages site via `_config.yml` and `.github/workflows/pages.yml`; the root `README.md` is the catalog entry point.

#### Copilot Studio Authoring Artifacts
Importable Power Platform/Copilot Studio solutions and reusable authoring snippets are the primary platform-facing assets. Solutions package bot definitions, topics, GPT configuration, connectors, and Dataverse actions; snippets provide smaller YAML/Adaptive Card patterns.
- `authoring/solutions/account-contact-lookup/sourcecode/bots/copilots_header_cref7_LookupDataAgent/bot.xml`
- `authoring/solutions/resume-job-finder/sourcecode/bots/cref7_resumeJobMatchAssistant/bot.xml`
- `authoring/snippets/adaptive-cards/ConversationStart.json`

#### Employee Self-Service Agent Domain
A pending-deprecation employee-service sample models conversational topics as `topic.yaml` plus XML actions for Workday and facilities systems. Runtime control begins with intent/topic selection, collects needed values, invokes an external action, and renders the result. Workday and WorkdayDA are parallel artifact sets; changes should generally preserve both variants.
- `EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/topic.yaml`
- `EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/msdyn_HRWorkdayHCMEmployeeGetVacationBalance.xml`
- `EmployeeSelfServiceAgent/Facilities/EmployeeGetDiningMenu/topic.yaml`

#### Extensibility and Agent-to-Agent Boundaries
Extensibility samples demonstrate services called by Copilot Studio rather than shared runtime infrastructure. MCP samples expose tool servers and OpenAPI custom connectors; A2A and Agents SDK samples host agent-compatible HTTP endpoints. The order-management sample is the clearest composed flow: chat UI → Copilot Studio agents/connectors → order or warehouse MCP server.
- `extensibility/mcp/order-management-enhanced-tc/mcp-servers/order-management/src/server.ts`
- `extensibility/mcp/order-management-enhanced-tc/connectors/order-management/apiDefinition.swagger.json`
- `extensibility/a2a/Simple-A2A-Sample/Program.cs`

#### Channel, UI, and Contact-Center Integration
These samples implement channel-specific boundaries around Copilot Studio/Direct Line: browser and hosted chat UIs authenticate users, obtain tokens, relay conversation traffic, and optionally hand off to live agents. Runtimes include Next.js/TypeScript, Node.js Azure Functions, and ASP.NET/C#; external systems include Direct Line, ServiceNow, Salesforce, SharePoint, Dynamics 365, and Genesys.
- `ui/custom-ui/assistant-ui/assistant-ui-mcs/app/api/chat/route.ts`
- `contact-center/servicenow/DirectLineAzureFunction/src/functions/relayToDirectLine.js`
- `contact-center/skill-handoff/HandoverToLiveAgentSample/Program.cs`

#### Identity and Deployment Boundaries
SSO examples cover Entra ID and Okta integrations, while infrastructure artifacts provision or configure networking and Power Platform billing workflows. Credentials, tenant/environment configuration, and network reachability are deployment concerns external to these samples.
- `sso/entra-id/index.html`
- `ui/embed/d365-cs-okta/app.js`
- `infrastructure/vnet-support/template.json`

#### Validation and Evaluation
Evaluation is a separate operational layer: test inputs drive authenticated Copilot/Agents SDK conversations, collect multi-turn responses, and can gate delivery pipelines. Load testing targets WebSocket conversation traffic.
- `testing/functional/PytestAgentsSDK/testinglib/copilot_client.py`
- `testing/evaluation/EvalGateADO/scripts/eval-gate.mjs`
- `testing/load/JMeterMultiThreadGroup/Multi Group WebSocket.jmx`

Main entry points: [`README.md`](https://github.com/microsoft/copilotstudiosamples/blob/main/README.md) (Repository catalog), [`ui/custom-ui/assistant-ui/assistant-ui-mcs/app/api/chat/route.ts`](https://github.com/microsoft/copilotstudiosamples/blob/main/ui/custom-ui/assistant-ui/assistant-ui-mcs/app/api/chat/route.ts) (Assistant UI chat route), [`EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/topic.yaml`](https://github.com/microsoft/copilotstudiosamples/blob/main/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/topic.yaml) (Vacation balance topic), [`authoring/solutions/account-contact-lookup/sourcecode/bots/copilots_header_cref7_LookupDataAgent/bot.xml`](https://github.com/microsoft/copilotstudiosamples/blob/main/authoring/solutions/account-contact-lookup/sourcecode/bots/copilots_header_cref7_LookupDataAgent/bot.xml) (Lookup Data Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Copilot Authoring"]
  node_copilot{{"Copilot Studio<br/>platform"}}
  node_lookup_solution["Lookup Data Agent<br/>solution bot<br/>[bot.xml]"]
  node_resume_solution["Resume Job Match Agent<br/>solution bot<br/>[bot.xml]"]
  node_card_snippet["Conversation-start card<br/>adaptive card snippet"]
end

subgraph group_employee["Employee Self-Service"]
  node_vacation_topic["Vacation balance topic<br/>[topic.yaml]"]
  node_workday_action["Workday vacation action<br/>Dataverse action"]
  node_dining_topic["Dining menu topic<br/>[topic.yaml]"]
end

subgraph group_extensibility["Extensibility"]
  node_order_connector["Order Management connector<br/>OpenAPI connector"]
  node_order_mcp{{"Order Management MCP server<br/>TypeScript MCP server<br/>[server.ts]"}}
  node_a2a_endpoint{{"Simple A2A endpoint<br/>ASP.NET agent endpoint<br/>[Program.cs]"}}
end

subgraph group_channels["Channels &amp; Contact Center"]
  node_chat_ui["Assistant UI chat route<br/>Next.js API route<br/>[route.ts]"]
  node_direct_line["Direct Line<br/>conversation channel"]
  node_relay["ServiceNow relay<br/>Azure Function"]
  node_live_handoff["Live-agent handoff<br/>ASP.NET handoff sample<br/>[Program.cs]"]
end

subgraph group_operations["Identity, Infrastructure &amp; Validation"]
  node_identity{{"SSO integrations<br/>Entra ID and Okta<br/>[index.html]"}}
  node_infrastructure["VNet support template<br/>infrastructure template<br/>[template.json]"]
  node_functional_tests["Authenticated conversation client<br/>Python test client<br/>[copilot_client.py]"]
  node_evaluation_gate["Evaluation gate<br/>delivery gate<br/>[eval-gate.mjs]"]
  node_load_test["WebSocket load test<br/>JMeter plan"]
end

node_catalog["Repository catalog<br/>documentation<br/>[README.md]"]

node_catalog -->|"catalogs"| node_lookup_solution
node_catalog -->|"catalogs"| node_resume_solution
node_catalog -->|"catalogs"| node_chat_ui
node_lookup_solution -->|"imports into"| node_copilot
node_resume_solution -->|"imports into"| node_copilot
node_card_snippet -.->|"reused by"| node_copilot
node_vacation_topic -->|"invokes"| node_workday_action
node_vacation_topic -->|"runs in"| node_copilot
node_dining_topic -->|"runs in"| node_copilot
node_copilot -->|"uses connector"| node_order_connector
node_order_connector -->|"calls tools"| node_order_mcp
node_copilot -->|"calls agent endpoint"| node_a2a_endpoint
node_chat_ui -->|"sends chat"| node_direct_line
node_relay -->|"relays traffic"| node_direct_line
node_direct_line -->|"connects conversations"| node_copilot
node_direct_line -->|"can hand off"| node_live_handoff
node_identity -->|"authenticates users"| node_chat_ui
node_infrastructure -.->|"supports network reachability"| node_copilot
node_functional_tests -->|"drives conversations"| node_copilot
node_evaluation_gate -->|"evaluates results"| node_functional_tests
node_load_test -->|"loads WebSocket traffic"| node_direct_line

click node_catalog "https://github.com/microsoft/copilotstudiosamples/blob/main/README.md"
click node_lookup_solution "https://github.com/microsoft/copilotstudiosamples/blob/main/authoring/solutions/account-contact-lookup/sourcecode/bots/copilots_header_cref7_LookupDataAgent/bot.xml"
click node_resume_solution "https://github.com/microsoft/copilotstudiosamples/blob/main/authoring/solutions/resume-job-finder/sourcecode/bots/cref7_resumeJobMatchAssistant/bot.xml"
click node_card_snippet "https://github.com/microsoft/copilotstudiosamples/blob/main/authoring/snippets/adaptive-cards/ConversationStart.json"
click node_vacation_topic "https://github.com/microsoft/copilotstudiosamples/blob/main/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/topic.yaml"
click node_workday_action "https://github.com/microsoft/copilotstudiosamples/blob/main/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/msdyn_HRWorkdayHCMEmployeeGetVacationBalance.xml"
click node_dining_topic "https://github.com/microsoft/copilotstudiosamples/blob/main/EmployeeSelfServiceAgent/Facilities/EmployeeGetDiningMenu/topic.yaml"
click node_order_connector "https://github.com/microsoft/copilotstudiosamples/blob/main/extensibility/mcp/order-management-enhanced-tc/connectors/order-management/apiDefinition.swagger.json"
click node_order_mcp "https://github.com/microsoft/copilotstudiosamples/blob/main/extensibility/mcp/order-management-enhanced-tc/mcp-servers/order-management/src/server.ts"
click node_a2a_endpoint "https://github.com/microsoft/copilotstudiosamples/blob/main/extensibility/a2a/Simple-A2A-Sample/Program.cs"
click node_chat_ui "https://github.com/microsoft/copilotstudiosamples/blob/main/ui/custom-ui/assistant-ui/assistant-ui-mcs/app/api/chat/route.ts"
click node_relay "https://github.com/microsoft/copilotstudiosamples/blob/main/contact-center/servicenow/DirectLineAzureFunction/src/functions/relayToDirectLine.js"
click node_live_handoff "https://github.com/microsoft/copilotstudiosamples/blob/main/contact-center/skill-handoff/HandoverToLiveAgentSample/Program.cs"
click node_identity "https://github.com/microsoft/copilotstudiosamples/blob/main/sso/entra-id/index.html"
click node_infrastructure "https://github.com/microsoft/copilotstudiosamples/blob/main/infrastructure/vnet-support/template.json"
click node_functional_tests "https://github.com/microsoft/copilotstudiosamples/blob/main/testing/functional/PytestAgentsSDK/testinglib/copilot_client.py"
click node_evaluation_gate "https://github.com/microsoft/copilotstudiosamples/blob/main/testing/evaluation/EvalGateADO/scripts/eval-gate.mjs"
click node_load_test "https://github.com/microsoft/copilotstudiosamples/blob/main/testing/load/JMeterMultiThreadGroup/Multi%20Group%20WebSocket.jmx"

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_copilot,node_lookup_solution,node_resume_solution,node_card_snippet toneBlue
class node_vacation_topic,node_workday_action,node_dining_topic toneAmber
class node_order_connector,node_order_mcp,node_a2a_endpoint toneMint
class node_chat_ui,node_direct_line,node_relay,node_live_handoff toneRose
class node_identity,node_infrastructure,node_functional_tests,node_evaluation_gate,node_load_test toneIndigo
class node_catalog toneNeutral
```

## Components

### Copilot Authoring

Importable solutions and reusable conversation artifacts.

- **Copilot Studio**: platform · Platform hosting imported agents, topics, and connectors.
- [Lookup Data Agent](https://github.com/microsoft/copilotstudiosamples/blob/main/authoring/solutions/account-contact-lookup/sourcecode/bots/copilots_header_cref7_LookupDataAgent/bot.xml): solution bot · `authoring/solutions/account-contact-lookup/sourcecode/bots/copilots_header_cref7_LookupDataAgent/bot.xml`
- [Resume Job Match Agent](https://github.com/microsoft/copilotstudiosamples/blob/main/authoring/solutions/resume-job-finder/sourcecode/bots/cref7_resumeJobMatchAssistant/bot.xml): solution bot · `authoring/solutions/resume-job-finder/sourcecode/bots/cref7_resumeJobMatchAssistant/bot.xml`
- [Conversation-start card](https://github.com/microsoft/copilotstudiosamples/blob/main/authoring/snippets/adaptive-cards/ConversationStart.json): adaptive card snippet · `authoring/snippets/adaptive-cards/ConversationStart.json`

### Employee Self-Service

Pending-deprecation topic and action samples.

- [Vacation balance topic](https://github.com/microsoft/copilotstudiosamples/blob/main/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/topic.yaml): topic · Intent flow gathers values and renders the returned balance. · `EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/topic.yaml`
- [Workday vacation action](https://github.com/microsoft/copilotstudiosamples/blob/main/EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/msdyn_HRWorkdayHCMEmployeeGetVacationBalance.xml): Dataverse action · Parallel Workday and WorkdayDA artifacts should remain aligned. · `EmployeeSelfServiceAgent/Workday/EmployeeScenarios/EmployeeGetVacationBalance/msdyn_HRWorkdayHCMEmployeeGetVacationBalance.xml`
- [Dining menu topic](https://github.com/microsoft/copilotstudiosamples/blob/main/EmployeeSelfServiceAgent/Facilities/EmployeeGetDiningMenu/topic.yaml): topic · `EmployeeSelfServiceAgent/Facilities/EmployeeGetDiningMenu/topic.yaml`

### Extensibility

Agent, connector, and MCP boundary samples.

- [Order Management connector](https://github.com/microsoft/copilotstudiosamples/blob/main/extensibility/mcp/order-management-enhanced-tc/connectors/order-management/apiDefinition.swagger.json): OpenAPI connector · `extensibility/mcp/order-management-enhanced-tc/connectors/order-management/apiDefinition.swagger.json`
- [Order Management MCP server](https://github.com/microsoft/copilotstudiosamples/blob/main/extensibility/mcp/order-management-enhanced-tc/mcp-servers/order-management/src/server.ts): TypeScript MCP server · Provides order and warehouse tools to connected agents. · `extensibility/mcp/order-management-enhanced-tc/mcp-servers/order-management/src/server.ts`
- [Simple A2A endpoint](https://github.com/microsoft/copilotstudiosamples/blob/main/extensibility/a2a/Simple-A2A-Sample/Program.cs): ASP.NET agent endpoint · Hosts an agent-compatible HTTP boundary. · `extensibility/a2a/Simple-A2A-Sample/Program.cs`

### Channels & Contact Center

UI, relay, and live-handoff integrations.

- [Assistant UI chat route](https://github.com/microsoft/copilotstudiosamples/blob/main/ui/custom-ui/assistant-ui/assistant-ui-mcs/app/api/chat/route.ts): Next.js API route · Browser chat boundary for Copilot Studio conversations. · `ui/custom-ui/assistant-ui/assistant-ui-mcs/app/api/chat/route.ts`
- **Direct Line**: conversation channel · Authenticated conversation transport between clients and agents.
- [ServiceNow relay](https://github.com/microsoft/copilotstudiosamples/blob/main/contact-center/servicenow/DirectLineAzureFunction/src/functions/relayToDirectLine.js): Azure Function · Relays ServiceNow conversation traffic to Direct Line. · `contact-center/servicenow/DirectLineAzureFunction/src/functions/relayToDirectLine.js`
- [Live-agent handoff](https://github.com/microsoft/copilotstudiosamples/blob/main/contact-center/skill-handoff/HandoverToLiveAgentSample/Program.cs): ASP.NET handoff sample · `contact-center/skill-handoff/HandoverToLiveAgentSample/Program.cs`

### Identity, Infrastructure & Validation

Deployment and quality-operating examples.

- [SSO integrations](https://github.com/microsoft/copilotstudiosamples/blob/main/sso/entra-id/index.html): Entra ID and Okta · Identity configuration and credentials remain external deployment concerns. · `sso/entra-id/index.html`
- [VNet support template](https://github.com/microsoft/copilotstudiosamples/blob/main/infrastructure/vnet-support/template.json): infrastructure template · Provisions networking support for Power Platform scenarios. · `infrastructure/vnet-support/template.json`
- [Authenticated conversation client](https://github.com/microsoft/copilotstudiosamples/blob/main/testing/functional/PytestAgentsSDK/testinglib/copilot_client.py): Python test client · Drives Copilot or Agents SDK multi-turn conversations. · `testing/functional/PytestAgentsSDK/testinglib/copilot_client.py`
- [Evaluation gate](https://github.com/microsoft/copilotstudiosamples/blob/main/testing/evaluation/EvalGateADO/scripts/eval-gate.mjs): delivery gate · Collects evaluations and can gate delivery pipelines. · `testing/evaluation/EvalGateADO/scripts/eval-gate.mjs`
- [WebSocket load test](https://github.com/microsoft/copilotstudiosamples/blob/main/testing/load/JMeterMultiThreadGroup/Multi%20Group%20WebSocket.jmx): JMeter plan · Targets concurrent conversation traffic. · `testing/load/JMeterMultiThreadGroup/Multi Group WebSocket.jmx`

### Other components

- [Repository catalog](https://github.com/microsoft/copilotstudiosamples/blob/main/README.md): documentation · README and GitHub Pages navigation expose the sample catalog. · `README.md`

## Connections

- Repository catalog → Lookup Data Agent: catalogs
- Repository catalog → Resume Job Match Agent: catalogs
- Repository catalog → Assistant UI chat route: catalogs
- Lookup Data Agent → Copilot Studio: imports into
- Resume Job Match Agent → Copilot Studio: imports into
- Conversation-start card → Copilot Studio: reused by
- Vacation balance topic → Workday vacation action: invokes
- Vacation balance topic → Copilot Studio: runs in
- Dining menu topic → Copilot Studio: runs in
- Copilot Studio → Order Management connector: uses connector
- Order Management connector → Order Management MCP server: calls tools
- Copilot Studio → Simple A2A endpoint: calls agent endpoint
- Assistant UI chat route → Direct Line: sends chat
- ServiceNow relay → Direct Line: relays traffic
- Direct Line → Copilot Studio: connects conversations
- Direct Line → Live-agent handoff: can hand off
- SSO integrations → Assistant UI chat route: authenticates users
- VNet support template → Copilot Studio: supports network reachability
- Authenticated conversation client → Copilot Studio: drives conversations
- Evaluation gate → Authenticated conversation client: evaluates results
- WebSocket load test → Direct Line: loads WebSocket traffic
