[agentserver-responses] Exclude failed response inputs from replayable conversation history

[prasanna164-code]

Description

Part of #48929 (provider-side fix; the hosted Foundry storage endpoint is tracked separately, see below).

When a turn fails, AgentServer already holds a stored response for it together with its input_items. get_history_item_ids() then keeps returning those input IDs for every later request in the same conversation_id, and for any request chained through previous_response_id. The input that made the turn fail (for example a function_call_output with no matching call) is replayed into each subsequent request, which fails the same way, so one bad request poisons the conversation indefinitely. The Agent Framework workaround (microsoft/agent-framework#7637) was closed in favour of fixing this in the provider layer, where the issue notes the behaviour is defined.

Change

The provider invariant suggested in the issue is now defined on ResponseProviderProtocol.get_history_item_ids and enforced by the in-memory and file providers:

• A response whose stored status is failed contributes only the history it inherited. Its own input items and output items are excluded from replayable history. The filter is applied while the chain is resolved, so it runs before the limit truncation and failed items never displace replayable ones.
• Every other status (completed, incomplete, cancelled, in-flight, or unknown) is unchanged.
• The failed response and its input items stay stored and retrievable through GET /responses/{id} and GET /responses/{id}/input_items for diagnostics.
• The rule lives in one place, store/_history.py (is_replayable_status), so both providers stay in lock-step.

Both providers read the status from the stored response envelope, which is the single source of truth for it. For FileResponseStore that means one extra small JSON read per response in the chain, and no second copy of the status that could drift from the envelope after a crash between two writes. Existing on-disk stores need no migration.

Output items are excluded along with the input because a failed turn may have produced a function_call that never received an output; replaying it would fail the next turn for the mirror-image reason.

Known limitation

This only affects previous_response_id chaining. When a response is chained, the history resolved for it is stored with it as a snapshot (history_item_ids). If a client chains to a response that is still running and that response later fails, the snapshot already holds the failed turn's input, so turns chained after it still receive it. Conversations are not affected: no snapshot is stored for them and their history is resolved from the store on every request, so a failed turn's input stops being replayed as soon as it has failed, even when another turn started while it was running.

This can be closed inside the providers without changing the protocol: when a response is created, record the earlier turns in its chain that had not finished yet, and at resolution time drop their items from the snapshot if they ended up failed. I have this working locally for both providers. It depends on the stored response carrying previous_response_id, which is set when the handler builds its event stream from the request (as the handler guide shows) but not otherwise, so I'd rather propose it as a follow-up; happy to open it if that direction works for you.

Hosted Foundry storage

FoundryStorageProvider delegates history resolution to the hosted history/item_ids endpoint, and hosted mode auto-selects that provider. The rule cannot be enforced client-side there: the storage API exposes per-response GET, batch item retrieval and history/item_ids (bare item IDs), with no conversation listing and no item ownership, so the client cannot tell which returned IDs belong to a failed response. The invariant is therefore defined on ResponseProviderProtocol and called out on FoundryStorageProvider.get_history_item_ids as the contract the hosted endpoint needs to implement (or expose a server-side filter for), as the issue suggests. This PR does not close #48929 on its own; the hosted part stays open with the service team.

Testing

tests/unit/test_failed_response_history.py runs every scenario against both InMemoryResponseProvider and FileResponseStore and asserts identical results:

• failed turn excluded from conversation history, earlier and later successful turns kept in order;
• a response created as in_progress and later updated to failed (the orchestrator's create-then-terminal-update path);
• previous_response_id chaining from a failed response yields only its inherited history, and a successful response chained after it stays clean;
• exclusion happens before limit truncation;
• get_input_items on the failed response still returns its items;
• file store reads the status from the envelope, so a stale or tampered indexes.json cannot make a failed turn replayable again;
• enum status members are normalised to their wire value.

tests/contract/test_failed_response_history.py drives ResponsesAgentServerHost end to end with the reproduction from the issue (a function_call_output for a call that does not exist): the next valid turn in the conversation succeeds and its handler sees no history from the failed turn, successful turns before and after the failure are kept, chaining through the failed response via previous_response_id is clean, and the same holds for streaming and background requests. The failed response and its input items are still retrievable.

With the status rule neutralised (old behaviour), 13 of the 22 new tests fail, including all end-to-end conversation, chaining, streaming and background cases. The existing unit and contract suites pass with the change. black, pylint with the repository guidelines checker, mypy and cspell are clean on the changed files.

All SDK Contribution checklist:

• The pull request does not introduce [breaking changes]
• CHANGELOG is updated for new features, bug fixes or other significant changes.
• I have read the contribution guidelines.

General Guidelines and Best Practices

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

[github-actions]

Thank you for your contribution prasanna164-code! We will review the pull request and get back to you soon.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
7 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

File-store status indexes can become stale or diverge from response envelopes, causing incorrect history replay.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Prevents failed response items from poisoning subsequent replayable history.

Changes:

• Defines shared failed-status replay rules.
• Applies filtering to memory and file stores, with persisted status indexes.
• Adds unit, contract, and changelog coverage.

File summaries

File	Description
CHANGELOG.md	Documents the history fix.
store/_base.py	Defines the provider invariant.
store/_history.py	Adds shared status normalization and filtering.
store/_memory.py	Filters failed response items in memory.
store/_file.py	Filters failed items using indexed status.
tests/unit/test_failed_response_history.py	Tests provider behavior and compatibility.
tests/contract/test_failed_response_history.py	Tests synchronous, streaming, and background flows.

Review details

Suppressed comments (1)

sdk/agentserver/azure-ai-agentserver-responses/azure/ai/agentserver/responses/store/_file.py:744

• None is both the default sentinel and a valid unknown status, so an update that omits/clears status leaves the previous indexed value intact. After updating a failed response without a status, the in-memory provider treats it as replayable, but the file provider remains non-replayable. Always rewrite the indexed status on an envelope update so it stays aligned with the source envelope.

        if status is not None:
            current["status"] = normalize_status(status)

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Balanced

---

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

[Copilot]

🟡 Changes recommended

The hosted Foundry provider still delegates to an endpoint that does not demonstrably enforce the new invariant.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟢 Approval recommended

The scoped provider fix is consistent, preserves diagnostics, and has comprehensive regression coverage.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

🟢 Approval recommended

The local provider fix is consistent, preserves diagnostic access, and has comprehensive regression coverage.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced