Service Catalog & Guided Onboarding
This skill is the entry point an agent hooks into to help a user discover and stand up the
components of the azd deployment. Treat the catalog below as a menu: assess what already exists,
present the relevant items, and onboard each one with concrete commands and a verification step.
Pair with deployment-guide for hook/flow internals and model availability, troubleshoot for
failure diagnosis, and observability-insights for telemetry. This skill is about discovery and
onboarding, not debugging.
Agent Playbook
Follow this loop. Do not dump the whole catalog unprompted — scope to the user's goal first.
- Assess state. Run the discovery commands below to learn what is already provisioned
(
azd env get-values, resource group contents). Never assume a clean slate.
- Clarify intent. Ask: full deployment (everything via
azd up) vs single component
(e.g. just enable a phone number, just seed CardAPI data, just turn on EasyAuth)?
- Present the relevant catalog rows — purpose, dependencies, and what the user must decide
(region, model, SKU, optional features).
- Onboard each item using its row: run/show the command, then run its verification.
- Confirm + hand off. Summarize what now exists and the logical next step (deploy, place a
test call, open the frontend).
Decision: full deploy vs targeted onboard
| User intent |
Route |
| "Deploy everything / get started" |
Core path: azd auth login → azd up → run post-provision onboarding |
| "Add/change one thing" |
Jump to that catalog row; skip provisioning that already succeeded |
| "What does this even use?" |
Present the Infrastructure Catalog, then ask what to set up |
Core Path (azd up)
azd auth login # 1. Authenticate
azd env new <name> # 2. (first time) create an environment
azd up # 3. preprovision → terraform apply → postprovision → deploy
- preprovision (
devops/scripts/azd/preprovision.sh): preflight checks (tools/auth/providers/
region/quota), Terraform backend, generates main.tfvars.json + provider config.
- terraform apply: creates the infrastructure rows below (
infra/terraform/*.tf).
- postprovision (
devops/scripts/azd/postprovision.sh): the onboarding catalog (data seed, phone,
App Config, .env.local, EasyAuth).
- deploy: builds/pushes the three
services from azure.yaml.
Service Catalog (deployed apps)
Defined in azure.yaml under services:. Each is a Container App.
| Service |
What it is |
Source |
Onboard / verify |
rtaudio-server |
FastAPI voice backend (orchestrators, agents, WS) |
apps/artagent/backend/Dockerfile |
azd deploy rtaudio-server → hit /health on the app URL |
rtaudio-client |
React frontend UI |
apps/artagent/frontend/Dockerfile |
azd deploy rtaudio-client → open the app URL in a browser |
cardapi-mcp |
CardAPI MCP tool server (sample backing tools) |
apps/cardapi/Dockerfile.mcp |
azd deploy cardapi-mcp → check MCP endpoint responds |
Infrastructure Catalog (provisioned by Terraform)
Each row maps to a infra/terraform/*.tf file. Tunable inputs live in
infra/terraform/params/main.tfvars.<env>.json and terraform.tfvars.example.
| Component |
Purpose |
Terraform |
Depends on |
Key knobs |
| Azure OpenAI / AI Foundry |
GPT-4o for SpeechCascade LLM |
ai-foundry.tf |
region + model quota |
model_deployments, region |
| AI Foundry (VoiceLive) |
OpenAI Realtime for VoiceLive mode |
ai-foundry-vl.tf |
region availability |
VoiceLive region/model |
| Speech Services |
STT/TTS for cascade mode |
ai-services.tf* |
region |
SKU (S0) |
| Communication Services |
Telephony, WebSocket, WebRTC |
communication.tf |
Speech (cognitive link) |
data location, phone number |
| Cosmos DB |
Session/conversation persistence |
data.tf |
— |
API (Mongo), autoscale RU/s |
| Storage Account |
Audio files & prompts |
data.tf |
— |
redundancy (LRS) |
| Redis Enterprise |
Session cache / worker affinity |
redis.tf |
quota |
SKU (E10) |
| Container Apps + Registry |
Hosting for the 3 services |
containers.tf |
Log Analytics, identities |
scaling, ACR tier |
| Key Vault |
Secrets |
keyvault.tf |
— |
RBAC mode |
| App Configuration |
Dynamic runtime config |
appconfig.tf |
— |
keys/labels |
| Core (LA, App Insights, UAI, RBAC) |
Observability + identity + roles |
core.tf |
— |
— |
| CardAPI resources |
Backing infra for cardapi-mcp |
cardapi.tf |
Cosmos |
— |
Onboarding Catalog (post-provision tasks)
These run automatically in postprovision.sh but each is independently runnable / re-runnable.
Order matches main() in that script.
| # |
Task |
What it does |
Re-run / enable |
Optional? |
| 1 |
CardAPI data provisioning |
Seeds Cosmos via apps/cardapi/scripts/provision_data.py |
re-run postprovision |
no (non-critical) |
| 2 |
Phone number config |
Provisions/links an ACS phone number (interactive) |
devops/scripts/azd/helpers/acs_phone_number_manager.py |
yes |
| 3 |
App Config URL updates |
Writes deployed service URLs into App Config |
re-run postprovision |
no |
| 4 |
Sync App Config |
devops/scripts/azd/helpers/sync-appconfig.sh |
re-run helper |
no |
| 5 |
Generate .env.local |
Local dev env from azd outputs |
devops/scripts/azd/helpers/local-dev-setup.sh |
no |
| 6 |
EasyAuth (backend) |
Entra auth on rtaudio-server (interactive) |
devops/scripts/azd/helpers/enable-easyauth.sh |
yes |
| 7 |
EasyAuth (CardAPI MCP) |
Entra auth on cardapi-mcp (interactive) |
devops/scripts/azd/helpers/enable-easyauth-cardapi-mcp.sh |
yes |
Discovery Commands (assess current state)
Run these before onboarding so you build on what exists rather than re-provisioning.
# What azd already knows (env, endpoints, resource group, location)
azd env get-values
# Which services are deployed
azd show
# Resources actually present in the group
az resource list -g <resource-group> -o table
# Is a phone number already configured?
azd env get-value ACS_PHONE_NUMBER
# Is EasyAuth on?
azd env get-value EASYAUTH_ENABLED
Prerequisites (gate before azd up)
Confirm before provisioning (enforced by devops/scripts/azd/helpers/preflight-checks.sh):
- Azure CLI
>=2.50.0, authenticated (az account show)
azd and Terraform >=1.0 installed- Contributor on the target subscription; required resource providers registered
- Sufficient Azure OpenAI + Speech quota in the chosen region (see
deployment-guide for region/model checks)
References
azure.yaml — services + hooksinfra/terraform/README.md — full component descriptions + RBACdevops/scripts/azd/postprovision.sh — onboarding task source of truthdocs/getting-started/quickstart.md — first-time azd up- Related skills:
deployment-guide, troubleshoot, observability-insights
1---2name: service-catalog3description: Service catalog and guided onboarding for the azd deployment. USE WHEN the user wants to discover, install, set up, or be walked through the deployable components (Azure OpenAI/AI Foundry, Speech, ACS/telephony, Cosmos DB, Redis, Container Apps, Key Vault, App Config, CardAPI MCP), asks "what gets deployed", "what services does this use", "help me onboard", "set up the deployment", "guide me through azd up", "which components do I need", or wants to enable optional pieces (phone number, EasyAuth, data seeding). Acts as the entry point an agent hooks into to assess current state, present the catalog, and onboard each component. DO NOT USE FOR: deep azd hook/flow internals or model-availability checks (use deployment-guide); runtime failure diagnosis (use troubleshoot); telemetry/log analysis (use observability-insights).4---56# Service Catalog & Guided Onboarding78This skill is the **entry point an agent hooks into** to help a user discover and stand up the9components of the azd deployment. Treat the catalog below as a menu: assess what already exists,10present the relevant items, and onboard each one with concrete commands and a verification step.1112> Pair with `deployment-guide` for hook/flow internals and model availability, `troubleshoot` for13> failure diagnosis, and `observability-insights` for telemetry. This skill is about **discovery and14> onboarding**, not debugging.1516## Agent Playbook1718Follow this loop. Do not dump the whole catalog unprompted — scope to the user's goal first.19201. **Assess state.** Run the discovery commands below to learn what is already provisioned21 (`azd env get-values`, resource group contents). Never assume a clean slate.222. **Clarify intent.** Ask: *full deployment* (everything via `azd up`) vs *single component*23 (e.g. just enable a phone number, just seed CardAPI data, just turn on EasyAuth)?243. **Present the relevant catalog rows** — purpose, dependencies, and what the user must decide25 (region, model, SKU, optional features).264. **Onboard each item** using its row: run/show the command, then run its verification.275. **Confirm + hand off.** Summarize what now exists and the logical next step (deploy, place a28 test call, open the frontend).2930### Decision: full deploy vs targeted onboard3132| User intent | Route |33|-------------|-------|34| "Deploy everything / get started" | Core path: `azd auth login` → `azd up` → run post-provision onboarding |35| "Add/change one thing" | Jump to that catalog row; skip provisioning that already succeeded |36| "What does this even use?" | Present the Infrastructure Catalog, then ask what to set up |3738## Core Path (`azd up`)3940```bash41azd auth login # 1. Authenticate42azd env new <name> # 2. (first time) create an environment43azd up # 3. preprovision → terraform apply → postprovision → deploy44```4546- **preprovision** (`devops/scripts/azd/preprovision.sh`): preflight checks (tools/auth/providers/47 region/quota), Terraform backend, generates `main.tfvars.json` + provider config.48- **terraform apply**: creates the infrastructure rows below (`infra/terraform/*.tf`).49- **postprovision** (`devops/scripts/azd/postprovision.sh`): the onboarding catalog (data seed, phone,50 App Config, `.env.local`, EasyAuth).51- **deploy**: builds/pushes the three `services` from `azure.yaml`.5253## Service Catalog (deployed apps)5455Defined in `azure.yaml` under `services:`. Each is a Container App.5657| Service | What it is | Source | Onboard / verify |58|---------|-----------|--------|------------------|59| `rtaudio-server` | FastAPI voice backend (orchestrators, agents, WS) | `apps/artagent/backend/Dockerfile` | `azd deploy rtaudio-server` → hit `/health` on the app URL |60| `rtaudio-client` | React frontend UI | `apps/artagent/frontend/Dockerfile` | `azd deploy rtaudio-client` → open the app URL in a browser |61| `cardapi-mcp` | CardAPI MCP tool server (sample backing tools) | `apps/cardapi/Dockerfile.mcp` | `azd deploy cardapi-mcp` → check MCP endpoint responds |6263## Infrastructure Catalog (provisioned by Terraform)6465Each row maps to a `infra/terraform/*.tf` file. Tunable inputs live in66`infra/terraform/params/main.tfvars.<env>.json` and `terraform.tfvars.example`.6768| Component | Purpose | Terraform | Depends on | Key knobs |69|-----------|---------|-----------|-----------|-----------|70| Azure OpenAI / AI Foundry | GPT-4o for SpeechCascade LLM | `ai-foundry.tf` | region + model quota | `model_deployments`, region |71| AI Foundry (VoiceLive) | OpenAI Realtime for VoiceLive mode | `ai-foundry-vl.tf` | region availability | VoiceLive region/model |72| Speech Services | STT/TTS for cascade mode | `ai-services.tf*` | region | SKU (S0) |73| Communication Services | Telephony, WebSocket, WebRTC | `communication.tf` | Speech (cognitive link) | data location, phone number |74| Cosmos DB | Session/conversation persistence | `data.tf` | — | API (Mongo), autoscale RU/s |75| Storage Account | Audio files & prompts | `data.tf` | — | redundancy (LRS) |76| Redis Enterprise | Session cache / worker affinity | `redis.tf` | quota | SKU (E10) |77| Container Apps + Registry | Hosting for the 3 services | `containers.tf` | Log Analytics, identities | scaling, ACR tier |78| Key Vault | Secrets | `keyvault.tf` | — | RBAC mode |79| App Configuration | Dynamic runtime config | `appconfig.tf` | — | keys/labels |80| Core (LA, App Insights, UAI, RBAC) | Observability + identity + roles | `core.tf` | — | — |81| CardAPI resources | Backing infra for `cardapi-mcp` | `cardapi.tf` | Cosmos | — |8283## Onboarding Catalog (post-provision tasks)8485These run automatically in `postprovision.sh` but each is independently runnable / re-runnable.86Order matches `main()` in that script.8788| # | Task | What it does | Re-run / enable | Optional? |89|---|------|--------------|-----------------|-----------|90| 1 | CardAPI data provisioning | Seeds Cosmos via `apps/cardapi/scripts/provision_data.py` | re-run postprovision | no (non-critical) |91| 2 | Phone number config | Provisions/links an ACS phone number (interactive) | `devops/scripts/azd/helpers/acs_phone_number_manager.py` | yes |92| 3 | App Config URL updates | Writes deployed service URLs into App Config | re-run postprovision | no |93| 4 | Sync App Config | `devops/scripts/azd/helpers/sync-appconfig.sh` | re-run helper | no |94| 5 | Generate `.env.local` | Local dev env from azd outputs | `devops/scripts/azd/helpers/local-dev-setup.sh` | no |95| 6 | EasyAuth (backend) | Entra auth on `rtaudio-server` (interactive) | `devops/scripts/azd/helpers/enable-easyauth.sh` | yes |96| 7 | EasyAuth (CardAPI MCP) | Entra auth on `cardapi-mcp` (interactive) | `devops/scripts/azd/helpers/enable-easyauth-cardapi-mcp.sh` | yes |9798## Discovery Commands (assess current state)99100Run these before onboarding so you build on what exists rather than re-provisioning.101102```bash103# What azd already knows (env, endpoints, resource group, location)104azd env get-values105106# Which services are deployed107azd show108109# Resources actually present in the group110az resource list -g <resource-group> -o table111112# Is a phone number already configured?113azd env get-value ACS_PHONE_NUMBER114115# Is EasyAuth on?116azd env get-value EASYAUTH_ENABLED117```118119## Prerequisites (gate before `azd up`)120121Confirm before provisioning (enforced by `devops/scripts/azd/helpers/preflight-checks.sh`):122123- Azure CLI `>=2.50.0`, authenticated (`az account show`)124- `azd` and Terraform `>=1.0` installed125- Contributor on the target subscription; required resource providers registered126- Sufficient Azure OpenAI + Speech quota in the chosen region (see `deployment-guide` for region/model checks)127128## References129130- `azure.yaml` — services + hooks131- `infra/terraform/README.md` — full component descriptions + RBAC132- `devops/scripts/azd/postprovision.sh` — onboarding task source of truth133- `docs/getting-started/quickstart.md` — first-time `azd up`134- Related skills: `deployment-guide`, `troubleshoot`, `observability-insights`
Azure-Samples