Agents + Chat Client Samples Doctsring Updates (#1028)

* agents + chat client samples doctsring updates

* fixes

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()