Skip to content

Python: [BREAKING] Make Foundry host configuration explicit - #10269

Merged
Eduard van Valkenburg (eavanvalkenburg) merged 1 commit into
microsoft:python-foundry-hosting-rcfrom
eavanvalkenburg:foundry-host-options
Nov 11, 2026
Merged

Eduard van Valkenburg (eavanvalkenburg) merged 1 commit into
microsoft:python-foundry-hosting-rcfrom
eavanvalkenburg:foundry-host-options

Conversation

@eavanvalkenburg

Copy link
Copy Markdown
Member

Motivation & Context

Make the Foundry hosting configuration boundary explicit instead of exposing the upstream Responses options bag or accepting arbitrary constructor keywords.

This is the focused configuration follow-up for #10012, targeting python-foundry-hosting-rc. It builds on the split hosts already in that branch and complements the broader RC preparation in #10260.

Description & Review Guide

  • What are the major changes?

Replace public ResponsesServerOptions arguments with supported history, heartbeat, shutdown, and resilient_background parameters. Keep log_level on all four public constructors, using the SDK's five canonical levels as Literal values.

All four hosts accept an explicit agent_server_kwargs mapping. Its contents go to AgentServer unchanged, without framework validation or mutation. Unknown top-level keywords now fail through Python argument binding.

Remove _InvocationsHostServer. Both public Invocations hosts inherit directly from the SDK host and own their agent/session or workflow/checkpoint execution paths. Small identity, wire-conversion, and streaming-cleanup helpers remain shared.

  • What is the impact of these changes?

This is an intentional breaking constructor migration. For an existing Agent named agent:

from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.responses import ResponsesServerOptions

# Before
host = ResponsesHostServer(
    agent=agent,
    options=ResponsesServerOptions(default_fetch_history_count=100),
    configure_observability=None,
)

# After
host = ResponsesHostServer(
    agent=agent,
    max_history_items=100,
    log_level="INFO",
    agent_server_kwargs={"configure_observability": None},
)

max_history_items=None supplies no SDK override; it does not promise unlimited history. Explicit caps apply only to regular host-managed agent history. Explicit heartbeat intervals must be positive, while None retains environment inheritance. No dependency floor or lockfile changes are needed.

Keep caller model-option handling, option-hook timing, state ownership, JSON/SSE wire formats, and supported recovery behavior unchanged. Outer background execution, provider background, and recovery remain separate; regular-agent recovery still requires a saved provider continuation, while native workflows use checkpoints. Framework-generated SDK options keep steering disabled and do not supply host model defaults, span callbacks, or custom version stamping.

  • What do you want reviewers to focus on?

The constructor/SDK boundary, history-default preservation, and lifecycle, cancellation, and persistence behavior moved out of the combined Invocations base. Tests cover SDK passthrough, early validation, history caps, heartbeat inheritance, logging, and the existing agent/workflow execution paths.

uv run --directory python --no-sync poe check -P foundry_hosting passed, including Ruff, source typing, all five test type checkers, and 1,243 unit tests.

uv run --directory python --no-sync --with 'azure-ai-agentserver-responses==2.2.0b1' python -m pytest -q --tb=short packages/foundry_hosting/tests/foundry_hosting/test_host_options.py passed all 76 cases against the minimum supported Responses SDK. The locked SDK is 2.3.0. Checks for the four changed samples, changed README code blocks, and wheel/source-distribution builds also passed. Live Foundry integration tests were not run.

Related Issue

Fixes #10012

The issue's November 9 maintainer decisions authorize the explicit configuration work. Follow-up review keeps the upstream resilient_background name and adds the explicit SDK mapping, direct Invocations inheritance, and literal logging levels.

#10260 is the parent RC-preparation PR, not a competing implementation. This PR contributes the focused configuration changes to its python-foundry-hosting-rc branch rather than replacing that PR.

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: GitHub Copilot assisted with implementation, tests, documentation, and this PR description.

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 links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

@agent-framework-automation 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 Nov 11, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAF Automated Review — Iteration 1

Result: No findings
Scope: full PR (1 commit(s)): 6f06ce6c8fa4
Model: gpt-5.6-sol

Overview

The PR replaces the broad SDK options surface with explicit, validated host settings while retaining a clearly documented passthrough for SDK-specific arguments. Constructor tests, state-scoping checks, bounded workflow snapshots, and cancellation-shielded cleanup preserve the existing protocol and lifecycle contracts across all four hosts. No publishable Critical, High, or Medium defect was established.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
No publishable findings remained after source verification for this scope.

This branch was successfully deployed

1 active deployment
github-app-auth — 6f06ce6c Deployed Nov 11, 2026 by eavanvalkenburg via team_check #9298
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking change Usage: [PRs], Target: all PRs that introduce changes that are not backward compatible documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants