Python: Redesign Foundry-hosting APIs in one beta release

[eavanvalkenburg]

Goal

Ship one coordinated beta update of agent-framework-foundry-hosting: first-class hosted agents and native workflows over Responses and Invocations, with explicit session ownership and sandbox isolation. Land small, reviewable PRs together before one release, not as a multi-release migration. Keep the directly relevant samples and tests alongside each implementation PR.

The committed design/implementation snapshot is eavanvalkenburg/agent-framework@8f2d58d325e09bc247711e31fcca8545ea226ec9; it is a source for carving slices, not the proposed monolithic PR. PR1's source branch is foundry-scope-foundation.

Proposed PR slices

1. Trusted hosted scope and storage foundation: platform session/user/call IDs, sandbox-scoped default MAF stores, conditional writes, and documented legacy-state boundary.
2. Responses agent lifecycle: caller store versus host/service/agent history, native options plus flattened extra_body precedence, developer option hooks, background polling, steering, and their basic/history/options/background samples.
3. Invocations agent lifecycle: application request parser and option hook, durable sessions, JSON/SSE handling, and basic Invocations samples. Offer an explicitly opted-in, deprecated legacy plain-text wire mode.
4. Responses agent integrations and isolation: session files, Cosmos, Memory, Toolbox/RAG, and directly related examples and tests.
5. Native Responses workflows: required request-to-start-executor parser, request-aware workflow factory, exact response/checkpoint binding, approval and user-input continuation, resilient background execution, and workflow/approval/declarative samples. Preserve the old WorkflowAgent hosting contract behind an explicit deprecation path unless a parity-tested adapter can replace it without losing history or approval semantics.
6. Native Invocations workflows: typed start inputs, scoped checkpoint continuation, streaming, and the matching workflow sample.

Every user-facing slice includes its representative sample and tests; there is no trailing samples-only PR. Each PR ultimately targets microsoft/agent-framework:main from a fork branch. Merge the prerequisites in order and do not publish a package release until the complete series lands.

Compatibility and safety requirements

• Distinguish Foundry sandbox agent_session_id, outer Responses conversation/response IDs, MAF AgentSession, downstream service continuation IDs, and workflow checkpoints. Trust platform identity, not caller-supplied options.
• store=False must not persist host-managed state or cause inner provider storage. A caller's background=True uses the outer response.id as the polling handle and must not require provider-native background support.
• Do not silently reinterpret the deprecated history_source="agent" in a way that discards an existing developer's downstream service history. Make the old behavior and explicit new inner_history choices clear and test both.
• Never fall back to old unscoped hosted-state keys across sandboxes. Existing hosted MAF state may require a fresh session unless a migration can verify its ownership. Warn/document the actual boundary; do not trade isolation for apparent compatibility.
• Ensure exact checkpoint/approval authority, replay rejection, and no promise of exactly-once external side effects across crashes.
• Exercise local and deployed store/background, session restoration, workflow approval, and cross-sandbox scenarios where the external dependencies permit. Credential-gated GitHub MCP/Telegram and Hyperlight KVM are separate test prerequisites, not hidden successes.

The proposed core workflow entry-state/per-AgentExecutor options change is tracked separately in #8711; this hosting redesign uses existing workflow kwargs and request-time agent defaults and does not depend on that core change.

Issue-linking convention: component PRs should say Part of this issue; close this umbrella only when the entire series and release gate are satisfied. Narrower issues such as #6558 (session-isolation documentation) should not be closed by PR1 alone.

[eavanvalkenburg]

Integration checks before the coordinated beta release (from PR1 review):

• Python: perf(foundry-hosting): cache FoundryStateStore in FoundryAgentSessionStore #8281 caches FoundryStateStore by the static root (agent_sessions). After child Python: Foundry hosting: isolate MAF state by trusted user and sandbox #8743, it must key by the full user+sandbox-scoped store name; otherwise a cached store could be reused across hosted sandboxes.
• Python: add opt-in deferred session persistence to foundry_hosting #8440 defers session_storage.set until after a response terminal event. If enabled with CAS, a 409/412 must not be logged and suppressed as though persistence succeeded; verify the client-visible failure contract together.
• Python: Foundry Hosting - support conversation branching #8618 adds branching snapshot writes in the Responses load/save path. Reconcile those writes with the per-key ETag/create-only rules in Python: Foundry hosting: isolate MAF state by trusted user and sandbox #8743, and run combined branching/concurrency tests.

These are integration hazards to check as the component PRs land, not extra issues that any one child PR automatically closes.

[UniversePeak]

I checked the current streaming work and found an important boundary before proposing code. #8894 already covers a Responses/Invocations wire contract with JSON and framed SSE, while #8464 and #8231 cover response metadata and completion-driven workflow streaming; #8428 also establishes mixed approval handling. A separate harness-level contract could still be useful for opt-in continuous tool/modal streams, but it should be defined against those existing boundaries: versioned envelopes with sequence/checkpoint fields, explicit producer backpressure, and pause/resume semantics that do not replay acknowledged events. Would you prefer this to be a follow-up under the coordinated hosting series (#8742), or should it target a narrower core streaming primitive first?