Skip to content

Latest commit

 

History

History
634 lines (503 loc) · 31 KB

deployment.md

File metadata and controls

634 lines (503 loc) · 31 KB

Deployment

Overview

Fibey Field Ops supports two agent modes:

  1. Foundry Hosted Mode (deployed demo) - Uses Foundry's managed agent hosting
  2. Local Development Mode - Runs the agent in-process with the gateway

This guide deploys the agent to Foundry hosted agents and the UI, gateway, and operational backend services to Azure Container Apps using azd.

Architecture

The deployment creates all resources in a single resource group (rg-<env-name>):

Component Azure Service Source Purpose
Chat UI Container App ui/ React frontend with activity sidebar
Gateway Container App src/fibey/gateway/ FastAPI proxy (hosted mode in the deployed demo)
Hosted agent Foundry hosted agent src/fibey/agent/hosted.py Field operations agent + Toolbox MCP
Work Orders API Container App services/work-orders-api/ Work order CRUD backend
Inventory MCP Container App services/inventory-mcp/ Inventory MCP server
Status Dashboard Container App services/status-dashboard/ Public, read-only demo network-health page; no API
Playwright workspace + connection Azure App Testing / Foundry infra/modules/playwright-workspace.bicep Managed browser infrastructure for Browser Automation
AI Foundry account + project Microsoft Foundry infra/core/ai/ Hosts the model deployment, hosted agent, and toolbox
Model deployment Foundry azure.yaml gpt-4.1-mini (configurable)
Foundry Toolbox + skills Foundry (postdeploy) scripts/setup-toolbox.sh Single MCP endpoint for backend tools and skill resources
AI Search Azure AI Search services/foundry-iq-docs/ Knowledge base index + KB MCP endpoint
Container Registry ACR — Docker image storage (apps + hosted agent)
Storage Account Blob Storage services/foundry-iq-docs/ Document storage
Log Analytics / App Insights Workspace — Logging and monitoring

Prerequisites

  • Azure subscription with Owner or Contributor + RBAC Admin roles
  • Azure CLI (az) and Azure Developer CLI (azd)
  • The azd AI agents extension: azd extension install azure.ai.agents
  • Docker Desktop (for local image builds if needed)

Quick Deployment

# 1. Clone repository
git clone https://github.com/Azure-Samples/fibey.git
cd fibey

# 2. Login
az login
azd auth login

# 3. Deploy everything
azd up

azd up performs the full deployment:

  1. Provision — creates the resource group, AI Foundry account + project, model deployment, AI Search, storage, ACR, Container Apps environment, all five container apps, the Playwright workspace, the Foundry knowledge-base and Browser Automation connections, and all RBAC assignments (Bicep in infra/).
  2. Postprovision hook — uploads FoundryIQ docs, builds the search index, and creates the knowledge source/base (scripts/setup-knowledge-base.sh).
  3. Deploy — builds and pushes container images for all apps and deploys the hosted agent to the Foundry project.
  4. Postdeploy hook — publishes the five skills from skills/, creates or updates the Foundry Toolbox with tool search and skill references, and promotes new versions to default (scripts/setup-toolbox.sh).

The gateway is provisioned with AGENT_MODE=hosted, the Foundry project endpoint, and HOSTED_AGENT_NAME=fibey-agent. It calls the agent's streaming Responses endpoint; the agent connects to the Toolbox for tools and skills. Toolbox publication happens after service deployment because it needs the Work Orders OpenAPI endpoint. If the agent starts before the Toolbox exists, initialization can fail; finish the hook and redeploy the agent.

The end-to-end run recorded in #36 completed azd up against an existing environment and verified hosted chat, multi-turn continuity, and toolbox-sourced field-briefing activity in the UI. A recovered fresh resource-group deployment was verified on 2026-11-01 using azd provision followed by azd deploy, after resolving the naming failure in #42, applying the approved demo-only storage exception in #43, and constraining Inventory MCP to the compatible MCP 1.x SDK in #44. All seven UI checks passed (six real hosted workflows and one mocked error case), including Toolbox-sourced field briefing and citations. Same-session continuity and local-mode inventory lookup also passed.

