OpenAI Agents

Microsoft Agent Framework supports two OpenAI client types — Responses and Chat Completion — in both C# and Python. Responses is the recommended primary client: it targets the newer OpenAI Responses API and supports the full set of hosted tools (code interpreter, file search, web search, hosted MCP, image generation). Use Chat Completion when you need broad model compatibility or have an existing Chat Completions integration to keep.

Client Type	API	Best For
Responses (recommended)	Responses API	Full-featured agents with hosted tools (code interpreter, file search, web search, hosted MCP)
Chat Completion	Chat Completions API	Simple agents, broad model support

Note

The OpenAI Assistants API is deprecated by OpenAI. New code should use the Responses client. If you are migrating from an existing Assistants-based app, see the Semantic Kernel migration guide.

Getting Started

Add the required NuGet packages to your project.

dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

Responses Client

The Responses client is the recommended primary client and provides the richest tool support including code interpreter, file search, web search, and hosted MCP.

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var responsesClient = client.GetResponseClient("gpt-4o-mini");

AIAgent agent = responsesClient.AsAIAgent(
    instructions: "You are a helpful coding assistant.",
    name: "CodeHelper");

Console.WriteLine(await agent.RunAsync("Write a Python function to sort a list."));

Supported tools: Function tools, tool approval, code interpreter, file search, web search, hosted MCP, local MCP tools.

Chat Completion Client

The Chat Completion client provides a straightforward way to create agents using the Chat Completions API. Use it when you need broad model compatibility or have an existing Chat Completions integration.

using Microsoft.Agents.AI;
using OpenAI;

OpenAIClient client = new OpenAIClient("<your_api_key>");
var chatClient = client.GetChatClient("gpt-4o-mini");

AIAgent agent = chatClient.AsAIAgent(
    instructions: "You are good at telling jokes.",
    name: "Joker");

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Supported tools: Function tools, web search, local MCP tools.

Assistants Client

Note

The OpenAI Assistants API is deprecated by OpenAI. The Agent Framework no longer documents an Assistants client — use the Responses client above for new code. For migrating an existing app, see the Semantic Kernel migration guide.

Using the Agent

Both client types produce a standard AIAgent that supports the same agent operations (streaming, threads, middleware).

For more information, see the Get Started tutorials.

Tools

The OpenAI .NET clients expose different tool surfaces depending on which API they target. The same matrix applies to the matching Azure OpenAI clients on the Azure OpenAI provider page.

Tool	Responses	Chat Completion
Function Tools	✅	✅
Tool Approval	✅	✅
Code Interpreter	✅	❌
File Search	✅	❌
Web Search	✅	✅
Hosted MCP Tools	✅	❌
Local MCP Tools	✅	✅

Note

Tool Approval is provided by the framework's function-invoking chat client, so it works with any function-tool call regardless of the underlying API.

Note

The OpenAI Assistants API is deprecated by OpenAI, and Python no longer ships an Assistants compatibility client/provider. Use OpenAIChatClient for Responses or OpenAIChatCompletionClient for Chat Completions. If you are migrating from a previous Agent Framework Python release, see the Python significant changes guide. If you are migrating from Semantic Kernel, see the Semantic Kernel migration guide.

Tip

In Python, Azure OpenAI now uses the same agent_framework.openai clients shown here. Pass explicit Azure routing inputs such as credential or azure_endpoint when you want Azure routing, then set api_version for the Azure API surface you want to use. If OPENAI_API_KEY is configured, the generic clients stay on OpenAI even when AZURE_OPENAI_* variables are also present. If you already have a full .../openai/v1 URL, use base_url instead of azure_endpoint. For Microsoft Foundry project endpoints and the Foundry Agent Service, see the Microsoft Foundry provider page. For local runtimes, see Foundry Local.

Installation

pip install agent-framework-openai

agent-framework-openai is the optional Python provider package for both direct OpenAI and Azure OpenAI usage.

Configuration

The Python OpenAI chat clients use these environment-variable patterns:

Responses

OPENAI_API_KEY="your-openai-api-key"
OPENAI_CHAT_MODEL="gpt-4o-mini"
# Optional shared fallback:
# OPENAI_MODEL="gpt-4o-mini"

Chat Completion

OPENAI_API_KEY="your-openai-api-key"
OPENAI_CHAT_COMPLETION_MODEL="gpt-4o-mini"
# Optional shared fallback:
# OPENAI_MODEL="gpt-4o-mini"

Azure OpenAI with the same clients

Azure OpenAI now uses the same Python OpenAI clients as direct OpenAI. The preferred and clearest Azure pattern is to pass explicit Azure routing inputs such as credential or azure_endpoint, then set api_version for Azure once routing is selected. If OPENAI_API_KEY is set, the generic clients stay on OpenAI unless you pass those Azure routing inputs. If you only have AZURE_OPENAI_* settings, Azure environment fallback still works. OpenAIChatClient prefers AZURE_OPENAI_CHAT_MODEL, OpenAIChatCompletionClient prefers AZURE_OPENAI_CHAT_COMPLETION_MODEL, and both fall back to AZURE_OPENAI_MODEL.

AZURE_OPENAI_ENDPOINT="https://<resource>.openai.azure.com"
AZURE_OPENAI_CHAT_MODEL="gpt-4o-mini"
# Optional shared fallback:
# AZURE_OPENAI_MODEL="gpt-4o-mini"
AZURE_OPENAI_API_VERSION="your-api-version"

import asyncio
import os
from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential

async def main():
    agent = OpenAIChatClient(
        model=os.environ["AZURE_OPENAI_CHAT_MODEL"],
        azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
        api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
        credential=AzureCliCredential(),
    ).as_agent(
        name="AzureOpenAIResponsesAgent",
        instructions="You are a helpful assistant.",
    )

    result = await agent.run("Hello!")
    print(result)

