.NET: [Breaking] Update Foundry Agents for Responses API by rogerbarreto · Pull Request #4502 · microsoft/agent-framework

rogerbarreto · 2026-03-05T16:26:56Z

Motivation and Context

Introduce self-contained Foundry agent types (FoundryAgent, FoundryVersionedAgent, FoundryAITool) that eliminate the need for callers to manually construct AIProjectClient instances. The existing AIProjectClient extension methods are preserved for backward compatibility but marked obsolete.

See ADR 0020 (docs/decisions/0020-foundry-agent-type-naming.md) for the full decision record.

Description

New types in `Microsoft.Agents.AI.AzureAI`

Type	Purpose
`FoundryAgent`	Responses API wrapper — no server-side agent. Explicit `Uri endpoint` + `AuthenticationTokenProvider` + `model` constructors.
`FoundryVersionedAgent`	Server-side versioned agent wrapper — private ctor, async static factories (`CreateAIAgentAsync`, `GetAIAgentAsync`, `AsAIAgent`), plus `DeleteAIAgentAsync` / `DeleteAIAgentVersionAsync`.
`FoundryAITool`	Static `AITool` factory wrapping `AgentTool.Create` / `ResponseTool.Create`, removing the `((ResponseTool)...).AsAITool()` casting ceremony.

Key design decisions

No env-var auto-discovery — constructors and factory methods require explicit endpoint, credential, and model parameters. Samples read env vars at the top of Program.cs and pass them in.
Obsolete extension methods — all 8 public AzureAIProjectChatClientExtensions methods (CreateAIAgentAsync ×3, GetAIAgentAsync ×2, AsAIAgent ×3) are marked [Obsolete] pointing to FoundryVersionedAgent.
FoundryAgent options ctor validates ModelId — prevents constructing an invalid agent that would fail later at runtime.
CreateConversationSessionAsync — convenience on both types that creates a server-side ProjectConversation and returns a linked ChatClientAgentSession.

Samples

Renamed FoundryResponseAgents/ → FoundryAgents/, old FoundryAgents/ → FoundryVersionedAgents/
All 49 Foundry sample programs updated to explicit endpoint/credential/model wiring
READMEs rewritten to match the current API (no stale auto-discovery language)
Non-Foundry samples that used obsolete extensions (Agent_With_AzureAIProject, AgentWithRAG_Step04, AgentWithMemory_Step04, HostedWorkflow) migrated to FoundryVersionedAgent

Tests

Unit tests: New FoundryAgentTests.cs and FoundryVersionedAgentTests.cs covering constructor/factory validation, metadata, GetService, functional HTTP behavior, and user-agent headers.
Integration tests: New conformance test suites for both FoundryAgent and FoundryVersionedAgent (run, streaming, chat-client, structured output, agent creation with tools). Old extension-method integration tests marked [Obsolete]. Full suite: 71 passed, 0 failed, 28 skipped.

Docs

ADR 0020 updated to "accepted" status with the final explicit-configuration design (Option 6).

Contribution Checklist

The code builds clean without any errors or warnings
The PR follows the Contribution Guidelines
All unit tests pass, and I have added new tests where possible
Is this a breaking change? No — obsolete extension methods still compile and work; this is additive.

...es/02-agents/FoundryResponseAgents/FoundryAgentsRAPI_Step02_MultiturnConversation/Program.cs

Added example usage of ChatClientAgent with JokerAgent.

Updated documentation to reflect changes in agent creation methods and added examples for using `ChatClientAgent`.