This run used a temporary workstation Search DNS override with normal TLS verification; no system DNS changes or fixed IPs were committed. The remaining resolver problem is tracked in #45. An uninterrupted first-run azd up remains unverified.

Important: Do NOT include ?api-version=v1 in the TOOLBOX_MCP_URL. The agent code automatically appends this.

Container App names retain <environment>-<service> when they satisfy Azure's naming rules, including the 32-character limit. Otherwise, they use fibey-<eight-character-resource-token>-<service>. Existing valid names are unchanged. Other Azure resources retain their own environment-name constraints. Use azd show -e <environment> to find the actual resource names and endpoints rather than constructing them.

Run the read-only infrastructure naming regression against an authorized test resource group:

FIBEY_INFRA_TEST_RESOURCE_GROUP=rg-<test-environment> \
  uv run --no-sync python -m unittest discover -s tests -p test_infra_names.py

This checks resolved ARM what-if names; preview/template validation alone can miss nested resource-provider naming constraints.

Browser Automation infrastructure

azd provision creates a Playwright workspace named pww-<resource-token> and a browser-automation connection in the Foundry project. The connection uses ProjectManagedIdentity, the workspace's MCP endpoint, and the https://mcp.playwright.microsoft.com audience. Bicep assigns Playwright Workspace Contributor to the project managed identity at workspace scope. Service access tokens are disabled; regional affinity is disabled to keep browser sessions in the selected workspace region.

AZURE_PLAYWRIGHT_LOCATION defaults to eastus, independently of the primary and Foundry regions, so existing eastus2 deployments need not move. Bicep accepts only the intersection of the documented Browser Automation regions and hosted-agent regions: australiaeast, eastus, japaneast, switzerlandnorth, westeurope, and westus3 (checked 2026-11-01). eastasia supports Browser Automation but not hosted agents; eastus2 supports hosted agents but not Browser Automation.

Provisioning exports AZURE_PLAYWRIGHT_WORKSPACE_NAME, AZURE_PLAYWRIGHT_WORKSPACE_ID, and BROWSER_AUTOMATION_CONNECTION_NAME. The connection should appear under the Foundry project's connected resources. Read-only ARM what-if checks cover workspace/connection naming and unsupported regions.

Live verification for #47 completed on 2026-11-01 against the existing fibey-dev environment and rg-fibey-dev resource group:

  • Registered Microsoft.LoadTestService using az provider register --namespace Microsoft.LoadTestService --wait.
  • Ran azd provision -e fibey-dev --no-prompt; infrastructure and the knowledge-base postprovision hook succeeded.
  • Confirmed pww-p7ramadxnx4wg is Succeeded in eastus, with local authentication and regional affinity disabled.
  • Listed browser-automation through both the Foundry project's ARM connections API and azd ai connection list -e fibey-dev -o json. The connection uses the workspace MCP endpoint, ProjectManagedIdentity, and the expected audience.
  • Confirmed the project's managed identity has Playwright Workspace Contributor at the exact workspace scope. Existing app images were preserved, UI and dashboard endpoints returned HTTP 200, the gateway remained healthy in hosted mode, and all eight knowledge-base documents indexed successfully.

The existing workstation DNS limitation from #45 also affects the dev Search endpoint. This run used a temporary, command-scoped curl DNS override for that hostname, with normal TLS verification. The helper was removed afterward; no system DNS changes or fixed IPs were committed. Native workstation DNS and uninterrupted first-run deployment remain unverified.

The postdeploy Toolbox publisher attaches Browser Automation using this connection. The Status Dashboard has external ingress so the managed browsers can reach it; provisioning exports its HTTPS address as STATUS_DASHBOARD_URL. This intentionally corrects the former internal-only ingress guidance: managed browsers do not share the Container Apps environment's private network. Private browsing requires separate networking configuration and is out of scope. The dashboard contains fake data and represents a page owned by another team or party with no API; no status MCP or OpenAPI backend is deployed.

The runtime path is agent -> Toolbox native browser_automation tool -> Playwright project connection/workspace -> public Status Dashboard. See the system architecture and Toolbox diagram for editable diagrams.

Hosted network-status smoke gate

The agent receives STATUS_DASHBOARD_URL through agent.yaml; local mode reads the same setting from .env. Both modes use shared network-status instructions without loading a workflow skill. An unset URL disables browsing for status requests; an invalid URL fails explicitly.

After deploying the agent, run the opt-in gate (incurs model and browser usage):

uv run --no-sync python scripts/smoke-network-status.py -e fibey-dev

The script sends a network-status question directly to the hosted Responses API, checks Browser Automation visited the configured page and returned dashboard content, and verifies NE-3/OLT-NE-201 fixture facts and source-only attribution (Source: Status Dashboard, without a URL). It prints safe evidence summaries and latency, never raw browser session URLs. Exit code 1 means the gate failed: stop and re-plan before dependent work. This tests neither gateway/UI activity rendering nor fresh provisioning.

In the UI, the network-status starter prompt should produce one Browse Status Dashboard activity covering session creation, navigation/snapshot, and closure. Activity details contain only the site label and safe status, never session IDs, browser URLs, or page dumps. A successful answer shows a source-only Status Dashboard citation; a failed read reports that the page could not be read and must not cite it.

Browser tool discovery must include session creation and closure, not just navigation/snapshots: navigation requires the ID returned by session creation. Close the browser session after reading. Tool descriptions request sharing Live View/recording links; the system instructions explicitly prohibit doing so. The model also needs the concrete dashboard citation line in its instructions; earlier spike runs read the page correctly but omitted attribution.

The #49 gate passed against hosted version 8 in the existing fibey-dev environment on 2026-11-01: two passing runs at 48.9 seconds total, 45.7–46.8 seconds to first answer text, four to five browser calls, and dashboard facts plus the source citation. The dashboard already had one minimum replica; browser/model orchestration still incurs latency. Preview runs also exposed generic function/argument-parsing errors, so a successful spike is not a reliability guarantee. Findings are recorded on parent #46.

Dashboard safety checks

The shared prompt limits browsing to the configured URL and read-only session operations, and treats page text as untrusted data. Failed reads must close the session before reporting that the dashboard could not be read, with no guessed status, fallback source, or dashboard source citation. An expired session may also fail to close; neither the read nor cleanup is retried.

Both modes use a session-scoped runtime guard to attempt cleanup immediately after a failed navigation or snapshot, even if the model omits the close call. It recognizes nested tool errors, reports cleanup failure, and blocks further reads or duplicate cleanup attempts for that session. Successful reads still follow the normal model-directed close step.

Run the opt-in real-model checks with controlled Browser Automation responses:

FIBEY_MODEL_SAFETY_TEST_ENVIRONMENT=fibey-dev \
  uv run --no-sync python -m unittest discover -s tests -p test_dashboard_safety.py

These checks use the shared prompt and the environment's Foundry model (incurs model usage), replacing only the Toolbox boundary with controlled responses. They cover an unreachable URL, an unreadable layout, session expiry including failed cleanup, and page instructions attempting to override facts, navigate elsewhere, run scripts, and modify a work order. They check the answer and attempted tool operations, including session cleanup and URL restrictions. They do not use a real browser or change the deployed dashboard. Run the hosted smoke gate above separately to check real Browser Automation integration. Prompt-based restrictions and passing model checks are not a browser-level security sandbox or a guarantee against every prompt injection.

Environment variables

Provisioned endpoints are produced as Bicep outputs and stored in the azd environment automatically. Useful configuration values:

