Repository navigation
Python: [BREAKING] Prepare Foundry Hosting for RC - #10260
Eduard van Valkenburg (eavanvalkenburg) wants to merge 5 commits into
Conversation
Code coverage overviewLanguages: Python Python / code-coverage/python
View coverage of the 9 most impacted files.
ℹ️ Calculations represent line coverage. Results may change as calculations are updated. Updated |
There was a problem hiding this comment.
🔵 Needs a closer look
Cleanup ownership is registered too late, allowing replay and pre-dispatch exits to leak constructor-created clients or credentials, with regression coverage needed for these paths.
No open issues 🎉
What changed in this PR
Integrates the breaking agent/native-workflow host split into Python Foundry Hosting as preparation for RC. Configuration, approval, consent, and final release qualification work remains outstanding.
Changes:
- Separates agent and native workflow hosts, with request-aware factories and explicit workflow parsers.
- Renames request/parser APIs and history/background source values; removes the constructor
store=alias while preserving wire-level storage semantics. - Updates shared internals, public exports, regression tests, maintained samples, migration guidance, and proposed ADR 0055.
| File | Description |
|---|---|
skills/agent-framework-builder-python/references/hosting-and-deployment.md |
Documents separate hosts and request-owned workflow resources. |
python/scripts/sample_validation/skills/foundry-hosted-agent-validation/SKILL.md |
Recognizes native workflow host entry points. |
python/samples/04-hosting/foundry-hosted-agents/responses/workflows/README.md |
Documents the workflow host and required factory. |
python/samples/04-hosting/foundry-hosted-agents/responses/workflows/main.py |
Migrates typed workflows to the new host/parser APIs. |
python/samples/04-hosting/foundry-hosted-agents/responses/workflows/approval.py |
Migrates the approval workflow host and parser. |
python/samples/04-hosting/foundry-hosted-agents/responses/tools/README.md |
Updates history-source terminology. |
python/samples/04-hosting/foundry-hosted-agents/responses/tools/main.py |
Updates the factory signature and history source. |
python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/verify_steering.py |
Makes the guard-check factory request-aware. |
python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/README.md |
Updates history-source documentation. |
python/samples/04-hosting/foundry-hosted-agents/responses/steerable_long_running_agent/main.py |
Uses the renamed host-managed history value. |
python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/README.md |
Identifies the native workflow host contract. |
python/samples/04-hosting/foundry-hosted-agents/responses/resilient_long_running_workflow/main.py |
Migrates resilient workflow construction and parsing. |
python/samples/04-hosting/foundry-hosted-agents/responses/observability/README.md |
Updates history-source terminology. |
python/samples/04-hosting/foundry-hosted-agents/responses/observability/main.py |
Updates request-aware construction and history configuration. |
python/samples/04-hosting/foundry-hosted-agents/responses/monty_codeact/README.md |
Updates the documented host configuration. |
python/samples/04-hosting/foundry-hosted-agents/responses/monty_codeact/main.py |
Migrates the CodeAct factory and history value. |
python/samples/04-hosting/foundry-hosted-agents/responses/mcp/README.md |
Updates history-source terminology. |
python/samples/04-hosting/foundry-hosted-agents/responses/mcp/main.py |
Migrates the MCP sample factory and history value. |
python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md |
Updates host-managed history documentation. |
python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/main.py |
Updates the Toolbox factory signature and configuration. |
python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/README.md |
Updates history-source terminology. |
python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox_mcp_skills/main.py |
Migrates request-aware Toolbox/skills construction. |
python/samples/04-hosting/foundry-hosted-agents/responses/foundry_memory/README.md |
Documents request-aware factories and renamed history. |
python/samples/04-hosting/foundry-hosted-agents/responses/foundry_memory/main.py |
Updates the Memory factory and history configuration. |
python/samples/04-hosting/foundry-hosted-agents/responses/files/README.md |
Updates the documented host configuration. |
python/samples/04-hosting/foundry-hosted-agents/responses/files/main.py |
Migrates file-tool factory construction and history. |
python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/README.md |
Documents the dedicated workflow host. |
python/samples/04-hosting/foundry-hosted-agents/responses/declarative_customer_support/main.py |
Migrates declarative workflow hosting and parsing. |
python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/README.md |
Updates history-source terminology. |
python/samples/04-hosting/foundry-hosted-agents/responses/custom_storage/main.py |
Updates the agent factory while retaining custom storage. |
python/samples/04-hosting/foundry-hosted-agents/responses/basic/service_history.py |
Uses inference_service history. |
python/samples/04-hosting/foundry-hosted-agents/responses/basic/README.md |
Explains renamed policies and storage-alias migration. |
python/samples/04-hosting/foundry-hosted-agents/responses/basic/provider_background.py |
Updates factory, history, and background settings. |
python/samples/04-hosting/foundry-hosted-agents/responses/basic/options.py |
Migrates the request annotation and history value. |
python/samples/04-hosting/foundry-hosted-agents/responses/basic/main.py |
Uses host_managed history. |
python/samples/04-hosting/foundry-hosted-agents/responses/basic/agent_history.py |
Uses agent_managed history. |
python/samples/04-hosting/foundry-hosted-agents/responses/azure_search_rag/README.md |
Updates history-source terminology. |
python/samples/04-hosting/foundry-hosted-agents/responses/azure_search_rag/main.py |
Migrates the Search factory and history configuration. |
python/samples/04-hosting/foundry-hosted-agents/README.md |
Aligns shared sample guidance with the renamed API. |
python/samples/04-hosting/foundry-hosted-agents/invocations/basic/workflow.py |
Uses the native Invocations host and parse_input. |
python/samples/04-hosting/foundry-hosted-agents/invocations/basic/README.md |
Documents separate hosts and required workflow factories. |
python/samples/04-hosting/foundry-hosted-agents/invocations/basic/main.py |
Renames the agent parser to parse_input. |
python/samples/02-agents/harness/build_your_own_claw/claw_step04_production_ready/README.md |
Updates the documented history configuration. |
python/samples/02-agents/harness/build_your_own_claw/claw_step04_production_ready/hosted.py |
Migrates the hosted harness factory and history value. |
python/samples/01-get-started/07_hosting.py |
Updates introductory hosting configuration. |
python/packages/foundry_hosting/tests/test_responses_int.py |
Migrates history/storage tests and native crash-recovery coverage. |
python/packages/foundry_hosting/tests/test_request.py |
Updates request contracts and shared-helper imports. |
python/packages/foundry_hosting/tests/test_invocations.py |
Covers factory contracts, request timing, and wrapper rejection. |
python/packages/foundry_hosting/tests/test_foundry_hosting_imports.py |
Tests exports, signatures, lazy imports, and invalid construction. |
python/packages/foundry_hosting/tests/foundry_hosting/test_workflow_state.py |
Updates resolver tests and verifies agent-source rejection. |
python/packages/foundry_hosting/tests/foundry_hosting/test_native_responses.py |
Migrates native-host tests and adds isolation/prefix coverage. |
python/packages/foundry_hosting/tests/foundry_hosting/test_invocations_workflow.py |
Migrates workflow tests and checks shared-resource rejection. |
python/packages/foundry_hosting/README.md |
Documents host selection, ownership, and breaking migrations. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/_workflow_state.py |
Imports workflow contracts from shared internals. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py |
Consolidates contracts, options, and factory validation/resolution. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses_workflow.py |
Exposes the dedicated native Responses workflow host. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/_request.py |
Removes request definitions relocated to _shared.py. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_workflow.py |
Adds the workflow-specific Invocations constructor. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_shared.py |
Shares protocol execution behind separate public hosts. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/_invocations_agent.py |
Adds the agent-specific Invocations constructor. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/_agent_source.py |
Removes factory helpers relocated to _shared.py. |
python/packages/foundry_hosting/agent_framework_foundry_hosting/__init__.py |
Updates lazy public exports and removes the old request name. |
python/packages/core/agent_framework/foundry/__init__.pyi |
Adds typing exports for workflow hosts and ResponsesRequest. |
python/packages/core/agent_framework/foundry/__init__.py |
Adds matching lazy runtime exports. |
docs/decisions/0055-python-foundry-hosting-contracts.md |
Records proposed contracts and outstanding implementation boundaries. |
Review effort: Balanced
There was a problem hiding this comment.
MAF Automated Review — Iteration 1
Result: Findings reported
Scope: full PR (1 commit(s)): f6299f152332
Model: gpt-5.6-sol
Overview
The PR cleanly separates agent and native-workflow hosts, adds explicit request-aware factory contracts, and preserves strong checkpoint, continuation, option-boundary, and request-owned cleanup guards with broad regression coverage. The factory signature checks, workflow state validation, and exact pending-reply matching substantially constrain misuse. One Medium compatibility defect remains: making workflow factories mandatory exposes an existing ownership check that rejects ordinary reusable stateless function tools after their first request.
Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.
Affected areas: python/packages/foundry_hosting/agent_framework_foundry_hosting/_shared.py
| if not callable(source) or inspect.isclass(source): | ||
| raise TypeError("workflow must be a built Workflow or a request-aware factory returning a built Workflow.") | ||
| """Require a factory accepting the protocol's request object.""" | ||
| if isinstance(source, (Workflow, SupportsAgentRun)) or not callable(source) or inspect.isclass(source): |
There was a problem hiding this comment.
Making every native workflow use a factory routes every request through WorkflowResolver, whose ownership scan also treats a module-level @tool function as request-owned. A factory that creates a fresh graph, executor, agent, and client but reuses a normal stateless function tool therefore succeeds once and fails on the second request; test_resolver_rejects_reused_local_and_mcp_tools demonstrates this. Please keep rejecting shared mutable/MCP resources while allowing reusable function tools, consistent with the ADR's requirement that only mutable tools be fresh.
8d72801 to
45f5035
Compare
Jose Alvarez (jpalvarezl)
left a comment
There was a problem hiding this comment.
Implementation-focused review.
| result = await result | ||
| if not isinstance(result, Mapping): | ||
| raise TypeError("prepare_options must return a mapping of MAF run options.") | ||
| request.set_options(result) |
There was a problem hiding this comment.
Could we validate that every key returned by prepare_options is a string before storing this mapping? InvocationRun and the Invocations hook reject non-string keys at their public boundary, but Responses currently accepts values such as {1: "value"} and passes them into ChatOptions, so the failure (or silent ignore) happens later during agent/provider dispatch. This should fail here alongside the existing mapping check.
Jose Alvarez (jpalvarezl)
left a comment
There was a problem hiding this comment.
Additional design question.
| service storage; it is not restricted to `HistoryProvider`. Remove the constructor `store=` alias, | ||
| including acceptance of `None`, without changing the wire flag or downstream storage controls. |
There was a problem hiding this comment.
Just going through the ADR first, but passing a different than None value to the store in a host_managed config, should probably raise an exception.
|
|
||
| | Setting | Contract | | ||
| | --- | --- | | ||
| | `log_level=None` | Available on all four hosts as `Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] \| None`, forwarded unchanged to the SDK constructor. `None` preserves the SDK default. | |
There was a problem hiding this comment.
Not sure what \| means here, but it could be that the pipe is being unnecessarily escaped?
There was a problem hiding this comment.
oh, this is within a table, maybe it needs to be escaped 🤔
| from agent_framework_foundry_hosting import ( | ||
| InvocationsWorkflowHostServer as InvocationsWorkflowHostServer, | ||
| ) | ||
| from agent_framework_foundry_hosting import ( | ||
| ResponsesRequest as ResponsesRequest, | ||
| ) | ||
| from agent_framework_foundry_hosting import ( | ||
| ResponsesWorkflowHostServer as ResponsesWorkflowHostServer, | ||
| ) |
There was a problem hiding this comment.
Not sure if these aliases are needed, they seem to duplicate the name anyway.
|
|
||
| logger = logging.getLogger(__name__) | ||
|
|
||
| _AGENT_CONTROLLED_FIELDS = frozenset({ |
There was a problem hiding this comment.
Nit: maybe this is me just getting familiar with the refactor, but I would find language that makes the distinction between native versus foundry_hosted a bit clearer. I haven't seen the code yet, but I am assuming that both classes will be ultimately surfaced as Agents, so this collection name doesn't really narrow the intended usage of these fields.
|
|
||
| @asynccontextmanager | ||
| async def _request_agent(self, request: Request) -> AsyncGenerator[SupportsAgentRun]: | ||
| agent = await resolve_agent(self._agent, request) |
There was a problem hiding this comment.
Not sure if my understanding of the syntax is correct, but I would think this call needs to happen within the block below, maybe right before yielding the agent?
| def _workflow_serialized_value(value: Any, path: str) -> Any: | ||
| if isinstance(value, (AgentResponse, AgentResponseUpdate, ChatResponse, ChatResponseUpdate)): | ||
| return value.to_dict(exclude={"continuation_token"}) | ||
| if isinstance(value, BaseModel): | ||
| _validate_workflow_mapping_keys(value.model_dump(mode="python"), f"{path}.model", set()) | ||
| return value.model_dump(mode="json") | ||
| if is_dataclass(value) and not isinstance(value, type): | ||
| return asdict(value) | ||
| to_dict = getattr(value, "to_dict", None) | ||
| if callable(to_dict): | ||
| return to_dict() | ||
| raise _WorkflowOutputError( | ||
| f"Workflow output at {path} is not JSON-serializable: unsupported type {type(value).__name__}." | ||
| ) | ||
|
|
||
|
|
||
| def _workflow_json_value(value: Any, path: str, active: set[int]) -> Any: |
There was a problem hiding this comment.
Just judging by the names of the methods is hard to tell, which one is for what. I would assume the _workflow_serialized_value would take in a string, and read a JSON object from it. The latter, is also a bit confusing, because it seems to take in a JSON object and runs a bunch of validation, so maybe this should renamed as _validate_json_payload for clarity?
Jose Alvarez (jpalvarezl)
left a comment
There was a problem hiding this comment.
Additional design question.
| ) | ||
|
|
||
|
|
||
| def _workflow_json_value(value: Any, path: str, active: set[int]) -> Any: |
There was a problem hiding this comment.
Could some of this recursive JSON normalization be delegated to Pydantic or pydantic_core.to_jsonable_python, which are already available here? I see that we need custom handling for framework responses, precise path errors, circular values, non-string keys, non-finite floats, and no string fallback, so I would not replace this blindly. I am mainly wondering whether a small framework-type adapter plus library-backed JSON conversion would reduce the amount of bespoke traversal while preserving those policies. The fixed snapshot frame shapes below may also be clearer as a small discriminated Pydantic model.
There was a problem hiding this comment.
I am not entirely sure if this change is more verbose than necessary. As far as I understood, the refactor should be mostly transparent for users, so I doubt that such an extensive update is necessary. It also references a lot of private files which might not be super relevant for the package readme doc
| def host_type( | ||
| request: pytest.FixtureRequest, | ||
| ) -> type[ResponsesHostServer | ResponsesWorkflowHostServer | InvocationsHostServer | InvocationsWorkflowHostServer]: | ||
| import agent_framework_foundry_hosting |
| """ | ||
|
|
||
| messages: AgentRunInputs | ||
| options: Mapping[str, Any] = field(default_factory=lambda: dict[str, Any]()) |
* Python: [BREAKING] Keep Foundry approval state native * Python: Fix native approval replay and publication * Python: Harden Foundry approval continuations * Python: Consolidate Foundry workflow state in shared
02a4678 to
654b227
Compare
| _MODEL_OUTPUT_REFUSAL = "refusal" | ||
| _NATIVE_APPROVAL_ID_KEY = "agent_framework_approval_id" | ||
| _NATIVE_APPROVAL_SESSION_KEY = "agent_framework_approval_session_id" | ||
| _HOSTED_PROVIDER_STATE_KEY = "_foundry_provider_background" |
| _NATIVE_APPROVAL_ID_KEY = "agent_framework_approval_id" | ||
| _NATIVE_APPROVAL_SESSION_KEY = "agent_framework_approval_session_id" | ||
| _HOSTED_PROVIDER_STATE_KEY = "_foundry_provider_background" | ||
| _HOSTED_SOURCE_CONVERSATION_KEY = "_foundry_source_conversation" |
| _NATIVE_APPROVAL_SESSION_KEY = "agent_framework_approval_session_id" | ||
| _HOSTED_PROVIDER_STATE_KEY = "_foundry_provider_background" | ||
| _HOSTED_SOURCE_CONVERSATION_KEY = "_foundry_source_conversation" | ||
| _HOSTED_SERVICE_CHILD_KEY = "_foundry_service_child" |
| _HOSTED_SOURCE_CONVERSATION_KEY = "_foundry_source_conversation" | ||
| _HOSTED_SERVICE_CHILD_KEY = "_foundry_service_child" | ||
| _HOSTED_CONVERSATION_CLAIM_KEY = "_foundry_conversation_claim" | ||
| _HOSTED_CONVERSATION_COMMITTED_KEY = "_foundry_conversation_committed" |
| _HOSTED_SERVICE_CHILD_KEY = "_foundry_service_child" | ||
| _HOSTED_CONVERSATION_CLAIM_KEY = "_foundry_conversation_claim" | ||
| _HOSTED_CONVERSATION_COMMITTED_KEY = "_foundry_conversation_committed" | ||
| _HOSTED_PROVIDER_OUTPUT_COUNT_KEY = "_foundry_provider_output_count" |
| _HOSTED_PROVIDER_USAGE_KEY = "_foundry_provider_usage" | ||
| _PENDING_CONTAINER_FILE_CITATIONS_KEY = "_foundry_pending_container_file_citations" | ||
| _CONTAINER_FILE_CITATIONS_KEY = "container_file_citations" | ||
| _PUBLIC_STREAM_FAILURE_MESSAGE = "An internal server error occurred." |
| # recorded in response.output. If this key is missing, the workflow will resume from the latest | ||
| # checkpoint in storage (if any), or replay the original input if none exists as no output was ever | ||
| # durably persisted. | ||
| _LATEST_CHECKPOINT_ID_KEY = "_last_checkpoint_id" |
Motivation & Context
Integrate the coordinated Python Foundry Hosting breaking changes from
python-foundry-hosting-rc. This draft tracks the release-integration work toward a stable Responses surface in oneagent-framework-foundry-hostingpackage, with Invocations and Toolbox remaining experimental.The branch currently contains the agent/native-workflow host split merged in #10224. The remaining agreed configuration, approval, consent, and options-boundary work is not implemented by that split and remains outstanding before this draft is ready for final review.
Description & Review Guide
ResponsesHostServerandInvocationsHostServerfor agents; introduceResponsesWorkflowHostServerandInvocationsWorkflowHostServerfor native workflows. Require fresh request-aware workflow factories and explicitparse_inputcallbacks. RenameHostedResponseRequesttoResponsesRequest, align history/background source literals, and remove the constructorstore=alias while retainingresponse_store=and the wire-levelstoreflag. Agent factories must declare a required namedrequestparameter and are invoked asfactory(request=request); zero-argument factories are no longer supported. Split shared protocol internals without duplicating engines, and update public exports, regression tests, maintained samples, migration guidance, and proposed ADR 0055.WorkflowAgent; native workflow hosts require factories returning fresh workflows and reject built workflow instances and agents. Agent continuation remains session-backed; native workflow continuation and pending authority remain checkpoint-owned. Factory-owned context-managed agents are closed per request, including failure and cancellation. The resource-sharing guard rejects known shared execution resources but cannot prove isolation of arbitrary application globals. Existing history/background defaults retain their meaning under their new names. This draft does not yet promote package or feature maturity.Before:
After:
The application supplies
build_fresh_graphandparse_workflow_turn. Build fresh workflows, executors, agents, clients, providers, and mutable tools per request. Keep workflow names and executor IDs stable for checkpoint restoration. Existing wrapper state is not automatically migrated; start a fresh chain where the documented migration requires it.Agent factories use an explicit request contract:
The application supplies
build_agent_for_user. Responses factories receive trusted scope, current-turn input helpers, and translated options beforeprepare_options; Invocations factories receive the StarletteRequestafter parsing and option preparation. Factory-body exceptions are not retried with another call shape. Agent instances remain supported and shared for the host lifetime.History sources become
"host_managed"(default),"agent_managed", and"inference_service"instead of"agent_server","agent", and"service". Background sources become"host_managed"(default) and"inference_service"instead of"agent_server"and"provider". Agent-managed history may use developer-owned providers or downstream storage. Supported inference-service agent background still requires inference-service history. Outer native-workflow background does not enable provider background on workflow agents.The release direction is explicitly agreed in #10009 and the linked issue comments. Remaining coordinated work includes explicit host configuration (#10012), options/background enforcement and documentation (#10023, #10017, #10022, #10021), session-backed agent approval authority (#10019), complete hosted MCP approval preflight (#9537), and structured stored OAuth consent (#10020, #9903). Final lifecycle declarations, sample support boundaries, and migration/release qualification must also be completed. Broader routing, dependency/steering investigation, and MCP vNext are deferred rather than implicitly included.
Validation evidence reported on merged #10224, not rerun when opening this integration draft:
uv run --directory python poe test -P foundry_hosting- reported passed: 1,137 tests, 36 integration tests deselected, 91% coverage.uv run --directory python poe syntax -P foundry_hosting- reported passed.uv run --directory python poe pyright -P foundry_hosting- reported passed, no errors or warnings.uv run --directory python poe test-typing -P foundry_hosting- reported passed for all five configured checkers.uv run --directory python/packages/foundry_hosting pytest -q --import-mode=prepend -m integration --runxfail tests/test_responses_int.py::TestWorkflowResilientRecoveryRealCrash- reported passed for all eight model-free real-process crash/recovery cases.uv run --directory python pytest -q -c packages/core/pyproject.toml packages/core/tests/core/test_foundry_namespace.py- reported passed for both tests.Credentialed integration tests, live Foundry deployment, and a distribution build were not run for this draft. Final integration validation against current
mainremains outstanding.Related Issue
Fixes #10010
Fixes #10014
Fixes #10015
Fixes #10018
Relates to #10009 and #7688. The broader workflow concurrency investigation is not completed by the factory isolation work.
This integrates merged #10224 into
main; it is not a competing implementation. Closed #10187 was consolidated into #10224. No existing open PR frompython-foundry-hosting-rctomainwas found before creation. Host split, naming, and the coordinated release direction have explicit maintainer agreement recorded in the linked issues and #10224.The remaining review and release issues above are intentionally not marked as fixed by the current branch contents.
AI Assistance
AI assistance details: Copilot assisted with the implementation, tests, samples, migration documentation, and validation described in #10224, and with this integration PR description.
Contribution Checklist
breaking changelabel (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.