asyncio.run(main())

If you already have a full Azure OpenAI URL that ends with /openai/v1, pass it as base_url instead of azure_endpoint. Keep api_version aligned to the Azure OpenAI API surface you are using. If OPENAI_API_KEY is also set in your environment, these explicit Azure inputs keep the client on Azure.

Note

Use OpenAIChatClient for the Responses API. For Azure key auth, you can still pass api_key, but credential= is now the preferred Azure auth surface.

Azure embeddings with the same client family

OpenAIEmbeddingClient follows the same routing rules as the chat clients. For Azure embeddings, pass the embedding deployment as model and prefer explicit Azure inputs:

import os
from agent_framework.openai import OpenAIEmbeddingClient
from azure.identity import AzureCliCredential

client = OpenAIEmbeddingClient(
    model=os.environ["AZURE_OPENAI_EMBEDDING_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

Create OpenAI Agents

Responses

OpenAIChatClient uses the Responses API — the recommended primary client with hosted tool support.

import asyncio
from agent_framework.openai import OpenAIChatClient

async def main():
    agent = OpenAIChatClient().as_agent(
        name="FullFeaturedAgent",
        instructions="You are a helpful assistant with access to many tools.",
    )
    result = await agent.run("Write and run a Python script that calculates fibonacci numbers.")
    print(result)

asyncio.run(main())

Supported tools: Function tools, tool approval, code interpreter, file search, web search, hosted MCP, local MCP tools.

Hosted Tools with Responses Client

The Responses client provides get_*_tool() methods for each hosted tool type:

async def hosted_tools_example():
    client = OpenAIChatClient()

    # Each tool is created via a client method
    code_interpreter = client.get_code_interpreter_tool()
    web_search = client.get_web_search_tool()
    file_search = client.get_file_search_tool(vector_store_ids=["vs_abc123"])
    mcp_tool = client.get_mcp_tool(
        name="GitHub",
        url="https://api.githubcopilot.com/mcp/",
        approval_mode="never_require",
    )

    agent = client.as_agent(
        name="PowerAgent",
        instructions="You have access to code execution, web search, files, and GitHub.",
        tools=[code_interpreter, web_search, file_search, mcp_tool],
    )
    result = await agent.run("Search the web for Python best practices, then write a summary.")
    print(result)

Chat Completion

OpenAIChatCompletionClient uses the Chat Completions API — use it when you need broad model compatibility or have an existing Chat Completions integration.

import asyncio
from agent_framework.openai import OpenAIChatCompletionClient

async def main():
    agent = OpenAIChatCompletionClient().as_agent(
        name="HelpfulAssistant",
        instructions="You are a helpful assistant.",
    )
    result = await agent.run("Hello, how can you help me?")
    print(result)

asyncio.run(main())

Supported tools: Function tools, web search, local MCP tools.

Web Search with Chat Completion

async def web_search_example():
    client = OpenAIChatCompletionClient()
    web_search = client.get_web_search_tool()

    agent = client.as_agent(
        name="SearchBot",
        instructions="You can search the web for current information.",
        tools=web_search,
    )
    result = await agent.run("What are the latest developments in AI?")
    print(result)

Important

Python no longer ships an Assistants compatibility client/provider. For current Python code, use OpenAIChatClient for Responses API scenarios or OpenAIChatCompletionClient for Chat Completions. If you need a service-managed agent in Microsoft Foundry, see the Microsoft Foundry provider page.

Common Features

These client types support these standard agent features:

Function Tools

from agent_framework import tool

@tool
def get_weather(location: str) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny, 25°C."

async def example():
    agent = OpenAIChatClient().as_agent(
        instructions="You are a weather assistant.",
        tools=get_weather,
    )
    result = await agent.run("What's the weather in Tokyo?")
    print(result)

Multi-Turn Conversations

async def thread_example():
    agent = OpenAIChatClient().as_agent(
        instructions="You are a helpful assistant.",
    )
    session = await agent.create_session()

    result1 = await agent.run("My name is Alice", session=session)
    print(result1)
    result2 = await agent.run("What's my name?", session=session)
    print(result2)  # Remembers "Alice"

Streaming

async def streaming_example():
    agent = OpenAIChatClient().as_agent(
        instructions="You are a creative storyteller.",
    )
    print("Agent: ", end="", flush=True)
    async for chunk in agent.run("Tell me a short story about AI.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Using the Agent

All client types produce a standard Agent that supports the same operations.

For more information, see the Get Started tutorials.

Tools

The Python OpenAI clients expose different tool surfaces depending on the underlying API. OpenAIChatClient (Responses) ships hosted tool factories via client.get_*_tool(...) — get_code_interpreter_tool, get_file_search_tool, get_web_search_tool, get_image_generation_tool, get_shell_tool, and get_mcp_tool. OpenAIChatCompletionClient only exposes get_web_search_tool. Both work with function tools and local MCP servers.

The same matrix applies when you point these clients at Azure OpenAI — see Azure OpenAI.

Tool	OpenAIChatClient (Responses)	OpenAIChatCompletionClient (Chat Completion)
Function Tools	✅	✅
Tool Approval	✅	✅
Code Interpreter	✅	❌
File Search	✅	❌
Web Search	✅	✅
Image Generation	✅ (get_image_generation_tool)	❌
Hosted Shell	✅ (get_shell_tool)	❌
Hosted MCP Tools	✅	❌
Local MCP Tools	✅	✅

Note

Tool Approval is handled by the framework's function-invoking chat client, so it works with any function-tool call regardless of the underlying API.

Next steps

Microsoft Foundry