version: "1.0.0" name: hosted-agent-deployment description: >- Help a learner deploy an agent to production as a Microsoft Foundry Hosted Agent, and decide when Capability Hosts are needed. Use for Lessons 4–5: hosted deployment, thread/memory persistence, bring-your-own storage, and enterprise governance.

Hosted agent deployment

Guidance for taking an agent to production (Lessons 4–5).

Guardrails (always apply)

• Terminology: Hosted Agents, Capability Hosts, Microsoft Foundry Agent Service.
• Deploy with the current SDK/Responses API; models gpt-5.1 (chat) / gpt-5-codex (coding).
• Config and secrets via .env / managed identity — never hardcode endpoints or keys.

The key distinction (teach this clearly)

• Hosted Agents provide the Microsoft-managed execution environment: compute, scaling, identity,

observability and session management. You do not need a Capability Host just to run a Hosted Agent.

• Capability Hosts are only required when you want Agent Service to use **customer-owned

resources** instead of Microsoft-managed storage.

• Happy with default Microsoft-managed storage, vector search and conversation persistence?

No Capability Host configuration is required.

• Need data sovereignty, private networking, compliance controls, or storage in your own

Azure Cosmos DB, Azure Storage Account and Azure AI Search? Configure Capability Hosts to connect Agent Service to those resources.

Concepts a learner should grasp

1. Basic vs standard setup: basic = Microsoft-managed; standard = bring-your-own resources via

Capability Hosts + connections.

1. Persistence: hosted agents persist threads and memory server-side (long-running conversations).
2. Governance: identity, private networking, Hosted MCP approval workflows, cost controls.

How to help

• Start from lesson-4-agentdeployment/ for the deploy + ChatKit front end, then

lesson-5-hosted-agents-production/ for enterprise/BYO-storage and governance.

• Before recommending Capability Hosts, ask whether the learner actually needs customer-owned

storage/networking — if not, keep the basic setup.

• Remind them of cost & cleanup: delete the resource group when finished.

Validate

• python -m py_compile on any deploy scripts.
• CI smoke test: .github/workflows/smoke-test-hosted-agent.yml (workflow_dispatch, OIDC) exercises

a deployed hosted agent.

References

• lesson-4-agentdeployment/README.md, lesson-5-hosted-agents-production/README.md