Python: Add AgentExecutorResponse.with_text() to preserve conversation history through custom executors

[kartikmadan11]

Motivation and Context

When a custom @executor sits between two AgentExecutor nodes in a workflow chain, it receives an AgentExecutorResponse (which carries the full conversation) but typically sends a plain str downstream. This causes the next AgentExecutor.from_str handler to start fresh with only that string, losing all prior conversation turns.

The issue reporter demonstrated this with a simple upper-case executor placed between four agents — the final agent could only see its own immediate input instead of the full history from all previous agents.

Fixes #5246

Description

The root cause is that custom executors have no convenient way to transform the agent's output text while keeping the AgentExecutorResponse wrapper intact. Sending a plain str routes to from_str, which discards the conversation chain.

This adds a with_text(text) method to AgentExecutorResponse that creates a new response with replaced text, preserving the prior conversation in full_conversation. This way the response type stays AgentExecutorResponse and routes to from_response instead, which properly feeds the full history into the next agent's cache.

Three regression tests are included:

• End-to-end workflow test mirroring the issue's reproduction (agent1 → agent2 → upper_case → agent3 → capture)
• Immutability check (original response is not mutated)
• Multi-message agent turn stripping (tool call chains are handled correctly)

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[kartikmadan11]

@microsoft-github-policy-service agree

[moonbox3]

Thanks for the PR. The helper itself looks correct and I'm supportive of merging it. One thing I'd like to see added before we do that, though:

The underlying issue in #5246 looks fundamentally like a discoverability problem. The typed-dispatch routing between from_str / from_response / from_message is working as designed (see _agent_executor.py:156-188), but a user writing a custom executor with output=str has no way to know they're silently dropping full_conversation. Adding with_text() gives them an escape hatch, but only if they already know it exists - the original reporter's code would have looked identical without this PR, and they'd hit the same wall.

Could we also:

1. Add a docstring note on AgentExecutor.from_str (and on the @executor decorator / tutorial docs for custom executors between agents) that explicitly calls out: "if the upstream executor received an AgentExecutorResponse, emitting a plain str will reset the conversation. Use AgentExecutorResponse.with_text(...) to preserve it."
2. Consider a logger.warning in from_str when the cache is empty and the incoming text looks like it came from an agent turn - or at minimum when the sending executor's declared input type is AgentExecutorResponse. (Optional; docs alone may be enough.)

Without the docs change the helper is hard to find, and users will keep filing this same bug.

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_agent_executor.py	198	16	91%	165, 189, 230, 256–257, 337–339, 341, 351–352, 399, 471–472, 544, 550
TOTAL	27551	3199	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
5573	20 💤	0 ❌	0 🔥	1m 25s ⏱️

[kartikmadan11]

Thanks for the review! Updated with:

• Warning: docstrings on both from_str and @executor
• logger.warning in from_str