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

[Roger Barreto (rogerbarreto)]

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.

[Copilot]

🟡 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.

[github-actions]

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

[Eduard van Valkenburg (eavanvalkenburg)]

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!

[Eduard van Valkenburg (eavanvalkenburg)]

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.

[Roger Barreto (rogerbarreto)]

Updated in a23359c. All inline discussions are answered and resolved, and the implementation now follows the revised agent callable approach. Current reported checks pass. The PR still reports merge conflicts with main; no rebase or checklist edit was included in this update.