Variable Default Description
FOUNDRY_MODEL gpt-4.1-mini Model deployment name
FOUNDRY_MODEL_CAPACITY 100 Model deployment capacity (TPM, in thousands). Preserved across azd up runs
TOOLBOX_NAME fibey-toolbox Foundry Toolbox name
BROWSER_AUTOMATION_CONNECTION_NAME browser-automation Provisioned Playwright connection used by the Toolbox publisher
STATUS_DASHBOARD_URL provisioned dashboard HTTPS address Public, read-only Status Dashboard
KB_NAME fibey-field-ops-kb Knowledge base name
AZURE_SEARCH_INDEX foundry-iq-docs-index Search index name
AZURE_AI_PROJECT_NAME fibey-project Foundry project name
AZURE_AI_DEPLOYMENTS_LOCATION primary location Region for the Foundry account/models
AZURE_PLAYWRIGHT_LOCATION eastus Playwright region; must also support hosted agents
IGNORE_STORAGE_SECURITY_CONTROL false Opt-in SecurityControl: Ignore storage tag; use only with explicit approval for a demo environment

The hosted model is selected by AZURE_AI_MODEL_DEPLOYMENT_NAME in agent.yaml (gpt-4.1-mini), with deployment configuration in azure.yaml. Changing FOUNDRY_MODEL alone does not change that selection; keep these files aligned when choosing a different model.

FoundryIQ Knowledge Base Setup

FoundryIQ knowledge path: source Markdown is uploaded to Blob Storage, ingested by an AI Search indexer, and exposed through an index, knowledge source, knowledge base, KB MCP endpoint, and Foundry connection.

Editable Draw.io source (open in draw.io).

Follow the numbered stages for the content and retrieval path: Markdown in services/foundry-iq-docs/docs/ is uploaded to Blob Storage and ingested by an AI Search indexer. The resulting index backs a knowledge source and knowledge base. The Toolbox accesses the KB MCP endpoint through a Foundry connection. This is not provisioning order: Bicep creates the connection before the postprovision hook builds the knowledge source and base.

This pipeline is configured automatically by the azd postprovision hook (azure.yaml → scripts/setup-knowledge-base.sh):

  1. Documents uploaded to blob storage from services/foundry-iq-docs/docs/.
  2. Search index and indexer created — blob data source, foundry-iq-docs-index, semantic configuration default, and the indexer that ingests the markdown files.
  3. Knowledge Source created — fibey-field-ops-ks (kind: searchIndex, api-version=2026-05-01-preview) pointing at foundry-iq-docs-index.
  4. Knowledge Base created — fibey-field-ops-kb, referencing fibey-field-ops-ks.
  5. Foundry connection — kb-fibey-field-ops-kb is created by Bicep (RemoteTool + ProjectManagedIdentity, target = KB MCP endpoint).
  6. RBAC — Bicep grants the Foundry project and account managed identities Search Index Data Reader on the search service.

To re-run manually: ./scripts/setup-knowledge-base.sh (requires an azd environment).

Deployed components

Layer Name Resource Group / Scope Notes
Search service <env>-search <resource-group> Azure AI Search, Basic SKU
Search index foundry-iq-docs-index Search service 8 text documents, semantic ranking only, no vectors
Semantic config default foundry-iq-docs-index titleField=metadata_storage_name, contentField=content
Knowledge source fibey-field-ops-ks AI Search REST API kind: searchIndex via 2026-05-01-preview
Knowledge base fibey-field-ops-kb AI Search REST API References fibey-field-ops-ks
MCP endpoint https://<search-service>.search.windows.net/knowledgebases/fibey-field-ops-kb/mcp?api-version=2026-05-01-preview AI Search Exposed by the knowledge base
Foundry connection kb-fibey-field-ops-kb AI Services account RemoteTool + ProjectManagedIdentity
RBAC Search Index Data Reader AI Services managed identity Required on the search service

The knowledge base retrieval was validated with semantic intents requests against fibey-field-ops-ks, returning references and source data:

{
  "intents": [{"search": "How do I splice a fiber optic cable?", "type": "semantic"}],
  "knowledgeSourceParams": [{"knowledgeSourceName": "fibey-field-ops-ks", "kind": "searchIndex", "includeReferences": true, "includeReferenceSourceData": true}]
}

Preview: The knowledge source, knowledge base, and KB MCP endpoint use 2026-05-01-preview for query planning and answer synthesis.

Note: Azure AI Foundry workspaces currently allow up to 120 connections. Plan for cleanup or capacity management if your workspace is near the limit.

Notes

  • All Container Apps are configured with minReplicas: 1 to avoid cold starts.
  • The FoundryIQ documents are uploaded to blob storage and indexed separately — they are not part of the container deployment.
  • The Status Dashboard requires external ingress for the managed Playwright browsers; it contains only demo data. Do not switch to internal-only ingress without configuring private browsing networking.
  • Infrastructure definitions live in infra/ (Bicep). The Foundry Toolbox and skills are published by the postdeploy hook (scripts/setup-toolbox.sh).
  • Blob uploads use authenticated access. Shared keys and anonymous blob access remain disabled; storage public networking is enabled for the upload hook. The storage security-control exemption is opt-in, not a production recommendation.

RBAC (automated)

Bicep assigns the gateway, Search, project, and deployment-principal roles during provisioning. Foundry's hosted capability-host setup supplies the runtime identity's project-scoped access, verified in #36:

Identity Role(s) Scope
gateway Container App Azure AI User (Foundry User), Cognitive Services User, Cognitive Services OpenAI User AI Foundry account
Foundry project + account Search Index Data Reader AI Search service
AI Search Storage Blob Data Reader Storage account
Foundry project AcrPull Container registry
Foundry project Playwright Workspace Contributor Playwright workspace
Hosted agent runtime identity Foundry User Foundry project (hosted capability-host identity assignment)
Developer/deployment principal Foundry User Foundry project

Foundry RBAC Roles (Reference)

Note: Foundry roles were recently renamed. Use role definition IDs (GUIDs) instead of role names:

Role Name Role ID (GUID) Purpose
Foundry User 53ca6127-db72-4b80-b1b0-d745d6d5456d Basic Foundry access
Foundry Owner c883944f-8b7b-4483-af10-35834be79c4a Full Foundry management
Foundry Account Owner e47c6f54-e4a2-4754-9501-8e0985b135e1 Account-level management
Foundry Project Manager eadc314b-1a2d-4efa-be10-5d325db5065e Project management

The gateway receives Foundry User plus the Cognitive Services roles at account scope. The hosted runtime has Foundry User at project scope; no extra account-wide hosted-runtime grant is needed.

Hosted Agent Deployment

The Foundry-hosted agent is deployed via azd using the azure.ai.agent host type.

Prerequisites

# Install the azd AI agents extension
azd extension install azure.ai.agents

# Log in
azd auth login
az login

Deploy

# From the repo root — builds Dockerfile.agent (remote build), deploys the
# agent to the Foundry project, and provisions the model deployment if needed
azd up

# Or deploy only the agent after backends, knowledge base, and Toolbox exist
azd deploy fibey-agent

Hosted agent environment variables

Variable Source Description
FOUNDRY_PROJECT_ENDPOINT Auto-injected Foundry project endpoint URL
AZURE_AI_MODEL_DEPLOYMENT_NAME agent.yaml Model deployment name; takes precedence over FOUNDRY_MODEL
TOOLBOX_MCP_URL agent.yaml (${TOOLBOX_MCP_URL} from the azd env, set by azd provision) Toolbox MCP endpoint URL
STATUS_DASHBOARD_URL agent.yaml (${STATUS_DASHBOARD_URL} from the azd env, set by azd provision) Public dashboard HTTPS address used by the shared network-status prompt

