Skip to content

Python: [Bug]: Concurrent stream close releases the functional workflow run guard too early #10262

Description

Observed Behavior

Calling close() on a functional workflow stream while a pull is active raises RuntimeError: aclose(): asynchronous generator is already running. The cleanup hook nevertheless releases the run guard while the original workflow is still executing. If the caller catches that error and starts another run on the same instance, the second run is accepted and the workflow functions overlap.

This is reproducible through both FunctionalWorkflow.run(..., stream=True) and FunctionalWorkflow.as_agent().run(..., stream=True).

Expected Behavior

A close racing an active pull may be rejected, but it must not release the workflow's single-run guard while that execution remains active. Another run must remain rejected until the first execution terminates. After normal completion or cancellation and cleanup, the instance should be reusable.

Steps to Reproduce

  1. Start a streaming run whose workflow function sets a started event, then waits for a release event.
  2. Begin reading the stream in a task, and wait for started so the workflow is definitely active.
  3. Call await stream.close() from the caller and catch the active-generator RuntimeError.
  4. Before setting release, attempt a second run on the same instance.
  5. Observe that the second workflow enters while the first is still waiting. A counter inside the actual workflow function reaches 2.

No model, credentials, external service, private-state mutation, or timing sleeps are needed.

Minimal Reproduction

The deterministic regression tests are in the submitted test file, in TestConcurrencyGuard:

  • test_close_racing_active_pull_preserves_guard: direct and agent paths, followed by normal completion or cancellation.
  • test_close_racing_checkpoint_load_releases_guard_after_failure: the same guard behavior during asynchronous checkpoint initialization, including failure and cancellation.
  • test_closed_unstarted_stream_cannot_execute_or_release_new_run: closed stale responses must not execute later or unlock a newer run.

Running these 10 cases against the unpatched source at 9dd1cbb7810e3e3a5de16d5ff4d4645886069a9b fails all 10; they pass with #10261. The first test's guard assertion fails because the second run does not raise the expected already-running error.

Error Messages and Observations

close(): RuntimeError: aclose(): asynchronous generator is already running
first workflow still active: true
second run: accepted
maximum active workflow functions: 2

The close error itself is not the defect. Releasing the guard despite that failed close is the defect.

Package Versions

agent-framework-core 1.25.0 from source. Reproduced on the original merged fix 31399727b0fd0142b4042e683d15cbf09104fd0a and main snapshot 9dd1cbb7810e3e3a5de16d5ff4d4645886069a9b.

Python Version

CPython 3.12.13.

Operating System

macOS, arm64.

Regression

The agent adapter exposes the race after close propagation was added in #10204. The direct workflow stream already exhibited it at the earlier 924a6e50ec0336f3c965ee8b1151c54085888b6e baseline. The first affected released version of the direct-stream behavior has not been established.

Additional Context

This issue tracks the concurrent-close finding from the review of #10220. It is separate from the early-close issue #10164, which was resolved by #10204. A proposed fix and regression tests are available in #10261.

ResponseStream.close() executes cleanup hooks even if the iterator's aclose() raises. Functional workflows currently use an unconditional guard-release hook. The existing cancellation tests await the cancelled pull before closing, so they miss this race.

The proposed fix keeps guard ownership with each run's actual generator lifetime, closes never-started generators, and handles retrying agent cleanup after a failed concurrent close. It preserves the existing generic ResponseStream cleanup-on-error contract.

Local validation of #10261: 259 functional workflow tests and 114 ResponseStream tests pass; the original #10164 reproduction still returns result: 2; changed-file formatting and type checks, and core wheel/sdist builds pass. The full repository and external provider integration suites were not run.

Reproduction, implementation, regression tests, local validation, and report preparation used AI assistance. The observed overlap is verified by local execution; duplicate external side effects or checkpoint corruption have not been separately demonstrated.

Activity

  1. added
    pythonUsage: [Issues, PRs], Target: Python
    triageUsage: [Issues], Target: All issues that still need to be triaged
    on Nov 11, 2026
  2. added
    needs-maintainer-triageUsage: [Issues], Target: all issues that the automated triage flow failed to process
    workflowsUsage: [Issues, PRs], Target: Workflows
    on Nov 11, 2026
  3. github-actions commented on Nov 11, 2026

    @github-actions
    Contributor

    Routing result: inconclusive, not independently reproduced in this run (test environment setup could not be completed). Source evidence is consistent with the report: in python/packages/core/agent_framework/_workflows/_functional.py, the stream registers _run_cleanup as a cleanup hook, and that hook unconditionally calls _release_run_guard(). If close() runs the hook even when aclose() raises (as described), the single-run guard would be released while the run is still active. Support boundary: unclear, so a maintainer should decide it. Proposed Fixes #10261 is open and not yet released. Routed to the workflows owner for maintainer triage. Run: https://github.com/microsoft/agent-framework/actions/runs/43003694869

    Generated by Issue Routing for #10262 · copilot · auto · ~20 AIC · ⌖ ~1 AIC · ⊞ 5.2K · ◷

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

needs-maintainer-triageUsage: [Issues], Target: all issues that the automated triage flow failed to processpythonUsage: [Issues, PRs], Target: PythontriageUsage: [Issues], Target: All issues that still need to be triagedworkflowsUsage: [Issues, PRs], Target: Workflows

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions