Agents + Chat Client Samples Doctsring Updates (#1028)

* agents + chat client samples doctsring updates

* fixes

python/samples/getting_started/agents/anthropic/README.md

@@ -0,0 +1,17 @@
+# Anthropic Examples
+
+This folder contains examples demonstrating how to use Anthropic's Claude models with the Agent Framework through the OpenAI Chat Client interface.
+
+## Examples
+
+| File | Description |
+|------|-------------|
+| [`anthropic_with_openai_chat_client.py`](anthropic_with_openai_chat_client.py) | Demonstrates how to configure OpenAI Chat Client to use Anthropic's Claude models. Shows both streaming and non-streaming responses with tool calling capabilities. |
+
+## Environment Variables
+
+Set the following environment variables before running the examples:
+
+- `ANTHROPIC_API_KEY`: Your Anthropic API key (get one from [Anthropic Console](https://console.anthropic.com/))
+- `ANTHROPIC_MODEL`: The Claude model to use (e.g., `claude-3-5-sonnet-20241022`, `claude-3-haiku-20240307`)
+

python/samples/getting_started/agents/anthropic/anthropic_with_openai_chat_client.py

@@ -10,16 +10,8 @@ from agent_framework.openai import OpenAIChatClient
 """
 Anthropic with OpenAI Chat Client Example
 
-This sample demonstrates how to use Anthropic models through the OpenAI Chat Client by
-configuring the base URL to point to Anthropic's API. The example includes:
-
-- Setting up OpenAI Chat Client with Anthropic API configuration
-- Creating an agent with tool calling capabilities (weather function)
-- Non-streaming response example to get complete results at once
-- Streaming response example to receive results as they are generated
-
-This approach allows you to leverage Anthropic's Claude models while using the familiar
-OpenAI client interface, making it easy to switch between different model providers.
+This sample demonstrates using Anthropic models through OpenAI Chat Client by
+configuring the base URL to point to Anthropic's API for cross-provider compatibility.
 """
 
 

python/samples/getting_started/agents/azure_ai/azure_ai_basic.py

@@ -8,6 +8,13 @@ from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure AI Agent Basic Example
+
+This sample demonstrates basic usage of AzureAIAgentClient to create agents with automatic
+lifecycle management. Shows both streaming and non-streaming responses with function tools.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py

@@ -9,6 +9,13 @@ from azure.ai.agents.models import (
 )
 from azure.identity.aio import AzureCliCredential
 
+"""
+Azure AI Agent with Code Interpreter Example
+
+This sample demonstrates using HostedCodeInterpreterTool with Azure AI Agents
+for Python code execution and mathematical problem solving.
+"""
+
 
 def print_code_interpreter_inputs(response: AgentRunResponse) -> None:
     """Helper method to access code interpreter data."""
@@ -43,7 +50,8 @@ async def main() -> None:
         print(f"User: {query}")
         response = await AgentRunResponse.from_agent_response_generator(agent.run_stream(query))
         print(f"Agent: {response}")
-        # To review the code interpreter outputs, you can access them from the response raw_representations, just uncomment the next line:
+        # To review the code interpreter outputs, you can access
+        # them from the response raw_representations, just uncomment the next line:
         # print_code_interpreter_inputs(response)
 
 

python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_agent.py

@@ -11,6 +11,13 @@ from azure.ai.projects.aio import AIProjectClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure AI Agent with Existing Agent Example
+
+This sample demonstrates working with pre-existing Azure AI Agents by providing
+agent IDs, showing agent reuse patterns for production scenarios.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_ai/azure_ai_with_existing_thread.py

@@ -11,6 +11,13 @@ from azure.ai.projects.aio import AIProjectClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure AI Agent with Existing Thread Example
+
+This sample demonstrates working with pre-existing conversation threads
+by providing thread IDs for thread reuse patterns.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py

@@ -10,6 +10,13 @@ from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure AI Agent with Explicit Settings Example
+
+This sample demonstrates creating Azure AI Agents with explicit configuration
+settings rather than relying on environment variable defaults.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_ai/azure_ai_with_function_tools.py

@@ -10,6 +10,13 @@ from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure AI Agent with Function Tools Example
+
+This sample demonstrates function tool integration with Azure AI Agents,
+showing both agent-level and query-level tool configuration patterns.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py

@@ -7,6 +7,13 @@ from agent_framework import AgentProtocol, AgentThread, HostedMCPTool
 from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 
+"""
+Azure AI Agent with Hosted MCP Example
+
+This sample demonstrates integration of Azure AI Agents with hosted Model Context Protocol (MCP)
+servers, including user approval workflows for function call security.
+"""
+
 
 async def handle_approvals_with_thread(query: str, agent: "AgentProtocol", thread: "AgentThread"):
     """Here we let the thread deal with the previous responses, and we just rerun with the approval."""

python/samples/getting_started/agents/azure_ai/azure_ai_with_local_mcp.py

@@ -6,6 +6,13 @@ from agent_framework import ChatAgent, MCPStreamableHTTPTool
 from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 
+"""
+Azure AI Agent with Local MCP Example
+
+This sample demonstrates integration of Azure AI Agents with local Model Context Protocol (MCP)
+servers, showing both agent-level and run-level tool configuration patterns.
+"""
+
 
 async def mcp_tools_on_run_level() -> None:
     """Example showing MCP tools defined when running the agent."""

python/samples/getting_started/agents/azure_ai/azure_ai_with_multiple_tools.py

@@ -13,6 +13,13 @@ from agent_framework import (
 from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 
+"""
+Azure AI Agent with Multiple Tools Example
+
+This sample demonstrates integrating multiple tools (MCP and Web Search) with Azure AI Agents,
+including user approval workflows for function call security.
+"""
+
 
 def get_time() -> str:
     """Get the current UTC time."""

python/samples/getting_started/agents/azure_ai/azure_ai_with_thread.py

@@ -9,6 +9,13 @@ from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure AI Agent with Thread Management Example
+
+This sample demonstrates thread management with Azure AI Agents, comparing
+automatic thread creation with explicit thread management for persistent context.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/README.md

@@ -21,6 +21,7 @@ This folder contains examples demonstrating different ways to create and use age
 | [`azure_responses_client_with_function_tools.py`](azure_responses_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). |
 | [`azure_responses_client_with_code_interpreter.py`](azure_responses_client_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with Azure agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. |
 | [`azure_responses_client_with_thread.py`](azure_responses_client_with_thread.py) | Demonstrates thread management with Azure agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
+| [`azure_responses_client_image_analysis.py`](azure_responses_client_image_analysis.py) | Shows how to use Azure OpenAI Responses for image analysis and vision tasks. Demonstrates multi-modal messages combining text and image content using remote URLs. |
 
 ## Environment Variables
 

python/samples/getting_started/agents/azure_openai/azure_assistants_basic.py

@@ -8,6 +8,13 @@ from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Assistants Basic Example
+
+This sample demonstrates basic usage of AzureOpenAIAssistantsClient with automatic
+assistant lifecycle management, showing both streaming and non-streaming responses.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_assistants_with_code_interpreter.py

@@ -13,6 +13,13 @@ from openai.types.beta.threads.runs import (
 )
 from openai.types.beta.threads.runs.code_interpreter_tool_call_delta import CodeInterpreter
 
+"""
+Azure OpenAI Assistants with Code Interpreter Example
+
+This sample demonstrates using HostedCodeInterpreterTool with Azure OpenAI Assistants
+for Python code execution and mathematical problem solving.
+"""
+
 
 def get_code_interpreter_chunk(chunk: AgentRunResponseUpdate) -> str | None:
     """Helper method to access code interpreter data."""

python/samples/getting_started/agents/azure_openai/azure_assistants_with_existing_assistant.py

@@ -11,6 +11,13 @@ from azure.identity import AzureCliCredential, get_bearer_token_provider
 from openai import AsyncAzureOpenAI
 from pydantic import Field
 
+"""
+Azure OpenAI Assistants with Existing Assistant Example
+
+This sample demonstrates working with pre-existing Azure OpenAI Assistants
+using existing assistant IDs rather than creating new ones.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_assistants_with_explicit_settings.py

@@ -9,6 +9,13 @@ from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Assistants with Explicit Settings Example
+
+This sample demonstrates creating Azure OpenAI Assistants with explicit configuration
+settings rather than relying on environment variable defaults.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_assistants_with_function_tools.py

@@ -10,6 +10,13 @@ from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Assistants with Function Tools Example
+
+This sample demonstrates function tool integration with Azure OpenAI Assistants,
+showing both agent-level and query-level tool configuration patterns.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_assistants_with_thread.py

@@ -9,6 +9,13 @@ from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Assistants with Thread Management Example
+
+This sample demonstrates thread management with Azure OpenAI Assistants, comparing
+automatic thread creation with explicit thread management for persistent context.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_chat_client_basic.py

@@ -8,6 +8,13 @@ from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Chat Client Basic Example
+
+This sample demonstrates basic usage of AzureOpenAIChatClient for direct chat-based
+interactions, showing both streaming and non-streaming responses.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_explicit_settings.py

@@ -9,6 +9,13 @@ from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Chat Client with Explicit Settings Example
+
+This sample demonstrates creating Azure OpenAI Chat Client with explicit configuration
+settings rather than relying on environment variable defaults.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_function_tools.py

@@ -10,6 +10,13 @@ from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Chat Client with Function Tools Example
+
+This sample demonstrates function tool integration with Azure OpenAI Chat Client,
+showing both agent-level and query-level tool configuration patterns.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_chat_client_with_thread.py

@@ -9,6 +9,13 @@ from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Chat Client with Thread Management Example
+
+This sample demonstrates thread management with Azure OpenAI Chat Client, comparing
+automatic thread creation with explicit thread management for persistent context.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_responses_client_basic.py

@@ -8,6 +8,13 @@ from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Responses Client Basic Example
+
+This sample demonstrates basic usage of AzureOpenAIResponsesClient for structured
+response generation, showing both streaming and non-streaming responses.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_responses_client_image_analysis.py

@@ -0,0 +1,46 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+
+from agent_framework import ChatMessage, TextContent, UriContent
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+
+"""
+Azure OpenAI Responses Client with Image Analysis Example
+
+This sample demonstrates using Azure OpenAI Responses for image analysis and vision tasks,
+showing multi-modal messages combining text and image content.
+"""
+
+
+async def main():
+    print("=== Azure Responses Agent with Image Analysis ===")
+
+    # 1. Create an Azure Responses agent with vision capabilities
+    agent = AzureOpenAIResponsesClient(credential=AzureCliCredential()).create_agent(
+        name="VisionAgent",
+        instructions="You are a helpful agent that can analyze images.",
+    )
+
+    # 2. Create a simple message with both text and image content
+    user_message = ChatMessage(
+        role="user",
+        contents=[
+            TextContent(text="What do you see in this image?"),
+            UriContent(
+                uri="https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
+                media_type="image/jpeg",
+            ),
+        ],
+    )
+
+    # 3. Get the agent's response
+    print("User: What do you see in this image? [Image provided]")
+    result = await agent.run(user_message)
+    print(f"Agent: {result.text}")
+    print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_code_interpreter.py

@@ -8,6 +8,13 @@ from azure.identity import AzureCliCredential
 from openai.types.responses.response import Response as OpenAIResponse
 from openai.types.responses.response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall
 
+"""
+Azure OpenAI Responses Client with Code Interpreter Example
+
+This sample demonstrates using HostedCodeInterpreterTool with Azure OpenAI Responses
+for Python code execution and mathematical problem solving.
+"""
+
 
 async def main() -> None:
     """Example showing how to use the HostedCodeInterpreterTool with Azure OpenAI Responses."""

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_explicit_settings.py

@@ -9,6 +9,13 @@ from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Responses Client with Explicit Settings Example
+
+This sample demonstrates creating Azure OpenAI Responses Client with explicit configuration
+settings rather than relying on environment variable defaults.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_function_tools.py

@@ -10,6 +10,13 @@ from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Responses Client with Function Tools Example
+
+This sample demonstrates function tool integration with Azure OpenAI Responses Client,
+showing both agent-level and query-level tool configuration patterns.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/azure_openai/azure_responses_client_with_thread.py

@@ -9,6 +9,13 @@ from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure OpenAI Responses Client with Thread Management Example
+
+This sample demonstrates thread management with Azure OpenAI Responses Client, comparing
+automatic thread creation with explicit thread management for persistent context.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/copilotstudio/copilotstudio_basic.py

@@ -4,6 +4,13 @@ import asyncio
 
 from agent_framework.microsoft import CopilotStudioAgent
 
+"""
+Copilot Studio Agent Basic Example
+
+This sample demonstrates basic usage of CopilotStudioAgent with automatic configuration
+from environment variables, showing both streaming and non-streaming responses.
+"""
+
 # Environment variables needed:
 # COPILOTSTUDIOAGENT__ENVIRONMENTID - Environment ID where your copilot is deployed
 # COPILOTSTUDIOAGENT__SCHEMANAME - Agent identifier/schema name of your copilot

python/samples/getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py

@@ -6,6 +6,13 @@ import os
 from agent_framework.microsoft import CopilotStudioAgent, acquire_token
 from microsoft_agents.copilotstudio.client import AgentType, ConnectionSettings, CopilotClient, PowerPlatformCloud
 
+"""
+Copilot Studio Agent with Explicit Settings Example
+
+This sample demonstrates explicit configuration of CopilotStudioAgent with manual
+token management and custom ConnectionSettings for production environments.
+"""
+
 # Environment variables needed:
 # COPILOTSTUDIOAGENT__ENVIRONMENTID - Environment ID where your copilot is deployed
 # COPILOTSTUDIOAGENT__SCHEMANAME - Agent identifier/schema name of your copilot

python/samples/getting_started/agents/custom/custom_agent.py

@@ -17,18 +17,8 @@ from agent_framework import (
 """
 Custom Agent Implementation Example
 
-This sample demonstrates how to implement a custom agent by extending the BaseAgent class.
-Custom agents provide complete control over the agent's behavior and capabilities, allowing
-developers to create specialized agents that don't rely on chat clients.
-
-This approach is useful when you need to:
-- Implement agents with custom logic that doesn't involve LLM interactions
-- Create agents that integrate with specialized APIs or services
-- Build agents with deterministic behaviors
-- Implement new agent types for the Microsoft Agent Framework
-
-The EchoAgent example shows the minimal requirements for implementing a custom agent,
-including both streaming and non-streaming response handling.
+This sample demonstrates implementing a custom agent by extending BaseAgent class,
+showing the minimal requirements for both streaming and non-streaming responses.
 """
 
 

python/samples/getting_started/agents/custom/custom_chat_client.py

@@ -20,20 +20,8 @@ from agent_framework import (
 """
 Custom Chat Client Implementation Example
 
-This sample demonstrates how to implement a custom chat client by extending the BaseChatClient class.
-Custom chat clients allow you to integrate any backend service or create new LLM providers
-for the Microsoft Agent Framework.
-
-This approach is useful when you need to:
-- Integrate with new or proprietary LLM services
-- Create mock implementations for testing
-- Add custom authentication or routing logic
-- Implement specialized preprocessing or postprocessing of requests and responses
-- Create new LLM providers that work seamlessly with the framework's ChatAgent
-
-The EchoingChatClient example shows the minimal requirements for implementing a custom chat client,
-including both streaming and non-streaming response handling, and demonstrates how to use the
-custom client with ChatAgent through the create_agent() method.
+This sample demonstrates implementing a custom chat client by extending BaseChatClient class,
+showing integration with ChatAgent and both streaming and non-streaming responses.
 """
 
 

python/samples/getting_started/agents/openai/README.md

@@ -1,4 +1,4 @@
-# OpenAI Assistants Agent Examples
+# OpenAI Agent Framework Examples
 
 This folder contains examples demonstrating different ways to create and use agents with the OpenAI Assistants client from the `agent_framework.openai` package.
 
@@ -20,14 +20,13 @@ This folder contains examples demonstrating different ways to create and use age
 | [`openai_chat_client_with_thread.py`](openai_chat_client_with_thread.py) | Demonstrates thread management with OpenAI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |
 | [`openai_chat_client_with_web_search.py`](openai_chat_client_with_web_search.py) | Shows how to use web search capabilities with OpenAI agents to retrieve and use information from the internet in responses. |
 | [`openai_responses_client_basic.py`](openai_responses_client_basic.py) | The simplest way to create an agent using `ChatAgent` with `OpenAIResponsesClient`. Shows both streaming and non-streaming responses for structured response generation with OpenAI models. |
-| [`openai_responses_client_reasoning.py`](openai_responses_client_reasoning.py) | Demonstrates how to use reasoning capabilities with OpenAI agents, showing how the agent can provide detailed reasoning for its responses. |
-| [`openai_responses_client_with_explicit_settings.py`](openai_responses_client_with_explicit_settings.py) | Shows how to initialize an agent with a specific responses client, configuring settings explicitly including API key and model ID. |
-| [`openai_responses_client_with_function_tools.py`](openai_responses_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and query-level tools (provided with specific queries). |
-| [`openai_responses_client_with_code_interpreter.py`](openai_responses_client_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with OpenAI agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. |
-| [`openai_responses_client_with_file_search.py`](openai_responses_client_with_file_search.py) | Demonstrates how to use file search capabilities with OpenAI agents, allowing the agent to search through uploaded files to answer questions. |
-| [`openai_responses_client_with_hosted_mcp.py`](openai_responses_client_with_hosted_mcp.py) | Shows how to integrate OpenAI agents with hosted Model Context Protocol (MCP) servers, including approval workflows and tool management for remote MCP services. |
 | [`openai_responses_client_image_analysis.py`](openai_responses_client_image_analysis.py) | Demonstrates how to use vision capabilities with agents to analyze images. |
-| [`openai_responses_client_image_generation.py`](openai_responses_client_image_generation.py) | Shows how to use image generation capabilities with agents to create images from text descriptions. Requires PIL (Pillow) for image display. |
+| [`openai_responses_client_reasoning.py`](openai_responses_client_reasoning.py) | Demonstrates how to use reasoning capabilities with OpenAI agents, showing how the agent can provide detailed reasoning for its responses. |
+| [`openai_responses_client_with_code_interpreter.py`](openai_responses_client_with_code_interpreter.py) | Shows how to use the HostedCodeInterpreterTool with OpenAI agents to write and execute Python code. Includes helper methods for accessing code interpreter data from response chunks. |
+| [`openai_responses_client_with_explicit_settings.py`](openai_responses_client_with_explicit_settings.py) | Shows how to initialize an agent with a specific responses client, configuring settings explicitly including API key and model ID. |
+| [`openai_responses_client_with_file_search.py`](openai_responses_client_with_file_search.py) | Demonstrates how to use file search capabilities with OpenAI agents, allowing the agent to search through uploaded files to answer questions. |
+| [`openai_responses_client_with_function_tools.py`](openai_responses_client_with_function_tools.py) | Demonstrates how to use function tools with agents. Shows both agent-level tools (defined when creating the agent) and run-level tools (provided with specific queries). |
+| [`openai_responses_client_with_hosted_mcp.py`](openai_responses_client_with_hosted_mcp.py) | Shows how to integrate OpenAI agents with hosted Model Context Protocol (MCP) servers, including approval workflows and tool management for remote MCP services. |
 | [`openai_responses_client_with_local_mcp.py`](openai_responses_client_with_local_mcp.py) | Shows how to integrate OpenAI agents with local Model Context Protocol (MCP) servers for enhanced functionality and tool integration. |
 | [`openai_responses_client_with_structured_output.py`](openai_responses_client_with_structured_output.py) | Demonstrates how to use structured outputs with OpenAI agents to get structured data responses in predefined formats. |
 | [`openai_responses_client_with_thread.py`](openai_responses_client_with_thread.py) | Demonstrates thread management with OpenAI agents, including automatic thread creation for stateless conversations and explicit thread management for maintaining conversation context across multiple interactions. |

python/samples/getting_started/agents/openai/openai_assistants_basic.py

@@ -7,6 +7,13 @@ from typing import Annotated
 from agent_framework.openai import OpenAIAssistantsClient
 from pydantic import Field
 
+"""
+OpenAI Assistants Basic Example
+
+This sample demonstrates basic usage of OpenAIAssistantsClient with automatic
+assistant lifecycle management, showing both streaming and non-streaming responses.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_assistants_with_code_interpreter.py

@@ -12,6 +12,13 @@ from openai.types.beta.threads.runs import (
 )
 from openai.types.beta.threads.runs.code_interpreter_tool_call_delta import CodeInterpreter
 
+"""
+OpenAI Assistants with Code Interpreter Example
+
+This sample demonstrates using HostedCodeInterpreterTool with OpenAI Assistants
+for Python code execution and mathematical problem solving.
+"""
+
 
 def get_code_interpreter_chunk(chunk: AgentRunResponseUpdate) -> str | None:
     """Helper method to access code interpreter data."""

python/samples/getting_started/agents/openai/openai_assistants_with_existing_assistant.py

@@ -10,6 +10,13 @@ from agent_framework.openai import OpenAIAssistantsClient
 from openai import AsyncOpenAI
 from pydantic import Field
 
+"""
+OpenAI Assistants with Existing Assistant Example
+
+This sample demonstrates working with pre-existing OpenAI Assistants
+using existing assistant IDs rather than creating new ones.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_assistants_with_explicit_settings.py

@@ -8,6 +8,13 @@ from typing import Annotated
 from agent_framework.openai import OpenAIAssistantsClient
 from pydantic import Field
 
+"""
+OpenAI Assistants with Explicit Settings Example
+
+This sample demonstrates creating OpenAI Assistants with explicit configuration
+settings rather than relying on environment variable defaults.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_assistants_with_file_search.py

@@ -5,6 +5,13 @@ import asyncio
 from agent_framework import ChatAgent, HostedFileSearchTool, HostedVectorStoreContent
 from agent_framework.openai import OpenAIAssistantsClient
 
+"""
+OpenAI Assistants with File Search Example
+
+This sample demonstrates using HostedFileSearchTool with OpenAI Assistants
+for document-based question answering and information retrieval.
+"""
+
 # Helper functions
 
 

python/samples/getting_started/agents/openai/openai_assistants_with_function_tools.py

@@ -9,6 +9,13 @@ from agent_framework import ChatAgent
 from agent_framework.openai import OpenAIAssistantsClient
 from pydantic import Field
 
+"""
+OpenAI Assistants with Function Tools Example
+
+This sample demonstrates function tool integration with OpenAI Assistants,
+showing both agent-level and query-level tool configuration patterns.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_assistants_with_thread.py

@@ -8,6 +8,13 @@ from agent_framework import AgentThread, ChatAgent
 from agent_framework.openai import OpenAIAssistantsClient
 from pydantic import Field
 
+"""
+OpenAI Assistants with Thread Management Example
+
+This sample demonstrates thread management with OpenAI Assistants, showing
+persistent conversation threads and context preservation across interactions.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_chat_client_basic.py

@@ -6,6 +6,13 @@ from typing import Annotated
 
 from agent_framework.openai import OpenAIChatClient
 
+"""
+OpenAI Chat Client Basic Example
+
+This sample demonstrates basic usage of OpenAIChatClient for direct chat-based
+interactions, showing both streaming and non-streaming responses.
+"""
+
 
 def get_weather(
     location: Annotated[str, "The location to get the weather for."],

python/samples/getting_started/agents/openai/openai_chat_client_with_explicit_settings.py

@@ -8,6 +8,13 @@ from typing import Annotated
 from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 
+"""
+OpenAI Chat Client with Explicit Settings Example
+
+This sample demonstrates creating OpenAI Chat Client with explicit configuration
+settings rather than relying on environment variable defaults.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_chat_client_with_function_tools.py

@@ -9,6 +9,13 @@ from agent_framework import ChatAgent
 from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 
+"""
+OpenAI Chat Client with Function Tools Example
+
+This sample demonstrates function tool integration with OpenAI Chat Client,
+showing both agent-level and query-level tool configuration patterns.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_chat_client_with_local_mcp.py

@@ -5,6 +5,13 @@ import asyncio
 from agent_framework import ChatAgent, MCPStreamableHTTPTool
 from agent_framework.openai import OpenAIChatClient
 
+"""
+OpenAI Chat Client with Local MCP Example
+
+This sample demonstrates integrating Model Context Protocol (MCP) tools with
+OpenAI Chat Client for extended functionality and external service access.
+"""
+
 
 async def mcp_tools_on_run_level() -> None:
     """Example showing MCP tools defined when running the agent."""

python/samples/getting_started/agents/openai/openai_chat_client_with_thread.py

@@ -8,6 +8,13 @@ from agent_framework import AgentThread, ChatAgent, ChatMessageStore
 from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 
+"""
+OpenAI Chat Client with Thread Management Example
+
+This sample demonstrates thread management with OpenAI Chat Client, showing
+conversation threads and message history preservation across interactions.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_chat_client_with_web_search.py

@@ -5,6 +5,13 @@ import asyncio
 from agent_framework import HostedWebSearchTool
 from agent_framework.openai import OpenAIChatClient
 
+"""
+OpenAI Chat Client with Web Search Example
+
+This sample demonstrates using HostedWebSearchTool with OpenAI Chat Client
+for real-time information retrieval and current data access.
+"""
+
 
 async def main() -> None:
     client = OpenAIChatClient(model_id="gpt-4o-search-preview")

python/samples/getting_started/agents/openai/openai_responses_client_basic.py

@@ -8,6 +8,13 @@ from agent_framework import ChatAgent
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
 
+"""
+OpenAI Responses Client Basic Example
+
+This sample demonstrates basic usage of OpenAIResponsesClient for structured
+response generation, showing both streaming and non-streaming responses.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_responses_client_image_analysis.py

@@ -5,6 +5,13 @@ import asyncio
 from agent_framework import ChatMessage, TextContent, UriContent
 from agent_framework.openai import OpenAIResponsesClient
 
+"""
+OpenAI Responses Client Image Analysis Example
+
+This sample demonstrates using OpenAI Responses Client for image analysis and vision tasks,
+showing multi-modal content handling with text and images.
+"""
+
 
 async def main():
     print("=== OpenAI Responses Agent with Image Analysis ===")

python/samples/getting_started/agents/openai/openai_responses_client_image_generation.py

@@ -6,6 +6,15 @@ import base64
 from agent_framework import DataContent, UriContent
 from agent_framework.openai import OpenAIResponsesClient
 
+"""
+OpenAI Responses Client Image Generation Example
+
+This sample demonstrates how to generate images using OpenAI's DALL-E models
+through the Responses Client. Image generation capabilities enable AI to create visual content from text,
+making it ideal for creative applications, content creation, design prototyping,
+and automated visual asset generation.
+"""
+
 
 def show_image_info(data_uri: str) -> None:
     """Display information about the generated image."""

python/samples/getting_started/agents/openai/openai_responses_client_reasoning.py

@@ -5,6 +5,13 @@ import asyncio
 from agent_framework import HostedCodeInterpreterTool, TextContent, TextReasoningContent, UsageContent
 from agent_framework.openai import OpenAIResponsesClient
 
+"""
+OpenAI Responses Client Reasoning Example
+
+This sample demonstrates advanced reasoning capabilities using OpenAI's o1 models,
+showing step-by-step reasoning process visualization and complex problem-solving.
+"""
+
 
 async def reasoning_example() -> None:
     """Example of reasoning response (get results as they are generated)."""

python/samples/getting_started/agents/openai/openai_responses_client_with_code_interpreter.py

@@ -7,6 +7,13 @@ from agent_framework.openai import OpenAIResponsesClient
 from openai.types.responses.response import Response as OpenAIResponse
 from openai.types.responses.response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall
 
+"""
+OpenAI Responses Client with Code Interpreter Example
+
+This sample demonstrates using HostedCodeInterpreterTool with OpenAI Responses Client
+for Python code execution and mathematical problem solving.
+"""
+
 
 async def main() -> None:
     """Example showing how to use the HostedCodeInterpreterTool with OpenAI Responses."""

python/samples/getting_started/agents/openai/openai_responses_client_with_explicit_settings.py

@@ -8,6 +8,13 @@ from typing import Annotated
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
 
+"""
+OpenAI Responses Client with Explicit Settings Example
+
+This sample demonstrates creating OpenAI Responses Client with explicit configuration
+settings rather than relying on environment variable defaults.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_responses_client_with_file_search.py

@@ -5,6 +5,13 @@ import asyncio
 from agent_framework import HostedFileSearchTool, HostedVectorStoreContent
 from agent_framework.openai import OpenAIResponsesClient
 
+"""
+OpenAI Responses Client with File Search Example
+
+This sample demonstrates using HostedFileSearchTool with OpenAI Responses Client
+for direct document-based question answering and information retrieval.
+"""
+
 # Helper functions
 
 

python/samples/getting_started/agents/openai/openai_responses_client_with_function_tools.py

@@ -9,6 +9,13 @@ from agent_framework import ChatAgent
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
 
+"""
+OpenAI Responses Client with Function Tools Example
+
+This sample demonstrates function tool integration with OpenAI Responses Client,
+showing both agent-level and query-level tool configuration patterns.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_responses_client_with_hosted_mcp.py

@@ -6,6 +6,13 @@ from typing import TYPE_CHECKING, Any
 from agent_framework import ChatAgent, HostedMCPTool
 from agent_framework.openai import OpenAIResponsesClient
 
+"""
+OpenAI Responses Client with Hosted MCP Example
+
+This sample demonstrates integrating hosted Model Context Protocol (MCP) tools with
+OpenAI Responses Client, including user approval workflows for function call security.
+"""
+
 if TYPE_CHECKING:
     from agent_framework import AgentProtocol, AgentThread
 

python/samples/getting_started/agents/openai/openai_responses_client_with_local_mcp.py

@@ -5,6 +5,13 @@ import asyncio
 from agent_framework import ChatAgent, MCPStreamableHTTPTool
 from agent_framework.openai import OpenAIResponsesClient
 
+"""
+OpenAI Responses Client with Local MCP Example
+
+This sample demonstrates integrating local Model Context Protocol (MCP) tools with
+OpenAI Responses Client for direct response generation with external capabilities.
+"""
+
 
 async def streaming_with_mcp(show_raw_stream: bool = False) -> None:
     """Example showing tools defined when creating the agent.

python/samples/getting_started/agents/openai/openai_responses_client_with_structured_output.py

@@ -6,6 +6,13 @@ from agent_framework import AgentRunResponse
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import BaseModel
 
+"""
+OpenAI Responses Client with Structured Output Example
+
+This sample demonstrates using structured output capabilities with OpenAI Responses Client,
+showing Pydantic model integration for type-safe response parsing and data extraction.
+"""
+
 
 class OutputStruct(BaseModel):
     """A structured output for testing purposes."""

python/samples/getting_started/agents/openai/openai_responses_client_with_thread.py

@@ -8,6 +8,13 @@ from agent_framework import AgentThread, ChatAgent
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
 
+"""
+OpenAI Responses Client with Thread Management Example
+
+This sample demonstrates thread management with OpenAI Responses Client, showing
+persistent conversation context and simplified response handling.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/agents/openai/openai_responses_client_with_web_search.py

@@ -5,6 +5,13 @@ import asyncio
 from agent_framework import HostedWebSearchTool
 from agent_framework.openai import OpenAIResponsesClient
 
+"""
+OpenAI Responses Client with Web Search Example
+
+This sample demonstrates using HostedWebSearchTool with OpenAI Responses Client
+for direct real-time information retrieval and current data access.
+"""
+
 
 async def main() -> None:
     client = OpenAIResponsesClient()

python/samples/getting_started/chat_client/azure_ai_chat_client.py

@@ -8,6 +8,13 @@ from agent_framework.azure import AzureAIAgentClient
 from azure.identity.aio import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure AI Chat Client Direct Usage Example
+
+Demonstrates direct AzureAIChatClient usage for chat interactions with Azure AI models.
+Shows function calling capabilities with custom business logic.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/chat_client/azure_assistants_client.py

@@ -8,6 +8,13 @@ from agent_framework.azure import AzureOpenAIAssistantsClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure Assistants Client Direct Usage Example
+
+Demonstrates direct AzureAssistantsClient usage for chat interactions with Azure OpenAI assistants.
+Shows function calling capabilities and automatic assistant creation.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/chat_client/azure_chat_client.py

@@ -8,6 +8,13 @@ from agent_framework.azure import AzureOpenAIChatClient
 from azure.identity import AzureCliCredential
 from pydantic import Field
 
+"""
+Azure Chat Client Direct Usage Example
+
+Demonstrates direct AzureChatClient usage for chat interactions with Azure OpenAI models.
+Shows function calling capabilities with custom business logic.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/chat_client/azure_responses_client.py

@@ -9,6 +9,13 @@ from agent_framework.azure import AzureOpenAIResponsesClient
 from azure.identity import AzureCliCredential
 from pydantic import BaseModel, Field
 
+"""
+Azure Responses Client Direct Usage Example
+
+Demonstrates direct AzureResponsesClient usage for structured response generation with Azure OpenAI models.
+Shows function calling capabilities with custom business logic.
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/chat_client/chat_response_cancellation.py

@@ -4,6 +4,13 @@ import asyncio
 
 from agent_framework.openai import OpenAIChatClient
 
+"""
+Chat Response Cancellation Example
+
+Demonstrates proper cancellation of streaming chat responses during execution.
+Shows asyncio task cancellation and resource cleanup techniques.
+"""
+
 
 async def main() -> None:
     """

python/samples/getting_started/chat_client/openai_assistants_client.py

@@ -7,6 +7,14 @@ from typing import Annotated
 from agent_framework.openai import OpenAIAssistantsClient
 from pydantic import Field
 
+"""
+OpenAI Assistants Client Direct Usage Example
+
+Demonstrates direct OpenAIAssistantsClient usage for chat interactions with OpenAI assistants.
+Shows function calling capabilities and automatic assistant creation.
+
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/chat_client/openai_chat_client.py

@@ -7,6 +7,14 @@ from typing import Annotated
 from agent_framework.openai import OpenAIChatClient
 from pydantic import Field
 
+"""
+OpenAI Chat Client Direct Usage Example
+
+Demonstrates direct OpenAIChatClient usage for chat interactions with OpenAI models.
+Shows function calling capabilities with custom business logic.
+
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],

python/samples/getting_started/chat_client/openai_responses_client.py

@@ -7,6 +7,14 @@ from typing import Annotated
 from agent_framework.openai import OpenAIResponsesClient
 from pydantic import Field
 
+"""
+OpenAI Responses Client Direct Usage Example
+
+Demonstrates direct OpenAIResponsesClient usage for structured response generation with OpenAI models.
+Shows function calling capabilities with custom business logic.
+
+"""
+
 
 def get_weather(
     location: Annotated[str, Field(description="The location to get the weather for.")],