Update Azure.AI.Projects.OpenAI references to Azure.AI.Projects.Agents and Azure.AI.Extensions.OpenAI to match Azure.AI.Projects 2.0.0-beta.2. - Replace deprecated namespace across samples, tests, and src - Fix renamed types: OpenAPIFunctionDefinition -> OpenApiFunctionDefinition, BingCustomSearchToolParameters -> BingCustomSearchToolOptions, BrowserAutomationToolParameters -> BrowserAutomationToolOptions - Fix API changes: AgentRecord.Versions -> GetLatestVersion(), ResponsesClient constructor, FunctionApprovalRequestContent -> ToolApprovalRequestContent - Apply dotnet format Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Switch Agent_Step07_AsMcpTool and A2AServer to use the non-obsolete PersistentAgentsClient.AsAIAgent(PersistentAgent) extension instead of the deprecated GetAIAgentAsync, fixing CS0618 build errors. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace stale ChatClientAgents_Step* folder references with the correct Agent_Step* names across all Responses sample READMEs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Fix charset and remove unused using in AzureAIProjectResponsesChatClient - Fix doc comment tags (code -> c) in FoundryAITool - Fix stray period in LocalMCP sample comment - Fix grammar in FoundryMemoryProvider xmldoc - Fix AIProjectClientAgentRunStreamingConversationTests base class Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Fix static call to CreateSessionAsync in Step02 samples and extension tests - Use expression-bodied lambda in FoundryMemoryProvider (RCS1021) - Apply PascalCase naming to const fields in ResponsesAgentExtensionCreateTests (IDE1006) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add FoundryAgent sealed class wrapping ChatClientAgent with: - Public ctors: (projectEndpoint, credential, model, instructions) and (agentEndpoint, credential) - Internal ctor: (AIProjectClient, ChatClientAgent) for extension use - CreateConversationSessionAsync() for server-side conversations - GetService<ChatClientAgent>() and GetService<AIProjectClient>() - MEAI user-agent policy on internally-created AIProjectClient - Change all AsAIAgent extension return types from ChatClientAgent to FoundryAgent - Update all samples and tests to use FoundryAgent type - Add 16 FoundryAgentTests covering ctors, GetService, UserAgent, RunAsync - Fix pre-existing Agent_Step12_Plugins build error Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Move all Responses/* samples up to AgentsWithFoundry/ (flat structure) - Remove entire Versioned/ folder (26 samples) - Add FoundryAgent_Step01 sample showing direct FoundryAgent ctor usage - Update slnx to reflect flat folder structure - Fix csproj ProjectReference paths for new depth Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Rewrite AgentsWithFoundry/README.md with FoundryAgent quick start - Fix cd commands and paths in 11 sample READMEs - Update 02-agents/README.md to single Foundry link - Update AGENTS.md tree to flat structure - Fix AgentWithMemory cross-reference Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Show the complete server-side agent lifecycle: create version with native SDK, wrap as FoundryAgent via AsAIAgent, run, then delete. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

RAPI samples should not reference FoundryAgent directly. Restored original sample code with only ChatClientAgent -> AIAgent type change to accommodate the AsAIAgent return type. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Step09, Step13, Step17, Step22 were using CreateAgentVersionAsync + PromptAgentDefinition which is the versioned pattern. Converted to use AsAIAgent(model, instructions, tools) which is the RAPI path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- FoundryAgent_Step01: CRLF -> LF - Agent_Step09: missing final newline - Agent_Step11_Middleware: add internal modifier, final newline - Agent_Step02: remove redundant cast (IDE0004) - Agent_Step08: simplify name (IDE0001) - FoundryAgentTests: s_ prefix, Async suffix naming conventions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace npx stdio GitHub MCP server with the public Microsoft Learn MCP endpoint (https://learn.microsoft.com/api/mcp) using HTTP transport. No external tooling required to run. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- FoundryAgent now inherits DelegatingAIAgent instead of AIAgent, removing manual delegation boilerplate (westey-m feedback) - Simplified Agent_Step01_Basics to single agent creation path, moved composable IChatClient approach to README (westey-m feedback) - Fixed FoundryAgentTests param name assertion Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…implifications, format fixes - Add DefaultAzureCredential production warning comments to ~25 samples - Simplify Anthropic and OpenAI Step01 samples to single agent - Convert Step11 Middleware regex patterns to [GeneratedRegex] - Remove unnecessary cleanup comment from Step06 - Fix Step09 README MCP transport description - Enhance FoundryAgent xmldoc with non-persistent agent comparison Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Split Step02 into 02.1 (simple multi-turn via sessions) and 02.2 (server-side conversations via CreateConversationSessionAsync) - RAG Step04: replace HostedFileSearchTool + MEAI wrapping with native OpenAI FileSearchTool - Step23: clarify DelegatingAIFunction wrapping pattern vs Step09 basic MCP Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…o PromptAgentDefinition Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Replace 'Azure AI Foundry' with 'Microsoft Foundry' in ADR 0020 - Fix 3 READMEs: 'ChatClientAgents' → 'AgentsWithFoundry' sample directory - Rename FoundryAgent_Step01 → Agent_Step00_FoundryAgentLifecycle for naming consistency Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

...mples/02-agents/AgentsWithFoundry/Agent_Step02.2_MultiturnWithServerConversations/Program.cs

alliscode reviewed Mar 5, 2026

View reviewed changes

...es/02-agents/FoundryResponseAgents/FoundryAgentsRAPI_Step02_MultiturnConversation/Program.cs Outdated Show resolved Hide resolved

markwallace-microsoft added documentation Improvements or additions to documentation .NET labels Mar 6, 2026

rogerbarreto temporarily deployed to integration March 6, 2026 09:40 — with GitHub Actions Inactive

github-actions bot changed the title ~~.Net: Update Foundry Agents for Responses API~~ .NET: Update Foundry Agents for Responses API Mar 6, 2026

rogerbarreto self-assigned this Mar 6, 2026

rogerbarreto had a problem deploying to integration March 6, 2026 10:12 — with GitHub Actions Error

rogerbarreto temporarily deployed to integration March 6, 2026 10:18 — with GitHub Actions Inactive

rogerbarreto temporarily deployed to integration March 6, 2026 10:34 — with GitHub Actions Inactive

rogerbarreto temporarily deployed to integration March 6, 2026 11:22 — with GitHub Actions Inactive

rogerbarreto had a problem deploying to integration March 9, 2026 18:10 — with GitHub Actions Failure

rogerbarreto temporarily deployed to integration March 9, 2026 18:10 — with GitHub Actions Inactive

rogerbarreto had a problem deploying to integration March 9, 2026 20:13 — with GitHub Actions Failure

rogerbarreto had a problem deploying to integration March 9, 2026 20:13 — with GitHub Actions Error

rogerbarreto temporarily deployed to integration March 9, 2026 20:19 — with GitHub Actions Inactive

rogerbarreto had a problem deploying to integration March 9, 2026 20:19 — with GitHub Actions Failure

rogerbarreto temporarily deployed to integration March 9, 2026 21:01 — with GitHub Actions Inactive

rogerbarreto had a problem deploying to integration March 9, 2026 21:01 — with GitHub Actions Failure

rogerbarreto had a problem deploying to integration March 10, 2026 13:54 — with GitHub Actions Error

rogerbarreto had a problem deploying to integration March 10, 2026 13:54 — with GitHub Actions Failure

rogerbarreto temporarily deployed to integration March 10, 2026 13:59 — with GitHub Actions Inactive

rogerbarreto temporarily deployed to integration March 10, 2026 14:14 — with GitHub Actions Inactive

markwallace-microsoft added the workflows Related to Workflows in agent-framework label Mar 11, 2026

rogerbarreto and others added 26 commits March 27, 2026 16:22

Update documentation for ChatClientAgent usage

a95faeb

Added example usage of ChatClientAgent with JokerAgent.

Refactor ChatClientAgent instantiation for clarity

9690c4d

Revise agent type naming and usage examples

915075d

Updated documentation to reflect changes in agent creation methods and added examples for using `ChatClientAgent`.

Address merge markers

b802780

Fix broken markdown links in Responses sample READMEs

82a8419

Replace stale ChatClientAgents_Step* folder references with the correct Agent_Step* names across all Responses sample READMEs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Apply dotnet format fixes to PR-changed files

e73b006

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix FoundryAgent_Step01 sample with full create/run/delete lifecycle

8416ce3

Show the complete server-side agent lifecycle: create version with native SDK, wrap as FoundryAgent via AsAIAgent, run, then delete. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix missing final newline in Step09 MCP sample

83112b8

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Update sample using Project specialized type instead

cacd72d

Fix Hosted MCP sample: use ResponseTool.CreateMcpTool and move tool t…

ef8a4db

…o PromptAgentDefinition Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Fix broken README link after Step02 split

f287444

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

westey-m reviewed Mar 27, 2026

View reviewed changes

...mples/02-agents/AgentsWithFoundry/Agent_Step02.2_MultiturnWithServerConversations/Program.cs Show resolved Hide resolved

westey-m approved these changes Mar 27, 2026

View reviewed changes

alliscode approved these changes Mar 27, 2026

View reviewed changes

SergeyMenshykh mentioned this pull request Apr 1, 2026

.NET: skill as class #5027

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

.NET: [Breaking] Update Foundry Agents for Responses API#4502

.NET: [Breaking] Update Foundry Agents for Responses API#4502
rogerbarreto merged 64 commits intomicrosoft:mainfrom
rogerbarreto:features/foundry-agent-client

rogerbarreto commented Mar 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Conversation

rogerbarreto commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Description

New types in Microsoft.Agents.AI.AzureAI

Key design decisions

Samples

Tests

Docs

Contribution Checklist

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

rogerbarreto commented Mar 5, 2026 •

edited

Loading

New types in `Microsoft.Agents.AI.AzureAI`