[BREAKING] Python: Add request-scoped Foundry agent factories by rogerbarreto · Pull Request #8372 · microsoft/agent-framework · GitHub

Motivation & Context

Foundry-hosted workflows need request-scoped execution objects while continuing conversations from saved state. A workflow agent retains mutable executor and conversation state that should not be reused for independent requests.

This change adds factory-based construction to both Python Foundry hosts while preserving the existing instance API for ordinary agents.

Description & Review Guide

What are the major changes? Add a zero-argument agent_factory accepting synchronous or asynchronous callables to ResponsesHostServer and InvocationsHostServer. Keep each returned agent local to its request through streaming and cleanup. Restore workflow state from user-scoped conversation/session stores, serialize updates within a host, and document that factory implementers must construct fresh mutable objects. Migrate the three Responses workflow samples and document ownership and continuation behavior.
What is the impact of these changes? Workflow callers must replace direct instances with factories that construct fresh mutable workflows and executors. Ordinary-agent instance callers keep their existing behavior. Invocations retains its text input/output format and gains workflow checkpoints and persistent ordinary factory sessions. Both graph and functional workflows reject pending or interrupted Invocations continuation. Functional responses are type-checked before saved state changes, and functional resilient Responses recovery remains unsupported. Hosting retains the runtime's checkpoint-error policy without patching runner internals.
What do you want reviewers to focus on? Request-local ownership through streaming, cancellation before and during execution, authorized checkpoint continuation, graph recovery, and compatibility of the ordinary-agent instance path. Regression coverage exercises workflow state, executor history, pending requests, resource cleanup, and host recreation. Additional HTTP coverage exercises independent requests on the same host through both protocols, including streaming and continuation by the owning user.

Related Issue

No linked issue.

Contribution Checklist

The code builds clean without any errors or warnings
All unit tests pass, and I have added new tests where possible
The PR follows the Contribution Guidelines
This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
This is not a breaking change. Workflow instance callers must migrate to agent_factory.

🟡 Changes recommended

Reused execution objects can escape detection, and functional continuations accept responses with incompatible types.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds request-scoped agent factories and durable workflow continuation to Python Foundry hosts.

Changes:

Adds synchronous/asynchronous factory resolution, scoped locking, lifecycle cleanup, and workflow reuse detection.
Persists workflow sessions and checkpoints for Responses and Invocations hosts.
Migrates samples and adds extensive continuation, cancellation, isolation, and recovery tests.

File summaries

File	Description
responses/workflows/README.md	Documents request-scoped workflow hosting.
responses/workflows/main.py	Migrates the workflow sample to a factory.
responses/resilient_long_running_workflow/README.md	Documents recovery ownership.
responses/resilient_long_running_workflow/main.py	Rebuilds recovery workflows per request.
responses/declarative_customer_support/README.md	Documents declarative factory behavior.
responses/declarative_customer_support/main.py	Creates declarative workflows per request.
tests/test_state_store.py	Tests separate Invocations namespaces.
tests/test_responses.py	Adapts workflow continuation tests.
tests/test_responses_factory.py	Covers Responses factory lifecycle and recovery.
tests/test_invocations_factory.py	Covers Invocations factories and persistence.
foundry_hosting/README.md	Documents factory and ownership contracts.
_state_store.py	Adds Invocations stores and checkpoint-error tracking.
_responses.py	Implements request-scoped Responses workflows.
_invocations.py	Implements factory-backed Invocations workflows.
_agent_factory.py	Adds shared factory and scope-lock utilities.
test_functional_workflow.py	Documents functional checkpoint limitations.
0040-python-foundry-request-agent-factories.md	Records the architectural decision.

Review details

Files reviewed: 17/17 changed files
Comments generated: 2
Review effort level: Balanced

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 0a3b84d49650
Model: gpt-5.6-sol-fast

Overview

The PR adds request-scoped agent factories with strong same-scope serialization, user-isolated persistence, cancellation cleanup, checkpoint consistency checks, and extensive regression coverage. Two gaps remain: ordinary Invocations factory sessions accumulate permanently in a process-wide dictionary, and workflow reuse detection does not cover the mutable executors that the factory contract requires to be fresh. The latter can allow state to bleed between otherwise independent request-local workflows.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (1 high, 1 medium) across 2 files. Details are attached to the affected lines below.

Affected areas: python/packages/foundry_hosting/agent_framework_foundry_hosting/_agent_factory.py, python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations.py

Thanks for the contribution. Before this is ready, could you please:

follow up on and resolve the discussions at _invocations.py:209, _state_store.py:55, and _agent_factory.py:101
get Python - Tests, Python - Test Coverage, and Merge Gatekeeper passing
resolve the merge conflicts with main
complete the build checklist item

