agent/agent-framework
2
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Python: [BREAKING] Replace Hosted*Tool classes with tool methods (#3634)

Browse Source 
* Replace Hosted*Tool classes with client static factory methods

* fixed failing test

* mypy fix

* mypy fix 2

* declarative mypy fix

* addressed comments

* ToolProtocol removal

* fixed test

* agents mypy fix

* fix failing tests

* mypy fix

* addressed comments

* fixed tests

* addressed comments + added factory method overrides for azureai v2 client

* mypy fix

* added kwargs to azureai tool methods

* fixed in test

* _sessions fix

* test fix
This commit is contained in:
Giles Odigwe
2026-02-10 16:04:27 -08:00
committed by GitHub
Unverified
parent d249473a6d
commit 7a88af0aef
133 changed files with 3018 additions and 2650 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/samples/getting_started/agents/openai/README.md
+10 -9
View File
@@ -1,6 +1,6 @@
# 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.
This folder contains examples demonstrating different ways to create and use agents with the OpenAI clients from the `agent_framework.openai` package.
## Examples
@@ -8,10 +8,10 @@ This folder contains examples demonstrating different ways to create and use age
|------|-------------|
| [`openai_assistants_basic.py`](openai_assistants_basic.py) | Basic usage of `OpenAIAssistantProvider` with streaming and non-streaming responses. |
| [`openai_assistants_provider_methods.py`](openai_assistants_provider_methods.py) | Demonstrates all `OpenAIAssistantProvider` methods: `create_agent()`, `get_agent()`, and `as_agent()`. |
| [`openai_assistants_with_code_interpreter.py`](openai_assistants_with_code_interpreter.py) | Using `HostedCodeInterpreterTool` with `OpenAIAssistantProvider` to execute Python code. |
| [`openai_assistants_with_code_interpreter.py`](openai_assistants_with_code_interpreter.py) | Using `OpenAIAssistantsClient.get_code_interpreter_tool()` with `OpenAIAssistantProvider` to execute Python code. |
| [`openai_assistants_with_existing_assistant.py`](openai_assistants_with_existing_assistant.py) | Working with pre-existing assistants using `get_agent()` and `as_agent()` methods. |
| [`openai_assistants_with_explicit_settings.py`](openai_assistants_with_explicit_settings.py) | Configuring `OpenAIAssistantProvider` with explicit settings including API key and model ID. |
| [`openai_assistants_with_file_search.py`](openai_assistants_with_file_search.py) | Using `HostedFileSearchTool` with `OpenAIAssistantProvider` for file search capabilities. |
| [`openai_assistants_with_file_search.py`](openai_assistants_with_file_search.py) | Using `OpenAIAssistantsClient.get_file_search_tool()` with `OpenAIAssistantProvider` for file search capabilities. |
| [`openai_assistants_with_function_tools.py`](openai_assistants_with_function_tools.py) | Function tools with `OpenAIAssistantProvider` at both agent-level and query-level. |
| [`openai_assistants_with_response_format.py`](openai_assistants_with_response_format.py) | Structured outputs with `OpenAIAssistantProvider` using Pydantic models. |
| [`openai_assistants_with_thread.py`](openai_assistants_with_thread.py) | Thread management with `OpenAIAssistantProvider` for conversation context persistence. |
@@ -20,24 +20,25 @@ This folder contains examples demonstrating different ways to create and use age
| [`openai_chat_client_with_function_tools.py`](openai_chat_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_chat_client_with_local_mcp.py`](openai_chat_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_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_chat_client_with_web_search.py`](openai_chat_client_with_web_search.py) | Shows how to use `OpenAIChatClient.get_web_search_tool()` for web search capabilities with OpenAI agents. |
| [`openai_chat_client_with_runtime_json_schema.py`](openai_chat_client_with_runtime_json_schema.py) | Shows how to supply a runtime JSON Schema via `additional_chat_options` for structured output without defining a Pydantic model. |
| [`openai_responses_client_basic.py`](openai_responses_client_basic.py) | The simplest way to create an agent using `Agent` with `OpenAIResponsesClient`. Shows both streaming and non-streaming responses for structured response generation with OpenAI models. |
| [`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) | Demonstrates how to use image generation capabilities with OpenAI agents to create images based on text descriptions. Requires PIL (Pillow) for image display. |
| [`openai_responses_client_image_generation.py`](openai_responses_client_image_generation.py) | Demonstrates how to use `OpenAIResponsesClient.get_image_generation_tool()` to create images based on text descriptions. |
| [`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_streaming_image_generation.py`](openai_responses_client_streaming_image_generation.py) | Demonstrates streaming image generation with partial images for real-time image creation feedback and improved user experience. |
| [`openai_responses_client_with_agent_as_tool.py`](openai_responses_client_with_agent_as_tool.py) | Shows how to use the agent-as-tool pattern with OpenAI Responses Client, where one agent delegates work to specialized sub-agents wrapped as tools using `as_tool()`. Demonstrates hierarchical agent architectures. |
| [`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_code_interpreter.py`](openai_responses_client_with_code_interpreter.py) | Shows how to use `OpenAIResponsesClient.get_code_interpreter_tool()` to write and execute Python code. |
| [`openai_responses_client_with_code_interpreter_files.py`](openai_responses_client_with_code_interpreter_files.py) | Shows how to use code interpreter with uploaded files for data analysis. |
| [`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_file_search.py`](openai_responses_client_with_file_search.py) | Demonstrates how to use `OpenAIResponsesClient.get_file_search_tool()` for searching through uploaded files. |
| [`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_hosted_mcp.py`](openai_responses_client_with_hosted_mcp.py) | Shows how to use `OpenAIResponsesClient.get_mcp_tool()` for hosted MCP servers, including approval workflows. |
| [`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_runtime_json_schema.py`](openai_responses_client_with_runtime_json_schema.py) | Shows how to supply a runtime JSON Schema via `additional_chat_options` for structured output without defining a Pydantic model. |
| [`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. |
| [`openai_responses_client_with_web_search.py`](openai_responses_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_with_web_search.py`](openai_responses_client_with_web_search.py) | Shows how to use `OpenAIResponsesClient.get_web_search_tool()` for web search capabilities. |
## Environment Variables
python/samples/getting_started/agents/openai/openai_assistants_basic.py
+3 -1
View File
@@ -18,7 +18,9 @@ assistant lifecycle management, showing both streaming and non-streaming respons
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
location: Annotated[str, Field(description="The location to get the weather for.")],
python/samples/getting_started/agents/openai/openai_assistants_provider_methods.py
+3 -1
View File
@@ -20,7 +20,9 @@ This sample demonstrates the methods available on the OpenAIAssistantProvider cl
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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
+6 -5
View File
@@ -3,8 +3,8 @@
import asyncio
import os
from agent_framework import AgentResponseUpdate, ChatResponseUpdate, HostedCodeInterpreterTool
from agent_framework.openai import OpenAIAssistantProvider
from agent_framework import AgentResponseUpdate, ChatResponseUpdate
from agent_framework.openai import OpenAIAssistantProvider, OpenAIAssistantsClient
from openai import AsyncOpenAI
from openai.types.beta.threads.runs import (
CodeInterpreterToolCallDelta,
@@ -17,7 +17,7 @@ from openai.types.beta.threads.runs.code_interpreter_tool_call_delta import Code
"""
OpenAI Assistants with Code Interpreter Example
This sample demonstrates using HostedCodeInterpreterTool with OpenAI Assistants
This sample demonstrates using get_code_interpreter_tool() with OpenAI Assistants
for Python code execution and mathematical problem solving.
"""
@@ -42,17 +42,18 @@ def get_code_interpreter_chunk(chunk: AgentResponseUpdate) -> str | None:
async def main() -> None:
"""Example showing how to use the HostedCodeInterpreterTool with OpenAI Assistants."""
"""Example showing how to use the code interpreter tool with OpenAI Assistants."""
print("=== OpenAI Assistants Provider with Code Interpreter Example ===")
client = AsyncOpenAI()
provider = OpenAIAssistantProvider(client)
chat_client = OpenAIAssistantsClient(client=client)
agent = await provider.create_agent(
name="CodeHelper",
model=os.environ.get("OPENAI_CHAT_MODEL_ID", "gpt-4"),
instructions="You are a helpful assistant that can write and execute Python code to solve problems.",
tools=[HostedCodeInterpreterTool()],
tools=[chat_client.get_code_interpreter_tool()],
)
try:
python/samples/getting_started/agents/openai/openai_assistants_with_explicit_settings.py
+6 -2
View File
@@ -18,7 +18,9 @@ settings rather than relying on environment variable defaults.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -43,7 +45,9 @@ async def main() -> None:
)
try:
result = await agent.run("What's the weather like in New York?")
query = "What's the weather like in New York?"
print(f"Query: {query}")
result = await agent.run(query)
print(f"Result: {result}\n")
finally:
await client.beta.assistants.delete(agent.id)
python/samples/getting_started/agents/openai/openai_assistants_with_file_search.py
+8 -7
View File
@@ -3,14 +3,14 @@
import asyncio
import os
from agent_framework import Content, HostedFileSearchTool
from agent_framework.openai import OpenAIAssistantProvider
from agent_framework import Content
from agent_framework.openai import OpenAIAssistantProvider, OpenAIAssistantsClient
from openai import AsyncOpenAI
"""
OpenAI Assistants with File Search Example
This sample demonstrates using HostedFileSearchTool with OpenAI Assistants
This sample demonstrates using get_file_search_tool() with OpenAI Assistants
for document-based question answering and information retrieval.
"""
@@ -42,29 +42,30 @@ async def main() -> None:
client = AsyncOpenAI()
provider = OpenAIAssistantProvider(client)
chat_client = OpenAIAssistantsClient(client=client)
agent = await provider.create_agent(
name="SearchAssistant",
model=os.environ.get("OPENAI_CHAT_MODEL_ID", "gpt-4"),
instructions="You are a helpful assistant that searches files in a knowledge base.",
tools=[HostedFileSearchTool()],
tools=[chat_client.get_file_search_tool()],
)
try:
query = "What is the weather today? Do a file search to find the answer."
file_id, vector_store = await create_vector_store(client)
file_id, vector_store_content = await create_vector_store(client)
print(f"User: {query}")
print("Agent: ", end="", flush=True)
async for chunk in agent.run(
query,
stream=True,
options={"tool_resources": {"file_search": {"vector_store_ids": [vector_store.vector_store_id]}}},
options={"tool_resources": {"file_search": {"vector_store_ids": [vector_store_content.vector_store_id]}}},
):
if chunk.text:
print(chunk.text, end="", flush=True)
await delete_vector_store(client, file_id, vector_store.vector_store_id)
await delete_vector_store(client, file_id, vector_store_content.vector_store_id)
finally:
await client.beta.assistants.delete(agent.id)
python/samples/getting_started/agents/openai/openai_assistants_with_thread.py
+3 -1
View File
@@ -18,7 +18,9 @@ persistent conversation threads and context preservation across interactions.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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
+3 -1
View File
@@ -15,7 +15,9 @@ interactions, showing both streaming and non-streaming responses.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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
+3 -1
View File
@@ -17,7 +17,9 @@ settings rather than relying on environment variable defaults.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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
+3 -1
View File
@@ -17,7 +17,9 @@ showing both agent-level and query-level tool configuration patterns.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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_thread.py
+3 -1
View File
@@ -16,7 +16,9 @@ conversation threads and message history preservation across interactions.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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
+10 -11
View File
@@ -2,30 +2,29 @@
import asyncio
from agent_framework import Agent, HostedWebSearchTool
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
"""
OpenAI Chat Client with Web Search Example
This sample demonstrates using HostedWebSearchTool with OpenAI Chat Client
This sample demonstrates using get_web_search_tool() with OpenAI Chat Client
for real-time information retrieval and current data access.
"""
async def main() -> None:
# Test that the agent will use the web search tool with location
additional_properties = {
"user_location": {
"country": "US",
"city": "Seattle",
}
}
client = OpenAIChatClient(model_id="gpt-4o-search-preview")
# Create web search tool with location context
web_search_tool = client.get_web_search_tool(
user_location={"city": "Seattle", "country": "US"},
)
agent = Agent(
client=OpenAIChatClient(model_id="gpt-4o-search-preview"),
client=client,
instructions="You are a helpful assistant that can search the web for current information.",
tools=[HostedWebSearchTool(additional_properties=additional_properties)],
tools=[web_search_tool],
)
message = "What is the current weather? Do not ask for my current location."
python/samples/getting_started/agents/openai/openai_responses_client_basic.py
+4 -2
View File
@@ -66,7 +66,9 @@ async def security_and_override_middleware(
print(type(context.result))
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
def get_weather(
location: Annotated[str, Field(description="The location to get the weather for.")],
@@ -101,7 +103,7 @@ async def streaming_example() -> None:
middleware=[security_and_override_middleware],
),
instructions="You are a helpful weather agent.",
# tools=get_weather,
tools=get_weather,
)
query = "What's the weather like in Portland?"
python/samples/getting_started/agents/openai/openai_responses_client_image_analysis.py
+1 -1
View File
@@ -28,7 +28,7 @@ async def main():
contents=[
Content.from_text(text="What do you see in this image?"),
Content.from_uri(
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",
uri="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800",
media_type="image/jpeg",
),
],
python/samples/getting_started/agents/openai/openai_responses_client_image_generation.py
+57 -38
View File
@@ -2,8 +2,12 @@
import asyncio
import base64
import tempfile
import urllib.request as urllib_request
from pathlib import Path
from agent_framework import HostedImageGenerationTool
import aiofiles # pyright: ignore[reportMissingModuleSource]
from agent_framework import Content
from agent_framework.openai import OpenAIResponsesClient
"""
@@ -16,65 +20,80 @@ and automated visual asset generation.
"""
def show_image_info(data_uri: str) -> None:
"""Display information about the generated image."""
try:
# Extract format and size info from data URI
if data_uri.startswith("data:image/"):
format_info = data_uri.split(";")[0].split("/")[1]
base64_data = data_uri.split(",", 1)[1]
image_bytes = base64.b64decode(base64_data)
size_kb = len(image_bytes) / 1024
async def save_image(output: Content) -> None:
"""Save the generated image to a temporary directory."""
filename = "generated_image.webp"
file_path = Path(tempfile.gettempdir()) / filename
print(" Image successfully generated!")
print(f" Format: {format_info.upper()}")
print(f" Size: {size_kb:.1f} KB")
print(f" Data URI length: {len(data_uri)} characters")
print("")
print(" To save and view the image:")
print(' 1. Install Pillow: "pip install pillow" or "uv add pillow"')
print(" 2. Use the data URI in your code to save/display the image")
print(" 3. Or copy the base64 data to an online base64 image decoder")
data_bytes: bytes | None = None
uri = getattr(output, "uri", None)
if isinstance(uri, str):
if ";base64," in uri:
try:
b64 = uri.split(";base64,", 1)[1]
data_bytes = base64.b64decode(b64)
except Exception:
data_bytes = None
else:
print(f" Image URL generated: {data_uri}")
print(" You can open this URL in a browser to view the image")
try:
data_bytes = await asyncio.to_thread(lambda: urllib_request.urlopen(uri).read())
except Exception:
data_bytes = None
except Exception as e:
print(f" Error processing image data: {e}")
print(" Image generated but couldn't parse details")
if data_bytes is None:
raise RuntimeError("Image output present but could not retrieve bytes.")
async with aiofiles.open(file_path, "wb") as f:
await f.write(data_bytes)
print(f"Image downloaded and saved to: {file_path}")
async def main() -> None:
print("=== OpenAI Responses Image Generation Agent Example ===")
# Create an agent with customized image generation options
agent = OpenAIResponsesClient().as_agent(
client = OpenAIResponsesClient()
agent = client.as_agent(
instructions="You are a helpful AI that can generate images.",
tools=[
HostedImageGenerationTool(
options={
"size": "1024x1024",
"output_format": "webp",
}
client.get_image_generation_tool(
size="1024x1024",
output_format="webp",
)
],
)
query = "Generate a nice beach scenery with blue skies in summer time."
query = "Generate a black furry cat."
print(f"User: {query}")
print("Generating image with parameters: 1024x1024 size, transparent background, low quality, WebP format...")
print("Generating image with parameters: 1024x1024 size, WebP format...")
result = await agent.run(query)
print(f"Agent: {result.text}")
# Show information about the generated image
# Find and save the generated image
image_saved = False
for message in result.messages:
for content in message.contents:
if content.type == "image_generation_tool_result" and content.outputs:
for output in content.outputs:
if output.type in ("data", "uri") and output.uri:
show_image_info(output.uri)
break
if content.type == "image_generation_tool_result_tool_result" and content.outputs:
output = content.outputs
if isinstance(output, Content) and output.uri:
await save_image(output)
image_saved = True
elif isinstance(output, list):
for out in output:
if isinstance(out, Content) and out.uri:
await save_image(out)
image_saved = True
break
if image_saved:
break
if image_saved:
break
if not image_saved:
print("No image data found in the agent response.")
if __name__ == "__main__":
python/samples/getting_started/agents/openai/openai_responses_client_streaming_image_generation.py
+17 -13
View File
@@ -2,9 +2,10 @@
import asyncio
import base64
import tempfile
from pathlib import Path
import anyio
from agent_framework import HostedImageGenerationTool
from agent_framework.openai import OpenAIResponsesClient
"""OpenAI Responses Client Streaming Image Generation Example
@@ -42,15 +43,14 @@ async def main():
print("=== OpenAI Streaming Image Generation Example ===\n")
# Create agent with streaming image generation enabled
agent = OpenAIResponsesClient().as_agent(
client = OpenAIResponsesClient()
agent = client.as_agent(
instructions="You are a helpful agent that can generate images.",
tools=[
HostedImageGenerationTool(
options={
"size": "1024x1024",
"quality": "high",
"partial_images": 3,
}
client.get_image_generation_tool(
size="1024x1024",
quality="high",
partial_images=3,
)
],
)
@@ -62,9 +62,9 @@ async def main():
# Track partial images
image_count = 0
# Create output directory
output_dir = anyio.Path("generated_images")
await output_dir.mkdir(exist_ok=True)
# Use temp directory for output
output_dir = Path(tempfile.gettempdir()) / "generated_images"
output_dir.mkdir(exist_ok=True)
print(" Streaming response:")
async for update in agent.run(query, stream=True):
@@ -72,7 +72,11 @@ async def main():
# Handle partial images
# The final partial image IS the complete, full-quality image. Each partial
# represents a progressive refinement, with the last one being the finished result.
if content.type == "data" and content.additional_properties.get("is_partial_image"):
if (
content.type == "uri"
and content.additional_properties
and content.additional_properties.get("is_partial_image")
):
print(f" Image {image_count} received")
# Extract file extension from media_type (e.g., "image/png" -> "png")
@@ -89,7 +93,7 @@ async def main():
# Summary
print("\n Summary:")
print(f" Images received: {image_count}")
print(" Output directory: generated_images")
print(f" Output directory: {output_dir}")
print("\n Streaming image generation completed!")
python/samples/getting_started/agents/openai/openai_responses_client_with_code_interpreter.py
+9 -7
View File
@@ -4,26 +4,27 @@ import asyncio
from agent_framework import (
Agent,
HostedCodeInterpreterTool,
Content,
)
from agent_framework.openai import OpenAIResponsesClient
"""
OpenAI Responses Client with Code Interpreter Example
This sample demonstrates using HostedCodeInterpreterTool with OpenAI Responses Client
This sample demonstrates using get_code_interpreter_tool() 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."""
"""Example showing how to use the code interpreter tool with OpenAI Responses."""
print("=== OpenAI Responses Agent with Code Interpreter Example ===")
client = OpenAIResponsesClient()
agent = Agent(
client=OpenAIResponsesClient(),
client=client,
instructions="You are a helpful assistant that can write and execute Python code to solve problems.",
tools=HostedCodeInterpreterTool(),
tools=client.get_code_interpreter_tool(),
)
query = "Use code to get the factorial of 100?"
@@ -34,16 +35,17 @@ async def main() -> None:
for message in result.messages:
code_blocks = [c for c in message.contents if c.type == "code_interpreter_tool_call"]
outputs = [c for c in message.contents if c.type == "code_interpreter_tool_result"]
if code_blocks:
code_inputs = code_blocks[0].inputs or []
for content in code_inputs:
if content.type == "text":
if isinstance(content, Content) and content.type == "text":
print(f"Generated code:\n{content.text}")
break
if outputs:
print("Execution outputs:")
for out in outputs[0].outputs or []:
if out.type == "text":
if isinstance(out, Content) and out.type == "text":
print(out.text)
python/samples/getting_started/agents/openai/openai_responses_client_with_code_interpreter_files.py
+5 -4
View File
@@ -4,14 +4,14 @@ import asyncio
import os
import tempfile
from agent_framework import Agent, HostedCodeInterpreterTool
from agent_framework import Agent
from agent_framework.openai import OpenAIResponsesClient
from openai import AsyncOpenAI
"""
OpenAI Responses Client with Code Interpreter and Files Example
This sample demonstrates using HostedCodeInterpreterTool with OpenAI Responses Client
This sample demonstrates using get_code_interpreter_tool() with OpenAI Responses Client
for Python code execution and data analysis with uploaded files.
"""
@@ -66,10 +66,11 @@ async def main() -> None:
temp_file_path, file_id = await create_sample_file_and_upload(openai_client)
# Create agent using OpenAI Responses client
client = OpenAIResponsesClient()
agent = Agent(
client=OpenAIResponsesClient(),
client=client,
instructions="You are a helpful assistant that can analyze data files using Python code.",
tools=HostedCodeInterpreterTool(inputs=[{"file_id": file_id}]),
tools=client.get_code_interpreter_tool(file_ids=[file_id]),
)
# Test the code interpreter with the uploaded file
python/samples/getting_started/agents/openai/openai_responses_client_with_explicit_settings.py
+3 -1
View File
@@ -17,7 +17,9 @@ settings rather than relying on environment variable defaults.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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
View File
@@ -2,13 +2,13 @@
import asyncio
from agent_framework import Agent, Content, HostedFileSearchTool
from agent_framework import Agent, Content
from agent_framework.openai import OpenAIResponsesClient
"""
OpenAI Responses Client with File Search Example
This sample demonstrates using HostedFileSearchTool with OpenAI Responses Client
This sample demonstrates using get_file_search_tool() with OpenAI Responses Client
for direct document-based question answering and information retrieval.
"""
@@ -33,7 +33,6 @@ async def create_vector_store(client: OpenAIResponsesClient) -> tuple[str, Conte
async def delete_vector_store(client: OpenAIResponsesClient, file_id: str, vector_store_id: str) -> None:
"""Delete the vector store after using it."""
await client.client.vector_stores.delete(vector_store_id=vector_store_id)
await client.client.files.delete(file_id=file_id)
@@ -45,12 +44,12 @@ async def main() -> None:
stream = False
print(f"User: {message}")
file_id, vector_store = await create_vector_store(client)
file_id, vector_store_id = await create_vector_store(client)
agent = Agent(
client=client,
instructions="You are a helpful assistant that can search through files to find information.",
tools=[HostedFileSearchTool(inputs=vector_store)],
tools=[client.get_file_search_tool(vector_store_ids=[vector_store_id])],
)
if stream:
@@ -62,7 +61,7 @@ async def main() -> None:
else:
response = await agent.run(message)
print(f"Assistant: {response}")
await delete_vector_store(client, file_id, vector_store.vector_store_id)
await delete_vector_store(client, file_id, vector_store_id)
if __name__ == "__main__":
python/samples/getting_started/agents/openai/openai_responses_client_with_function_tools.py
+3 -1
View File
@@ -17,7 +17,9 @@ showing both agent-level and query-level tool configuration patterns.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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
+52 -42
View File
@@ -3,7 +3,7 @@
import asyncio
from typing import TYPE_CHECKING, Any
from agent_framework import Agent, HostedMCPTool
from agent_framework import Agent
from agent_framework.openai import OpenAIResponsesClient
"""
@@ -32,7 +32,10 @@ async def handle_approvals_without_thread(query: str, agent: "SupportsAgentRun")
new_inputs.append(Message(role="assistant", contents=[user_input_needed]))
user_approval = input("Approve function call? (y/n): ")
new_inputs.append(
Message(role="user", contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")])
Message(
role="user",
contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
)
)
result = await agent.run(new_inputs)
@@ -81,7 +84,8 @@ async def handle_approvals_with_thread_streaming(query: str, agent: "SupportsAge
user_approval = input("Approve function call? (y/n): ")
new_input.append(
Message(
role="user", contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")]
role="user",
contents=[user_input_needed.to_function_approval_response(user_approval.lower() == "y")],
)
)
new_input_added = True
@@ -93,19 +97,21 @@ async def run_hosted_mcp_without_thread_and_specific_approval() -> None:
"""Example showing Mcp Tools with approvals without using a thread."""
print("=== Mcp with approvals and without thread ===")
# Tools are provided when creating the agent
# The agent can use these tools for any query during its lifetime
client = OpenAIResponsesClient()
# Create MCP tool with specific approval mode
mcp_tool = client.get_mcp_tool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp",
# we don't require approval for microsoft_docs_search tool calls
# but we do for any other tool
approval_mode={"never_require_approval": ["microsoft_docs_search"]},
)
async with Agent(
client=OpenAIResponsesClient(),
client=client,
name="DocsAgent",
instructions="You are a helpful assistant that can help with microsoft documentation questions.",
tools=HostedMCPTool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp",
# we don't require approval for microsoft_docs_search tool calls
# but we do for any other tool
approval_mode={"never_require_approval": ["microsoft_docs_search"]},
),
tools=mcp_tool,
) as agent:
# First query
query1 = "How to create an Azure storage account using az cli?"
@@ -124,20 +130,20 @@ async def run_hosted_mcp_without_approval() -> None:
"""Example showing Mcp Tools without approvals."""
print("=== Mcp without approvals ===")
# Tools are provided when creating the agent
# The agent can use these tools for any query during its lifetime
client = OpenAIResponsesClient()
# Create MCP tool that never requires approval
mcp_tool = client.get_mcp_tool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp",
# we don't require approval for any function calls
approval_mode="never_require",
)
async with Agent(
client=OpenAIResponsesClient(),
client=client,
name="DocsAgent",
instructions="You are a helpful assistant that can help with microsoft documentation questions.",
tools=HostedMCPTool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp",
# we don't require approval for any function calls
# this means we will not see the approval messages,
# it is fully handled by the service and a final response is returned.
approval_mode="never_require",
),
tools=mcp_tool,
) as agent:
# First query
query1 = "How to create an Azure storage account using az cli?"
@@ -156,18 +162,20 @@ async def run_hosted_mcp_with_thread() -> None:
"""Example showing Mcp Tools with approvals using a thread."""
print("=== Mcp with approvals and with thread ===")
# Tools are provided when creating the agent
# The agent can use these tools for any query during its lifetime
client = OpenAIResponsesClient()
# Create MCP tool that always requires approval
mcp_tool = client.get_mcp_tool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp",
# we require approval for all function calls
approval_mode="always_require",
)
async with Agent(
client=OpenAIResponsesClient(),
client=client,
name="DocsAgent",
instructions="You are a helpful assistant that can help with microsoft documentation questions.",
tools=HostedMCPTool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp",
# we require approval for all function calls
approval_mode="always_require",
),
tools=mcp_tool,
) as agent:
# First query
thread = agent.get_new_thread()
@@ -187,18 +195,20 @@ async def run_hosted_mcp_with_thread_streaming() -> None:
"""Example showing Mcp Tools with approvals using a thread."""
print("=== Mcp with approvals and with thread ===")
# Tools are provided when creating the agent
# The agent can use these tools for any query during its lifetime
client = OpenAIResponsesClient()
# Create MCP tool that always requires approval
mcp_tool = client.get_mcp_tool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp",
# we require approval for all function calls
approval_mode="always_require",
)
async with Agent(
client=OpenAIResponsesClient(),
client=client,
name="DocsAgent",
instructions="You are a helpful assistant that can help with microsoft documentation questions.",
tools=HostedMCPTool(
name="Microsoft Learn MCP",
url="https://learn.microsoft.com/api/mcp",
# we require approval for all function calls
approval_mode="always_require",
),
tools=mcp_tool,
) as agent:
# First query
thread = agent.get_new_thread()
python/samples/getting_started/agents/openai/openai_responses_client_with_thread.py
+3 -1
View File
@@ -16,7 +16,9 @@ persistent conversation context and simplified response handling.
"""
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production; see samples/getting_started/tools/function_tool_with_approval.py and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
# NOTE: approval_mode="never_require" is for sample brevity. Use "always_require" in production;
# see samples/getting_started/tools/function_tool_with_approval.py
# and samples/getting_started/tools/function_tool_with_approval_and_threads.py.
@tool(approval_mode="never_require")
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
+10 -11
View File
@@ -2,30 +2,29 @@
import asyncio
from agent_framework import Agent, HostedWebSearchTool
from agent_framework import Agent
from agent_framework.openai import OpenAIResponsesClient
"""
OpenAI Responses Client with Web Search Example
This sample demonstrates using HostedWebSearchTool with OpenAI Responses Client
This sample demonstrates using get_web_search_tool() with OpenAI Responses Client
for direct real-time information retrieval and current data access.
"""
async def main() -> None:
# Test that the agent will use the web search tool with location
additional_properties = {
"user_location": {
"country": "US",
"city": "Seattle",
}
}
client = OpenAIResponsesClient()
# Create web search tool with location context
web_search_tool = client.get_web_search_tool(
user_location={"city": "Seattle", "country": "US"},
)
agent = Agent(
client=OpenAIResponsesClient(),
client=client,
instructions="You are a helpful assistant that can search the web for current information.",
tools=[HostedWebSearchTool(additional_properties=additional_properties)],
tools=[web_search_tool],
)
message = "What is the current weather? Do not ask for my current location."