MicrosoftDocs · learn-build-service-prod · Jul 16, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -21,13 +21,18 @@ title: Page title
 description: Brief description
 zone_pivot_groups: programming-languages  # If showing code in multiple languages
 author: github-username
-ms.topic: conceptual
+ms.topic: article
 ms.author: microsoft-alias
 ms.date: MM/DD/YYYY
 ms.service: semantic-kernel
 ---
 ```
 
+Use `article` by default. The docsets also use `how-to`, `overview`,
+`quickstart`, `reference`, `sample`, `tutorial`, and
+`upgrade-and-migration-article` when those types match the page's purpose.
+Do not use `conceptual`.
+
 ### Zone Pivots for Multi-Language Content
 
 Zone pivots show language-specific content. **Note the different language support per docset:**

diff --git a/agent-framework/AGENTS.md b/agent-framework/AGENTS.md
@@ -74,6 +74,14 @@ agent-framework/
 │   ├── openai-endpoints.md
 │   ├── m365.md
 │   └── purview.md
+├── hosting/                   # Hosting model selection and guides
+│   ├── index.md               # Managed vs self-hosted overview
+│   ├── foundry-hosted-agent.md
+│   └── self-hosting/
+│       ├── index.md           # Shared self-hosting state and protocol choices
+│       ├── responses.md
+│       ├── telegram.md
+│       └── a2a.md
 ├── devui/                     # DevUI reference (top-level)
 │   ├── index.md
 │   └── ...
@@ -97,12 +105,14 @@ agent-framework/
    builds complexity step by step. Agents/workflows/integrations are reference
    docs organized by topic — users land here from "Go deeper" links.
 
-2. **Zone pivots for languages**: Every page that shows code uses
-   `zone_pivot_groups: programming-languages` in its YAML frontmatter.
-   Code blocks are wrapped in `:::zone pivot="programming-language-csharp"`,
-   `:::zone pivot="programming-language-python"`, and
-   `:::zone pivot="programming-language-go"` sections when the feature is
-   supported in those SDKs.
+2. **Zone pivots for languages**: Use
+   `zone_pivot_groups: programming-languages` and matching
+   `:::zone pivot="..."` sections only when a page presents code in multiple
+   supported SDKs. You can also use a non-empty "coming soon" zone for an SDK
+   that is planned but not yet supported. When you use a pivot group, include a
+   non-empty zone for every pivot ID it defines; otherwise the validator reports
+   blank language tabs. Do not declare a multi-language pivot group on a
+   language-specific page.
 
 3. **Code snippets as source of truth**: Prefer `:::code` directives that point
    to sample files in the code repo, so docs stay synced with runnable samples.
@@ -173,19 +183,24 @@ title: "Page Title"
 description: "One-line description for SEO"
 zone_pivot_groups: programming-languages
 author: eavanvalkenburg
-ms.topic: article           # or "tutorial" for get-started
+ms.topic: article           # Use overview, tutorial, how-to, reference, or upgrade-and-migration-article when appropriate
 ms.date: MM/DD/YYYY
 ms.service: agent-framework
 ---
 ```
 
+Use `article` by default. Do not use `conceptual`; it is not a supported
+topic value. Use `overview` for section landing pages and choose `tutorial`,
+`how-to`, `reference`, or `upgrade-and-migration-article` only when they
+match the page's purpose.
+
 ## TOC.yml conventions
 
 - **Single flat TOC**: All entries are in the root `TOC.yml` — no nested sub-TOC
   files (`href: .../TOC.yml`). This avoids breadcrumb compatibility issues and
   keeps navigation in a single source of truth.
 - Top-level items: Agent Framework, Get Started, Agents, Workflows, Integrations,
-  DevUI, Migration Guide, API Reference, Support
+  Hosting, DevUI, Migration Guide, API Reference, Support
 - Each section uses `items:` for child pages
 - `expanded: true` only on Get Started (first section users see)
 
@@ -226,6 +241,11 @@ Every docs page maps to sample files in both repos:
 | `integrations/hyperlight.md` | `02-agents/context_providers/code_act/code_act.py` | `02-agents/AgentWithCodeAct/` |
 | `integrations/a2a.md` | `04-hosting/a2a/` | `04-hosting/a2a/` |
 | `integrations/durable-extension.md` | `04-hosting/azure_functions/`, `04-hosting/durabletask/` | `04-hosting/DurableAgents/`, `04-hosting/DurableWorkflows/` |
