Python: [Feature]: Python: Define lifecycle ownership for agents with MCP tools inside workflows and orchestrations #9369

Problem

In Python, an Agent that has an MCP tool (MCPStdioTool, MCPStreamableHTTPTool, MCPWebsocketTool) connects lazily on its first run(). It closes the tool only through async with agent:, agent.close() or tool.close().

When the agent is placed in a workflow or orchestration (AgentExecutor, SequentialBuilder, ConcurrentBuilder, group chat, handoff, Magentic), nothing opens or closes it:

• The executors only call agent.run().
• The workflow's async with aclosing(...) only closes the event stream.
• The orchestrations package has no open or close calls.

With no async with, the first workflow run spawns the stdio subprocess (or opens the HTTP or WebSocket session). Nothing closes it until the process exits, and there is no warning. There is also no documented way to manage this for workflows. The MCP samples all use async with Agent(...), and none combine an MCP tool with a workflow.

Use Case and Evidence

A multi-agent workflow where some participants use stdio MCP servers (for example npx-launched servers), run from a long-lived service. Each workflow run reuses the agents, and the subprocesses are never shut down cleanly. In concurrent fan-out, several run() calls may also race to connect the same tool lazily.

Relevant code: Agent.open() and Agent.close() in _agents.py, the lazy connect branch in the run path, and _agent_executor.py (_run_agent_and_emit).

Desired Outcome

Users can tell, from documentation or behavior, how to open and close MCP-backed agents used in workflows and orchestrations, and the workflow case is covered by a sample.

Alternatives Considered

Wrap the whole workflow run in async with agent_a, agent_b:. This works, but it is undocumented, and users must track every agent themselves, including ones created inside orchestrations. Having AgentExecutor close agents it did not create is also undesirable, since agents can be shared or reused after the workflow finishes.

Proposed Direction

Either of these, or both:

1. Document the async with pattern and add a sample with an MCP tool in a workflow.
2. Add an opt-in lifecycle hook, for example a way for a workflow or builder to cascade open and close to its participant agents, or a warning when a lazily connected MCP tool is never closed.

Scope and Non-Goals

Python only. This does not change MCP v2 client lifecycle internals, which are covered by #8245 and #9237. It does not cover declarative workflows (#8662) or hosted MCP.

Language

Python

Contribution Intent

I can help with implementation or testing

Related

#8245, #9237, #8662, #8752