generative-ui-foundry-hosted-agents: Skill for Claude Code

Skill: Deploy a Foundry Hosted Agent + CopilotKit runtime + SWA

Validated, end-to-end deployment flow for the three-component generative-UI solution (agent → runtime → frontend). Assumes infra is provisioned via azd (azd up). Pair with the foundry-hosted-agent-maf skill for the agent code.

Deployment order (matters)

1. Provision infra — azd up (ACR, App Service, SWA, Foundry account + model, App Insights, managed identities).
2. Deploy runtime + frontend — azd deploy runtime, azd deploy web (or via azd up). The runtime boots even before the agent exists (lazy 503).
3. Build the agent image to ACR.
4. Register a hosted-agent version and poll to active.
5. Grant RBAC to the agent instance identity.
6. Wire the runtime to the invocations endpoint (with api-version).
7. Verify end-to-end through the SWA.

1–2. Provision + deploy

azd auth login
azd up
azd deploy runtime      # redeploy after runtime/src/server.ts changes (npm run build first)

The azure.ai.agents postdeploy hook logs AZURE_AI_PROJECT_ENDPOINT is not set — cosmetic, deploy succeeds. Node App Service cold start ≈100s.

3. Build the agent image

$acr = (azd env get-values | ConvertFrom-StringData).AZURE_CONTAINER_REGISTRY_NAME.Trim('"')
$tag = "maf-agui-$(Get-Date -Format yyyyMMddHHmmss)"
az acr build --registry $acr --image "analytics-agent:$tag" --image "analytics-agent:latest" ./agent

4. Register a hosted-agent version

Use the azure-ai-projects Python SDK (see scripts/register_agent.py — update IMAGE to the new tag, then run it):

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    HostedAgentDefinition, ProtocolVersionRecord, AgentEndpointProtocol, ContainerConfiguration,
)
from azure.identity import DefaultAzureCredential

project = AIProjectClient(endpoint=PROJECT_ENDPOINT,
                          credential=DefaultAzureCredential(), allow_preview=True)
agent = project.agents.create_version(
    agent_name="analytics-agent",
    definition=HostedAgentDefinition(
        container_configuration=ContainerConfiguration(image=IMAGE),
        protocol_versions=[ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS, version="1.0.0")],
        cpu="1", memory="2Gi",
        environment_variables={
            "AZURE_OPENAI_ENDPOINT": "https://<account>.openai.azure.com/",
            "MODEL_DEPLOYMENT_NAME": "model-router",
        },
    ),
)

• PROJECT_ENDPOINT = https://<account>.services.ai.azure.com/api/projects/<project>.
• Poll project.agents.get_version("analytics-agent", agent_version="N").status until it equals AgentVersionStatus.ACTIVE (usually near-instant). Compare to the enum, not str(status) — under Python 3.11+ str(status) is "AgentVersionStatus.ACTIVE".
• The agent's Entra instance identity principal is on the create response at agent.instance_identity.principal_id.