+| `hosting/self-hosting/index.md` | `04-hosting/af-hosting/` | N/A |
+| `hosting/self-hosting/responses.md` | `04-hosting/af-hosting/local_responses/`, `04-hosting/af-hosting/local_responses_workflow/` | N/A |
+| `hosting/self-hosting/telegram.md` | `04-hosting/af-hosting/local_telegram/` | N/A |
+| `hosting/self-hosting/a2a.md` | `04-hosting/a2a/` | N/A |
+| `hosting/self-hosting/mcp.md` | `04-hosting/mcp/` | N/A |
 
 ## When adding a new docs page
 

diff --git a/agent-framework/TOC.yml b/agent-framework/TOC.yml
@@ -232,10 +232,22 @@ items:
       href: integrations/ag-ui/testing-with-dojo.md
 - name: Hosting
   items:
+  - name: Overview
+    href: hosting/index.md
   - name: Foundry Hosted Agents
     href: hosting/foundry-hosted-agent.md
-  - name: A2A
-    href: hosting/agent-to-agent.md
+  - name: Self-hosting
+    items:
+    - name: Overview
+      href: hosting/self-hosting/index.md
+    - name: OpenAI Responses
+      href: hosting/self-hosting/responses.md
+    - name: Telegram
+      href: hosting/self-hosting/telegram.md
+    - name: A2A
+      href: hosting/self-hosting/a2a.md
+    - name: MCP
+      href: hosting/self-hosting/mcp.md
 - name: The Agent Development Journey
   items:
   - name: Overview

diff --git a/agent-framework/get-started/hosting.md b/agent-framework/get-started/hosting.md
@@ -132,6 +132,8 @@ app.Run();
 
 :::zone pivot="programming-language-python"
 
+Azure Functions is one self-managed hosting option. For a comparison of Microsoft-managed Foundry Hosted Agents, self-hosting, and durable Azure Functions workloads, see [Hosting Agent Framework applications](../hosting/index.md).
+
 Install the Azure Functions hosting package, Foundry client, and Azure authentication package:
 
 ```bash
@@ -239,6 +241,7 @@ http.ListenAndServe(":5000", mux)
 - [A2A Protocol](../integrations/a2a.md) — expose and consume agents via A2A
 - [Durable Extension](../integrations/durable-extension.md) — durable C# and Python agent and workflow hosting
 - [AG-UI Protocol](../integrations/ag-ui/index.md) — web-based agent UIs
+- [Hosting overview](../hosting/index.md) — choose Foundry Hosted Agents, self-hosting, or durable hosting
 - [Foundry Hosted Agents docs](/azure/ai-foundry/agents/concepts/hosted-agents) — understand hosted agents in Microsoft Foundry
 - [Foundry Hosted Agents sample (Python)](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework) — run an end-to-end Agent Framework hosted-agent sample
 

diff --git a/agent-framework/hosting/foundry-hosted-agent.md b/agent-framework/hosting/foundry-hosted-agent.md
@@ -5,7 +5,7 @@ zone_pivot_groups: programming-languages
 author: taochen
 ms.topic: article
 ms.author: taochen
-ms.date: 05/27/2026
+ms.date: 07/17/2026
 ms.service: agent-framework
 ---
 
@@ -24,9 +24,9 @@ ms.service: agent-framework
 
 # Foundry Hosted Agents
 
-[Hosted agents](/azure/foundry/agents/concepts/hosted-agents) in Microsoft Foundry Agent Service let you deploy Agent Framework agents as containerized applications to Microsoft-managed infrastructure. The platform handles scaling, session state persistence, security, and lifecycle management so you can focus on your agent's logic.
+[Hosted agents](/azure/foundry/agents/concepts/hosted-agents) in Microsoft Foundry Agent Service let you deploy Agent Framework agents as containerized applications to Microsoft-managed infrastructure. The platform handles scaling, session state persistence, security, and lifecycle management so you can focus on your agent's logic. Microsoft Foundry Hosted Agents is generally available.
 
-With the Agent Framework hosting integration, you can take any `Agent` or workflow and expose it through the Foundry Responses or Invocations protocol with minimal code.
+With the Agent Framework hosting integration, you can expose an `Agent`, including a workflow wrapped with `Workflow.as_agent()`, through the Foundry Responses or Invocations protocol with minimal code.
 
 ## When to use hosted agents
 
@@ -38,7 +38,7 @@ Choose Foundry hosted agents when you want:
 - **OpenAI-compatible endpoints** — clients can interact with your agent using any OpenAI-compatible SDK through the Responses protocol.
 
 > [!NOTE]
-> Foundry hosted agents are currently in preview. See the [Foundry hosted agents documentation](/azure/foundry/agents/concepts/hosted-agents#limits-pricing-and-availability-preview) for the latest availability, limits, and pricing.
+> The Python `agent-framework-foundry-hosting` integration is prerelease. Microsoft Foundry Hosted Agents, the managed hosting service, is generally available.
 
 ## Prerequisites
 
@@ -67,14 +67,16 @@ dotnet add package Azure.AI.Projects --prerelease
 
 - Python 3.10 or later
 
-Install the hosting Python package:
+Install the prerelease hosting package, Foundry client, and Azure authentication package:
 
 ```bash
