PR Summary

Overview

• Wire LangChain's structured-output response_format into MCPAgent without recreating the agent per call.
• Introduce a dynamic middleware that only forces structured output once the agent reaches its final turn.
• Preserve a fast fallback path for single-turn answers by formatting the model response via provider-native structured output.
• Tighten connector initialization logic and add a fresh example demonstrating the new structured output flow.

Key Changes

• mcp_use/agents/mcpagent.py
  • Added dynamic_structured_output middleware (@wrap_model_call) that inspects pending tool calls and updates the ModelRequest with AutoStrategy only when the agent is about to return a final response. This avoids constraining intermediate reasoning/tool-selection steps.
  • Propagate the optional response_format through the agent's astream context so LangChain can surface native structured_response payloads.
  • Track structured_response chunks during streaming and, on completion, deliver them directly when present. When the provider did not emit a native payload (e.g., single-shot replies), re-run the final answer through llm.with_structured_output(schema) to coerce it into the requested schema without re-executing the agent loop.
• examples/python/new_structured_output_example.py
  • Added a runnable sample that connects to the Airbnb MCP server and requests a structured result, illustrating the new workflow end-to-end.

Design Decisions & Rationale

• Deferred response-format enforcement: Applying structured output at agent creation would force every LLM turn into the schema, preventing tool planning. The middleware pattern lets us inspect the conversation state and only set response_format after tools finish (or when no tools were needed), keeping agent behaviour unchanged while still leveraging LangChain 1.0's structured output pipeline.
• Provider-native fallback over custom parsing: Previous structured output relied on an extra prompt/validation step, which was slower. Using with_structured_output() is faster and more reliable; we still have _attempt_structured_output available if future providers lack native support.
• Context propagation: Passing context={"response_format": output_schema} into astream ensures LangChain's compiled graph can produce structured_response entries, unlocking the zero-copy fast path when available.

Testing Notes

• Exercised the new example script (new_structured_output_example.py) to confirm:
  • Tool-using runs surface native structured responses without extra formatting.
  • Simple one-shot queries (no tools) still yield structured data via the fallback formatter.

Follow-ups / Considerations

• If we integrate providers without native structured-output APIs, we should wrap the fallback formatter in try/except and fall back to _attempt_structured_output (already present) for compatibility.
• Documentation can be updated to highlight the middleware-driven structured output pattern and the new example script.

Fixes #397