TL;DR
Use the Responses client for new projects if you want the newest, richest hosted tools and structured outputs; use the Chat Completion client when you need maximum backward compatibility or are constrained to the Chat-completions API (for example, Go-only paths or older models).
Why this matters
Choosing between a Responses client and a Chat Completion client in Microsoft Agent Framework affects which provider API and hosted tools your agent can use, how easy it is to migrate, and what models/back ends you can target. That can influence development effort, feature availability (hosted code execution, file search, image generation, structured outputs), and runtime portability.
High-level comparison
- Responses client: wraps the newer Responses API (recommended). Exposes a broad hosted-tool surface (hosted code interpreter, hosted file & web search, image generation, hosted model-completion-providers (MCP), structured/typed outputs, and long-running or background/stateful responses). It is best for modern, full-featured agents and Foundry/Azure OpenAI deployments.
- Chat Completion client: wraps the classic Chat Completions API surface. Supports a smaller set of integrations (function-like tools, web search integrations, and local MCPs) and offers broader model/back-end compatibility today. Useful for legacy integrations, older runtimes, or when Go-only support is required.
Agent-level parity
From the Agent Framework developer perspective, both client types can be wrapped into an agent (for example, ChatClientAgent/ChatAgent or AIAgent wrappers). The agent programming model—adding middleware and tools, streaming behavior, sessions, and calling agent.RunAsync—looks the same. The practical differences are primarily the underlying provider API and which tools and structured responses the agent can use.
Feature differences (what you get with Responses vs. Chat Completion)
- Responses client (richer feature set)
- Hosted tools: hosted code execution (Hosted Code Interpreter), hosted file search, hosted web search, hosted MCPs, image generation. This is what we do in the demo program BlogWriter.
- Structured and typed outputs: direct support for structured response formats and schema-like outputs.
- Long-lived or background/stateful responses: support for tasks that can run/continue beyond a single request (callbacks, async background work, persistent contexts).
- Better integration with Foundry/Azure OpenAI advanced features.
- Chat Completion client (compatibility-focused)
- Classic chat-completions features and function-style tools.
- Local MCP integrations and web search via function/tools.
- Broader compatibility with older models and provider runtime implementations.
Compatibility and portability
- Choose Chat Completion client when you must target older models or runtimes that do not yet expose the Responses API, or when you need the broadest cross-provider compatibility. Agent Framework’s current Go path is aligned to the Chat Completion client, making it the practical choice for Go-only environments.
- Choose Responses client when you deploy to providers that support the Responses API (Foundry, Azure OpenAI) and when you need hosted tools and structured outputs.
Tiny runnable examples
Responses client (recommended pattern)
- Required using statements:
using Azure.AI.OpenAI;
using Microsoft.Agents.AI; // (conceptual; align with your Agent Framework namespaces) - Pattern:
var client = new OpenAIClient(“”);
var responsesClient = client.GetResponsesClient();
AIAgent agent = responsesClient.AsAIAgent(model: “gpt-4o-mini”, instructions: “You are a helpful coding assistant.”);
var result = await agent.RunAsync(“Write a Python function to sort a list.”);
Console.WriteLine(result); - Expected behavior: prints a Python function that sorts a list. The agent can also invoke hosted tools (if enabled) for code execution, file search, etc.
C# — Chat Completion client
- Pattern:
var client = new OpenAIClient(“”);
var chatClient = client.GetChatClient(“gpt-4o-mini”);
AIAgent agent = chatClient.AsAIAgent(instructions: “You are good at telling jokes.”);
var result = await agent.RunAsync(“Tell me a joke about a pirate.”);
Console.WriteLine(result); - Expected behavior: prints a joke about a pirate. Tooling is limited to chat-completions-style integrations.
Migration and practical gotchas
- Feature parity is not 1:1. If you migrate from Chat Completion to Responses, confirm the hosted tools you need exist and behave the same (especially structured outputs and background tasks).
- Streaming and rate limits: Responses may differ in streaming semantics and rate limits per provider; test streaming handlers and error handling.
- Tool availability: Not all providers expose the same hosted tools. Verify Foundry/Azure OpenAI capabilities in your deployment target.
- Structured outputs: If your app relies on function-like JSON outputs, test parsing and schema enforcement under Responses.
Conclusion / recommendation
For new projects, prefer the Responses client: it unlocks hosted tools, structured outputs, and modern provider features. Use the Chat Completion client when backward compatibility, legacy models, or Go-only constraints dictate it. Because both client types integrate under the same agent abstraction, migrating is mostly about swapping the client and validating tool-specific behaviors
