mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00

Files

T

Roger Barreto eb709d8fc9 .NET: Update FoundryAgent to address HostedAgents strict URL routing (#5677 )

* .NET: Foundry agent-endpoint constructor uses ProjectOpenAIClient directly to fix hosted-agent URL routing

Fixes the experimental FoundryAgent(Uri agentEndpoint, AuthenticationTokenProvider, ...)
constructor so it actually works against Foundry hosted agents.

The previous implementation routed through AzureAIProjectChatClient, which
internally called aiProjectClient.GetProjectOpenAIClient().GetProjectResponsesClientForAgent(...).
For an agent-endpoint URL of the canonical shape

https://<host>/api/projects/<project>/agents/<agentName>/endpoint/protocols/openai

the chain produced

POST https://<host>/api/projects/<project>/openai/v1/responses

(project-level path, no /agents/ segment). The Foundry service rejects this with
HTTP 400 "Hosted agents can only be called through the agent endpoint:
.../agents/<agentName>/endpoint/protocols/openai/responses".

The constructor also extracted the agent name via
agentEndpoint.Segments[^1].TrimEnd('/'), which returns "openai" (the last segment),
not the agent name.

What changed
- Public ctor signature: clientOptions parameter type changed from
AIProjectClientOptions? to ProjectOpenAIClientOptions?. The constructor is
fundamentally building a ProjectOpenAIClient; accepting AIProjectClientOptions
was a leaky abstraction whose translation silently dropped any pipeline
policies the caller added via AddPolicy(...). With the direct type, caller
policies pass through to the per-agent traffic verbatim.
- Per-agent client construction: `new ProjectOpenAIClient(BearerTokenPolicy, ProjectOpenAIClientOptions)`
with Endpoint and AgentName set, then `GetProjectResponsesClient().AsIChatClient()`.
The SDK auto-appends ?api-version=v1 when AgentName is set.
- New private static ParseAgentEndpoint helper: single source of truth for both
agent-name extraction and project-root derivation. Tolerates trailing slash,
case variants on /agents/ and the suffix segment, strips query/fragment, and
throws ArgumentException with paramName=nameof(agentEndpoint) for malformed input.
- Project-level client (used by CreateConversationSessionAsync) is built fresh
from the derived project root with primitive properties copied
(RetryPolicy/NetworkTimeout/Transport/UserAgentApplicationId) plus MEAI UA.
- New GetService<ProjectOpenAIClient>() entry alongside the existing
GetService<AIProjectClient>() (the latter returns null in agent-endpoint mode
since no AIProjectClient is constructed on that path).
- Endpoint and AgentName on caller-supplied ProjectOpenAIClientOptions are
overridden by values derived from agentEndpoint.

Compatibility
- FoundryAgent is [Experimental(OPENAI001)]. No GA surface touched. The Foundry
project does not maintain PublicAPI.*.txt baselines so there is no shipped
baseline to update.
- The Microsoft.Agents.AI.Foundry csproj pins
Azure.AI.Projects to VersionOverride 2.1.0-beta.1 (matching what the IT and
hosting projects already use); the central pin in Directory.Packages.props
stays at 2.0.0.
- WireClientHeaders from PR #5652 is invoked on the agent-endpoint path so
per-call x-client-* headers behave identically across both ctors.

Tests
- 23 new unit tests in FoundryAgentTests.cs:
- 12 for the agent-endpoint constructor (URL routing for non-streaming and
streaming, conversations URL shape, MEAI UA stamping, caller-policy
passthrough on the per-agent pipeline, Endpoint/AgentName override
semantics, GetService matrix, ProjectOpenAIClient propagation,
UserAgentApplicationId propagation, null-arg validation, ID/Name slug)
- 9 for ParseAgentEndpoint (standard shape, trailing slash, casing,
sovereign-cloud host without /api/projects/ literal prefix, special chars
in agent name, query/fragment stripping, three negative cases)
- 2 null-arg tests for the public ctor
- All 250 Microsoft.Agents.AI.Foundry.UnitTests pass (was 221 baseline plus
29 from PR #5652 plus 23 new in this PR equals 273; pre-existing tests
collapsed by the rebase merge keep the total at 250).
- All 225 Microsoft.Agents.AI.Foundry.Hosting.UnitTests pass; no behavioral
change to the hosting layer.
- dotnet build clean across net8/9/10/netstandard2.0/net472 with
TreatWarningsAsErrors=true.
- dotnet format --verify-no-changes clean for the touched src and test projects.

* .NET: Bump central Azure.AI.Projects pin to 2.1.0-beta.1 and flip Microsoft.Agents.AI.Foundry to preview

Required to fix the NU1109 downgrade chain that broke CI on the agent-endpoint
constructor rewire (#5677). Microsoft.Agents.AI.Foundry now depends on
ProjectOpenAIClientOptions.AgentName and the (AuthenticationPolicy, options)
constructor that only exist in Azure.AI.Projects 2.1.0-beta.1.

Changes:
* Directory.Packages.props: Azure.AI.Projects 2.0.0 -> 2.1.0-beta.1.
* Microsoft.Agents.AI.Foundry.csproj: drop IsReleased=true so the package ships
as preview (matches the beta SDK we now depend on). Add a comment noting the
flip is temporary and should revert once Azure.AI.Projects ships a stable
2.1.0.
* Drop redundant VersionOverride="2.1.0-beta.1" from the 10 csprojs that had it
as a workaround; the central pin now suffices.

Verified:
* dotnet build agent-framework-dotnet.slnx --warnaserror clean across all TFMs.
* Microsoft.Agents.AI.Foundry.UnitTests 250/250 pass.
* Microsoft.Agents.AI.Foundry.Hosting.UnitTests 211/211 pass.
* dotnet format --verify-no-changes clean for the touched src and test projects.

eb709d8fc9 · 2026-05-08 14:46:52 +00:00

History

01-get-started

Fix typo:sesionEleme -> sessionElement (#5674 )

2026-05-07 21:05:41 +00:00

02-agents

.NET: Update FoundryAgent to address HostedAgents strict URL routing (#5677 )

2026-05-08 14:46:52 +00:00

03-workflows

.NET: Add declarative HttpRequestAction sample (#5572 )

2026-04-29 19:19:31 +00:00

04-hosting

.NET: Update FoundryAgent to address HostedAgents strict URL routing (#5677 )

2026-05-08 14:46:52 +00:00

05-end-to-end

.NET: [Breaking] Migrate A2A agent and hosting to A2A SDK v1 (#5423 )

2026-04-23 07:53:00 +00:00

.editorconfig

Update analyzers for .NET 10 SDK (#2611 )

2025-12-10 10:34:56 +00:00

AGENTS.md

.NET: Update models used in dotnet samples to gpt-5.4-mini (#5080 )

2026-04-07 15:34:00 +00:00

Directory.Build.props

.NET: Simplify store=false scenario for responses (#4124 )

2026-02-23 12:24:32 +00:00

README.md

.NET: [Breaking] Migrate A2A agent and hosting to A2A SDK v1 (#5423 )

2026-04-23 07:53:00 +00:00

README.md

Agent Framework Samples

The agent framework samples are designed to help you get started with building AI-powered agents from various providers.

The Agent Framework supports building agents using various inference and inference-style services. All these are supported using the single ChatClientAgent class.

The Agent Framework also supports creating proxy agents, that allow accessing remote agents as if they were local agents. These are supported using various AIAgent subclasses.

Sample Structure

Folder	Description
`01-get-started/`	Progressive tutorial: hello agent → hosting
`02-agents/`	Deep-dive by concept: tools, middleware, providers, orchestrations
`03-workflows/`	Workflow patterns: sequential, concurrent, state, declarative
`04-hosting/`	Deployment: Azure Functions, Durable Tasks
`05-end-to-end/`	Full applications, evaluation, demos

Getting Started

Start with 01-get-started/ and work through the numbered files:

01_hello_agent — Create and run your first agent
02_add_tools — Add function tools
03_multi_turn — Multi-turn conversations with AgentSession
04_memory — Agent memory with AIContextProvider
05_first_workflow — Build a workflow with executors and edges
06_host_your_agent — Host your agent via Azure Functions

Additional Samples

Some additional samples of note include:

Agents: Basic steps to get started with the agent framework. These samples demonstrate the fundamental concepts and functionalities of the agent framework when using the AIAgent and can be used with any underlying service that provides an AIAgent implementation.
Agent Providers: Shows how to create an AIAgent instance for a selection of providers.
Agent Telemetry: Demo which showcases the integration of OpenTelemetry with the Microsoft Agent Framework using Azure OpenAI and .NET Aspire Dashboard for telemetry visualization.
Durable Agents - Azure Functions: Samples for using the Microsoft Agent Framework with Azure Functions via the durable task extension.
Durable Agents - Console Apps: Samples demonstrating durable agents in console applications.

Migration from Semantic Kernel

If you are migrating from Semantic Kernel to the Microsoft Agent Framework, the following resources provide guidance and side-by-side examples to help you transition your existing agents, tools, and orchestration patterns. The migration samples map Semantic Kernel primitives (such as ChatCompletionAgent and Team orchestrations) to their Agent Framework equivalents (such as ChatClientAgent and workflow builders).

For an in-depth migration guide, see the official migration documentation.

Prerequisites

For prerequisites see each set of samples for their specific requirements.