microsoft / microsoft/agent-framework

.NET: Hosting.Channels surface - Phase 1

Open
#6,152 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

.NET hosting python
Dominant language
Python
Stars
13.6k
Forks
2.3k
Avg merge
2d 45m
Merged PRs (30d)
358

Description

## Scope

Port the Python `feature/python-hosting` work (the "hosting channels" surface) to .NET. Tracks the staged delivery onto the existing `microsoft/agent-framework:feature/dotnet-hosting-channels` integration branch.

Spec: [`docs/specs/003-dotnet-hosting-channels.md`](https://github.com/microsoft/agent-framework/blob/feature/dotnet-hosting-channels/docs/specs/003-dotnet-hosting-channels.md) (lands with the first PR).

## Why

Today every wire format (Responses, A2A, AG-UI, Functions, Foundry hosting) has its own `Map*` extension and its own state-and-identity story bolted on. As more transports land (Telegram, Discord, Slack, Activity Protocol), the surface area multiplies and cross-channel scenarios (link a Telegram identity to a Responses session, fan a response out to multiple destinations, etc.) have no consistent place to live.

The hosting-channels surface introduces a single composable seam — one `AgentFrameworkHost` per target, many `Channel`s mounted side-by-side — with shared infrastructure for authorization, identity linking, link policies, host-execution state, durable push, and response-target routing. Python locked the design first; this issue tracks the literal .NET port.

## Posture

Translate, not redesign. Python is canonical. Names, taxonomy, wire-level behaviors mirror Python; ASP.NET Core mechanics only where they have to. Net-new in v1; existing `Hosting.OpenAI` / `Hosting.A2A` / `Hosting.AGUI.AspNetCore` / `Hosting.AzureFunctions` / `Foundry.Hosting` packages stay untouched.

## Delivery plan

Staged PRs against `feature/dotnet-hosting-channels`.

1. **Core scaffold** — `Microsoft.Agents.AI.Hosting.Channels` (`Channel`, `ChannelContribution`, capability interfaces, `ChannelRequest`, `ResponseTarget`, `HostedRunResult`, `HostedStreamItem`, `AgentFrameworkHost` + `AuthorizeAsync` pipeline, `IAgentFrameworkHostBuilder`, `Map/AddAgentFrameworkHost` extensions, `IsolationKeys`).
2. **Identity + state + runner** — `IIdentityAllowlist` family + combinators + `AuthorizationProfile`, `IIdentityLinker`, `ILinkPolicy` + 4 built-ins, `IHostStateStore` + `InMemory` and `File` impls, `IDurableTaskRunner` + `InProcessDurableTaskRunner`, `OneTimeCodeIdentityLinker`, `ResponseRouter` (registers `hosting.push`, walks response targets, fans out, runs per-destination hooks, echo idempotency).
3. **Channel: Invocations** — `Microsoft.Agents.AI.Hosting.Channels.Invocations`. JSON `POST /invocations/invoke` + background + polling. `WorkflowRunResult` rendered as `awaiting_input` / `completed` / `failed`.
4. **Workflow runner** — drives `InProcessExecution.RunStreamingAsync`, persists resume tokens on `IHostStateStore`, resumes via `ExternalResponse`.
5. **Channel: Telegram** — `Microsoft.Agents.AI.Hosting.Channels.Telegram`. Polling + webhook over raw HTTP. `IChannelPush`. `ConversationScope` (`PerUser` / `PerUserPerConversation` / `PerConversation`). `AcceptInGroup` (`MentionOnly` default for groups). DM-redirect link challenge. `setMyCommands` at startup.
6. **Sample + unit tests** — one sample per channel under `samples/04-hosting/HostingChannels/`. `Microsoft.Agents.AI.Hosting.Channels.UnitTests` covering response target / allowlists / state store / linker / durable runner.
7. **Fast-follow** (separate issues): `Microsoft.Agents.AI.Hosting.Channels.Responses` (Responses wire-compat), `FoundryHostedAgentRunner` in `Microsoft.Agents.AI.Foundry.Hosting`, `IsolationKeysMiddleware` (ASP.NET Core header lifting), workflow-runner durability across process restarts, per-channel `IChannelPushCodec` (for JSON-payload durable runners), `.DurableTask` / `.Discord` / `.Activity` / `.EntraId` packages.

## Active PRs

- [#6151](https://github.com/microsoft/agent-framework/pull/6151) — draft scaffold (commits 1–6 above)

## Out of scope (v1)

- Rewriting any existing `Map*` extension to delegate to the new builder. Tier-2 migration ships as a separate, fast-follow release once v1 is stable.
- Any hard break in alpha or shipped packages.

## References

- Python source branch: [`feature/python-hosting`](https://github.com/microsoft/agent-framework/tree/feature/python-hosting)
- Python Discord channel PR (fast-follow reference): #6081
- Python hosting spec (the spec this .NET work ports): `docs/specs/002-python-hosting-channels.md` on the Python branch

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/specs/003-dotnet-hosting-channels.md and compare the Python feature/python-hosting branch, since Python is canonical. Review draft PR #6151 and the staged delivery plan to identify the remaining phase. Done means the listed .NET hosting-channels phases and their specified tests and samples are delivered without changing the existing hosting packages.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, python
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.