docs: Add function calling migration guide for Responses API

[ishanrajsingh]

📋 Summary
This PR adds a comprehensive example demonstrating the correct pattern for multi-turn conversations with function calling in the Responses API. This addresses a common source of confusion when migrating from Chat Completions to the Responses API.

🎯 Motivation
Many developers are encountering issues when migrating from /v1/chat/completions to /v1/responses, specifically around tool calling patterns (see #2677). The Responses API uses a fundamentally different approach:

❌ Old Pattern (Chat Completions):

Uses {"role": "assistant", "tool_calls": [...]} in messages

Uses {"role": "tool", "content": "..."} for tool results

Manually constructs assistant messages with tool calls

✅ New Pattern (Responses API):

Appends response.output directly to input

Uses typed items: {"type": "function_call_output", ...}

Never manually creates assistant messages with tool_calls

📝 Changes Made
Added: examples/responses/multi_turn_tools.py - Complete working example with:

Initial request with tools definition

Function call detection and execution

Proper handling of function outputs as typed items

Follow-up request with updated input

Extensive inline documentation explaining each step

Updated: examples/README.md - Added documentation section for the new example with:

Quick reference for correct vs incorrect patterns

Usage instructions

Links to related issues

🧪 Testing
Tested successfully with:

Python: 3.9, 3.10, 3.11

Library version: openai==1.108.0

Model: gpt-4o

Scenarios: Single function call, no function call, multi-turn conversation

Example output:

text
INITIAL REQUEST
Status: completed
Output items: 2
EXECUTING 1 FUNCTION CALL(S)
Function: get_weather
Result: {'location': 'Paris', 'temperature': 22, 'unit': 'celsius', 'conditions': 'Sunny'}
FINAL REQUEST
Final response: The weather in Paris is currently 22°C and sunny.
🔗 Related Issues
Closes #2677

✅ Checklist
Code follows repository style guidelines

Added comprehensive inline comments

Updated relevant documentation

Example runs without errors

Addresses the issue described in #2677

💡 Additional Context
This example can serve as a migration guide for developers transitioning existing agent systems from Chat Completions to Responses API. The key takeaway is that the Responses API manages conversation state through typed output items rather than role-based messages.