Once those are addressed, please re-request review. Thanks!

Validate functional response batches before state changes, persist ordinary Invocations factory sessions, and document fresh execution objects as the factory author responsibility. Stabilize recovery fixtures and correct CI test typing.

Require recorded completion for both Invocations workflow types. Preserve stored state when incomplete continuation is rejected.

For me, the fix itself is overengineered and too complex for what it is trying to solve, and it really feels like a bandaid over something we need to fix in the first place (the use of workflow.as_agent itself, rather then just leveraging the workflow directly). So if we are making a breaking change in this space, we should fix that.

Keep checkpoint error policy with the workflow runtime. Add HTTP coverage for request-scoped factory behavior.

Copilot AI balanced review requested due to automatic review settings September 14, 2026 14:05

Roger Barreto (rogerbarreto) deployed to github-app-auth September 14, 2026 14:05 — with GitHub Actions Active

Roger Barreto (rogerbarreto) deployed to github-app-auth September 14, 2026 14:06 — with GitHub Actions Active

agent-framework-automation Bot added documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python breaking change Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible labels Sep 14, 2026

Copilot started reviewing on behalf of Roger Barreto (rogerbarreto) September 14, 2026 14:06 View session

Copilot AI reviewed Sep 14, 2026

View reviewed changes

Comment thread python/packages/foundry_hosting/agent_framework_foundry_hosting/_agent_factory.py Outdated

Comment thread python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py Outdated

github-actions Bot reviewed Sep 14, 2026

View reviewed changes

Comment thread python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations.py Outdated

Comment thread python/packages/foundry_hosting/agent_framework_foundry_hosting/_agent_factory.py Outdated

Roger Barreto (rogerbarreto) deployed to github-app-auth September 14, 2026 17:37 — with GitHub Actions Active

Evan Mattson (moonbox3) reviewed Sep 15, 2026

View reviewed changes

Roger Barreto (rogerbarreto) added 3 commits September 15, 2026 09:58

Python: Add request-scoped Foundry agent factories

7439f2c

fix: align workflow continuation checks

2e1de12

Require recorded completion for both Invocations workflow types. Preserve stored state when incomplete continuation is rejected.

Eduard van Valkenburg (eavanvalkenburg) reviewed Sep 16, 2026

View reviewed changes

refactor: simplify hosting checkpoint handling

0db17c0

Keep checkpoint error policy with the workflow runtime. Add HTTP coverage for request-scoped factory behavior.

Roger Barreto (rogerbarreto) force-pushed the hosted-workflow-agent-factory branch from 02e5dc3 to 0db17c0 Compare September 16, 2026 11:34

Roger Barreto (rogerbarreto) deployed to github-app-auth September 16, 2026 11:34 — with GitHub Actions Active

Roger Barreto (rogerbarreto) mentioned this pull request Oct 7, 2026

Python: [BREAKING] Require request-scoped WorkflowAgent factories in Foundry hosting #9141

Closed

3 of 5 tasks

Eduard van Valkenburg (eavanvalkenburg) mentioned this pull request Oct 7, 2026

Python: Foundry hosting: warn against hosting a WorkflowAgent through agent= #9146

Merged

4 of 5 tasks

[BREAKING] Python: Add request-scoped Foundry agent factories by rogerbarreto · Pull Request #8372 · microsoft/agent-framework · GitHub

Repository navigation

[BREAKING] Python: Add request-scoped Foundry agent factories - #8372

[BREAKING] Python: Add request-scoped Foundry agent factories#8372
Roger Barreto (rogerbarreto) merged 12 commits into
microsoft:mainfrom
rogerbarreto:hosted-workflow-agent-factory

Roger Barreto (rogerbarreto) commented Sep 14, 2026 •
edited
Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Eduard van Valkenburg (eavanvalkenburg) commented Sep 15, 2026

Uh oh!

Eduard van Valkenburg (eavanvalkenburg) left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

[BREAKING] Python: Add request-scoped Foundry agent factories by rogerbarreto · Pull Request #8372 · microsoft/agent-framework · GitHub

Repository navigation

[BREAKING] Python: Add request-scoped Foundry agent factories - #8372

Conversation

Roger Barreto (rogerbarreto) commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation & Context

Description & Review Guide

Related Issue

Contribution Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

MAF Automated Review — Iteration 1

Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Eduard van Valkenburg (eavanvalkenburg) commented Sep 15, 2026

Uh oh!

Eduard van Valkenburg (eavanvalkenburg) left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Roger Barreto (rogerbarreto) commented Sep 14, 2026 •
edited
Loading