Note: All FOUNDRY_* and AGENT_* env vars are reserved by the platform. Do not set reserved names in agent.yaml; use the supported model variable above and the provisioned Toolbox URL.

Local vs Hosted mode

Local Mode Hosted Mode
Entrypoint src/fibey/agent/agent.py src/fibey/agent/hosted.py
Server FastAPI gateway (api_server.py) ResponsesHostServer
History In-memory AgentSession Foundry Responses history; gateway keeps previous_response_id per UI session in memory
Toolbox auth Azure CLI credential Bearer token from managed identity
Skills SkillsProvider(McpSkillsSource(session)) SkillsProvider(McpSkillsSource(session))

Local Toolbox authentication prefers Azure CLI, falls back to default Azure credentials, and supports an optional TOOLBOX_API_KEY. Hosted authentication uses platform managed identity with an azd credential fallback for development. Gateway restarts clear its hosted response-ID mapping. The session-reset endpoint currently clears only local state, not this hosted mapping; reusing the same hosted session ID continues the prior conversation. Use a new session ID to start a separate hosted conversation.

Foundry Toolbox

The Toolbox lives in the same Foundry project and provides a single MCP endpoint that dispatches to the backend tools. It is created automatically by the postdeploy hook (scripts/setup-toolbox.sh):

Tool Type Backend
Tool Search toolbox_search_preview Toolbox built-in tool discovery
Work Orders OpenAPI (anonymous) Container App (work-orders-api)
Inventory MCP Container App (inventory-mcp)
Knowledge Base MCP via kb-fibey-field-ops-kb connection AI Search knowledge base (fibey-field-ops-kb)
Browser Automation browser_automation via browser-automation connection Playwright workspace

The Status Dashboard is deployed separately with public ingress. The native browser definition has name: browser_automation so it can coexist with Tool Search, and references the connection's full resource ID. Registering the tool does not by itself enforce the agent's read-only, dashboard-only policy; that belongs to the agent's runtime instructions.

Tool search is enabled on the toolbox: the initial tools/list exposes only tool_search and call_tool, and the agent discovers backend tools on demand by searching their descriptions. This keeps the model's tool list small as more tools are added.

Publishing skills and Toolbox updates

skills/<name>/SKILL.md is the git source of truth for five skills: field-briefing, inventory-lookup, knowledge-retrieval, work-order-management, and work-order-preparation.

The hook checks and publishes skills even when the Toolbox already exists:

  1. Compare each skill's default-version content with its source SKILL.md. Unchanged content is a no-op; changed content is uploaded through POST /skills/{name}/versions?api-version=v1 and promoted to default_version.
  2. Attach skills as unpinned {"type":"skill_reference","name":"..."} entries, resolving each skill's default version.
  3. If skill attachment names or the browser connection/name changed (including a missing browser entry), create an immutable Toolbox version preserving the other existing tools and promote it to default. Content-only skill changes need no new Toolbox version. An unchanged rerun creates no version.

To publish edited skill content or changed attachments:

./scripts/setup-toolbox.sh

To rebuild tool definitions (for example, after backend FQDNs or the OpenAPI spec change) and publish a new default Toolbox version:

FORCE_TOOLBOX_UPDATE=1 ./scripts/setup-toolbox.sh

Publishing uses REST (curl, Azure CLI authentication, and Python 3), not azd ai. Running the publisher alone does not restart agents: hosted skills are cached for the lifetime of the MCP source. After changing skills, run azd deploy fibey-agent to refresh the hosted runtime.

Verification for #48 used the existing fibey-dev environment in rg-fibey-dev: the dashboard's public /healthz returned HTTP 200, the publisher promoted Toolbox version 11 with Browser Automation while preserving the other tools and five skill references, and a second run created no version. MCP tool_search discovered the browser_automation___browser_* operations, and the public root page served the expected network status HTML. STATUS_DASHBOARD_URL was also saved in that azd environment. The Bicep output is compiled and covered locally; no fresh resource-group deployment or agent-driven browser session was run for this ticket.