-pip install agent-framework agent-framework-foundry-hosting
+pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity
 ```
 
 :::zone-end
 
+In Foundry, the platform supplies the caller's user context and call context; the hosting infrastructure uses them to isolate state per user and forward request context to Foundry services. Local runs don't receive that platform context, so applications must supply their own identity and state controls when needed.
+
 ## Responses protocol
 
 The **Responses** protocol is the recommended starting point for most agents. It exposes an OpenAI-compatible `/responses` endpoint, and the platform manages conversation history, streaming, and session lifecycle automatically.
@@ -363,7 +365,7 @@ Once deployed, your agent is accessible through its dedicated Foundry endpoint a
 
 - [Deploy a hosted agent with the Foundry SDK](/azure/foundry/agents/how-to/deploy-hosted-agent)
 - [Manage hosted agents](/azure/foundry/agents/how-to/manage-hosted-agent)
-- [Azure Functions (Durable) hosting](../integrations/azure-functions.md)
-- [A2A Hosting](agent-to-agent.md)
+- [Azure Functions and durable hosting](../integrations/durable-extension.md)
+- [Self-host A2A agents](self-hosting/a2a.md)
 - [Python samples](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework)
 - [C# samples](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/hosted-agents/agent-framework)
diff --git a/agent-framework/hosting/index.md b/agent-framework/hosting/index.md
@@ -0,0 +1,51 @@
+---
+title: Hosting Agent Framework applications
+description: Choose between Microsoft-managed Foundry Hosted Agents and self-hosting Agent Framework applications.
+author: eavanvalkenburg
+ms.topic: overview
+ms.author: edvan
+ms.date: 07/21/2026
+ms.service: agent-framework
+---
+
+# Hosting Agent Framework applications
+
+After you build an agent or workflow, first choose who operates its infrastructure. This is an operational choice between Microsoft-managed Foundry Hosted Agents and self-hosting; it is separate from the protocol that clients use to reach your agent.
+
+## Choose a hosting model
+
+| | [Foundry Hosted Agents](foundry-hosted-agent.md) | [Self-hosting](self-hosting/index.md) |
+|---|---|---|
+| **Who operates the infrastructure?** | Microsoft Foundry Agent Service runs the container, scaling, session lifecycle, and platform integration. | Your application runs in your web service, container, runtime, or existing infrastructure. |
+| **What do you operate?** | Your agent code and Foundry configuration. | Routes, identity, authorization, request policy, storage, deployment, scaling, and native client libraries. |
+| **Choose this when** | You want Microsoft-managed agent hosting. | You need application-level control or must integrate with your existing infrastructure. |
+| **Start here** | [Host an agent in Foundry](foundry-hosted-agent.md) | [Self-host an Agent Framework application](self-hosting/index.md) |
+
+Microsoft Foundry Hosted Agents is generally available. The current Python self-hosting packages are prerelease; see the self-hosting guide for package-specific lifecycle information.
+
+For Azure Functions triggers, durable execution, or long-running orchestration, use the [Durable Extension](../integrations/durable-extension.md). It is a self-managed hosting path with Durable Task infrastructure.
+
+## Choose a protocol separately
+
+The hosting model does not determine the protocol. For example, the OpenAI Responses protocol works with both models:
+
+- **Foundry Hosted Agents** expose managed Responses and Invocations endpoints and support the Activity protocol for Microsoft 365 channels.
+- **Self-hosting** lets your application use the Responses helpers to expose a `/responses` endpoint with its own framework, routing, and policy.
+
+After choosing a host, select the client integration that fits your scenario:
+
+- [OpenAI-compatible endpoints](../integrations/openai-endpoints.md) for Responses and Chat Completions-compatible APIs.
+- [Agent-to-Agent (A2A)](../integrations/a2a.md) for agent interoperability.
+- [AG-UI](../integrations/ag-ui/index.md) for web-based agent applications.
+- [Telegram bots](self-hosting/telegram.md) for a self-hosted native Telegram Bot API integration.
+- [MCP tools](self-hosting/mcp.md) for exposing an agent or workflow as a native MCP tool.
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Choose Foundry Hosted Agents](foundry-hosted-agent.md)
+
+**Go deeper:**
+
+- [Self-hosting](self-hosting/index.md)
+- [Durable Extension](../integrations/durable-extension.md)