Skills and preview caveats

The Toolbox exposes attached skills as MCP Resources (SEP-2640): resources/list advertises skill://index.json, and resources/read returns the index and referenced SKILL.md content. Python Agent Framework 1.5.0 has no native MCP-skills source (the C# framework has UseMcpSkills), so src/fibey/agent/mcp_skills.py adapts these resources to SkillsProvider. The provider retains the load_skill tool used by the activity sidebar.

Both agent modes send Foundry-Features: Toolboxes=V1Preview,Skills=V1Preview on MCP requests. Skill publication uses Skills=V1Preview. These are preview surfaces; schema, API, hosting availability, and regional support may change. The gateway Responses endpoint uses 2025-11-15-preview.

With a Toolbox URL configured, MCP/resource errors, a malformed or missing skills index, and empty skill content propagate as failures. An absent index with no skill resources, or an empty index, produces a warning and no skill tools. With no Toolbox URL, the agent warns and has no Toolbox skills.

Gateway Modes

The gateway supports two modes configured via the AGENT_MODE environment variable. Unsupported values cause the gateway to fail at startup.

1. Foundry Hosted Mode (Deployed Demo)

AGENT_MODE=hosted
HOSTED_AGENT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
HOSTED_AGENT_NAME=fibey-agent
  • Uses Foundry's managed agent hosting
  • Agent image runs in Foundry, not a Container App
  • Requires hosted agent deployment in Foundry project
  • Configured automatically for the gateway by azd up

2. Local Mode (Default for Local Development)

AGENT_MODE=local
  • Agent runs in-process with gateway
  • For local development and testing
  • Not suitable for production

Troubleshooting

Toolbox MCP Connection Errors

Symptom: 400 BadRequest from Toolbox MCP endpoint during initialization

Solution: The Toolbox MCP endpoint requires api-version=v1 (not date-based versions). Both agent entrypoints automatically append it to TOOLBOX_MCP_URL if absent. Verify:

  1. TOOLBOX_MCP_URL does NOT include ?api-version=...
  2. Both entrypoints retain URL normalization and the Toolbox/Skills preview headers

Test directly:

TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)
curl "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<name>/mcp?api-version=v1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Foundry-Features: Toolboxes=V1Preview,Skills=V1Preview" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Authentication Errors

Symptom: DefaultAzureCredential failed to retrieve a token

Solution: Verify managed identity has required roles:

az role assignment list \
  --assignee "$AGENT_MI_ID" \
  --query "[].{role:roleDefinitionName,scope:scope}" \
  --output table

Container App Logs

# Application logs
az containerapp logs show \
  --name <env>-gateway \
  --resource-group <resource-group> \
  --type console \
  --tail 100

# System logs
az containerapp logs show \
  --name <env>-gateway \
  --resource-group <resource-group> \
  --type system \
  --tail 50

Redeploy the Hosted Agent

# Rebuild Dockerfile.agent and deploy to the Foundry project
azd deploy fibey-agent

Verification

After deployment, test the stack:

# Test UI
curl https://<env>-ui.<env-subdomain>.azurecontainerapps.io/

# Test gateway health (mode should be hosted)
curl https://<env>-gateway.<env-subdomain>.azurecontainerapps.io/api/health

# Test end-to-end skill loading via gateway (watch the SSE stream)
curl -N -X POST https://<env>-gateway.<env-subdomain>.azurecontainerapps.io/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Give me a field briefing for WO-007.","session_id":"test-123"}'

In the UI, confirm load_skill activity for field-briefing, followed by work order, inventory, and knowledge retrieval, an answer with sources, and no error events. Ask a follow-up in the same session to confirm continuity.

Cleanup

# Remove all deployed resources
azd down

# Or manually delete resource group
az group delete --name <resource-group> --yes --no-wait