From 8e2cc4bedcf3ec0cf331f2f683d9884a0b72a7d7 Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Thu, 26 Feb 2026 16:51:25 +0900
Subject: [PATCH 01/24] Python: Update workflow orchestration samples to use
AzureOpenAIResponsesClient (#4285)
* Update workflow orchestration samples to use AzureOpenAIResponsesClient
* Fix broken link
---
docs/decisions/0001-agent-run-response.md | 2 +-
python/samples/03-workflows/README.md | 8 ++++++
.../agent_to_function_tool/main.py | 11 +++++---
.../declarative/function_tools/README.md | 8 ++++--
.../03-workflows/orchestrations/README.md | 4 +++
.../orchestrations/concurrent_agents.py | 15 ++++++++---
.../concurrent_custom_agent_executors.py | 21 ++++++++++-----
.../concurrent_custom_aggregator.py | 15 ++++++++---
.../group_chat_agent_manager.py | 15 ++++++++---
.../group_chat_philosophical_debate.py | 15 ++++++++---
.../group_chat_simple_selector.py | 15 ++++++++---
.../orchestrations/handoff_autonomous.py | 16 +++++++----
.../orchestrations/handoff_simple.py | 20 +++++++++-----
.../03-workflows/orchestrations/magentic.py | 24 +++++++++++------
.../orchestrations/magentic_checkpoint.py | 27 ++++++++++++++-----
.../magentic_human_plan_review.py | 20 ++++++++++----
.../orchestrations/sequential_agents.py | 13 ++++++---
.../sequential_custom_executors.py | 13 ++++++---
18 files changed, 192 insertions(+), 70 deletions(-)
diff --git a/docs/decisions/0001-agent-run-response.md b/docs/decisions/0001-agent-run-response.md
index 6f3385e1a1..fb4a962802 100644
--- a/docs/decisions/0001-agent-run-response.md
+++ b/docs/decisions/0001-agent-run-response.md
@@ -498,7 +498,7 @@ We need to decide what AIContent types, each agent response type will be mapped
| Google ADK | **Approach 1** Both [input and output schemas can be specified for LLM Agents](https://google.github.io/adk-docs/agents/llm-agents/#structuring-data-input_schema-output_schema-output_key) at construction time. This option is specific to this agent type and other agent types do not necessarily support |
| AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent/#strands.agent.agent.Agent.structured_output) |
| LangGraph | **Approach 1** Supports [configuring an agent](https://langchain-ai.github.io/langgraph/agents/agents/?h=structured#6-configure-structured-output) at agent construction time, and a [structured response](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) can be retrieved as a special property on the agent response |
-| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/examples/getting-started/structured-output) at agent construction time |
+| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/input-output/structured-output/agent) at agent construction time |
| A2A | **Informal Approach 2** Doesn't formally support schema negotiation, but [hints can be provided via metadata](https://a2a-protocol.org/latest/specification/#97-structured-data-exchange-requesting-and-providing-json) at invocation time |
| Protocol Activity | Supports returning [Complex types](https://github.com/microsoft/Agents/blob/main/specs/activity/protocol-activity.md#complex-types) but no support for requesting a type |
diff --git a/python/samples/03-workflows/README.md b/python/samples/03-workflows/README.md
index c5abe202ac..4dfdd68157 100644
--- a/python/samples/03-workflows/README.md
+++ b/python/samples/03-workflows/README.md
@@ -160,6 +160,14 @@ Sequential orchestration uses a few small adapter nodes for plumbing:
These may appear in event streams (executor_invoked/executor_completed). They're analogous to
concurrent’s dispatcher and aggregator and can be ignored if you only care about agent activity.
+### AzureOpenAIResponsesClient vs AzureAIAgent
+
+Workflow and orchestration samples use `AzureOpenAIResponsesClient` rather than the CRUD-style `AzureAIAgent` client. The key difference:
+
+- **`AzureOpenAIResponsesClient`** — A lightweight client that uses the underlying Agent Service V2 (Responses API) for non-CRUD-style agents. Orchestrations use this client because agents are created locally and do not require server-side lifecycle management (create/update/delete). This is the recommended client for orchestration patterns (Sequential, Concurrent, Handoff, GroupChat, Magentic).
+
+- **`AzureAIAgent`** — A CRUD-style client for server-managed agents. Use this when you need persistent, server-side agent definitions with features like file search, code interpreter sessions, or thread management provided by the Azure AI Agent Service.
+
### Environment Variables
Workflow samples that use `AzureOpenAIResponsesClient` expect:
diff --git a/python/samples/03-workflows/declarative/agent_to_function_tool/main.py b/python/samples/03-workflows/declarative/agent_to_function_tool/main.py
index 55ba77c073..d4346d826e 100644
--- a/python/samples/03-workflows/declarative/agent_to_function_tool/main.py
+++ b/python/samples/03-workflows/declarative/agent_to_function_tool/main.py
@@ -18,10 +18,11 @@ Run with:
"""
import asyncio
+import os
from pathlib import Path
from typing import Any
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.declarative import WorkflowFactory
from azure.identity import AzureCliCredential
from pydantic import BaseModel, Field
@@ -196,8 +197,12 @@ def format_order_confirmation(order_data: dict[str, Any], order_calculation: dic
async def main():
"""Run the agent to function tool workflow."""
- # Create Azure OpenAI client
- chat_client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ # Create Azure OpenAI Responses client
+ chat_client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
# Create the order analysis agent with structured output
order_analysis_agent = chat_client.as_agent(
diff --git a/python/samples/03-workflows/declarative/function_tools/README.md b/python/samples/03-workflows/declarative/function_tools/README.md
index 78e7cf361e..e831ba51d7 100644
--- a/python/samples/03-workflows/declarative/function_tools/README.md
+++ b/python/samples/03-workflows/declarative/function_tools/README.md
@@ -6,7 +6,7 @@ This sample demonstrates an agent with function tools responding to user queries
The workflow showcases:
- **Function Tools**: Agent equipped with tools to query menu data
-- **Real Azure OpenAI Agent**: Uses `AzureOpenAIChatClient` to create an agent with tools
+- **Real Azure OpenAI Agent**: Uses `AzureOpenAIResponsesClient` to create an agent with tools
- **Agent Registration**: Shows how to register agents with the `WorkflowFactory`
## Tools
@@ -72,7 +72,11 @@ Session Complete
```python
# Create the agent with tools
-client = AzureOpenAIChatClient(credential=AzureCliCredential())
+client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+)
menu_agent = client.as_agent(
name="MenuAgent",
instructions="You are a helpful restaurant menu assistant...",
diff --git a/python/samples/03-workflows/orchestrations/README.md b/python/samples/03-workflows/orchestrations/README.md
index 3ce85cd1ab..527a414295 100644
--- a/python/samples/03-workflows/orchestrations/README.md
+++ b/python/samples/03-workflows/orchestrations/README.md
@@ -92,6 +92,10 @@ from agent_framework.orchestrations import (
These may appear in event streams (executor_invoked/executor_completed). They're analogous to concurrent's dispatcher and aggregator and can be ignored if you only care about agent activity.
+## Why AzureOpenAIResponsesClient?
+
+Orchestration samples use `AzureOpenAIResponsesClient` rather than the CRUD-style `AzureAIAgent` client. Orchestrations create agents locally and do not require server-side lifecycle management (create/update/delete). `AzureOpenAIResponsesClient` is a lightweight client that uses the underlying Agent Service V2 (Responses API) for non-CRUD-style agents, which is ideal for orchestration patterns like Sequential, Concurrent, Handoff, GroupChat, and Magentic.
+
## Environment Variables
Orchestration samples that use `AzureOpenAIResponsesClient` expect:
diff --git a/python/samples/03-workflows/orchestrations/concurrent_agents.py b/python/samples/03-workflows/orchestrations/concurrent_agents.py
index f6aae589a6..78e56b38bf 100644
--- a/python/samples/03-workflows/orchestrations/concurrent_agents.py
+++ b/python/samples/03-workflows/orchestrations/concurrent_agents.py
@@ -1,10 +1,11 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
+import os
from typing import Any
from agent_framework import Message
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import ConcurrentBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -26,14 +27,20 @@ Demonstrates:
- Workflow completion when idle with no pending work
Prerequisites:
-- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
- Familiarity with Workflow events (WorkflowEvent)
"""
async def main() -> None:
- # 1) Create three domain agents using AzureOpenAIChatClient
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ # 1) Create three domain agents using AzureOpenAIResponsesClient
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
researcher = client.as_agent(
instructions=(
diff --git a/python/samples/03-workflows/orchestrations/concurrent_custom_agent_executors.py b/python/samples/03-workflows/orchestrations/concurrent_custom_agent_executors.py
index 82df710435..3e0a9b63c6 100644
--- a/python/samples/03-workflows/orchestrations/concurrent_custom_agent_executors.py
+++ b/python/samples/03-workflows/orchestrations/concurrent_custom_agent_executors.py
@@ -1,6 +1,7 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
+import os
from typing import Any
from agent_framework import (
@@ -12,7 +13,7 @@ from agent_framework import (
WorkflowContext,
handler,
)
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import ConcurrentBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -29,21 +30,23 @@ and emit AgentExecutorResponse outputs, which allows reuse of the high-level
ConcurrentBuilder API and the default aggregator.
Demonstrates:
-- Executors that create their Agent in __init__ (via AzureOpenAIChatClient)
+- Executors that create their Agent in __init__ (via AzureOpenAIResponsesClient)
- A @handler that converts AgentExecutorRequest -> AgentExecutorResponse
- ConcurrentBuilder(participants=[...]) to build fan-out/fan-in
- Default aggregator returning list[Message] (one user + one assistant per agent)
- Workflow completion when all participants become idle
Prerequisites:
-- Azure OpenAI configured for AzureOpenAIChatClient (az login + required env vars)
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
class ResearcherExec(Executor):
agent: Agent
- def __init__(self, client: AzureOpenAIChatClient, id: str = "researcher"):
+ def __init__(self, client: AzureOpenAIResponsesClient, id: str = "researcher"):
self.agent = client.as_agent(
instructions=(
"You're an expert market and product researcher. Given a prompt, provide concise, factual insights,"
@@ -63,7 +66,7 @@ class ResearcherExec(Executor):
class MarketerExec(Executor):
agent: Agent
- def __init__(self, client: AzureOpenAIChatClient, id: str = "marketer"):
+ def __init__(self, client: AzureOpenAIResponsesClient, id: str = "marketer"):
self.agent = client.as_agent(
instructions=(
"You're a creative marketing strategist. Craft compelling value propositions and target messaging"
@@ -83,7 +86,7 @@ class MarketerExec(Executor):
class LegalExec(Executor):
agent: Agent
- def __init__(self, client: AzureOpenAIChatClient, id: str = "legal"):
+ def __init__(self, client: AzureOpenAIResponsesClient, id: str = "legal"):
self.agent = client.as_agent(
instructions=(
"You're a cautious legal/compliance reviewer. Highlight constraints, disclaimers, and policy concerns"
@@ -101,7 +104,11 @@ class LegalExec(Executor):
async def main() -> None:
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
researcher = ResearcherExec(client)
marketer = MarketerExec(client)
diff --git a/python/samples/03-workflows/orchestrations/concurrent_custom_aggregator.py b/python/samples/03-workflows/orchestrations/concurrent_custom_aggregator.py
index 3014a0e3cf..b622e0f6b7 100644
--- a/python/samples/03-workflows/orchestrations/concurrent_custom_aggregator.py
+++ b/python/samples/03-workflows/orchestrations/concurrent_custom_aggregator.py
@@ -1,10 +1,11 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
+import os
from typing import Any
from agent_framework import Message
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import ConcurrentBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -17,7 +18,7 @@ Sample: Concurrent Orchestration with Custom Aggregator
Build a concurrent workflow with ConcurrentBuilder that fans out one prompt to
multiple domain agents and fans in their responses. Override the default
-aggregator with a custom async callback that uses AzureOpenAIChatClient.get_response()
+aggregator with a custom async callback that uses AzureOpenAIResponsesClient.get_response()
to synthesize a concise, consolidated summary from the experts' outputs.
The workflow completes when all participants become idle.
@@ -28,12 +29,18 @@ Demonstrates:
- Workflow output yielded with the synthesized summary string
Prerequisites:
-- Azure OpenAI configured for AzureOpenAIChatClient (az login + required env vars)
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
async def main() -> None:
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
researcher = client.as_agent(
instructions=(
diff --git a/python/samples/03-workflows/orchestrations/group_chat_agent_manager.py b/python/samples/03-workflows/orchestrations/group_chat_agent_manager.py
index d057756160..2fecc34282 100644
--- a/python/samples/03-workflows/orchestrations/group_chat_agent_manager.py
+++ b/python/samples/03-workflows/orchestrations/group_chat_agent_manager.py
@@ -1,6 +1,7 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
+import os
from typing import cast
from agent_framework import (
@@ -8,7 +9,7 @@ from agent_framework import (
AgentResponseUpdate,
Message,
)
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import GroupChatBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -25,7 +26,9 @@ What it does:
- Coordinates a researcher and writer agent to solve tasks collaboratively
Prerequisites:
-- OpenAI environment variables configured for OpenAIChatClient
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
ORCHESTRATOR_AGENT_INSTRUCTIONS = """
@@ -39,8 +42,12 @@ Guidelines:
async def main() -> None:
- # Create a chat client using Azure OpenAI and Azure CLI credentials for all agents
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ # Create a Responses client using Azure OpenAI and Azure CLI credentials for all agents
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
# Orchestrator agent that manages the conversation
# Note: This agent (and the underlying chat client) must support structured outputs.
diff --git a/python/samples/03-workflows/orchestrations/group_chat_philosophical_debate.py b/python/samples/03-workflows/orchestrations/group_chat_philosophical_debate.py
index 5e55fe9204..a8dd2aebfe 100644
--- a/python/samples/03-workflows/orchestrations/group_chat_philosophical_debate.py
+++ b/python/samples/03-workflows/orchestrations/group_chat_philosophical_debate.py
@@ -2,6 +2,7 @@
import asyncio
import logging
+import os
from typing import cast
from agent_framework import (
@@ -9,7 +10,7 @@ from agent_framework import (
AgentResponseUpdate,
Message,
)
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import GroupChatBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -38,15 +39,21 @@ Participants represent:
- Doctor from Scandinavia (public health, equity, societal support)
Prerequisites:
-- OpenAI environment variables configured for OpenAIChatClient
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
# Load environment variables from .env file
load_dotenv()
-def _get_chat_client() -> AzureOpenAIChatClient:
- return AzureOpenAIChatClient(credential=AzureCliCredential())
+def _get_chat_client() -> AzureOpenAIResponsesClient:
+ return AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
async def main() -> None:
diff --git a/python/samples/03-workflows/orchestrations/group_chat_simple_selector.py b/python/samples/03-workflows/orchestrations/group_chat_simple_selector.py
index cf9b6aa8ec..984b46c6a4 100644
--- a/python/samples/03-workflows/orchestrations/group_chat_simple_selector.py
+++ b/python/samples/03-workflows/orchestrations/group_chat_simple_selector.py
@@ -1,6 +1,7 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
+import os
from typing import cast
from agent_framework import (
@@ -8,7 +9,7 @@ from agent_framework import (
AgentResponseUpdate,
Message,
)
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import GroupChatBuilder, GroupChatState
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -24,7 +25,9 @@ What it does:
- Uses a pure Python function to control speaker selection based on conversation state
Prerequisites:
-- OpenAI environment variables configured for OpenAIChatClient
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
@@ -36,8 +39,12 @@ def round_robin_selector(state: GroupChatState) -> str:
async def main() -> None:
- # Create a chat client using Azure OpenAI and Azure CLI credentials for all agents
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ # Create a Responses client using Azure OpenAI and Azure CLI credentials for all agents
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
# Participant agents
expert = Agent(
diff --git a/python/samples/03-workflows/orchestrations/handoff_autonomous.py b/python/samples/03-workflows/orchestrations/handoff_autonomous.py
index d97006df12..7b86e73cf8 100644
--- a/python/samples/03-workflows/orchestrations/handoff_autonomous.py
+++ b/python/samples/03-workflows/orchestrations/handoff_autonomous.py
@@ -2,6 +2,7 @@
import asyncio
import logging
+import os
from typing import cast
from agent_framework import (
@@ -10,7 +11,7 @@ from agent_framework import (
Message,
resolve_agent_id,
)
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import HandoffBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -28,8 +29,9 @@ Routing Pattern:
User -> Coordinator -> Specialist (iterates N times) -> Handoff -> Final Output
Prerequisites:
- - `az login` (Azure CLI authentication)
- - Environment variables for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
+ - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+ - Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+ - Authentication via azure-identity. Use AzureCliCredential and run `az login` before executing the sample.
Key Concepts:
- Autonomous interaction mode: agents iterate until they handoff
@@ -41,7 +43,7 @@ load_dotenv()
def create_agents(
- client: AzureOpenAIChatClient,
+ client: AzureOpenAIResponsesClient,
) -> tuple[Agent, Agent, Agent]:
"""Create coordinator and specialists for autonomous iteration."""
coordinator = client.as_agent(
@@ -77,7 +79,11 @@ def create_agents(
async def main() -> None:
"""Run an autonomous handoff workflow with specialist iteration enabled."""
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
coordinator, research_agent, summary_agent = create_agents(client)
# Build the workflow with autonomous mode
diff --git a/python/samples/03-workflows/orchestrations/handoff_simple.py b/python/samples/03-workflows/orchestrations/handoff_simple.py
index 5a2319d4d2..1b4820ccbe 100644
--- a/python/samples/03-workflows/orchestrations/handoff_simple.py
+++ b/python/samples/03-workflows/orchestrations/handoff_simple.py
@@ -1,6 +1,7 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
+import os
from typing import Annotated, cast
from agent_framework import (
@@ -11,7 +12,7 @@ from agent_framework import (
WorkflowRunState,
tool,
)
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import HandoffAgentUserRequest, HandoffBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -25,8 +26,9 @@ A handoff workflow defines a pattern that assembles agents in a mesh topology, a
them to transfer control to each other based on the conversation context.
Prerequisites:
- - `az login` (Azure CLI authentication)
- - Environment variables configured for AzureOpenAIChatClient (AZURE_OPENAI_ENDPOINT, etc.)
+ - AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+ - Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+ - Authentication via azure-identity. Use AzureCliCredential and run `az login` before executing the sample.
Key Concepts:
- Auto-registered handoff tools: HandoffBuilder automatically creates handoff tools
@@ -58,11 +60,11 @@ def process_return(order_number: Annotated[str, "Order number to process return
return f"Return initiated successfully for order {order_number}. You will receive return instructions via email."
-def create_agents(client: AzureOpenAIChatClient) -> tuple[Agent, Agent, Agent, Agent]:
+def create_agents(client: AzureOpenAIResponsesClient) -> tuple[Agent, Agent, Agent, Agent]:
"""Create and configure the triage and specialist agents.
Args:
- client: The AzureOpenAIChatClient to use for creating agents.
+ client: The AzureOpenAIResponsesClient to use for creating agents.
Returns:
Tuple of (triage_agent, refund_agent, order_agent, return_agent)
@@ -192,8 +194,12 @@ async def main() -> None:
the demo reproducible and testable. In a production application, you would
replace the scripted_responses with actual user input collection.
"""
- # Initialize the Azure OpenAI chat client
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ # Initialize the Azure OpenAI Responses client
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
# Create all agents: triage + specialists
triage, refund, order, support = create_agents(client)
diff --git a/python/samples/03-workflows/orchestrations/magentic.py b/python/samples/03-workflows/orchestrations/magentic.py
index 2420b74245..b412fd0b9d 100644
--- a/python/samples/03-workflows/orchestrations/magentic.py
+++ b/python/samples/03-workflows/orchestrations/magentic.py
@@ -3,6 +3,7 @@
import asyncio
import json
import logging
+import os
from typing import cast
from agent_framework import (
@@ -11,8 +12,9 @@ from agent_framework import (
Message,
WorkflowEvent,
)
-from agent_framework.openai import OpenAIChatClient, OpenAIResponsesClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import GroupChatRequestSentEvent, MagenticBuilder, MagenticProgressLedger
+from azure.identity import AzureCliCredential
from dotenv import load_dotenv
logging.basicConfig(level=logging.WARNING)
@@ -40,7 +42,9 @@ energy efficiency and CO2 emissions of several ML models, streams intermediate
events, and prints the final answer. The workflow completes when idle.
Prerequisites:
-- OpenAI credentials configured for `OpenAIChatClient` and `OpenAIResponsesClient`.
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
# Load environment variables from .env file
@@ -48,25 +52,29 @@ load_dotenv()
async def main() -> None:
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
+
researcher_agent = Agent(
name="ResearcherAgent",
description="Specialist in research and information gathering",
instructions=(
"You are a Researcher. You find information without additional computation or quantitative analysis."
),
- # This agent requires the gpt-4o-search-preview model to perform web searches.
- client=OpenAIChatClient(model_id="gpt-4o-search-preview"),
+ client=client,
)
# Create code interpreter tool using instance method
- coder_client = OpenAIResponsesClient()
- code_interpreter_tool = coder_client.get_code_interpreter_tool()
+ code_interpreter_tool = client.get_code_interpreter_tool()
coder_agent = Agent(
name="CoderAgent",
description="A helpful assistant that writes and executes code to process and analyze data.",
instructions="You solve questions using code. Please provide detailed analysis and computation process.",
- client=coder_client,
+ client=client,
tools=code_interpreter_tool,
)
@@ -75,7 +83,7 @@ async def main() -> None:
name="MagenticManager",
description="Orchestrator that coordinates the research and coding workflow",
instructions="You coordinate a team to complete complex tasks efficiently.",
- client=OpenAIChatClient(),
+ client=client,
)
print("\nBuilding Magentic Workflow...")
diff --git a/python/samples/03-workflows/orchestrations/magentic_checkpoint.py b/python/samples/03-workflows/orchestrations/magentic_checkpoint.py
index 940e47759f..ab3da11c1d 100644
--- a/python/samples/03-workflows/orchestrations/magentic_checkpoint.py
+++ b/python/samples/03-workflows/orchestrations/magentic_checkpoint.py
@@ -2,6 +2,7 @@
import asyncio
import json
+import os
from datetime import datetime
from pathlib import Path
from typing import cast
@@ -14,9 +15,9 @@ from agent_framework import (
WorkflowEvent,
WorkflowRunState,
)
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import MagenticBuilder, MagenticPlanReviewRequest
-from azure.identity._credentials import AzureCliCredential
+from azure.identity import AzureCliCredential
from dotenv import load_dotenv
# Load environment variables from .env file
@@ -38,7 +39,9 @@ Concepts highlighted here:
`responses` mapping so we can inject the stored human reply during restoration.
Prerequisites:
-- OpenAI environment variables configured for `OpenAIChatClient`.
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
TASK = (
@@ -61,14 +64,22 @@ def build_workflow(checkpoint_storage: FileCheckpointStorage):
name="ResearcherAgent",
description="Collects background facts and references for the project.",
instructions=("You are the research lead. Gather crisp bullet points the team should know."),
- client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+ client=AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ ),
)
writer = Agent(
name="WriterAgent",
description="Synthesizes the final brief for stakeholders.",
instructions=("You convert the research notes into a structured brief with milestones and risks."),
- client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+ client=AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ ),
)
# Create a manager agent for orchestration
@@ -76,7 +87,11 @@ def build_workflow(checkpoint_storage: FileCheckpointStorage):
name="MagenticManager",
description="Orchestrator that coordinates the research and writing workflow",
instructions="You coordinate a team to complete complex tasks efficiently.",
- client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+ client=AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ ),
)
# The builder wires in the Magentic orchestrator, sets the plan review path, and
diff --git a/python/samples/03-workflows/orchestrations/magentic_human_plan_review.py b/python/samples/03-workflows/orchestrations/magentic_human_plan_review.py
index d9234026aa..61f1cd412d 100644
--- a/python/samples/03-workflows/orchestrations/magentic_human_plan_review.py
+++ b/python/samples/03-workflows/orchestrations/magentic_human_plan_review.py
@@ -2,6 +2,7 @@
import asyncio
import json
+import os
from collections.abc import AsyncIterable
from typing import cast
@@ -11,8 +12,9 @@ from agent_framework import (
Message,
WorkflowEvent,
)
-from agent_framework.openai import OpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import MagenticBuilder, MagenticPlanReviewRequest, MagenticPlanReviewResponse
+from azure.identity import AzureCliCredential
from dotenv import load_dotenv
# Load environment variables from .env file
@@ -35,7 +37,9 @@ Plan review options:
- revise(feedback): Provide textual feedback to modify the plan
Prerequisites:
-- OpenAI credentials configured for `OpenAIChatClient`.
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
# Keep track of the last response to format output nicely in streaming mode
@@ -96,25 +100,31 @@ async def process_event_stream(stream: AsyncIterable[WorkflowEvent]) -> dict[str
async def main() -> None:
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
+
researcher_agent = Agent(
name="ResearcherAgent",
description="Specialist in research and information gathering",
instructions="You are a Researcher. You find information and gather facts.",
- client=OpenAIChatClient(model_id="gpt-4o"),
+ client=client,
)
analyst_agent = Agent(
name="AnalystAgent",
description="Data analyst who processes and summarizes research findings",
instructions="You are an Analyst. You analyze findings and create summaries.",
- client=OpenAIChatClient(model_id="gpt-4o"),
+ client=client,
)
manager_agent = Agent(
name="MagenticManager",
description="Orchestrator that coordinates the workflow",
instructions="You coordinate a team to complete tasks efficiently.",
- client=OpenAIChatClient(model_id="gpt-4o"),
+ client=client,
)
print("\nBuilding Magentic Workflow with Human Plan Review...")
diff --git a/python/samples/03-workflows/orchestrations/sequential_agents.py b/python/samples/03-workflows/orchestrations/sequential_agents.py
index 6eda11ece9..916ecbee9c 100644
--- a/python/samples/03-workflows/orchestrations/sequential_agents.py
+++ b/python/samples/03-workflows/orchestrations/sequential_agents.py
@@ -1,10 +1,11 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
+import os
from typing import cast
from agent_framework import Message
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import SequentialBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -28,13 +29,19 @@ Note on internal adapters:
You can safely ignore them when focusing on agent progress.
Prerequisites:
-- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
async def main() -> None:
# 1) Create agents
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
writer = client.as_agent(
instructions=("You are a concise copywriter. Provide a single, punchy marketing sentence based on the prompt."),
diff --git a/python/samples/03-workflows/orchestrations/sequential_custom_executors.py b/python/samples/03-workflows/orchestrations/sequential_custom_executors.py
index 56308d2b5f..b46971cffe 100644
--- a/python/samples/03-workflows/orchestrations/sequential_custom_executors.py
+++ b/python/samples/03-workflows/orchestrations/sequential_custom_executors.py
@@ -1,6 +1,7 @@
# Copyright (c) Microsoft. All rights reserved.
import asyncio
+import os
from typing import Any
from agent_framework import (
@@ -10,7 +11,7 @@ from agent_framework import (
WorkflowContext,
handler,
)
-from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
from agent_framework.orchestrations import SequentialBuilder
from azure.identity import AzureCliCredential
from dotenv import load_dotenv
@@ -32,7 +33,9 @@ Custom executor contract:
- Emit the updated conversation via ctx.send_message([...])
Prerequisites:
-- Azure OpenAI access configured for AzureOpenAIChatClient (use az login + env vars)
+- AZURE_AI_PROJECT_ENDPOINT must be your Azure AI Foundry Agent Service (V2) project endpoint.
+- Azure OpenAI configured for AzureOpenAIResponsesClient with required environment variables.
+- Authentication via azure-identity. Use AzureCliCredential and run az login before executing the sample.
"""
@@ -62,7 +65,11 @@ class Summarizer(Executor):
async def main() -> None:
# 1) Create a content agent
- client = AzureOpenAIChatClient(credential=AzureCliCredential())
+ client = AzureOpenAIResponsesClient(
+ project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+ deployment_name=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+ credential=AzureCliCredential(),
+ )
content = client.as_agent(
instructions="Produce a concise paragraph answering the user's request.",
name="content",
From c9cd067be6b2981791a9d93b1c832390a39b507a Mon Sep 17 00:00:00 2001
From: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>
Date: Thu, 26 Feb 2026 13:17:21 +0000
Subject: [PATCH 02/24] .NET: Support hosted code interpreter for skill script
execution (#4192)
* support script execution by code interpretor
* improve the instruction prompt
* Add DefaultAzureCredential production warning to AgentSkills samples
Add the standard three-line WARNING comment about DefaultAzureCredential
production considerations to both AgentSkills sample Program.cs files,
matching the convention used in all other GettingStarted/Agents samples.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* address pr review comments
* address feedback
* rename Skill* types to FileAgentSkill* prefix for consistency
- Rename SkillFrontmatter -> FileAgentSkillFrontmatter
- Rename SkillScriptExecutor -> FileAgentSkillScriptExecutor
- Add FileAgentSkillScriptExecutionContext and FileAgentSkillScriptExecutionDetails
- Update sample, provider, loader, and tests accordingly
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* reorder usings
* use set for props initialization instead of init
* rename HostedCodeInterpreterSkillScriptExecutor
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
dotnet/agent-framework-dotnet.slnx | 1 +
.../Agent_Step01_BasicSkills/Program.cs | 3 +
..._ScriptExecutionWithCodeInterpreter.csproj | 28 +++
.../Program.cs | 49 +++++
.../README.md | 72 ++++++++
.../skills/password-generator/SKILL.md | 16 ++
.../references/PASSWORD_GUIDELINES.md | 24 +++
.../password-generator/scripts/generate.py | 11 ++
.../samples/02-agents/AgentSkills/README.md | 1 +
.../Skills/FileAgentSkill.cs | 23 +--
...matter.cs => FileAgentSkillFrontmatter.cs} | 9 +-
.../Skills/FileAgentSkillLoader.cs | 22 ++-
.../FileAgentSkillScriptExecutionContext.cs | 35 ++++
.../FileAgentSkillScriptExecutionDetails.cs | 25 +++
.../Skills/FileAgentSkillScriptExecutor.cs | 42 +++++
.../Skills/FileAgentSkillsProvider.cs | 49 +++--
.../Skills/FileAgentSkillsProviderOptions.cs | 14 +-
...InterpreterFileAgentSkillScriptExecutor.cs | 35 ++++
.../AgentSkills/FileAgentSkillLoaderTests.cs | 50 +++++-
.../FileAgentSkillScriptExecutorTests.cs | 170 ++++++++++++++++++
.../FileAgentSkillsProviderTests.cs | 17 +-
...preterFileAgentSkillScriptExecutorTests.cs | 72 ++++++++
22 files changed, 702 insertions(+), 66 deletions(-)
create mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj
create mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Program.cs
create mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/README.md
create mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/SKILL.md
create mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/references/PASSWORD_GUIDELINES.md
create mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/scripts/generate.py
rename dotnet/src/Microsoft.Agents.AI/Skills/{SkillFrontmatter.cs => FileAgentSkillFrontmatter.cs} (70%)
create mode 100644 dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionContext.cs
create mode 100644 dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionDetails.cs
create mode 100644 dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutor.cs
create mode 100644 dotnet/src/Microsoft.Agents.AI/Skills/HostedCodeInterpreterFileAgentSkillScriptExecutor.cs
create mode 100644 dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillScriptExecutorTests.cs
create mode 100644 dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/HostedCodeInterpreterFileAgentSkillScriptExecutorTests.cs
diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx
index 2bb11b01b8..424f88d7bf 100644
--- a/dotnet/agent-framework-dotnet.slnx
+++ b/dotnet/agent-framework-dotnet.slnx
@@ -82,6 +82,7 @@
+
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs b/dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs
index 290c3f9b6b..eef57e840a 100644
--- a/dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs
+++ b/dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs
@@ -22,6 +22,9 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
var skillsProvider = new FileAgentSkillsProvider(skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));
// --- Agent Setup ---
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
.GetResponsesClient(deploymentName)
.AsAIAgent(new ChatClientAgentOptions
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj
new file mode 100644
index 0000000000..2a503bbfb2
--- /dev/null
+++ b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj
@@ -0,0 +1,28 @@
+
+
+
+ Exe
+ net10.0
+
+ enable
+ enable
+ $(NoWarn);MAAI001
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ PreserveNewest
+
+
+
+
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Program.cs b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Program.cs
new file mode 100644
index 0000000000..2835ec70ab
--- /dev/null
+++ b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Program.cs
@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use Agent Skills with script execution via the hosted code interpreter.
+// When FileAgentSkillScriptExecutor.HostedCodeInterpreter() is configured, the agent can load and execute scripts
+// from skill resources using the LLM provider's built-in code interpreter.
+//
+// This sample includes the password-generator skill:
+// - A Python script for generating secure passwords
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Responses;
+
+// --- Configuration ---
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+ ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+// --- Skills Provider with Script Execution ---
+// Discovers skills and enables script execution via the hosted code interpreter
+var skillsProvider = new FileAgentSkillsProvider(
+ skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
+ options: new FileAgentSkillsProviderOptions
+ {
+ ScriptExecutor = FileAgentSkillScriptExecutor.HostedCodeInterpreter()
+ });
+
+// --- Agent Setup ---
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+ .GetResponsesClient(deploymentName)
+ .AsAIAgent(new ChatClientAgentOptions
+ {
+ Name = "SkillsAgent",
+ ChatOptions = new()
+ {
+ Instructions = "You are a helpful assistant that can generate secure passwords.",
+ },
+ AIContextProviders = [skillsProvider],
+ });
+
+// --- Example: Password generation with script execution ---
+Console.WriteLine("Example: Generating a password with a skill script");
+Console.WriteLine("---------------------------------------------------");
+AgentResponse response = await agent.RunAsync("Generate a secure password for my database account.");
+Console.WriteLine($"Agent: {response.Text}\n");
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/README.md b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/README.md
new file mode 100644
index 0000000000..f5bf63c44a
--- /dev/null
+++ b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/README.md
@@ -0,0 +1,72 @@
+# Script Execution with Code Interpreter
+
+This sample demonstrates how to use **Agent Skills** with **script execution** via the hosted code interpreter.
+
+## What's Different from Step01?
+
+In the [basic skills sample](../Agent_Step01_BasicSkills/), skills only provide instructions and resources as text. This sample adds **script execution** — the agent can load Python scripts from skill resources and execute them using the LLM provider's built-in code interpreter.
+
+This is enabled by configuring `FileAgentSkillScriptExecutor.HostedCodeInterpreter()` on the skills provider options:
+
+```csharp
+var skillsProvider = new FileAgentSkillsProvider(
+ skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
+ options: new FileAgentSkillsProviderOptions
+ {
+ ScriptExecutor = FileAgentSkillScriptExecutor.HostedCodeInterpreter()
+ });
+```
+
+## Skills Included
+
+### password-generator
+Generates secure passwords using a Python script with configurable length and complexity.
+- `scripts/generate.py` — Password generation script
+- `references/PASSWORD_GUIDELINES.md` — Recommended length and symbol sets by use case
+
+## Project Structure
+
+```
+Agent_Step02_ScriptExecutionWithCodeInterpreter/
+├── Program.cs
+├── Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj
+└── skills/
+ └── password-generator/
+ ├── SKILL.md
+ ├── scripts/
+ │ └── generate.py
+ └── references/
+ └── PASSWORD_GUIDELINES.md
+```
+
+## Running the Sample
+
+### Prerequisites
+- .NET 10.0 SDK
+- Azure OpenAI endpoint with a deployed model that supports code interpreter
+
+### Setup
+1. Set environment variables:
+ ```bash
+ export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
+ export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+ ```
+
+2. Run the sample:
+ ```bash
+ dotnet run
+ ```
+
+### Example
+
+The sample asks the agent to generate a secure password. The agent:
+1. Loads the password-generator skill
+2. Reads the `generate.py` script via `read_skill_resource`
+3. Executes the script using the code interpreter with appropriate parameters
+4. Returns the generated password
+
+## Learn More
+
+- [Agent Skills Specification](https://agentskills.io/)
+- [Step01: Basic Skills](../Agent_Step01_BasicSkills/) — Skills without script execution
+- [Microsoft Agent Framework Documentation](../../../../../docs/)
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/SKILL.md b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/SKILL.md
new file mode 100644
index 0000000000..c3ef67401b
--- /dev/null
+++ b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/SKILL.md
@@ -0,0 +1,16 @@
+---
+name: password-generator
+description: Generate secure passwords using a Python script. Use when asked to create passwords or credentials.
+---
+
+# Password Generator
+
+This skill generates secure passwords using a Python script.
+
+## Usage
+
+When the user requests a password:
+1. First, review `references/PASSWORD_GUIDELINES.md` to determine the recommended password length and character sets for the user's use case
+2. Load `scripts/generate.py` and adjust its parameters (length, character set) based on the guidelines and user's requirements
+3. Execute the script
+4. Present the generated password clearly
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/references/PASSWORD_GUIDELINES.md b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/references/PASSWORD_GUIDELINES.md
new file mode 100644
index 0000000000..be9145a4dd
--- /dev/null
+++ b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/references/PASSWORD_GUIDELINES.md
@@ -0,0 +1,24 @@
+# Password Generation Guidelines
+
+## General Rules
+
+- Never reuse passwords across services.
+- Always use cryptographically secure randomness (e.g., `random.SystemRandom()`).
+- Avoid dictionary words, keyboard patterns, and personal information.
+
+## Recommended Settings by Use Case
+
+| Use Case | Min Length | Character Set | Example |
+|-----------------------|-----------|----------------------------------------|--------------------------|
+| Web account | 16 | Upper + lower + digits + symbols | `G7!kQp@2xM#nW9$z` |
+| Database credential | 24 | Upper + lower + digits + symbols | `aR3$vK8!mN2@pQ7&xL5#wY` |
+| Wi-Fi / network key | 20 | Upper + lower + digits + symbols | `Ht4&jL9!rP2#mK7@xQ` |
+| API key / token | 32 | Upper + lower + digits (no symbols) | `k8Rm3xQ7nW2pL9vT4jH6yA` |
+| Encryption passphrase | 32 | Upper + lower + digits + symbols | `Xp4!kR8@mN2#vQ7&jL9$wT` |
+
+## Symbol Sets
+
+- **Standard symbols**: `!@#$%^&*()-_=+`
+- **Extended symbols**: `~`{}[]|;:'",.<>?/\`
+- **Safe symbols** (URL/shell-safe): `!@#$&*-_=+`
+- If the target system restricts symbols, use only the **safe** set.
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/scripts/generate.py b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/scripts/generate.py
new file mode 100644
index 0000000000..b44f3d9731
--- /dev/null
+++ b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/scripts/generate.py
@@ -0,0 +1,11 @@
+# Password generator script
+# Usage: Adjust 'length' as needed, then run
+
+import random
+import string
+
+length = 16 # desired length
+
+pool = string.ascii_lowercase + string.ascii_uppercase + string.digits + string.punctuation
+password = "".join(random.SystemRandom().choice(pool) for _ in range(length))
+print(f"Generated password ({length} chars): {password}")
diff --git a/dotnet/samples/02-agents/AgentSkills/README.md b/dotnet/samples/02-agents/AgentSkills/README.md
index 8488ec9eed..477a738fb8 100644
--- a/dotnet/samples/02-agents/AgentSkills/README.md
+++ b/dotnet/samples/02-agents/AgentSkills/README.md
@@ -5,3 +5,4 @@ Samples demonstrating Agent Skills capabilities.
| Sample | Description |
|--------|-------------|
| [Agent_Step01_BasicSkills](Agent_Step01_BasicSkills/) | Using Agent Skills with a ChatClientAgent, including progressive disclosure and skill resources |
+| [Agent_Step02_ScriptExecutionWithCodeInterpreter](Agent_Step02_ScriptExecutionWithCodeInterpreter/) | Using Agent Skills with script execution via the hosted code interpreter |
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkill.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkill.cs
index f28bad3ab0..da0d0b83dd 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkill.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkill.cs
@@ -1,6 +1,8 @@
// Copyright (c) Microsoft. All rights reserved.
using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
using Microsoft.Shared.Diagnostics;
namespace Microsoft.Agents.AI;
@@ -13,7 +15,8 @@ namespace Microsoft.Agents.AI;
/// and a markdown body with instructions. Resource files referenced in the body are validated at
/// discovery time and read from disk on demand.
///
-internal sealed class FileAgentSkill
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAgentSkill
{
///
/// Initializes a new instance of the class.
@@ -22,8 +25,8 @@ internal sealed class FileAgentSkill
/// The SKILL.md content after the closing --- delimiter.
/// Absolute path to the directory containing this skill.
/// Relative paths of resource files referenced in the skill body.
- public FileAgentSkill(
- SkillFrontmatter frontmatter,
+ internal FileAgentSkill(
+ FileAgentSkillFrontmatter frontmatter,
string body,
string sourcePath,
IReadOnlyList? resourceNames = null)
@@ -37,20 +40,20 @@ internal sealed class FileAgentSkill
///
/// Gets the parsed YAML frontmatter (name and description).
///
- public SkillFrontmatter Frontmatter { get; }
-
- ///
- /// Gets the SKILL.md body content (without the YAML frontmatter).
- ///
- public string Body { get; }
+ public FileAgentSkillFrontmatter Frontmatter { get; }
///
/// Gets the directory path where the skill was discovered.
///
public string SourcePath { get; }
+ ///
+ /// Gets the SKILL.md body content (without the YAML frontmatter).
+ ///
+ internal string Body { get; }
+
///
/// Gets the relative paths of resource files referenced in the skill body (e.g., "references/FAQ.md").
///
- public IReadOnlyList ResourceNames { get; }
+ internal IReadOnlyList ResourceNames { get; }
}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/SkillFrontmatter.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillFrontmatter.cs
similarity index 70%
rename from dotnet/src/Microsoft.Agents.AI/Skills/SkillFrontmatter.cs
rename to dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillFrontmatter.cs
index 123a6c43f4..c369ad319f 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/SkillFrontmatter.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillFrontmatter.cs
@@ -1,5 +1,7 @@
// Copyright (c) Microsoft. All rights reserved.
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
using Microsoft.Shared.Diagnostics;
namespace Microsoft.Agents.AI;
@@ -7,14 +9,15 @@ namespace Microsoft.Agents.AI;
///
/// Parsed YAML frontmatter from a SKILL.md file, containing the skill's name and description.
///
-internal sealed class SkillFrontmatter
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAgentSkillFrontmatter
{
///
- /// Initializes a new instance of the class.
+ /// Initializes a new instance of the class.
///
/// Skill name.
/// Skill description.
- public SkillFrontmatter(string name, string description)
+ internal FileAgentSkillFrontmatter(string name, string description)
{
this.Name = Throw.IfNullOrWhitespace(name);
this.Description = Throw.IfNullOrWhitespace(description);
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillLoader.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillLoader.cs
index 8c034b3122..8f55fc93c3 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillLoader.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillLoader.cs
@@ -2,6 +2,7 @@
using System;
using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
using System.IO;
using System.Linq;
using System.Text;
@@ -9,6 +10,7 @@ using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
+using Microsoft.Shared.DiagnosticIds;
namespace Microsoft.Agents.AI;
@@ -20,7 +22,8 @@ namespace Microsoft.Agents.AI;
/// Each file is validated for YAML frontmatter and resource integrity. Invalid skills are excluded
/// with logged warnings. Resource paths are checked against path traversal and symlink escape attacks.
///
-internal sealed partial class FileAgentSkillLoader
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed partial class FileAgentSkillLoader
{
private const string SkillFileName = "SKILL.md";
private const int MaxSearchDepth = 2;
@@ -33,13 +36,16 @@ internal sealed partial class FileAgentSkillLoader
// Example: "---\nname: foo\n---\nBody" → Group 1: "name: foo\n"
private static readonly Regex s_frontmatterRegex = new(@"\A\uFEFF?^---\s*$(.+?)^---\s*$", RegexOptions.Multiline | RegexOptions.Singleline | RegexOptions.Compiled, TimeSpan.FromSeconds(5));
- // Matches markdown links to local resource files. Group 1 = relative file path.
+ // Matches resource file references in skill markdown. Group 1 = relative file path.
+ // Supports two forms:
+ // 1. Markdown links: [text](path/file.ext)
+ // 2. Backtick-quoted paths: `path/file.ext`
// Supports optional ./ or ../ prefixes; excludes URLs (no ":" in the path character class).
// Intentionally conservative: only matches paths with word characters, hyphens, dots,
// and forward slashes. Paths with spaces or special characters are not supported.
- // Examples: [doc](refs/FAQ.md) → "refs/FAQ.md", [s](./s.json) → "./s.json",
+ // Examples: [doc](refs/FAQ.md) → "refs/FAQ.md", `./scripts/run.py` → "./scripts/run.py",
// [p](../shared/doc.txt) → "../shared/doc.txt"
- private static readonly Regex s_resourceLinkRegex = new(@"\[.*?\]\((\.?\.?/?[\w][\w\-./]*\.\w+)\)", RegexOptions.Compiled, TimeSpan.FromSeconds(5));
+ private static readonly Regex s_resourceLinkRegex = new(@"(?:\[.*?\]\(|`)(\.?\.?/?[\w][\w\-./]*\.\w+)(?:\)|`)", RegexOptions.Compiled, TimeSpan.FromSeconds(5));
// Matches YAML "key: value" lines. Group 1 = key, Group 2 = quoted value, Group 3 = unquoted value.
// Accepts single or double quotes; the lazy quantifier trims trailing whitespace on unquoted values.
@@ -111,7 +117,7 @@ internal sealed partial class FileAgentSkillLoader
///
/// The resource is not registered, resolves outside the skill directory, or does not exist.
///
- internal async Task ReadSkillResourceAsync(FileAgentSkill skill, string resourceName, CancellationToken cancellationToken = default)
+ public async Task ReadSkillResourceAsync(FileAgentSkill skill, string resourceName, CancellationToken cancellationToken = default)
{
resourceName = NormalizeResourcePath(resourceName);
@@ -189,7 +195,7 @@ internal sealed partial class FileAgentSkillLoader
string content = File.ReadAllText(skillFilePath, Encoding.UTF8);
- if (!this.TryParseSkillDocument(content, skillFilePath, out SkillFrontmatter frontmatter, out string body))
+ if (!this.TryParseSkillDocument(content, skillFilePath, out FileAgentSkillFrontmatter frontmatter, out string body))
{
return null;
}
@@ -208,7 +214,7 @@ internal sealed partial class FileAgentSkillLoader
resourceNames: resourceNames);
}
- private bool TryParseSkillDocument(string content, string skillFilePath, out SkillFrontmatter frontmatter, out string body)
+ private bool TryParseSkillDocument(string content, string skillFilePath, out FileAgentSkillFrontmatter frontmatter, out string body)
{
frontmatter = null!;
body = null!;
@@ -264,7 +270,7 @@ internal sealed partial class FileAgentSkillLoader
return false;
}
- frontmatter = new SkillFrontmatter(name, description);
+ frontmatter = new FileAgentSkillFrontmatter(name, description);
body = content.Substring(match.Index + match.Length).TrimStart();
return true;
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionContext.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionContext.cs
new file mode 100644
index 0000000000..c28333a715
--- /dev/null
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionContext.cs
@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+///
+/// Provides access to loaded skills and the skill loader for use by implementations.
+///
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAgentSkillScriptExecutionContext
+{
+ ///
+ /// Initializes a new instance of the class.
+ ///
+ /// The loaded skills dictionary.
+ /// The skill loader for reading resources.
+ internal FileAgentSkillScriptExecutionContext(Dictionary skills, FileAgentSkillLoader loader)
+ {
+ this.Skills = skills;
+ this.Loader = loader;
+ }
+
+ ///
+ /// Gets the loaded skills keyed by name.
+ ///
+ public IReadOnlyDictionary Skills { get; }
+
+ ///
+ /// Gets the skill loader for reading resources.
+ ///
+ public FileAgentSkillLoader Loader { get; }
+}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionDetails.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionDetails.cs
new file mode 100644
index 0000000000..4c12848386
--- /dev/null
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionDetails.cs
@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+///
+/// Represents the tools and instructions contributed by a .
+///
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAgentSkillScriptExecutionDetails
+{
+ ///
+ /// Gets the additional instructions to provide to the agent for script execution.
+ ///
+ public string? Instructions { get; set; }
+
+ ///
+ /// Gets the additional tools to provide to the agent for script execution.
+ ///
+ public IReadOnlyList? Tools { get; set; }
+}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutor.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutor.cs
new file mode 100644
index 0000000000..1171940e72
--- /dev/null
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutor.cs
@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+///
+/// Defines the contract for skill script execution modes.
+///
+///
+///
+/// A provides the instructions and tools needed to enable
+/// script execution within an agent skill. Concrete implementations determine how scripts
+/// are executed (e.g., via the LLM's hosted code interpreter, an external executor, or a hybrid approach).
+///
+///
+/// Use the static factory methods to create instances:
+///
+/// — executes scripts using the LLM provider's built-in code interpreter.
+///
+///
+///
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public abstract class FileAgentSkillScriptExecutor
+{
+ ///
+ /// Creates a that uses the LLM provider's hosted code interpreter for script execution.
+ ///
+ /// A instance configured for hosted code interpreter execution.
+ public static FileAgentSkillScriptExecutor HostedCodeInterpreter() => new HostedCodeInterpreterFileAgentSkillScriptExecutor();
+
+ ///
+ /// Returns the tools and instructions contributed by this executor.
+ ///
+ ///
+ /// The execution context provided by the skills provider, containing the loaded skills
+ /// and the skill loader for reading resources.
+ ///
+ /// A containing the executor's tools and instructions.
+ protected internal abstract FileAgentSkillScriptExecutionDetails GetExecutionDetails(FileAgentSkillScriptExecutionContext context);
+}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
index 847bf36a52..7acec160d4 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
@@ -48,21 +48,21 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
Each skill provides specialized instructions, reference documents, and assets for specific tasks.
- {0}
+ {skills}
When a task aligns with a skill's domain:
- 1. Use `load_skill` to retrieve the skill's instructions
- 2. Follow the provided guidance
- 3. Use `read_skill_resource` to read any references or other files mentioned by the skill
-
+ - Use `load_skill` to retrieve the skill's instructions
+ - Follow the provided guidance
+ - Use `read_skill_resource` to read any references or other files mentioned by the skill, always using the full path as written (e.g. `references/FAQ.md`, not just `FAQ.md`)
+ {executor_instructions}
Only load what is needed, when it is needed.
""";
private readonly Dictionary _skills;
private readonly ILogger _logger;
private readonly FileAgentSkillLoader _loader;
- private readonly AITool[] _tools;
+ private readonly IEnumerable _tools;
private readonly string? _skillsInstructionPrompt;
///
@@ -91,9 +91,13 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
this._loader = new FileAgentSkillLoader(this._logger);
this._skills = this._loader.DiscoverAndLoadSkills(skillPaths);
- this._skillsInstructionPrompt = BuildSkillsInstructionPrompt(options, this._skills);
+ var executionDetails = options?.ScriptExecutor is { } executor
+ ? executor.GetExecutionDetails(new(this._skills, this._loader))
+ : null;
- this._tools =
+ this._skillsInstructionPrompt = BuildSkillsInstructionPrompt(options, this._skills, executionDetails?.Instructions);
+
+ AITool[] baseTools =
[
AIFunctionFactory.Create(
this.LoadSkill,
@@ -104,6 +108,10 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
name: "read_skill_resource",
description: "Reads a file associated with a skill, such as references or assets."),
];
+
+ this._tools = executionDetails?.Tools is { Count: > 0 } executorTools
+ ? baseTools.Concat(executorTools)
+ : baseTools;
}
///
@@ -117,7 +125,7 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
return new ValueTask(new AIContext
{
Instructions = this._skillsInstructionPrompt,
- Tools = this._tools
+ Tools = this._tools,
});
}
@@ -166,24 +174,9 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
}
}
- private static string? BuildSkillsInstructionPrompt(FileAgentSkillsProviderOptions? options, Dictionary skills)
+ private static string? BuildSkillsInstructionPrompt(FileAgentSkillsProviderOptions? options, Dictionary skills, string? instructions)
{
- string promptTemplate = DefaultSkillsInstructionPrompt;
-
- if (options?.SkillsInstructionPrompt is { } optionsInstructions)
- {
- try
- {
- promptTemplate = string.Format(optionsInstructions, string.Empty);
- }
- catch (FormatException ex)
- {
- throw new ArgumentException(
- "The provided SkillsInstructionPrompt is not a valid format string. It must contain a '{0}' placeholder and escape any literal '{' or '}' by doubling them ('{{' or '}}').",
- nameof(options),
- ex);
- }
- }
+ string promptTemplate = options?.SkillsInstructionPrompt ?? DefaultSkillsInstructionPrompt;
if (skills.Count == 0)
{
@@ -202,7 +195,9 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
sb.AppendLine(" ");
}
- return string.Format(promptTemplate, sb.ToString().TrimEnd());
+ return promptTemplate
+ .Replace("{skills}", sb.ToString().TrimEnd())
+ .Replace("{executor_instructions}", instructions ?? "\n");
}
[LoggerMessage(LogLevel.Information, "Loading skill: {SkillName}")]
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProviderOptions.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProviderOptions.cs
index a47841c260..7d86d3b4ae 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProviderOptions.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProviderOptions.cs
@@ -13,8 +13,20 @@ public sealed class FileAgentSkillsProviderOptions
{
///
/// Gets or sets a custom system prompt template for advertising skills.
- /// Use {0} as the placeholder for the generated skills list.
+ /// Use {skills} as the placeholder for the generated skills list and
+ /// {executor_instructions} for executor-provided instructions.
/// When , a default template is used.
///
public string? SkillsInstructionPrompt { get; set; }
+
+ ///
+ /// Gets or sets the skill executor that enables script execution for loaded skills.
+ ///
+ ///
+ /// When (the default), script execution is disabled and skills only provide
+ /// instructions and resources. Set this to a instance (e.g.,
+ /// ) to enable script execution with
+ /// mode-specific instructions and tools.
+ ///
+ public FileAgentSkillScriptExecutor? ScriptExecutor { get; set; }
}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/HostedCodeInterpreterFileAgentSkillScriptExecutor.cs b/dotnet/src/Microsoft.Agents.AI/Skills/HostedCodeInterpreterFileAgentSkillScriptExecutor.cs
new file mode 100644
index 0000000000..88fb1f86a2
--- /dev/null
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/HostedCodeInterpreterFileAgentSkillScriptExecutor.cs
@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI;
+
+///
+/// A that uses the LLM provider's hosted code interpreter for script execution.
+///
+///
+/// This executor directs the LLM to load scripts via read_skill_resource and execute them
+/// using the provider's built-in code interpreter. A is
+/// registered to signal the provider to enable its code interpreter sandbox.
+///
+internal sealed class HostedCodeInterpreterFileAgentSkillScriptExecutor : FileAgentSkillScriptExecutor
+{
+ private static readonly FileAgentSkillScriptExecutionDetails s_contribution = new()
+ {
+ Instructions =
+ """
+
+ Some skills include executable scripts (e.g., Python files) in their resources.
+ When a skill's instructions reference a script:
+ 1. Use `read_skill_resource` to load the script content
+ 2. Execute the script using the code interpreter
+
+ """,
+ Tools = [new HostedCodeInterpreterTool()],
+ };
+
+ ///
+#pragma warning disable RCS1168 // Parameter name differs from base name
+ protected internal override FileAgentSkillScriptExecutionDetails GetExecutionDetails(FileAgentSkillScriptExecutionContext _) => s_contribution;
+#pragma warning restore RCS1168 // Parameter name differs from base name
+}
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
index c34eb6d7f2..c9e154a277 100644
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
@@ -501,7 +501,7 @@ public sealed class FileAgentSkillLoaderTests : IDisposable
}
// Manually construct a skill that bypasses discovery validation
- var frontmatter = new SkillFrontmatter("symlink-read-skill", "A skill");
+ var frontmatter = new FileAgentSkillFrontmatter("symlink-read-skill", "A skill");
var skill = new FileAgentSkill(
frontmatter: frontmatter,
body: "See [doc](refs/data.md).",
@@ -532,6 +532,54 @@ public sealed class FileAgentSkillLoaderTests : IDisposable
Assert.Equal("Body content.", skills["bom-skill"].Body);
}
+ [Theory]
+ [InlineData("No resource references.", new string[0])]
+ [InlineData("Review `refs/FAQ.md` for details.", new[] { "refs/FAQ.md" })]
+ [InlineData("See [guide](refs/guide.md) then run `scripts/run.py`.", new[] { "refs/guide.md", "scripts/run.py" })]
+ public void DiscoverAndLoadSkills_ResourceReferences_ExtractsExpectedResourceNames(string body, string[] expectedResources)
+ {
+ // Arrange — create skill with resource files on disk so validation passes
+ string skillDir = Path.Combine(this._testRoot, "res-skill");
+ Directory.CreateDirectory(skillDir);
+ foreach (string resource in expectedResources)
+ {
+ string resourcePath = Path.Combine(skillDir, resource.Replace('/', Path.DirectorySeparatorChar));
+ Directory.CreateDirectory(Path.GetDirectoryName(resourcePath)!);
+ File.WriteAllText(resourcePath, "content");
+ }
+
+ File.WriteAllText(
+ Path.Combine(skillDir, "SKILL.md"),
+ $"---\nname: res-skill\ndescription: Resource test\n---\n{body}");
+
+ // Act
+ var skills = this._loader.DiscoverAndLoadSkills(new[] { this._testRoot });
+
+ // Assert
+ Assert.Single(skills);
+ var skill = skills["res-skill"];
+ Assert.Equal(expectedResources.Length, skill.ResourceNames.Count);
+ foreach (string expected in expectedResources)
+ {
+ Assert.Contains(expected, skill.ResourceNames);
+ }
+ }
+
+ [Fact]
+ public async Task ReadSkillResourceAsync_BacktickResourcePath_ReturnsContentAsync()
+ {
+ // Arrange — skill body uses backtick-quoted path
+ _ = this.CreateSkillDirectoryWithResource("backtick-read", "A skill", "Load `refs/doc.md` first.", "refs/doc.md", "Backtick content.");
+ var skills = this._loader.DiscoverAndLoadSkills(new[] { this._testRoot });
+ var skill = skills["backtick-read"];
+
+ // Act
+ string content = await this._loader.ReadSkillResourceAsync(skill, "refs/doc.md");
+
+ // Assert
+ Assert.Equal("Backtick content.", content);
+ }
+
private string CreateSkillDirectory(string name, string description, string body)
{
string skillDir = Path.Combine(this._testRoot, name);
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillScriptExecutorTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillScriptExecutorTests.cs
new file mode 100644
index 0000000000..1be56e49c9
--- /dev/null
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillScriptExecutorTests.cs
@@ -0,0 +1,170 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging.Abstractions;
+
+namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
+
+///
+/// Unit tests for and its integration with .
+///
+public sealed class FileAgentSkillScriptExecutorTests : IDisposable
+{
+ private readonly string _testRoot;
+ private readonly TestAIAgent _agent = new();
+ private static readonly FileAgentSkillScriptExecutionContext s_emptyContext = new(
+ new Dictionary(StringComparer.OrdinalIgnoreCase),
+ new FileAgentSkillLoader(NullLogger.Instance));
+
+ public FileAgentSkillScriptExecutorTests()
+ {
+ this._testRoot = Path.Combine(Path.GetTempPath(), "skill-executor-tests-" + Guid.NewGuid().ToString("N"));
+ Directory.CreateDirectory(this._testRoot);
+ }
+
+ public void Dispose()
+ {
+ if (Directory.Exists(this._testRoot))
+ {
+ Directory.Delete(this._testRoot, recursive: true);
+ }
+ }
+
+ [Fact]
+ public void HostedCodeInterpreter_ReturnsNonNullInstance()
+ {
+ // Act
+ var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
+
+ // Assert
+ Assert.NotNull(executor);
+ }
+
+ [Fact]
+ public void HostedCodeInterpreter_GetExecutionDetails_ReturnsNonNullInstructions()
+ {
+ // Arrange
+ var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
+
+ // Act
+ var details = executor.GetExecutionDetails(s_emptyContext);
+
+ // Assert
+ Assert.NotNull(details);
+ Assert.NotNull(details.Instructions);
+ Assert.NotEmpty(details.Instructions);
+ }
+
+ [Fact]
+ public void HostedCodeInterpreter_GetExecutionDetails_ReturnsNonEmptyToolsList()
+ {
+ // Arrange
+ var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
+
+ // Act
+ var details = executor.GetExecutionDetails(s_emptyContext);
+
+ // Assert
+ Assert.NotNull(details);
+ Assert.NotNull(details.Tools);
+ Assert.NotEmpty(details.Tools);
+ }
+
+ [Fact]
+ public async Task Provider_WithExecutor_IncludesExecutorInstructionsInPromptAsync()
+ {
+ // Arrange
+ CreateSkill(this._testRoot, "exec-skill", "Executor test", "Body.");
+ var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
+ var options = new FileAgentSkillsProviderOptions { ScriptExecutor = executor };
+ var provider = new FileAgentSkillsProvider(this._testRoot, options);
+ var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
+
+ // Act
+ var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
+
+ // Assert — executor instructions should be merged into the prompt
+ Assert.NotNull(result.Instructions);
+ Assert.Contains("code interpreter", result.Instructions, StringComparison.OrdinalIgnoreCase);
+ }
+
+ [Fact]
+ public async Task Provider_WithExecutor_IncludesExecutorToolsAsync()
+ {
+ // Arrange
+ CreateSkill(this._testRoot, "tools-exec-skill", "Executor tools test", "Body.");
+ var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
+ var options = new FileAgentSkillsProviderOptions { ScriptExecutor = executor };
+ var provider = new FileAgentSkillsProvider(this._testRoot, options);
+ var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
+
+ // Act
+ var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
+
+ // Assert — should have 3 tools: load_skill, read_skill_resource, and HostedCodeInterpreterTool
+ Assert.NotNull(result.Tools);
+ Assert.Equal(3, result.Tools!.Count());
+ var toolNames = result.Tools!.Select(t => t.Name).ToList();
+ Assert.Contains("load_skill", toolNames);
+ Assert.Contains("read_skill_resource", toolNames);
+ Assert.Single(result.Tools!, t => t is HostedCodeInterpreterTool);
+ }
+
+ [Fact]
+ public async Task Provider_WithoutExecutor_DoesNotIncludeExecutorToolsAsync()
+ {
+ // Arrange
+ CreateSkill(this._testRoot, "no-exec-skill", "No executor test", "Body.");
+ var provider = new FileAgentSkillsProvider(this._testRoot);
+ var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
+
+ // Act
+ var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
+
+ // Assert — should only have the two base tools
+ Assert.NotNull(result.Tools);
+ Assert.Equal(2, result.Tools!.Count());
+ }
+
+ [Fact]
+ public async Task Provider_WithHostedCodeInterpreter_MergesScriptInstructionsIntoPromptAsync()
+ {
+ // Arrange
+ CreateSkill(this._testRoot, "merge-skill", "Merge test", "Body.");
+ var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
+ var options = new FileAgentSkillsProviderOptions { ScriptExecutor = executor };
+ var provider = new FileAgentSkillsProvider(this._testRoot, options);
+ var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
+
+ // Act
+ var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
+
+ // Assert — prompt should contain both the skill listing and the executor's script instructions
+ Assert.NotNull(result.Instructions);
+ string instructions = result.Instructions!;
+
+ // Skill listing is present
+ Assert.Contains("merge-skill", instructions);
+ Assert.Contains("Merge test", instructions);
+
+ // Hosted code interpreter script instructions are merged into the prompt
+ Assert.Contains("executable scripts", instructions);
+ Assert.Contains("read_skill_resource", instructions);
+ Assert.Contains("Execute the script using the code interpreter", instructions);
+ }
+
+ private static void CreateSkill(string root, string name, string description, string body)
+ {
+ string skillDir = Path.Combine(root, name);
+ Directory.CreateDirectory(skillDir);
+ File.WriteAllText(
+ Path.Combine(skillDir, "SKILL.md"),
+ $"---\nname: {name}\ndescription: {description}\n---\n{body}");
+ }
+}
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
index 6bfaf1b546..f95f3a7080 100644
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
@@ -96,7 +96,7 @@ public sealed class FileAgentSkillsProviderTests : IDisposable
this.CreateSkill("custom-prompt-skill", "Custom prompt", "Body.");
var options = new FileAgentSkillsProviderOptions
{
- SkillsInstructionPrompt = "Custom template: {0}"
+ SkillsInstructionPrompt = "Custom template: {skills}"
};
var provider = new FileAgentSkillsProvider(this._testRoot, options);
var inputContext = new AIContext();
@@ -110,21 +110,6 @@ public sealed class FileAgentSkillsProviderTests : IDisposable
Assert.StartsWith("Custom template:", result.Instructions);
}
- [Fact]
- public void Constructor_InvalidPromptTemplate_ThrowsArgumentException()
- {
- // Arrange — template with unescaped braces and no valid {0} placeholder
- var options = new FileAgentSkillsProviderOptions
- {
- SkillsInstructionPrompt = "Bad template with {unescaped} braces"
- };
-
- // Act & Assert
- var ex = Assert.Throws(() => new FileAgentSkillsProvider(this._testRoot, options));
- Assert.Contains("SkillsInstructionPrompt", ex.Message);
- Assert.Equal("options", ex.ParamName);
- }
-
[Fact]
public async Task InvokingCoreAsync_SkillNamesAreXmlEscapedAsync()
{
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/HostedCodeInterpreterFileAgentSkillScriptExecutorTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/HostedCodeInterpreterFileAgentSkillScriptExecutorTests.cs
new file mode 100644
index 0000000000..84a4446779
--- /dev/null
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/HostedCodeInterpreterFileAgentSkillScriptExecutorTests.cs
@@ -0,0 +1,72 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging.Abstractions;
+
+namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
+
+///
+/// Unit tests for .
+///
+public sealed class HostedCodeInterpreterFileAgentSkillScriptExecutorTests
+{
+ private static readonly FileAgentSkillScriptExecutionContext s_emptyContext = new(
+ new Dictionary(StringComparer.OrdinalIgnoreCase),
+ new FileAgentSkillLoader(NullLogger.Instance));
+
+ [Fact]
+ public void GetExecutionDetails_ReturnsScriptExecutionGuidance()
+ {
+ // Arrange
+ var executor = new HostedCodeInterpreterFileAgentSkillScriptExecutor();
+
+ // Act
+ var details = executor.GetExecutionDetails(s_emptyContext);
+
+ // Assert
+ Assert.NotNull(details.Instructions);
+ Assert.Contains("read_skill_resource", details.Instructions);
+ Assert.Contains("code interpreter", details.Instructions);
+ }
+
+ [Fact]
+ public void GetExecutionDetails_ReturnsSingleHostedCodeInterpreterTool()
+ {
+ // Arrange
+ var executor = new HostedCodeInterpreterFileAgentSkillScriptExecutor();
+
+ // Act
+ var details = executor.GetExecutionDetails(s_emptyContext);
+
+ // Assert
+ Assert.NotNull(details.Tools);
+ Assert.Single(details.Tools!);
+ Assert.IsType(details.Tools![0]);
+ }
+
+ [Fact]
+ public void GetExecutionDetails_ReturnsSameInstanceOnMultipleCalls()
+ {
+ // Arrange
+ var executor = new HostedCodeInterpreterFileAgentSkillScriptExecutor();
+
+ // Act
+ var details1 = executor.GetExecutionDetails(s_emptyContext);
+ var details2 = executor.GetExecutionDetails(s_emptyContext);
+
+ // Assert — static details should be reused
+ Assert.Same(details1, details2);
+ }
+
+ [Fact]
+ public void FactoryMethod_ReturnsHostedCodeInterpreterFileAgentSkillScriptExecutor()
+ {
+ // Act
+ var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
+
+ // Assert
+ Assert.IsType(executor);
+ }
+}
From 822a3eb5eac7bda64dbe28ff53553249bc882719 Mon Sep 17 00:00:00 2001
From: westey <164392973+westey-m@users.noreply.github.com>
Date: Thu, 26 Feb 2026 14:16:21 +0000
Subject: [PATCH 03/24] .NET: Add helpers to more easily access in-memory
ChatHistory and make ChatHistoryProvider management more configurable.
(#4224)
* Add helpers to more easily access in-memory ChatHistory and make ChatHistoryProvider management more configurable.
* Apply suggestion from @Copilot
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
.../Agent_Step13_ChatReduction/Program.cs | 26 +-
.../AgentSessionExtensions.cs | 67 +++++
.../ChatClient/ChatClientAgent.cs | 36 +--
.../ChatClient/ChatClientAgentLogMessages.cs | 13 +
.../ChatClient/ChatClientAgentOptions.cs | 34 +++
.../AgentSessionExtensionsTests.cs | 231 ++++++++++++++++++
.../ChatClient/ChatClientAgentOptionsTests.cs | 14 +-
...tClientAgent_ChatHistoryManagementTests.cs | 118 +++++++++
8 files changed, 510 insertions(+), 29 deletions(-)
create mode 100644 dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSessionExtensions.cs
create mode 100644 dotnet/tests/Microsoft.Agents.AI.Abstractions.UnitTests/AgentSessionExtensionsTests.cs
diff --git a/dotnet/samples/02-agents/Agents/Agent_Step13_ChatReduction/Program.cs b/dotnet/samples/02-agents/Agents/Agent_Step13_ChatReduction/Program.cs
index c95f46a6c0..fe93ed785c 100644
--- a/dotnet/samples/02-agents/Agents/Agent_Step13_ChatReduction/Program.cs
+++ b/dotnet/samples/02-agents/Agents/Agent_Step13_ChatReduction/Program.cs
@@ -10,7 +10,6 @@ using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using OpenAI.Chat;
-using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
@@ -39,9 +38,10 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session
// We can use the ChatHistoryProvider, that is also used by the agent, to read the
// chat history from the session state, and see how the reducer is affecting the stored messages.
// Here we expect to see 2 messages, the original user message and the agent response message.
-var provider = agent.GetService();
-List? chatHistory = provider?.GetMessages(session);
-Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
+if (session.TryGetInMemoryChatHistory(out var chatHistory))
+{
+ Console.WriteLine($"\nChat history has {chatHistory.Count} messages.\n");
+}
// Invoke the agent a few more times.
Console.WriteLine(await agent.RunAsync("Tell me a joke about a robot.", session));
@@ -51,16 +51,22 @@ Console.WriteLine(await agent.RunAsync("Tell me a joke about a robot.", session)
// to trigger the reducer is just before messages are contributed to a new agent run.
// So at this time, we have not yet triggered the reducer for the most recently added messages,
// and they are still in the chat history.
-chatHistory = provider?.GetMessages(session);
-Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
+if (session.TryGetInMemoryChatHistory(out chatHistory))
+{
+ Console.WriteLine($"\nChat history has {chatHistory.Count} messages.\n");
+}
Console.WriteLine(await agent.RunAsync("Tell me a joke about a lemur.", session));
-chatHistory = provider?.GetMessages(session);
-Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
+if (session.TryGetInMemoryChatHistory(out chatHistory))
+{
+ Console.WriteLine($"\nChat history has {chatHistory.Count} messages.\n");
+}
// At this point, the chat history has exceeded the limit and the original message will not exist anymore,
// so asking a follow up question about it may not work as expected.
Console.WriteLine(await agent.RunAsync("What was the first joke I asked you to tell again?", session));
-chatHistory = provider?.GetMessages(session);
-Console.WriteLine($"\nChat history has {chatHistory?.Count} messages.\n");
+if (session.TryGetInMemoryChatHistory(out chatHistory))
+{
+ Console.WriteLine($"\nChat history has {chatHistory.Count} messages.\n");
+}
diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSessionExtensions.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSessionExtensions.cs
new file mode 100644
index 0000000000..dbc3b878bf
--- /dev/null
+++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentSessionExtensions.cs
@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+///
+/// Provides extension methods for .
+///
+public static class AgentSessionExtensions
+{
+ ///
+ /// Attempts to retrieve the in-memory chat history messages associated with the specified agent session, if the agent is storing memories in the session using the
+ ///
+ ///
+ /// This method is only applicable when using and if the service does not require in-service chat history storage.
+ ///
+ /// The agent session from which to retrieve in-memory chat history.
+ /// When this method returns, contains the list of chat history messages if available; otherwise, null.
+ /// An optional key used to identify the chat history state in the session's state bag. If null, the default key for
+ /// in-memory chat history is used.
+ /// Optional JSON serializer options to use when accessing the session state. If null, default options are used.
+ /// if the in-memory chat history messages were found and retrieved; otherwise.
+ public static bool TryGetInMemoryChatHistory(this AgentSession session, [MaybeNullWhen(false)] out List messages, string? stateKey = null, JsonSerializerOptions? jsonSerializerOptions = null)
+ {
+ _ = Throw.IfNull(session);
+
+ if (session.StateBag.TryGetValue(stateKey ?? nameof(InMemoryChatHistoryProvider), out InMemoryChatHistoryProvider.State? state, jsonSerializerOptions ?? AgentAbstractionsJsonUtilities.DefaultOptions) && state?.Messages is not null)
+ {
+ messages = state.Messages;
+ return true;
+ }
+
+ messages = null;
+ return false;
+ }
+
+ ///
+ /// Sets the in-memory chat message history for the specified agent session, replacing any existing messages.
+ ///
+ ///
+ /// This method is only applicable when using and if the service does not require in-service chat history storage.
+ /// If messages are set, but a different is used, or if chat history is stored in the underlying AI service, the messages will be ignored.
+ ///
+ /// The agent session whose in-memory chat history will be updated.
+ /// The list of chat messages to store in memory for the session. Replaces any existing messages for the specified
+ /// state key.
+ /// The key used to identify the in-memory chat history within the session's state bag. If null, a default key is
+ /// used.
+ /// The serializer options used when accessing or storing the state. If null, default options are applied.
+ public static void SetInMemoryChatHistory(this AgentSession session, List messages, string? stateKey = null, JsonSerializerOptions? jsonSerializerOptions = null)
+ {
+ _ = Throw.IfNull(session);
+
+ if (session.StateBag.TryGetValue(stateKey ?? nameof(InMemoryChatHistoryProvider), out InMemoryChatHistoryProvider.State? state, jsonSerializerOptions ?? AgentAbstractionsJsonUtilities.DefaultOptions) && state is not null)
+ {
+ state.Messages = messages;
+ return;
+ }
+
+ session.StateBag.SetValue(stateKey ?? nameof(InMemoryChatHistoryProvider), new InMemoryChatHistoryProvider.State() { Messages = messages }, jsonSerializerOptions ?? AgentAbstractionsJsonUtilities.DefaultOptions);
+ }
+}
diff --git a/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs b/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs
index b1dbacd438..d52ea52e43 100644
--- a/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs
+++ b/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs
@@ -109,7 +109,7 @@ public sealed partial class ChatClientAgent : AIAgent
// Use the ChatHistoryProvider from options if provided.
// If one was not provided, and we later find out that the underlying service does not manage chat history server-side,
// we will use the default InMemoryChatHistoryProvider at that time.
- this.ChatHistoryProvider = options?.ChatHistoryProvider;
+ this.ChatHistoryProvider = options?.ChatHistoryProvider ?? new InMemoryChatHistoryProvider();
this.AIContextProviders = this._agentOptions?.AIContextProviders as IReadOnlyList ?? this._agentOptions?.AIContextProviders?.ToList();
// Validate that no two providers share the same StateKey, since they would overwrite each other's state in the session.
@@ -743,25 +743,31 @@ public sealed partial class ChatClientAgent : AIAgent
if (!string.IsNullOrWhiteSpace(responseConversationId))
{
- if (this.ChatHistoryProvider is not null)
+ if (this._agentOptions?.ChatHistoryProvider is not null)
{
// The agent has a ChatHistoryProvider configured, but the service returned a conversation id,
// meaning the service manages chat history server-side. Both cannot be used simultaneously.
- throw new InvalidOperationException(
- $"Only {nameof(ChatClientAgentSession.ConversationId)} or {nameof(this.ChatHistoryProvider)} may be used, but not both. The service returned a conversation id indicating server-side chat history management, but the agent has a {nameof(this.ChatHistoryProvider)} configured.");
+ if (this._agentOptions?.WarnOnChatHistoryProviderConflict is true)
+ {
+ this._logger.LogAgentChatClientHistoryProviderConflict(nameof(ChatClientAgentSession.ConversationId), nameof(this.ChatHistoryProvider), this.Id, this.GetLoggingAgentName());
+ }
+
+ if (this._agentOptions?.ThrowOnChatHistoryProviderConflict is true)
+ {
+ throw new InvalidOperationException(
+ $"Only {nameof(ChatClientAgentSession.ConversationId)} or {nameof(this.ChatHistoryProvider)} may be used, but not both. The service returned a conversation id indicating server-side chat history management, but the agent has a {nameof(this.ChatHistoryProvider)} configured.");
+ }
+
+ if (this._agentOptions?.ClearOnChatHistoryProviderConflict is true)
+ {
+ this.ChatHistoryProvider = null;
+ }
}
// If we got a conversation id back from the chat client, it means that the service supports server side session storage
// so we should update the session with the new id.
session.ConversationId = responseConversationId;
}
- else
- {
- // If the service doesn't use service side chat history storage (i.e. we got no id back from invocation), and
- // the agent has no ChatHistoryProvider yet, we should use the default InMemoryChatHistoryProvider so that
- // we have somewhere to store the chat history.
- this.ChatHistoryProvider ??= new InMemoryChatHistoryProvider();
- }
}
private Task NotifyChatHistoryProviderOfFailureAsync(
@@ -807,13 +813,7 @@ public sealed partial class ChatClientAgent : AIAgent
private ChatHistoryProvider? ResolveChatHistoryProvider(ChatOptions? chatOptions, ChatClientAgentSession session)
{
- ChatHistoryProvider? provider = this.ChatHistoryProvider;
-
- if (session.ConversationId is not null && provider is not null)
- {
- throw new InvalidOperationException(
- $"Only {nameof(ChatClientAgentSession.ConversationId)} or {nameof(this.ChatHistoryProvider)} may be used, but not both. The current {nameof(ChatClientAgentSession)} has a {nameof(ChatClientAgentSession.ConversationId)} indicating server-side chat history management, but the agent has a {nameof(this.ChatHistoryProvider)} configured.");
- }
+ ChatHistoryProvider? provider = session.ConversationId is null ? this.ChatHistoryProvider : null;
// If someone provided an override ChatHistoryProvider via AdditionalProperties, we should use that instead.
if (chatOptions?.AdditionalProperties?.TryGetValue(out ChatHistoryProvider? overrideProvider) is true)
diff --git a/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentLogMessages.cs b/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentLogMessages.cs
index a1804a0383..98ff4583dc 100644
--- a/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentLogMessages.cs
+++ b/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentLogMessages.cs
@@ -56,4 +56,17 @@ internal static partial class ChatClientAgentLogMessages
string agentId,
string agentName,
Type clientType);
+
+ ///
+ /// Logs warning about conflict.
+ ///
+ [LoggerMessage(
+ Level = LogLevel.Warning,
+ Message = "Agent {AgentId}/{AgentName}: Only {ConversationIdName} or {ChatHistoryProviderName} may be used, but not both. The service returned a conversation id indicating server-side chat history management, but the agent has a {ChatHistoryProviderName} configured.")]
+ public static partial void LogAgentChatClientHistoryProviderConflict(
+ this ILogger logger,
+ string conversationIdName,
+ string chatHistoryProviderName,
+ string agentId,
+ string agentName);
}
diff --git a/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs b/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs
index ddca9197ab..38cad40bbe 100644
--- a/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs
+++ b/dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs
@@ -59,6 +59,36 @@ public sealed class ChatClientAgentOptions
///
public bool UseProvidedChatClientAsIs { get; set; }
+ ///
+ /// Gets or sets a value indicating whether to set the to
+ /// if the underlying AI service indicates that it manages chat history (for example, by returning a conversation id in the response), but a is configured for the agent.
+ ///
+ ///
+ /// Note that even if this setting is set to , the will still not be used if the underlying AI service indicates that it manages chat history.
+ ///
+ ///
+ /// Default is .
+ ///
+ public bool ClearOnChatHistoryProviderConflict { get; set; } = true;
+
+ ///
+ /// Gets or sets a value indicating whether to log a warning if the underlying AI service indicates that it manages chat history
+ /// (for example, by returning a conversation id in the response), but a is configured for the agent.
+ ///
+ ///
+ /// Default is .
+ ///
+ public bool WarnOnChatHistoryProviderConflict { get; set; } = true;
+
+ ///
+ /// Gets or sets a value indicating whether an exception is thrown if the underlying AI service indicates that it manages chat history
+ /// (for example, by returning a conversation id in the response), but a is configured for the agent.
+ ///
+ ///
+ /// Default is .
+ ///
+ public bool ThrowOnChatHistoryProviderConflict { get; set; } = true;
+
///
/// Creates a new instance of with the same values as this instance.
///
@@ -71,5 +101,9 @@ public sealed class ChatClientAgentOptions
ChatOptions = this.ChatOptions?.Clone(),
ChatHistoryProvider = this.ChatHistoryProvider,
AIContextProviders = this.AIContextProviders is null ? null : new List(this.AIContextProviders),
+ UseProvidedChatClientAsIs = this.UseProvidedChatClientAsIs,
+ ClearOnChatHistoryProviderConflict = this.ClearOnChatHistoryProviderConflict,
+ WarnOnChatHistoryProviderConflict = this.WarnOnChatHistoryProviderConflict,
+ ThrowOnChatHistoryProviderConflict = this.ThrowOnChatHistoryProviderConflict,
};
}
diff --git a/dotnet/tests/Microsoft.Agents.AI.Abstractions.UnitTests/AgentSessionExtensionsTests.cs b/dotnet/tests/Microsoft.Agents.AI.Abstractions.UnitTests/AgentSessionExtensionsTests.cs
new file mode 100644
index 0000000000..7d06fa854d
--- /dev/null
+++ b/dotnet/tests/Microsoft.Agents.AI.Abstractions.UnitTests/AgentSessionExtensionsTests.cs
@@ -0,0 +1,231 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.Extensions.AI;
+using Moq;
+
+namespace Microsoft.Agents.AI.Abstractions.UnitTests;
+
+///
+/// Tests for .
+///
+public class AgentSessionExtensionsTests
+{
+ #region TryGetInMemoryChatHistory Tests
+
+ [Fact]
+ public void TryGetInMemoryChatHistory_WithNullSession_ThrowsArgumentNullException()
+ {
+ // Arrange
+ AgentSession session = null!;
+
+ // Act & Assert
+ Assert.Throws(() => session.TryGetInMemoryChatHistory(out _));
+ }
+
+ [Fact]
+ public void TryGetInMemoryChatHistory_WhenStateExists_ReturnsTrueAndMessages()
+ {
+ // Arrange
+ var session = new Mock().Object;
+ var expectedMessages = new List
+ {
+ new(ChatRole.User, "Hello"),
+ new(ChatRole.Assistant, "Hi there!")
+ };
+
+ session.StateBag.SetValue(
+ nameof(InMemoryChatHistoryProvider),
+ new InMemoryChatHistoryProvider.State { Messages = expectedMessages });
+
+ // Act
+ var result = session.TryGetInMemoryChatHistory(out var messages);
+
+ // Assert
+ Assert.True(result);
+ Assert.NotNull(messages);
+ Assert.Same(expectedMessages, messages);
+ }
+
+ [Fact]
+ public void TryGetInMemoryChatHistory_WhenStateDoesNotExist_ReturnsFalse()
+ {
+ // Arrange
+ var session = new Mock().Object;
+
+ // Act
+ var result = session.TryGetInMemoryChatHistory(out var messages);
+
+ // Assert
+ Assert.False(result);
+ Assert.Null(messages);
+ }
+
+ [Fact]
+ public void TryGetInMemoryChatHistory_WithCustomStateKey_UsesCustomKey()
+ {
+ // Arrange
+ var session = new Mock().Object;
+ const string CustomKey = "custom-history-key";
+ var expectedMessages = new List
+ {
+ new(ChatRole.User, "Test message")
+ };
+
+ session.StateBag.SetValue(
+ CustomKey,
+ new InMemoryChatHistoryProvider.State { Messages = expectedMessages });
+
+ // Act
+ var result = session.TryGetInMemoryChatHistory(out var messages, stateKey: CustomKey);
+
+ // Assert
+ Assert.True(result);
+ Assert.NotNull(messages);
+ Assert.Same(expectedMessages, messages);
+ }
+
+ [Fact]
+ public void TryGetInMemoryChatHistory_WithCustomStateKey_DoesNotFindDefaultKey()
+ {
+ // Arrange
+ var session = new Mock().Object;
+ var expectedMessages = new List
+ {
+ new(ChatRole.User, "Test message")
+ };
+
+ session.StateBag.SetValue(
+ nameof(InMemoryChatHistoryProvider),
+ new InMemoryChatHistoryProvider.State { Messages = expectedMessages });
+
+ // Act
+ var result = session.TryGetInMemoryChatHistory(out var messages, stateKey: "other-key");
+
+ // Assert
+ Assert.False(result);
+ Assert.Null(messages);
+ }
+
+ [Fact]
+ public void TryGetInMemoryChatHistory_WhenStateExistsWithNullMessages_ReturnsFalse()
+ {
+ // Arrange
+ var session = new Mock().Object;
+ session.StateBag.SetValue(
+ nameof(InMemoryChatHistoryProvider),
+ new InMemoryChatHistoryProvider.State { Messages = null! });
+
+ // Act
+ var result = session.TryGetInMemoryChatHistory(out var messages);
+
+ // Assert
+ Assert.False(result);
+ Assert.Null(messages);
+ }
+
+ #endregion
+
+ #region SetInMemoryChatHistory Tests
+
+ [Fact]
+ public void SetInMemoryChatHistory_WithNullSession_ThrowsArgumentNullException()
+ {
+ // Arrange
+ AgentSession session = null!;
+ var messages = new List();
+
+ // Act & Assert
+ Assert.Throws(() => session.SetInMemoryChatHistory(messages));
+ }
+
+ [Fact]
+ public void SetInMemoryChatHistory_WhenNoExistingState_CreatesNewState()
+ {
+ // Arrange
+ var session = new Mock().Object;
+ var messages = new List
+ {
+ new(ChatRole.User, "Hello"),
+ new(ChatRole.Assistant, "Hi!")
+ };
+
+ // Act
+ session.SetInMemoryChatHistory(messages);
+
+ // Assert
+ var result = session.TryGetInMemoryChatHistory(out var retrievedMessages);
+ Assert.True(result);
+ Assert.Same(messages, retrievedMessages);
+ }
+
+ [Fact]
+ public void SetInMemoryChatHistory_WhenExistingState_ReplacesMessages()
+ {
+ // Arrange
+ var session = new Mock().Object;
+ var originalMessages = new List
+ {
+ new(ChatRole.User, "Original")
+ };
+ var newMessages = new List
+ {
+ new(ChatRole.User, "New message"),
+ new(ChatRole.Assistant, "New response")
+ };
+
+ session.SetInMemoryChatHistory(originalMessages);
+
+ // Act
+ session.SetInMemoryChatHistory(newMessages);
+
+ // Assert
+ var result = session.TryGetInMemoryChatHistory(out var retrievedMessages);
+ Assert.True(result);
+ Assert.Same(newMessages, retrievedMessages);
+ }
+
+ [Fact]
+ public void SetInMemoryChatHistory_WithCustomStateKey_UsesCustomKey()
+ {
+ // Arrange
+ var session = new Mock().Object;
+ const string CustomKey = "custom-history-key";
+ var messages = new List
+ {
+ new(ChatRole.User, "Test")
+ };
+
+ // Act
+ session.SetInMemoryChatHistory(messages, stateKey: CustomKey);
+
+ // Assert
+ var result = session.TryGetInMemoryChatHistory(out var retrievedMessages, stateKey: CustomKey);
+ Assert.True(result);
+ Assert.Same(messages, retrievedMessages);
+
+ // Verify default key is not set
+ var defaultResult = session.TryGetInMemoryChatHistory(out _);
+ Assert.False(defaultResult);
+ }
+
+ [Fact]
+ public void SetInMemoryChatHistory_WithEmptyList_SetsEmptyList()
+ {
+ // Arrange
+ var session = new Mock().Object;
+ var messages = new List();
+
+ // Act
+ session.SetInMemoryChatHistory(messages);
+
+ // Assert
+ var result = session.TryGetInMemoryChatHistory(out var retrievedMessages);
+ Assert.True(result);
+ Assert.NotNull(retrievedMessages);
+ Assert.Empty(retrievedMessages);
+ }
+
+ #endregion
+}
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs
index b8e3c57af6..1798afb433 100644
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs
@@ -23,6 +23,10 @@ public class ChatClientAgentOptionsTests
Assert.Null(options.ChatOptions);
Assert.Null(options.ChatHistoryProvider);
Assert.Null(options.AIContextProviders);
+ Assert.False(options.UseProvidedChatClientAsIs);
+ Assert.True(options.ClearOnChatHistoryProviderConflict);
+ Assert.True(options.WarnOnChatHistoryProviderConflict);
+ Assert.True(options.ThrowOnChatHistoryProviderConflict);
}
[Fact]
@@ -125,7 +129,11 @@ public class ChatClientAgentOptionsTests
ChatOptions = new() { Tools = tools },
Id = "test-id",
ChatHistoryProvider = mockChatHistoryProvider,
- AIContextProviders = [mockAIContextProvider]
+ AIContextProviders = [mockAIContextProvider],
+ UseProvidedChatClientAsIs = true,
+ ClearOnChatHistoryProviderConflict = false,
+ WarnOnChatHistoryProviderConflict = false,
+ ThrowOnChatHistoryProviderConflict = false,
};
// Act
@@ -138,6 +146,10 @@ public class ChatClientAgentOptionsTests
Assert.Equal(original.Description, clone.Description);
Assert.Same(original.ChatHistoryProvider, clone.ChatHistoryProvider);
Assert.Equal(original.AIContextProviders, clone.AIContextProviders);
+ Assert.Equal(original.UseProvidedChatClientAsIs, clone.UseProvidedChatClientAsIs);
+ Assert.Equal(original.ClearOnChatHistoryProviderConflict, clone.ClearOnChatHistoryProviderConflict);
+ Assert.Equal(original.WarnOnChatHistoryProviderConflict, clone.WarnOnChatHistoryProviderConflict);
+ Assert.Equal(original.ThrowOnChatHistoryProviderConflict, clone.ThrowOnChatHistoryProviderConflict);
// ChatOptions should be cloned, not the same reference
Assert.NotSame(original.ChatOptions, clone.ChatOptions);
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgent_ChatHistoryManagementTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgent_ChatHistoryManagementTests.cs
index 423c867abd..4d8326269a 100644
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgent_ChatHistoryManagementTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgent_ChatHistoryManagementTests.cs
@@ -291,6 +291,124 @@ public class ChatClientAgent_ChatHistoryManagementTests
Assert.Equal("Only ConversationId or ChatHistoryProvider may be used, but not both. The service returned a conversation id indicating server-side chat history management, but the agent has a ChatHistoryProvider configured.", exception.Message);
}
+ ///
+ /// Verify that RunAsync clears the ChatHistoryProvider when ThrowOnChatHistoryProviderConflict is false
+ /// and ClearOnChatHistoryProviderConflict is true.
+ ///
+ [Fact]
+ public async Task RunAsync_ClearsChatHistoryProvider_WhenThrowDisabledAndClearEnabledAsync()
+ {
+ // Arrange
+ Mock mockService = new();
+ mockService.Setup(
+ s => s.GetResponseAsync(
+ It.IsAny>(),
+ It.IsAny(),
+ It.IsAny())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]) { ConversationId = "ConvId" });
+ ChatClientAgent agent = new(mockService.Object, options: new()
+ {
+ ChatOptions = new() { Instructions = "test instructions" },
+ ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+ ThrowOnChatHistoryProviderConflict = false,
+ ClearOnChatHistoryProviderConflict = true,
+ });
+
+ // Act
+ ChatClientAgentSession? session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+ await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+ // Assert
+ Assert.Null(agent.ChatHistoryProvider);
+ Assert.Equal("ConvId", session!.ConversationId);
+ }
+
+ ///
+ /// Verify that RunAsync does not throw and does not clear the ChatHistoryProvider when both
+ /// ThrowOnChatHistoryProviderConflict and ClearOnChatHistoryProviderConflict are false.
+ ///
+ [Fact]
+ public async Task RunAsync_KeepsChatHistoryProvider_WhenThrowAndClearDisabledAsync()
+ {
+ // Arrange
+ Mock mockService = new();
+ mockService.Setup(
+ s => s.GetResponseAsync(
+ It.IsAny>(),
+ It.IsAny(),
+ It.IsAny())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]) { ConversationId = "ConvId" });
+ var chatHistoryProvider = new InMemoryChatHistoryProvider();
+ ChatClientAgent agent = new(mockService.Object, options: new()
+ {
+ ChatOptions = new() { Instructions = "test instructions" },
+ ChatHistoryProvider = chatHistoryProvider,
+ ThrowOnChatHistoryProviderConflict = false,
+ ClearOnChatHistoryProviderConflict = false,
+ WarnOnChatHistoryProviderConflict = false,
+ });
+
+ // Act
+ ChatClientAgentSession? session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+ await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+ // Assert
+ Assert.Same(chatHistoryProvider, agent.ChatHistoryProvider);
+ Assert.Equal("ConvId", session!.ConversationId);
+ }
+
+ ///
+ /// Verify that RunAsync still throws when ThrowOnChatHistoryProviderConflict is true
+ /// even if ClearOnChatHistoryProviderConflict is also true (throw takes precedence).
+ ///
+ [Fact]
+ public async Task RunAsync_Throws_WhenThrowEnabledRegardlessOfClearSettingAsync()
+ {
+ // Arrange
+ Mock mockService = new();
+ mockService.Setup(
+ s => s.GetResponseAsync(
+ It.IsAny>(),
+ It.IsAny(),
+ It.IsAny())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]) { ConversationId = "ConvId" });
+ ChatClientAgent agent = new(mockService.Object, options: new()
+ {
+ ChatOptions = new() { Instructions = "test instructions" },
+ ChatHistoryProvider = new InMemoryChatHistoryProvider(),
+ ThrowOnChatHistoryProviderConflict = true,
+ ClearOnChatHistoryProviderConflict = true,
+ });
+
+ // Act & Assert
+ ChatClientAgentSession? session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+ await Assert.ThrowsAsync(() => agent.RunAsync([new(ChatRole.User, "test")], session));
+ }
+
+ ///
+ /// Verify that RunAsync does not throw when no ChatHistoryProvider is configured on options,
+ /// even if the service returns a conversation id (default InMemoryChatHistoryProvider is used but not from options).
+ ///
+ [Fact]
+ public async Task RunAsync_DoesNotThrow_WhenNoChatHistoryProviderInOptionsAndConversationIdReturnedAsync()
+ {
+ // Arrange
+ Mock mockService = new();
+ mockService.Setup(
+ s => s.GetResponseAsync(
+ It.IsAny>(),
+ It.IsAny(),
+ It.IsAny())).ReturnsAsync(new ChatResponse([new(ChatRole.Assistant, "response")]) { ConversationId = "ConvId" });
+ ChatClientAgent agent = new(mockService.Object, options: new()
+ {
+ ChatOptions = new() { Instructions = "test instructions" },
+ });
+
+ // Act
+ ChatClientAgentSession? session = await agent.CreateSessionAsync() as ChatClientAgentSession;
+ await agent.RunAsync([new(ChatRole.User, "test")], session);
+
+ // Assert - no exception, session gets the conversation id
+ Assert.Equal("ConvId", session!.ConversationId);
+ }
+
#endregion
#region ChatHistoryProvider Override Tests
From b295a16c0ef0b2b9dc4dc129b390358589f68922 Mon Sep 17 00:00:00 2001
From: westey <164392973+westey-m@users.noreply.github.com>
Date: Thu, 26 Feb 2026 14:19:42 +0000
Subject: [PATCH 04/24] .NET: AgentThread serialization alternatives ADR
(#3062)
* AgentThread serialization alternatives ADR
* Update decision drivers.
* Address some Copilot PR comments.
* Fix typo.
* Add ChatClientAgentThread to sample code
* Address comments, rename ADR and update SLNX.
---
.../0018-agentthread-serialization.md | 163 ++++++++++++++++++
dotnet/agent-framework-dotnet.slnx | 4 +
2 files changed, 167 insertions(+)
create mode 100644 docs/decisions/0018-agentthread-serialization.md
diff --git a/docs/decisions/0018-agentthread-serialization.md b/docs/decisions/0018-agentthread-serialization.md
new file mode 100644
index 0000000000..4a1ba3b692
--- /dev/null
+++ b/docs/decisions/0018-agentthread-serialization.md
@@ -0,0 +1,163 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+contact: westey-m
+date: 2026-02-25
+deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
+consulted:
+informed:
+---
+
+# AgentSession serialization
+
+## Context and Problem Statement
+
+Serializing AgentSessions is done today by calling SerializeSession on the AIAgent instance and deserialization
+is done via the DeserializeSession method on the AIAgent instance.
+
+This approach has some drawbacks:
+
+1. It requires each AgentSession implementation to implement its own serialization logic. This can lead to inconsistencies and errors if not done correctly.
+1. It means that only one serialization format can be supported at a time. If we want to support multiple formats (e.g., JSON, XML, binary), we would need to implement separate serialization logic for each format.
+1. It is not possible to serialize and deserialize lists of AgentSessions, since each need to be handled individually.
+1. Users may not realise that they need to call these specific methods to serialize/deserialize AgentSessions.
+
+The reason why this approach was chosen initially is that AgentSessions may have behaviors that are attached to them and only the agent knows what behaviors to attach.
+These behaviors also have their own state that are attached to the AgentSession.
+The behaviors may have references to SDKs or other resources that cannot be created via standard deserialization mechanisms.
+E.g. an AgentSession may have a custom ChatMessageStore that knows how to store chat history in a specific storage backend and has a reference to the SDK client for that backend.
+When deserializing the AgentSession, we need to make sure that the ChatMessageStore is created with the correct SDK client.
+
+## Decision Drivers
+
+- A. Ability to continue to support custom behaviors (AIContextProviders / ChatHistoryProviders).
+- B. Ability to serialize and deserialize AgentSessions via standard serialization mechanisms, e.g. JsonSerializer.Serialize and JsonSerializer.Deserialize.
+- C. Ability for the caller to access custom providers.
+
+## Considered Options
+
+- Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
+- Option 2: Separate state from behavior, and only have state on AgentSession
+- Option 3: Keep the current approach of custom Serialize/Deserialize methods
+
+### Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
+
+Decision Drivers satisfied: A, B and C (C only partially)
+
+Have separate properties on the AgentSession for state and behavior and mark the behavior property with [JsonIgnore].
+After deserializing the AgentSession, the behavior is null and when the AgentSession is first used by the Agent, the behavior is created and attached to the AgentSession.
+
+This requires polymorphic deserialization to be supported, so that the correct AgentSession subclass and the correct behavior state is created during deserialization.
+Since the implementations for AgentSessions and their behaviors are not all known at compile time, we need a way to register custom AgentSession types and their corresponding behavior types for serialization with System.Text.Json on our JsonUtilities helpers.
+
+A drawback of this approach is that the AgentSession is in an incomplete state after deserialization until it is first used,
+so if a user was to call `GetService()` on the AgentSession before it is used by the Agent, it would return null.
+
+Behaviors like ChatMessageStore and AIContextProviders would need to change to support taking state as input and exposing state publicly.
+
+```csharp
+public class ChatClientAgentSession
+{
+ ...
+ public ChatMessageStoreState ChatMessageStoreState { get; }
+ public ChatMessageStore? ChatMessageStore { get; }
+ ...
+}
+
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
+[JsonDerivedType(typeof(InMemoryChatMessageStoreState), nameof(InMemoryChatMessageStoreState))]
+public abstract class ChatMessageStoreState
+{
+}
+public class InMemoryChatMessageStoreState : ChatMessageStoreState
+{
+ public IList Messages { get; set; } = [];
+}
+
+public abstract class ChatMessageStore
+ where TState : ChatMessageStoreState
+{
+ ...
+ public abstract TState State { get; }
+ ...
+}
+
+public sealed class InMemoryChatMessageStore : ChatMessageStore, IList
+{
+ private readonly InMemoryChatMessageStoreState _state;
+
+ public InMemoryChatMessageStore(InMemoryChatMessageStoreState? state)
+ {
+ this._state = state ?? new InMemoryChatMessageStoreState();
+ }
+
+ public override InMemoryChatMessageStoreState State => this._state;
+
+ ...
+}
+```
+
+ChatClientAgent factories would need to change to support creating behaviors based on state:
+
+```csharp
+ public Func? ChatMessageStoreFactory { get; set; }
+
+ public class ChatMessageStoreFactoryContext
+ {
+ public ChatMessageStoreState? State { get; set; }
+ }
+```
+
+The run behavior of the ChatClientAgent would be as follows:
+
+1. If an AgentSession is provided, check if the ChatMessageStore property is null.
+1. If it is, check if the ChatMessageStoreState property is null.
+ 1. If ChatMessageStoreState is null, check if there is a provided ChatMessageStoreFactory.
+ 1. If there is, call it with a ChatMessageStoreFactoryContext containing null State to create a default ChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
+ 2. If there is not, create a default InMemoryChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
+ 1. If ChatMessageStoreState is not null, check if there is a provided ChatMessageStoreFactory.
+ 1. If there is, call it with a ChatMessageStoreFactoryContext containing the State to create a ChatMessageStore behavior based on the state.
+ 2. If there is not, create an InMemoryChatMessageStore behavior based on the State.
+
+### Option 2: Separate state from behavior, and only have state on AgentSession
+
+Decision Drivers satisfied: A, B and C.
+
+This is similar to Option 1 but instead of having a behavior property on the AgentSession, we only have a StateBag property on the AgentSession.
+Behaviors really make more sense to live with the agent rather than the Session, but state should live on the session.
+When the AgentSession is used by the Agent, the Agent runs the behaviors against the Session, and the behavior stores it's state on the Session StateBag.
+
+This means that users are unable to access the behavior from the AgentSession, e.g. via `AgentSession.GetService()`.
+
+However, the behaviors can be public properties on the Agent or can be retrieved from the agent via `AIAgent.GetService()`.
+
+```csharp
+public class AgentSession
+{
+ ...
+ public AgentSessionStateBag StateBag { get; protected set; } = new();
+ ...
+}
+```
+
+### Option 3: Keep the current approach of custom Serialize/Deserialize methods
+
+Decision Drivers satisfied: A and C
+
+This option keeps the current approach of having custom Serialize/Deserialize methods on the AgentSession and AIAgent.
+
+## Decision Outcome
+
+Chosen option:
+
+**Option 2** — separate state from behavior, with only state on the AgentSession — because it satisfies all decision drivers and provides the cleanest separation of concerns. Since not all AgentSession implementations have yet been cleanly separated from their behaviors, AIAgent.SerializeSession and AIAgent.DeserializeSession is kept for the time being, but most session types can be serialized and deserialized directly using JsonSerializer.
+
+### Consequences
+
+- Good, because providers are fully stateless — the same provider instance works correctly across any number of concurrent sessions without risk of state leakage.
+- Good, because `AgentSession` can be serialized and deserialized with standard `System.Text.Json` mechanisms, satisfying decision driver B.
+- Good, because the generic `StateBag` is extensible — new providers can store arbitrary state without requiring changes to the session class.
+- Good, because users can access providers via the agent (e.g. `agent.GetService()`) satisfying decision driver C.
+- Good, because sessions are always in a complete and valid state after deserialization — there is no "incomplete until first use" problem as in Option 1.
+- Neutral, because providers cannot be accessed directly from the session; callers must go through the agent. This is a minor usability trade-off but keeps the session focused on state only.
+- Bad, because each provider must be disciplined about using `ProviderSessionState` and not storing session-specific data in instance fields. This is a correctness concern for custom provider implementers.
diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx
index 424f88d7bf..1ab73c2b8b 100644
--- a/dotnet/agent-framework-dotnet.slnx
+++ b/dotnet/agent-framework-dotnet.slnx
@@ -329,6 +329,10 @@
+
+
+
+
From a033721ac202471f161e316da69eae7e81bb7a98 Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 03:28:14 +0900
Subject: [PATCH 05/24] Python: Fix response_format resolution in streaming
finalizer (#4291)
* Python: Fix AgentResponse.value being None when streaming workflow (#3970)
The streaming path in BaseAgent.run() used the raw 'options' parameter
(passed by the caller) to bind response_format into the outer stream's
finalizer. When response_format was set in default_options rather than
runtime options, it was missing from the finalizer and value was None.
Fix: Use the merged chat_options from the run context (via ctx_holder),
matching the non-streaming path which already uses ctx['chat_options'].
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address review feedback for #3970: safer ctx access, add test coverage
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../packages/core/agent_framework/_agents.py | 9 ++--
.../packages/core/tests/core/test_agents.py | 52 +++++++++++++++++++
2 files changed, 58 insertions(+), 3 deletions(-)
diff --git a/python/packages/core/agent_framework/_agents.py b/python/packages/core/agent_framework/_agents.py
index a3f4570b6e..580b6e2c6d 100644
--- a/python/packages/core/agent_framework/_agents.py
+++ b/python/packages/core/agent_framework/_agents.py
@@ -935,6 +935,11 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]): # type: ignore[misc]
session.service_session_id = conv_id
return update
+ def _finalizer(updates: Sequence[AgentResponseUpdate]) -> AgentResponse[Any]:
+ ctx = ctx_holder["ctx"]
+ rf = ctx.get("chat_options", {}).get("response_format") if ctx else (options.get("response_format") if options else None)
+ return self._finalize_response_updates(updates, response_format=rf)
+
return (
ResponseStream
.from_awaitable(_get_stream())
@@ -943,9 +948,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]): # type: ignore[misc]
map_chat_to_agent_update,
agent_name=self.name,
),
- finalizer=partial(
- self._finalize_response_updates, response_format=options.get("response_format") if options else None
- ),
+ finalizer=_finalizer,
)
.with_transform_hook(_propagate_conversation_id)
.with_result_hook(_post_hook)
diff --git a/python/packages/core/tests/core/test_agents.py b/python/packages/core/tests/core/test_agents.py
index 627987a1f2..b6f84dc970 100644
--- a/python/packages/core/tests/core/test_agents.py
+++ b/python/packages/core/tests/core/test_agents.py
@@ -97,6 +97,58 @@ async def test_chat_client_agent_run_streaming(client: SupportsChatGetResponse)
assert result.text == "test streaming response another update"
+async def test_chat_client_agent_streaming_response_format_from_default_options(
+ client: SupportsChatGetResponse,
+) -> None:
+ """AgentResponse.value must be parsed when response_format is set in default_options and streaming."""
+ from pydantic import BaseModel
+
+ class Greeting(BaseModel):
+ greeting: str
+
+ json_text = '{"greeting": "Hello"}'
+ client.streaming_responses.append( # type: ignore[attr-defined]
+ [ChatResponseUpdate(contents=[Content.from_text(json_text)], role="assistant", finish_reason="stop")]
+ )
+
+ agent = Agent(client=client, default_options={"response_format": Greeting})
+ stream = agent.run("Hello", stream=True)
+ async for _ in stream:
+ pass
+ result = await stream.get_final_response()
+
+ assert result.text == json_text
+ assert result.value is not None
+ assert isinstance(result.value, Greeting)
+ assert result.value.greeting == "Hello"
+
+
+async def test_chat_client_agent_streaming_response_format_from_run_options(
+ client: SupportsChatGetResponse,
+) -> None:
+ """AgentResponse.value must be parsed when response_format is passed via run() options kwarg."""
+ from pydantic import BaseModel
+
+ class Greeting(BaseModel):
+ greeting: str
+
+ json_text = '{"greeting": "Hi"}'
+ client.streaming_responses.append( # type: ignore[attr-defined]
+ [ChatResponseUpdate(contents=[Content.from_text(json_text)], role="assistant", finish_reason="stop")]
+ )
+
+ agent = Agent(client=client)
+ stream = agent.run("Hello", stream=True, options={"response_format": Greeting})
+ async for _ in stream:
+ pass
+ result = await stream.get_final_response()
+
+ assert result.text == json_text
+ assert result.value is not None
+ assert isinstance(result.value, Greeting)
+ assert result.value.greeting == "Hi"
+
+
async def test_chat_client_agent_create_session(client: SupportsChatGetResponse) -> None:
agent = Agent(client=client)
session = agent.create_session()
From 97b24990d902a358e64d19c219961eaaebfa543b Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 05:52:06 +0900
Subject: [PATCH 06/24] Python: Tighten HandoffBuilder to require Agent instead
of SupportsAgentRun (#4301) (#4302)
HandoffBuilder.participants() accepted SupportsAgentRun by API contract,
but build() failed at runtime because _prepare_agent_with_handoffs()
requires Agent instances for cloning, tool injection, and middleware.
Fix: Update all public type hints, docstrings, and validation in
HandoffBuilder and HandoffAgentExecutor to require Agent explicitly.
The isinstance check is now performed early in participants() with a
clear error message explaining why Agent is required.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../_handoff.py | 65 ++++++++++---------
.../orchestrations/tests/test_handoff.py | 26 ++++++++
2 files changed, 59 insertions(+), 32 deletions(-)
diff --git a/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py b/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py
index d2ff5af959..5d6e84ef05 100644
--- a/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py
+++ b/python/packages/orchestrations/agent_framework_orchestrations/_handoff.py
@@ -197,7 +197,7 @@ class HandoffAgentExecutor(AgentExecutor):
def __init__(
self,
- agent: SupportsAgentRun,
+ agent: Agent,
handoffs: Sequence[HandoffConfiguration],
*,
agent_session: AgentSession | None = None,
@@ -210,7 +210,7 @@ class HandoffAgentExecutor(AgentExecutor):
"""Initialize the HandoffAgentExecutor.
Args:
- agent: The agent to execute
+ agent: The ``Agent`` instance to execute
handoffs: Sequence of handoff configurations defining target agents
agent_session: Optional AgentSession that manages the agent's execution context
is_start_agent: Whether this agent is the starting agent in the handoff workflow.
@@ -240,20 +240,18 @@ class HandoffAgentExecutor(AgentExecutor):
def _prepare_agent_with_handoffs(
self,
- agent: SupportsAgentRun,
+ agent: Agent,
handoffs: Sequence[HandoffConfiguration],
- ) -> SupportsAgentRun:
+ ) -> Agent:
"""Prepare an agent by adding handoff tools for the specified target agents.
Args:
- agent: The agent to prepare
+ agent: The ``Agent`` instance to prepare
handoffs: Sequence of handoff configurations defining target agents
Returns:
- A new AgentExecutor instance with handoff tools added
+ A cloned ``Agent`` instance with handoff tools added
"""
- if not isinstance(agent, Agent):
- raise TypeError("Handoff can only be applied to Agent. Please ensure the agent is a Agent instance.")
# Clone the agent to avoid mutating the original
cloned_agent = self._clone_chat_agent(agent) # type: ignore
@@ -701,13 +699,15 @@ class HandoffBuilder:
approach to multi-agent collaboration. Handoffs can be configured using `.add_handoff`. If
none are specified, all agents can hand off to all others by default (making a mesh topology).
- Participants must be agents. Support for custom executors is not available in handoff workflows.
+ Participants must be ``Agent`` instances. ``SupportsAgentRun`` protocol implementors that
+ are not ``Agent`` subclasses are not supported because handoff workflows require cloning,
+ tool injection, and middleware — capabilities only available on ``Agent``.
Outputs:
The final conversation history as a list of Message once the group chat completes.
Note:
- 1. Agents in handoff workflows must be Agent instances and support local tool calls.
+ 1. Agents in handoff workflows must be ``Agent`` instances and support local tool calls.
2. Handoff doesn't support intermediate outputs from agents. All outputs are returned as
they become available. This is because agents in handoff workflows are not considered
sub-agents of a central orchestrator, thus all outputs are directly emitted.
@@ -717,7 +717,7 @@ class HandoffBuilder:
self,
*,
name: str | None = None,
- participants: Sequence[SupportsAgentRun] | None = None,
+ participants: Sequence[Agent] | None = None,
description: str | None = None,
checkpoint_storage: CheckpointStorage | None = None,
termination_condition: TerminationCondition | None = None,
@@ -734,7 +734,7 @@ class HandoffBuilder:
Args:
name: Optional workflow identifier used in logging and debugging.
If not provided, a default name will be generated.
- participants: Optional list of agents that will participate in the handoff workflow.
+ participants: Optional list of ``Agent`` instances that will participate in the handoff workflow.
You can also call `.participants([...])` later. Each participant must have a
unique identifier (`.name` is preferred if set, otherwise `.id` is used).
description: Optional human-readable description explaining the workflow's
@@ -747,7 +747,7 @@ class HandoffBuilder:
self._description = description
# Participant related members
- self._participants: dict[str, SupportsAgentRun] = {}
+ self._participants: dict[str, Agent] = {}
self._start_id: str | None = None
if participants:
@@ -768,11 +768,11 @@ class HandoffBuilder:
# Termination related members
self._termination_condition: Callable[[list[Message]], bool | Awaitable[bool]] | None = termination_condition
- def participants(self, participants: Sequence[SupportsAgentRun]) -> "HandoffBuilder":
+ def participants(self, participants: Sequence[Agent]) -> "HandoffBuilder":
"""Register the agents that will participate in the handoff workflow.
Args:
- participants: Sequence of SupportsAgentRun instances. Each must have a unique identifier.
+ participants: Sequence of ``Agent`` instances. Each must have a unique identifier.
(`.name` is preferred if set, otherwise `.id` is used).
Returns:
@@ -781,7 +781,7 @@ class HandoffBuilder:
Raises:
ValueError: If participants is empty, contains duplicates, or `.participants()`
has already been called.
- TypeError: If participants are not SupportsAgentRun instances.
+ TypeError: If participants are not ``Agent`` instances.
Example:
@@ -804,14 +804,15 @@ class HandoffBuilder:
if not participants:
raise ValueError("participants cannot be empty")
- named: dict[str, SupportsAgentRun] = {}
+ named: dict[str, Agent] = {}
for participant in participants:
- if isinstance(participant, SupportsAgentRun):
- resolved_id = self._resolve_to_id(participant)
- else:
+ if not isinstance(participant, Agent):
raise TypeError(
- f"Participants must be SupportsAgentRun or Executor instances. Got {type(participant).__name__}."
+ f"Participants must be Agent instances. Got {type(participant).__name__}. "
+ "Handoff workflows require Agent because they rely on cloning, tool injection, "
+ "and middleware capabilities."
)
+ resolved_id = self._resolve_to_id(participant)
if resolved_id in named:
raise ValueError(f"Duplicate participant name '{resolved_id}' detected")
@@ -823,8 +824,8 @@ class HandoffBuilder:
def add_handoff(
self,
- source: SupportsAgentRun,
- targets: Sequence[SupportsAgentRun],
+ source: Agent,
+ targets: Sequence[Agent],
*,
description: str | None = None,
) -> "HandoffBuilder":
@@ -905,7 +906,7 @@ class HandoffBuilder:
return self
- def with_start_agent(self, agent: SupportsAgentRun) -> "HandoffBuilder":
+ def with_start_agent(self, agent: Agent) -> "HandoffBuilder":
"""Set the agent that will initiate the handoff workflow.
If not specified, the first registered participant will be used as the starting agent.
@@ -929,7 +930,7 @@ class HandoffBuilder:
def with_autonomous_mode(
self,
*,
- agents: Sequence[SupportsAgentRun] | Sequence[str] | None = None,
+ agents: Sequence[Agent] | Sequence[str] | None = None,
prompts: dict[str, str] | None = None,
turn_limits: dict[str, int] | None = None,
) -> "HandoffBuilder":
@@ -943,7 +944,7 @@ class HandoffBuilder:
Args:
agents: Optional list of agents to enable autonomous mode for. Can be:
- Factory names (str): If using participant factories
- - SupportsAgentRun instances: The actual agent objects
+ - SupportsAgentRun / Agent instances: The actual agent objects
- If not provided, all agents will operate in autonomous mode.
prompts: Optional mapping of agent identifiers/factory names to custom prompts to use when continuing
in autonomous mode. If not provided, a default prompt will be used.
@@ -1092,22 +1093,22 @@ class HandoffBuilder:
# region Internal Helper Methods
- def _resolve_agents(self) -> dict[str, SupportsAgentRun]:
+ def _resolve_agents(self) -> dict[str, Agent]:
"""Resolve participant instances into agent instances.
Returns:
- Map of executor IDs to `SupportsAgentRun` instances
+ Map of executor IDs to ``Agent`` instances
"""
if not self._participants:
raise ValueError("No participants provided. Call .participants() first.")
return self._participants
- def _resolve_handoffs(self, agents: dict[str, SupportsAgentRun]) -> dict[str, list[HandoffConfiguration]]:
+ def _resolve_handoffs(self, agents: dict[str, Agent]) -> dict[str, list[HandoffConfiguration]]:
"""Resolve handoff configurations to executor IDs.
Args:
- agents: Map of agent IDs to `SupportsAgentRun` instances
+ agents: Map of agent IDs to ``Agent`` instances
Returns:
Map of executor IDs to list of HandoffConfiguration instances
@@ -1154,13 +1155,13 @@ class HandoffBuilder:
def _resolve_executors(
self,
- agents: dict[str, SupportsAgentRun],
+ agents: dict[str, Agent],
handoffs: dict[str, list[HandoffConfiguration]],
) -> dict[str, HandoffAgentExecutor]:
"""Resolve agents into HandoffAgentExecutors.
Args:
- agents: Map of agent IDs to `SupportsAgentRun` instances
+ agents: Map of agent IDs to ``Agent`` instances
handoffs: Map of executor IDs to list of HandoffConfiguration instances
Returns:
diff --git a/python/packages/orchestrations/tests/test_handoff.py b/python/packages/orchestrations/tests/test_handoff.py
index e0d94355b6..43c2f9153a 100644
--- a/python/packages/orchestrations/tests/test_handoff.py
+++ b/python/packages/orchestrations/tests/test_handoff.py
@@ -1091,3 +1091,29 @@ async def test_auto_handoff_middleware_calls_next_for_non_handoff_tool() -> None
call_next.assert_awaited_once()
assert context.result is None
+
+
+def test_handoff_builder_rejects_non_agent_supports_agent_run():
+ """Verify that participants() rejects SupportsAgentRun implementations that are not Agent instances."""
+ from agent_framework import AgentResponse, AgentSession, SupportsAgentRun
+
+ class FakeAgentRun:
+ def __init__(self, id, name):
+ self.id = id
+ self.name = name
+ self.description = "d"
+
+ async def run(self, messages=None, *, stream=False, session=None, **kwargs):
+ return AgentResponse(messages=[Message(role="assistant", contents=[Content.from_text("ok")])])
+
+ def create_session(self, **kwargs):
+ return AgentSession()
+
+ def get_session(self, *, service_session_id, **kwargs):
+ return AgentSession(service_session_id=service_session_id)
+
+ fake = FakeAgentRun("a", "A")
+ assert isinstance(fake, SupportsAgentRun)
+
+ with pytest.raises(TypeError, match="Participants must be Agent instances"):
+ HandoffBuilder().participants([fake])
From 823e714ccf5c994fe802a7ede7c0e30cf7e5e2d8 Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 05:53:20 +0900
Subject: [PATCH 07/24] Python: Strip reserved kwargs in AgentExecutor to
prevent duplicate-argument TypeError (#4298)
* Python: Strip reserved kwargs in AgentExecutor to prevent collision (#4295)
workflow.run(session=...) passed 'session' through to agent.run() via
**run_kwargs while AgentExecutor also passes session=self._session
explicitly, causing TypeError: got multiple values for keyword argument.
_prepare_agent_run_args now strips reserved params (session, stream,
messages) from run_kwargs and logs a warning when they are present.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address PR review feedback for #4295
- Use _RESERVED_RUN_PARAMS constant in stripping loop instead of
hardcoded tuple to maintain single source of truth
- Trim frozenset to only stripped keys (session, stream, messages);
options and additional_function_arguments have separate merge logic
- Fix caplog type annotation to use TYPE_CHECKING pattern
- Assert options return value in reserved-kwarg stripping test
- Add test for multiple reserved kwargs supplied simultaneously
- Add integration test for messages= kwarg via workflow.run()
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../_workflows/_agent_executor.py | 19 ++++
.../tests/workflow/test_agent_executor.py | 90 ++++++++++++++++++-
2 files changed, 108 insertions(+), 1 deletion(-)
diff --git a/python/packages/core/agent_framework/_workflows/_agent_executor.py b/python/packages/core/agent_framework/_workflows/_agent_executor.py
index 257833bb6a..acec8e48e2 100644
--- a/python/packages/core/agent_framework/_workflows/_agent_executor.py
+++ b/python/packages/core/agent_framework/_workflows/_agent_executor.py
@@ -415,6 +415,10 @@ class AgentExecutor(Executor):
return response
+ # Parameters that are explicitly passed to agent.run() by AgentExecutor
+ # and must not appear in **run_kwargs to avoid TypeError from duplicate values.
+ _RESERVED_RUN_PARAMS: frozenset[str] = frozenset({"session", "stream", "messages"})
+
@staticmethod
def _prepare_agent_run_args(raw_run_kwargs: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any] | None]:
"""Prepare kwargs and options for agent.run(), avoiding duplicate option passing.
@@ -423,8 +427,23 @@ class AgentExecutor(Executor):
`options.additional_function_arguments`. If workflow kwargs include an
`options` key, merge it into the final options object and remove it from
kwargs before spreading `**run_kwargs`.
+
+ Reserved parameters (session, stream, messages) that are explicitly
+ managed by AgentExecutor are stripped from run_kwargs to prevent
+ ``TypeError: got multiple values for keyword argument`` collisions.
"""
run_kwargs = dict(raw_run_kwargs)
+
+ # Strip reserved params that AgentExecutor passes explicitly to agent.run().
+ for key in AgentExecutor._RESERVED_RUN_PARAMS:
+ if key in run_kwargs:
+ logger.warning(
+ "Workflow kwarg '%s' is reserved by AgentExecutor and will be ignored. "
+ "Remove it from workflow.run() kwargs to silence this warning.",
+ key,
+ )
+ run_kwargs.pop(key)
+
options_from_workflow = run_kwargs.pop("options", None)
workflow_additional_args = run_kwargs.pop("additional_function_arguments", None)
diff --git a/python/packages/core/tests/workflow/test_agent_executor.py b/python/packages/core/tests/workflow/test_agent_executor.py
index 7c2e6fc356..db53868ee1 100644
--- a/python/packages/core/tests/workflow/test_agent_executor.py
+++ b/python/packages/core/tests/workflow/test_agent_executor.py
@@ -1,7 +1,10 @@
# Copyright (c) Microsoft. All rights reserved.
+import logging
from collections.abc import AsyncIterable, Awaitable
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+import pytest
from agent_framework import (
AgentExecutor,
@@ -18,6 +21,9 @@ from agent_framework._workflows._agent_executor import AgentExecutorResponse
from agent_framework._workflows._checkpoint import InMemoryCheckpointStorage
from agent_framework.orchestrations import SequentialBuilder
+if TYPE_CHECKING:
+ from _pytest.logging import LogCaptureFixture
+
class _CountingAgent(BaseAgent):
"""Agent that echoes messages with a counter to verify session state persistence."""
@@ -251,3 +257,85 @@ async def test_agent_executor_save_and_restore_state_directly() -> None:
# Verify session was restored with correct session_id
restored_session = new_executor._session # type: ignore[reportPrivateUsage]
assert restored_session.session_id == session.session_id
+
+
+async def test_agent_executor_run_with_session_kwarg_does_not_raise() -> None:
+ """Passing session= via workflow.run() should not cause a duplicate-keyword TypeError (#4295)."""
+ agent = _CountingAgent(id="session_kwarg_agent", name="SessionKwargAgent")
+ executor = AgentExecutor(agent, id="session_kwarg_exec")
+ workflow = SequentialBuilder(participants=[executor]).build()
+
+ # This previously raised: TypeError: run() got multiple values for keyword argument 'session'
+ result = await workflow.run("hello", session="user-supplied-value")
+ assert result is not None
+ assert agent.call_count == 1
+
+
+async def test_agent_executor_run_streaming_with_stream_kwarg_does_not_raise() -> None:
+ """Passing stream= via workflow.run() kwargs should not cause a duplicate-keyword TypeError."""
+ agent = _CountingAgent(id="stream_kwarg_agent", name="StreamKwargAgent")
+ executor = AgentExecutor(agent, id="stream_kwarg_exec")
+ workflow = SequentialBuilder(participants=[executor]).build()
+
+ # stream=True at workflow level triggers streaming mode (returns async iterable)
+ events = []
+ async for event in workflow.run("hello", stream=True):
+ events.append(event)
+ assert len(events) > 0
+ assert agent.call_count == 1
+
+
+@pytest.mark.parametrize("reserved_kwarg", ["session", "stream", "messages"])
+async def test_prepare_agent_run_args_strips_reserved_kwargs(
+ reserved_kwarg: str, caplog: "LogCaptureFixture"
+) -> None:
+ """_prepare_agent_run_args must remove reserved kwargs and log a warning."""
+ raw = {reserved_kwarg: "should-be-stripped", "custom_key": "keep-me"}
+
+ with caplog.at_level(logging.WARNING):
+ run_kwargs, options = AgentExecutor._prepare_agent_run_args(raw)
+
+ assert reserved_kwarg not in run_kwargs
+ assert "custom_key" in run_kwargs
+ assert options is not None
+ assert options["additional_function_arguments"]["custom_key"] == "keep-me"
+ assert any(reserved_kwarg in record.message for record in caplog.records)
+
+
+async def test_prepare_agent_run_args_preserves_non_reserved_kwargs() -> None:
+ """Non-reserved workflow kwargs should pass through unchanged."""
+ raw = {"custom_param": "value", "another": 42}
+ run_kwargs, options = AgentExecutor._prepare_agent_run_args(raw)
+ assert run_kwargs["custom_param"] == "value"
+ assert run_kwargs["another"] == 42
+
+
+async def test_prepare_agent_run_args_strips_all_reserved_kwargs_at_once(
+ caplog: "LogCaptureFixture",
+) -> None:
+ """All reserved kwargs should be stripped when supplied together, each emitting a warning."""
+ raw = {"session": "x", "stream": True, "messages": [], "custom": 1}
+
+ with caplog.at_level(logging.WARNING):
+ run_kwargs, options = AgentExecutor._prepare_agent_run_args(raw)
+
+ assert "session" not in run_kwargs
+ assert "stream" not in run_kwargs
+ assert "messages" not in run_kwargs
+ assert run_kwargs["custom"] == 1
+ assert options is not None
+ assert options["additional_function_arguments"]["custom"] == 1
+
+ warned_keys = {r.message.split("'")[1] for r in caplog.records if "reserved" in r.message.lower()}
+ assert warned_keys == {"session", "stream", "messages"}
+
+
+async def test_agent_executor_run_with_messages_kwarg_does_not_raise() -> None:
+ """Passing messages= via workflow.run() kwargs should not cause a duplicate-keyword TypeError."""
+ agent = _CountingAgent(id="messages_kwarg_agent", name="MessagesKwargAgent")
+ executor = AgentExecutor(agent, id="messages_kwarg_exec")
+ workflow = SequentialBuilder(participants=[executor]).build()
+
+ result = await workflow.run("hello", messages=["stale"])
+ assert result is not None
+ assert agent.call_count == 1
From b46fe1c82e33f43e6b76cf1c841e536904131100 Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 05:57:04 +0900
Subject: [PATCH 08/24] Python: Preserve workflow run kwargs when continuing
with `run(responses=...)` (#4296)
* fix(python): preserve workflow run kwargs on response continuation (#4293)
When continuing a paused workflow with run(responses=...), the existing
run kwargs stored in state were unconditionally overwritten with an empty
dict. This caused subsequent agent invocations to lose the original run
context (e.g., custom_data, user tokens).
Now kwargs are only overwritten when:
- New kwargs are explicitly provided (override), or
- State was just cleared for a fresh run (initialize to {})
On continuation without new kwargs, existing kwargs are preserved.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address PR review feedback for #4293
- Use consistent get_state(key, {}) default pattern in _agent_executor.py
and _workflow_executor.py instead of get_state(key) or {} to safely
handle missing WORKFLOW_RUN_KWARGS_KEY
- Add test for empty-value kwargs on continuation (custom_data={}) to
verify the is-not-None boundary between overwrite and preserve
- Add test for reset_context=True with no kwargs to exercise the elif
branch that initializes WORKFLOW_RUN_KWARGS_KEY to {}
- Add len assertion to override test for consistency
- Document kwargs-collapsing behavior at the public API call site
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../_workflows/_agent_executor.py | 2 +-
.../agent_framework/_workflows/_workflow.py | 15 +-
.../_workflows/_workflow_executor.py | 2 +-
.../tests/workflow/test_workflow_kwargs.py | 209 ++++++++++++++++++
4 files changed, 223 insertions(+), 5 deletions(-)
diff --git a/python/packages/core/agent_framework/_workflows/_agent_executor.py b/python/packages/core/agent_framework/_workflows/_agent_executor.py
index acec8e48e2..3d8024a35e 100644
--- a/python/packages/core/agent_framework/_workflows/_agent_executor.py
+++ b/python/packages/core/agent_framework/_workflows/_agent_executor.py
@@ -360,7 +360,7 @@ class AgentExecutor(Executor):
Returns:
The complete AgentResponse, or None if waiting for user input.
"""
- run_kwargs, options = self._prepare_agent_run_args(ctx.get_state(WORKFLOW_RUN_KWARGS_KEY) or {})
+ run_kwargs, options = self._prepare_agent_run_args(ctx.get_state(WORKFLOW_RUN_KWARGS_KEY, {}))
updates: list[AgentResponseUpdate] = []
streamed_user_input_requests: list[Content] = []
diff --git a/python/packages/core/agent_framework/_workflows/_workflow.py b/python/packages/core/agent_framework/_workflows/_workflow.py
index cd7dbb4a68..f545fbe5d8 100644
--- a/python/packages/core/agent_framework/_workflows/_workflow.py
+++ b/python/packages/core/agent_framework/_workflows/_workflow.py
@@ -345,9 +345,14 @@ class Workflow(DictConvertible):
self._runner.context.reset_for_new_run()
self._state.clear()
- # Store run kwargs in State so executors can access them
- # Always store (even empty dict) so retrieval is deterministic
- self._state.set(WORKFLOW_RUN_KWARGS_KEY, run_kwargs or {})
+ # Store run kwargs in State so executors can access them.
+ # Only overwrite when new kwargs are explicitly provided or state was
+ # just cleared (fresh run). On continuation (reset_context=False) with
+ # no new kwargs, preserve the kwargs from the original run.
+ if run_kwargs is not None:
+ self._state.set(WORKFLOW_RUN_KWARGS_KEY, run_kwargs)
+ elif reset_context:
+ self._state.set(WORKFLOW_RUN_KWARGS_KEY, {})
self._state.commit() # Commit immediately so kwargs are available
# Set streaming mode after reset
@@ -564,6 +569,10 @@ class Workflow(DictConvertible):
initial_executor_fn=initial_executor_fn,
reset_context=reset_context,
streaming=streaming,
+ # Empty **kwargs (no caller-provided kwargs) is collapsed to None so that
+ # continuation calls without explicit kwargs preserve the original run's kwargs.
+ # A non-empty kwargs dict (even one with empty values like {"key": {}})
+ # is passed through and will overwrite stored kwargs.
run_kwargs=kwargs if kwargs else None,
):
if event.type == "output" and not self._should_yield_output_event(event):
diff --git a/python/packages/core/agent_framework/_workflows/_workflow_executor.py b/python/packages/core/agent_framework/_workflows/_workflow_executor.py
index 0d2c86070c..e9e4196bfd 100644
--- a/python/packages/core/agent_framework/_workflows/_workflow_executor.py
+++ b/python/packages/core/agent_framework/_workflows/_workflow_executor.py
@@ -385,7 +385,7 @@ class WorkflowExecutor(Executor):
try:
# Get kwargs from parent workflow's State to propagate to subworkflow
- parent_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY) or {}
+ parent_kwargs: dict[str, Any] = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY, {})
# Run the sub-workflow and collect all events, passing parent kwargs
result = await self.workflow.run(input_data, **parent_kwargs)
diff --git a/python/packages/core/tests/workflow/test_workflow_kwargs.py b/python/packages/core/tests/workflow/test_workflow_kwargs.py
index bf1fd00974..379435e124 100644
--- a/python/packages/core/tests/workflow/test_workflow_kwargs.py
+++ b/python/packages/core/tests/workflow/test_workflow_kwargs.py
@@ -446,6 +446,215 @@ async def test_kwargs_with_complex_nested_data() -> None:
assert received.get("complex_data") == complex_data
+async def test_kwargs_preserved_on_response_continuation() -> None:
+ """Test that run kwargs are preserved when continuing a paused workflow with run(responses=...).
+
+ Regression test for #4293: kwargs were overwritten to {} on continuation calls.
+ """
+
+ class _ApprovalCapturingAgent(BaseAgent):
+ """Agent that pauses for approval on first call and captures kwargs on every call."""
+
+ captured_kwargs: list[dict[str, Any]]
+ _asked: bool
+
+ def __init__(self) -> None:
+ super().__init__(name="approval_agent", description="Test agent")
+ self.captured_kwargs = []
+ self._asked = False
+
+ def run(
+ self,
+ messages: str | Content | Message | Sequence[str | Content | Message] | None = None,
+ *,
+ stream: bool = False,
+ session: AgentSession | None = None,
+ **kwargs: Any,
+ ) -> Awaitable[AgentResponse] | ResponseStream[AgentResponseUpdate, AgentResponse]:
+ self.captured_kwargs.append(dict(kwargs))
+ if not self._asked:
+ self._asked = True
+
+ async def _pause() -> AgentResponse:
+ call = Content.from_function_call(call_id="c1", name="do_thing", arguments="{}")
+ req = Content.from_function_approval_request(id="r1", function_call=call)
+ return AgentResponse(messages=[Message("assistant", [req])])
+
+ return _pause()
+
+ async def _done() -> AgentResponse:
+ return AgentResponse(messages=[Message("assistant", ["done"])])
+
+ return _done()
+
+ from agent_framework import WorkflowBuilder
+
+ agent = _ApprovalCapturingAgent()
+ workflow = WorkflowBuilder(start_executor=agent, output_executors=[agent]).build()
+
+ # Initial run with kwargs — workflow should pause for approval
+ result = await workflow.run("go", custom_data={"token": "abc"})
+ request_events = result.get_request_info_events()
+ assert len(request_events) == 1
+
+ # Continue with responses only — no new kwargs
+ approval = request_events[0]
+ await workflow.run(
+ responses={approval.request_id: approval.data.to_function_approval_response(True)}
+ )
+
+ # Both calls should have received the original kwargs
+ assert len(agent.captured_kwargs) == 2
+ assert agent.captured_kwargs[0].get("custom_data") == {"token": "abc"}
+ assert agent.captured_kwargs[1].get("custom_data") == {"token": "abc"}, (
+ f"kwargs should be preserved on continuation, got: {agent.captured_kwargs[1]}"
+ )
+
+
+async def test_kwargs_overridden_on_response_continuation() -> None:
+ """Test that explicitly provided kwargs override prior kwargs on continuation."""
+
+ class _ApprovalCapturingAgent(BaseAgent):
+ captured_kwargs: list[dict[str, Any]]
+ _asked: bool
+
+ def __init__(self) -> None:
+ super().__init__(name="approval_agent", description="Test agent")
+ self.captured_kwargs = []
+ self._asked = False
+
+ def run(
+ self,
+ messages: str | Content | Message | Sequence[str | Content | Message] | None = None,
+ *,
+ stream: bool = False,
+ session: AgentSession | None = None,
+ **kwargs: Any,
+ ) -> Awaitable[AgentResponse] | ResponseStream[AgentResponseUpdate, AgentResponse]:
+ self.captured_kwargs.append(dict(kwargs))
+ if not self._asked:
+ self._asked = True
+
+ async def _pause() -> AgentResponse:
+ call = Content.from_function_call(call_id="c1", name="do_thing", arguments="{}")
+ req = Content.from_function_approval_request(id="r1", function_call=call)
+ return AgentResponse(messages=[Message("assistant", [req])])
+
+ return _pause()
+
+ async def _done() -> AgentResponse:
+ return AgentResponse(messages=[Message("assistant", ["done"])])
+
+ return _done()
+
+ from agent_framework import WorkflowBuilder
+
+ agent = _ApprovalCapturingAgent()
+ workflow = WorkflowBuilder(start_executor=agent, output_executors=[agent]).build()
+
+ result = await workflow.run("go", custom_data={"token": "abc"})
+ request_events = result.get_request_info_events()
+ approval = request_events[0]
+
+ # Continue with responses AND new kwargs — should override
+ await workflow.run(
+ responses={approval.request_id: approval.data.to_function_approval_response(True)},
+ custom_data={"token": "xyz"},
+ )
+
+ assert len(agent.captured_kwargs) == 2
+ assert agent.captured_kwargs[0].get("custom_data") == {"token": "abc"}
+ assert agent.captured_kwargs[1].get("custom_data") == {"token": "xyz"}
+
+
+async def test_kwargs_empty_value_passed_on_continuation() -> None:
+ """Test that explicitly passing a kwarg with an empty value on continuation overrides prior kwargs.
+
+ This exercises the boundary where the caller provides kwargs (e.g., custom_data={})
+ that differ from the original run. Because the kwargs dict is non-empty (it has a key),
+ it passes the `kwargs if kwargs else None` gate and the `is not None` check, so it
+ overwrites the previously stored kwargs.
+ """
+
+ class _ApprovalCapturingAgent(BaseAgent):
+ captured_kwargs: list[dict[str, Any]]
+ _asked: bool
+
+ def __init__(self) -> None:
+ super().__init__(name="approval_agent", description="Test agent")
+ self.captured_kwargs = []
+ self._asked = False
+
+ def run(
+ self,
+ messages: str | Content | Message | Sequence[str | Content | Message] | None = None,
+ *,
+ stream: bool = False,
+ session: AgentSession | None = None,
+ **kwargs: Any,
+ ) -> Awaitable[AgentResponse] | ResponseStream[AgentResponseUpdate, AgentResponse]:
+ self.captured_kwargs.append(dict(kwargs))
+ if not self._asked:
+ self._asked = True
+
+ async def _pause() -> AgentResponse:
+ call = Content.from_function_call(call_id="c1", name="do_thing", arguments="{}")
+ req = Content.from_function_approval_request(id="r1", function_call=call)
+ return AgentResponse(messages=[Message("assistant", [req])])
+
+ return _pause()
+
+ async def _done() -> AgentResponse:
+ return AgentResponse(messages=[Message("assistant", ["done"])])
+
+ return _done()
+
+ from agent_framework import WorkflowBuilder
+
+ agent = _ApprovalCapturingAgent()
+ workflow = WorkflowBuilder(start_executor=agent, output_executors=[agent]).build()
+
+ # Initial run with non-empty kwargs
+ result = await workflow.run("go", custom_data={"token": "abc"})
+ request_events = result.get_request_info_events()
+ assert len(request_events) == 1
+
+ # Continue with custom_data={} — explicitly clearing the value.
+ # kwargs={"custom_data": {}} is truthy (has a key), so run_kwargs is set.
+ approval = request_events[0]
+ await workflow.run(
+ responses={approval.request_id: approval.data.to_function_approval_response(True)},
+ custom_data={},
+ )
+
+ assert len(agent.captured_kwargs) == 2
+ assert agent.captured_kwargs[0].get("custom_data") == {"token": "abc"}
+ # The continuation explicitly set custom_data={}, overriding the original
+ assert agent.captured_kwargs[1].get("custom_data") == {}
+
+
+async def test_kwargs_reset_context_stores_empty_dict() -> None:
+ """Test that reset_context=True with no kwargs stores an empty dict.
+
+ This exercises the `elif reset_context` branch that ensures WORKFLOW_RUN_KWARGS_KEY
+ is always populated after a fresh run, even when no kwargs are provided.
+ """
+ agent = _KwargsCapturingAgent(name="reset_ctx_test")
+
+ workflow = SequentialBuilder(participants=[agent]).build()
+
+ # Run with no kwargs and reset_context=True (the default for a fresh run)
+ async for event in workflow.run("test", stream=True):
+ if event.type == "status" and event.state == WorkflowRunState.IDLE:
+ break
+
+ assert len(agent.captured_kwargs) >= 1
+ # The only kwarg should be the framework-injected 'options' (no user-provided kwargs)
+ received = agent.captured_kwargs[0]
+ assert "custom_data" not in received
+ assert received.get("options") is None
+
+
async def test_kwargs_preserved_across_workflow_reruns() -> None:
"""Test that kwargs are correctly isolated between workflow runs."""
agent = _KwargsCapturingAgent(name="rerun_test")
From e0461b42c12ed2ca492ad6512583ef1920c649a6 Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 07:07:23 +0900
Subject: [PATCH 09/24] Python: Map file citation annotations from
TextDeltaBlock in Assistants API streaming (#4316) (#4320)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
During Assistants API streaming, TextDeltaBlock.text.annotations was
ignored when creating Content objects. This caused raw placeholder
strings like 【4:0†source】 to pass through to downstream consumers
(including AG-UI) instead of being resolved to citation metadata.
Map FileCitationDeltaAnnotation and FilePathDeltaAnnotation from
delta_block.text.annotations to Annotation objects on the Content,
consistent with the existing patterns in _responses_client.py and
_chat_client.py.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../openai/_assistants_client.py | 50 +++++++-
.../openai/test_openai_assistants_client.py | 116 ++++++++++++++++++
2 files changed, 165 insertions(+), 1 deletion(-)
diff --git a/python/packages/core/agent_framework/openai/_assistants_client.py b/python/packages/core/agent_framework/openai/_assistants_client.py
index 42a5e32732..dc05411a52 100644
--- a/python/packages/core/agent_framework/openai/_assistants_client.py
+++ b/python/packages/core/agent_framework/openai/_assistants_client.py
@@ -16,6 +16,8 @@ from typing import TYPE_CHECKING, Any, Generic, Literal, TypedDict, cast
from openai import AsyncOpenAI
from openai.types.beta.threads import (
+ FileCitationDeltaAnnotation,
+ FilePathDeltaAnnotation,
ImageURLContentBlockParam,
ImageURLParam,
MessageContentPartParam,
@@ -39,12 +41,14 @@ from .._tools import (
normalize_tools,
)
from .._types import (
+ Annotation,
ChatOptions,
ChatResponse,
ChatResponseUpdate,
Content,
Message,
ResponseStream,
+ TextSpanRegion,
UsageDetails,
)
from ..observability import ChatTelemetryLayer
@@ -554,9 +558,53 @@ class OpenAIAssistantsClient( # type: ignore[misc]
for delta_block in delta.content or []:
if isinstance(delta_block, TextDeltaBlock) and delta_block.text and delta_block.text.value:
+ text_content = Content.from_text(delta_block.text.value)
+ if delta_block.text.annotations:
+ text_content.annotations = []
+ for annotation in delta_block.text.annotations:
+ if isinstance(annotation, FileCitationDeltaAnnotation):
+ ann: Annotation = Annotation(
+ type="citation",
+ additional_properties={
+ "text": annotation.text,
+ "index": annotation.index,
+ },
+ raw_representation=annotation,
+ )
+ if annotation.file_citation and annotation.file_citation.file_id:
+ ann["file_id"] = annotation.file_citation.file_id
+ if annotation.start_index is not None and annotation.end_index is not None:
+ ann["annotated_regions"] = [
+ TextSpanRegion(
+ type="text_span",
+ start_index=annotation.start_index,
+ end_index=annotation.end_index,
+ )
+ ]
+ text_content.annotations.append(ann)
+ elif isinstance(annotation, FilePathDeltaAnnotation):
+ ann = Annotation(
+ type="citation",
+ additional_properties={
+ "text": annotation.text,
+ "index": annotation.index,
+ },
+ raw_representation=annotation,
+ )
+ if annotation.file_path and annotation.file_path.file_id:
+ ann["file_id"] = annotation.file_path.file_id
+ if annotation.start_index is not None and annotation.end_index is not None:
+ ann["annotated_regions"] = [
+ TextSpanRegion(
+ type="text_span",
+ start_index=annotation.start_index,
+ end_index=annotation.end_index,
+ )
+ ]
+ text_content.annotations.append(ann)
yield ChatResponseUpdate(
role=role, # type: ignore[arg-type]
- contents=[Content.from_text(delta_block.text.value)],
+ contents=[text_content],
conversation_id=thread_id,
message_id=response_id,
raw_representation=response.data,
diff --git a/python/packages/core/tests/openai/test_openai_assistants_client.py b/python/packages/core/tests/openai/test_openai_assistants_client.py
index cf8d74f959..8f39573006 100644
--- a/python/packages/core/tests/openai/test_openai_assistants_client.py
+++ b/python/packages/core/tests/openai/test_openai_assistants_client.py
@@ -7,6 +7,8 @@ from unittest.mock import AsyncMock, MagicMock
import pytest
from openai.types.beta.threads import MessageDeltaEvent, Run, TextDeltaBlock
+from openai.types.beta.threads.file_citation_delta_annotation import FileCitationDeltaAnnotation
+from openai.types.beta.threads.file_path_delta_annotation import FilePathDeltaAnnotation
from openai.types.beta.threads.runs import RunStep
from pydantic import Field
@@ -443,6 +445,120 @@ async def test_process_stream_events_message_delta_text(mock_async_openai: Magic
assert update.raw_representation == mock_message_delta
+async def test_process_stream_events_message_delta_text_with_file_citation_annotations(
+ mock_async_openai: MagicMock,
+) -> None:
+ """Test _process_stream_events maps file citation annotations from TextDeltaBlock."""
+ client = create_test_openai_assistants_client(mock_async_openai)
+
+ mock_annotation = FileCitationDeltaAnnotation(
+ index=0,
+ type="file_citation",
+ file_citation={"file_id": "file-abc123"},
+ start_index=10,
+ end_index=24,
+ text="【4:0†source】",
+ )
+
+ mock_delta_block = MagicMock(spec=TextDeltaBlock)
+ mock_delta_block.text = MagicMock()
+ mock_delta_block.text.value = "Some text 【4:0†source】 more text"
+ mock_delta_block.text.annotations = [mock_annotation]
+
+ mock_delta = MagicMock()
+ mock_delta.role = "assistant"
+ mock_delta.content = [mock_delta_block]
+
+ mock_message_delta = MagicMock(spec=MessageDeltaEvent)
+ mock_message_delta.delta = mock_delta
+
+ mock_response = MagicMock()
+ mock_response.event = "thread.message.delta"
+ mock_response.data = mock_message_delta
+
+ async def async_iterator() -> Any:
+ yield mock_response
+
+ mock_stream = MagicMock()
+ mock_stream.__aenter__ = AsyncMock(return_value=async_iterator())
+ mock_stream.__aexit__ = AsyncMock(return_value=None)
+
+ thread_id = "thread-789"
+ updates: list[ChatResponseUpdate] = []
+ async for update in client._process_stream_events(mock_stream, thread_id): # type: ignore
+ updates.append(update)
+
+ assert len(updates) == 1
+ update = updates[0]
+ assert update.text == "Some text 【4:0†source】 more text"
+ assert update.contents is not None
+ content = update.contents[0]
+ assert content.annotations is not None
+ assert len(content.annotations) == 1
+ ann = content.annotations[0]
+ assert ann["type"] == "citation"
+ assert ann["file_id"] == "file-abc123"
+ assert ann["annotated_regions"] is not None
+ assert ann["annotated_regions"][0]["start_index"] == 10
+ assert ann["annotated_regions"][0]["end_index"] == 24
+ assert ann["additional_properties"]["text"] == "【4:0†source】"
+
+
+async def test_process_stream_events_message_delta_text_with_file_path_annotations(
+ mock_async_openai: MagicMock,
+) -> None:
+ """Test _process_stream_events maps file path annotations from TextDeltaBlock."""
+ client = create_test_openai_assistants_client(mock_async_openai)
+
+ mock_annotation = FilePathDeltaAnnotation(
+ index=0,
+ type="file_path",
+ file_path={"file_id": "file-xyz789"},
+ start_index=5,
+ end_index=20,
+ text="sandbox:/path/to/file",
+ )
+
+ mock_delta_block = MagicMock(spec=TextDeltaBlock)
+ mock_delta_block.text = MagicMock()
+ mock_delta_block.text.value = "Here sandbox:/path/to/file is the file"
+ mock_delta_block.text.annotations = [mock_annotation]
+
+ mock_delta = MagicMock()
+ mock_delta.role = "assistant"
+ mock_delta.content = [mock_delta_block]
+
+ mock_message_delta = MagicMock(spec=MessageDeltaEvent)
+ mock_message_delta.delta = mock_delta
+
+ mock_response = MagicMock()
+ mock_response.event = "thread.message.delta"
+ mock_response.data = mock_message_delta
+
+ async def async_iterator() -> Any:
+ yield mock_response
+
+ mock_stream = MagicMock()
+ mock_stream.__aenter__ = AsyncMock(return_value=async_iterator())
+ mock_stream.__aexit__ = AsyncMock(return_value=None)
+
+ thread_id = "thread-annotation"
+ updates: list[ChatResponseUpdate] = []
+ async for update in client._process_stream_events(mock_stream, thread_id): # type: ignore
+ updates.append(update)
+
+ assert len(updates) == 1
+ content = updates[0].contents[0]
+ assert content.annotations is not None
+ assert len(content.annotations) == 1
+ ann = content.annotations[0]
+ assert ann["type"] == "citation"
+ assert ann["file_id"] == "file-xyz789"
+ assert ann["annotated_regions"] is not None
+ assert ann["annotated_regions"][0]["start_index"] == 5
+ assert ann["annotated_regions"][0]["end_index"] == 20
+
+
async def test_process_stream_events_requires_action(mock_async_openai: MagicMock) -> None:
"""Test _process_stream_events with thread.run.requires_action event."""
client = create_test_openai_assistants_client(mock_async_openai)
From 6f7e55c430ef35ae9f36c806f563d239388419bd Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 07:07:58 +0900
Subject: [PATCH 10/24] Python: Fix WorkflowAgent not persisting response
messages to session history (#1694) (#4319)
WorkflowAgent._run_impl() and _run_stream_impl() did not set
session_context._response before calling _run_after_providers().
This caused InMemoryHistoryProvider.after_run() to see context.response
as None, so response messages were never stored in the session.
On subsequent runs, the workflow only received prior user inputs without
assistant responses, breaking multi-turn conversations.
Fix: Set session_context._response to the workflow result before running
after_run providers, matching the behavior of the regular Agent class.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../core/agent_framework/_workflows/_agent.py | 13 +++
.../tests/workflow/test_workflow_agent.py | 86 +++++++++++++++++++
2 files changed, 99 insertions(+)
diff --git a/python/packages/core/agent_framework/_workflows/_agent.py b/python/packages/core/agent_framework/_workflows/_agent.py
index 3fb83803c4..bf615814b3 100644
--- a/python/packages/core/agent_framework/_workflows/_agent.py
+++ b/python/packages/core/agent_framework/_workflows/_agent.py
@@ -270,6 +270,11 @@ class WorkflowAgent(BaseAgent):
output_events.append(event)
result = self._convert_workflow_events_to_agent_response(response_id, output_events)
+
+ # Set the response on the context so after_run providers (e.g. InMemoryHistoryProvider)
+ # can persist the response messages alongside input messages.
+ session_context._response = result # type: ignore[assignment]
+
await self._run_after_providers(session=provider_session, context=session_context)
return result
@@ -322,12 +327,20 @@ class WorkflowAgent(BaseAgent):
# combine the messages
session_messages: list[Message] = session_context.get_messages(include_input=True)
+ all_updates: list[AgentResponseUpdate] = []
async for event in self._run_core(
session_messages, checkpoint_id, checkpoint_storage, streaming=True, **kwargs
):
updates = self._convert_workflow_event_to_agent_response_updates(response_id, event)
for update in updates:
+ all_updates.append(update)
yield update
+
+ # Build the final response from collected updates so after_run providers
+ # (e.g. InMemoryHistoryProvider) can persist the response messages.
+ if all_updates:
+ session_context._response = AgentResponse.from_updates(all_updates) # type: ignore[assignment]
+
await self._run_after_providers(session=provider_session, context=session_context)
async def _run_core(
diff --git a/python/packages/core/tests/workflow/test_workflow_agent.py b/python/packages/core/tests/workflow/test_workflow_agent.py
index b2fbded39b..d20d60ba3b 100644
--- a/python/packages/core/tests/workflow/test_workflow_agent.py
+++ b/python/packages/core/tests/workflow/test_workflow_agent.py
@@ -578,6 +578,92 @@ class TestWorkflowAgent:
assert "first message" in texts
assert "second message" in texts
+ async def test_multi_turn_session_stores_responses(self) -> None:
+ """Test that WorkflowAgent stores response messages in session history (issue #1694).
+
+ Previously, session_context._response was not set before running after_run
+ providers, so InMemoryHistoryProvider never persisted response messages.
+ On subsequent runs the workflow only received prior user inputs, not prior
+ assistant responses, breaking multi-turn conversations.
+ """
+ capturing_executor = ConversationHistoryCapturingExecutor(id="multi_turn_test", streaming=False)
+ workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+ agent = workflow.as_agent(name="Multi Turn Agent")
+ session = AgentSession()
+
+ # First turn
+ await agent.run("My name is Bob", session=session)
+
+ # Second turn — the executor should see prior user+assistant messages plus new input
+ await agent.run("What is my name?", session=session)
+
+ received = capturing_executor.received_messages
+ roles = [m.role for m in received]
+ texts = [m.text for m in received]
+
+ # History should include: user("My name is Bob"), assistant(response), user("What is my name?")
+ assert len(received) == 3, f"Expected 3 messages (user, assistant, user), got {len(received)}: {roles}"
+ assert roles[0] == "user"
+ assert "My name is Bob" in (texts[0] or "")
+ assert roles[1] == "assistant"
+ assert roles[2] == "user"
+ assert "What is my name?" in (texts[2] or "")
+
+ async def test_multi_turn_session_stores_responses_streaming(self) -> None:
+ """Streaming variant: WorkflowAgent stores response messages in session history."""
+ capturing_executor = ConversationHistoryCapturingExecutor(id="multi_turn_stream_test", streaming=True)
+ workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+ agent = workflow.as_agent(name="Multi Turn Stream Agent")
+ session = AgentSession()
+
+ # First turn (streaming)
+ stream = agent.run("Hello", stream=True, session=session)
+ async for _ in stream:
+ pass
+ await stream.get_final_response()
+
+ # Second turn — should include prior history
+ stream2 = agent.run("Follow up", stream=True, session=session)
+ async for _ in stream2:
+ pass
+ await stream2.get_final_response()
+
+ received = capturing_executor.received_messages
+ roles = [m.role for m in received]
+
+ assert len(received) == 3, f"Expected 3 messages, got {len(received)}: {roles}"
+ assert roles[0] == "user"
+ assert roles[1] == "assistant"
+ assert roles[2] == "user"
+
+ async def test_multi_turn_session_roundtrip_serialization(self) -> None:
+ """Test that session can be serialized/deserialized and multi-turn still works."""
+ capturing_executor = ConversationHistoryCapturingExecutor(id="roundtrip_test", streaming=False)
+ workflow = WorkflowBuilder(start_executor=capturing_executor).build()
+ agent = workflow.as_agent(name="Roundtrip Agent")
+ session = AgentSession()
+
+ # First turn
+ await agent.run("My name is Bob", session=session)
+
+ # Serialize and deserialize the session
+ serialized = session.to_dict()
+ restored_session = AgentSession.from_dict(serialized)
+
+ # Second turn with restored session
+ await agent.run("What is my name?", session=restored_session)
+
+ received = capturing_executor.received_messages
+ roles = [m.role for m in received]
+ texts = [m.text for m in received]
+
+ assert len(received) == 3, f"Expected 3 messages, got {len(received)}: {roles}"
+ assert roles[0] == "user"
+ assert "My name is Bob" in (texts[0] or "")
+ assert roles[1] == "assistant"
+ assert roles[2] == "user"
+ assert "What is my name?" in (texts[2] or "")
+
async def test_workflow_agent_keeps_explicit_context_providers(self) -> None:
"""Test that WorkflowAgent does not append defaults when context providers are explicitly provided."""
workflow = WorkflowBuilder(
From ff124c44a99129fd720158928d629c7bd8b319cc Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 07:09:28 +0900
Subject: [PATCH 11/24] Python: Fix single-tool input handling in
OpenAIResponsesClient._prepare_tools_for_openai (#4312)
* Fix OpenAIResponsesClient mishandling single-tool inputs (#4304)
Use normalize_tools() in _prepare_tools_for_openai to wrap single tools
(FunctionTool or dict) in a list before iteration, consistent with the
chat client implementation.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address PR review feedback for #4304
- Use precise type annotation matching normalize_tools/OpenAIChatClient signature
instead of collapsed Sequence[Any] | Any | None
- Move emptiness guard after normalize_tools() call so single falsy tool
objects are not silently swallowed
- Import ToolTypes for the type annotation
- Expand test_prepare_tools_for_openai_single_function_tool assertions to
verify parameters, strict, and parameter schema fields
- Add test_prepare_tools_for_openai_none to verify None input returns []
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../openai/_responses_client.py | 13 ++++--
.../openai/test_openai_responses_client.py | 46 +++++++++++++++++++
2 files changed, 55 insertions(+), 4 deletions(-)
diff --git a/python/packages/core/agent_framework/openai/_responses_client.py b/python/packages/core/agent_framework/openai/_responses_client.py
index fa140ee0b7..5ba0bbc686 100644
--- a/python/packages/core/agent_framework/openai/_responses_client.py
+++ b/python/packages/core/agent_framework/openai/_responses_client.py
@@ -43,6 +43,8 @@ from .._tools import (
FunctionInvocationConfiguration,
FunctionInvocationLayer,
FunctionTool,
+ ToolTypes,
+ normalize_tools,
)
from .._types import (
Annotation,
@@ -425,21 +427,24 @@ class RawOpenAIResponsesClient( # type: ignore[misc]
# region Prep methods
- def _prepare_tools_for_openai(self, tools: Sequence[Any] | None) -> list[Any]:
+ def _prepare_tools_for_openai(
+ self, tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None
+ ) -> list[Any]:
"""Prepare tools for the OpenAI Responses API.
Converts FunctionTool to Responses API format. All other tools pass through unchanged.
Args:
- tools: Sequence of tools to prepare.
+ tools: A single tool or sequence of tools to prepare.
Returns:
List of tool parameters ready for the OpenAI API.
"""
- if not tools:
+ tools_list = normalize_tools(tools)
+ if not tools_list:
return []
response_tools: list[Any] = []
- for tool in tools:
+ for tool in tools_list:
if isinstance(tool, FunctionTool):
params = tool.parameters()
params["additionalProperties"] = False
diff --git a/python/packages/core/tests/openai/test_openai_responses_client.py b/python/packages/core/tests/openai/test_openai_responses_client.py
index 12e5b42d6d..7eaae1e776 100644
--- a/python/packages/core/tests/openai/test_openai_responses_client.py
+++ b/python/packages/core/tests/openai/test_openai_responses_client.py
@@ -1193,6 +1193,52 @@ def test_prepare_tools_for_openai_with_mcp() -> None:
assert "require_approval" in mcp
+def test_prepare_tools_for_openai_single_function_tool() -> None:
+ """Test that a single FunctionTool (not wrapped in a list) is handled correctly."""
+ client = OpenAIResponsesClient(model_id="test-model", api_key="test-key")
+
+ @tool
+ def hello(name: str) -> str:
+ """Say hello."""
+ return name
+
+ resp_tools = client._prepare_tools_for_openai(hello)
+ assert isinstance(resp_tools, list)
+ assert len(resp_tools) == 1
+ tool_def = resp_tools[0]
+ assert tool_def["type"] == "function"
+ assert tool_def["name"] == "hello"
+ assert tool_def["strict"] is False
+ assert "parameters" in tool_def
+ params = tool_def["parameters"]
+ assert isinstance(params, dict)
+ assert params.get("type") == "object"
+ assert "properties" in params
+ assert "name" in params["properties"]
+ assert params["properties"]["name"]["type"] == "string"
+
+
+def test_prepare_tools_for_openai_single_dict_tool() -> None:
+ """Test that a single dict tool (not wrapped in a list) is handled correctly."""
+ client = OpenAIResponsesClient(model_id="test-model", api_key="test-key")
+
+ web_tool = OpenAIResponsesClient.get_web_search_tool(search_context_size="low")
+ resp_tools = client._prepare_tools_for_openai(web_tool)
+ assert isinstance(resp_tools, list)
+ assert len(resp_tools) == 1
+ assert "type" in resp_tools[0]
+ assert resp_tools[0]["search_context_size"] == "low"
+
+
+def test_prepare_tools_for_openai_none() -> None:
+ """Test that passing None returns an empty list."""
+ client = OpenAIResponsesClient(model_id="test-model", api_key="test-key")
+
+ resp_tools = client._prepare_tools_for_openai(None)
+ assert isinstance(resp_tools, list)
+ assert len(resp_tools) == 0
+
+
def test_parse_response_from_openai_with_mcp_approval_request() -> None:
"""Test that a non-streaming mcp_approval_request is parsed into FunctionApprovalRequestContent."""
client = OpenAIResponsesClient(model_id="test-model", api_key="test-key")
From 54c0bea3b6b5c6b396e7ae79724077e4038a252e Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 07:09:36 +0900
Subject: [PATCH 12/24] Python: Fix agent option merge to support dict-defined
tools (#4314)
* Fix _merge_options dropping dict-defined tools (#4303)
_merge_options used getattr(tool, 'name', None) to de-duplicate tools,
which returns None for dict-style tool definitions. This caused all
override dict tools to be treated as duplicates of each other and of any
base dict tools, silently dropping them.
Add _get_tool_name() helper that extracts the name from both object-style
tools (via .name attribute) and dict-style tools (via tool['function']['name']).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address review: fix None dedup bug and add comprehensive tests (#4303)
- Exclude None from existing_names set so nameless/malformed tools are
not silently deduplicated against each other
- Add test for cross-type dedup (dict tool + object tool with same name)
- Add test verifying nameless tools are preserved (not falsely deduped)
- Add unit tests for _get_tool_name edge cases: missing function key,
non-dict function value, missing name, no name attribute, non-dict
inputs, and valid dict/object tools
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../packages/core/agent_framework/_agents.py | 14 +-
.../packages/core/tests/core/test_agents.py | 148 +++++++++++++++++-
2 files changed, 159 insertions(+), 3 deletions(-)
diff --git a/python/packages/core/agent_framework/_agents.py b/python/packages/core/agent_framework/_agents.py
index 580b6e2c6d..a519796b17 100644
--- a/python/packages/core/agent_framework/_agents.py
+++ b/python/packages/core/agent_framework/_agents.py
@@ -81,6 +81,16 @@ OptionsCoT = TypeVar(
)
+def _get_tool_name(tool: Any) -> str | None:
+ """Extract a tool's name from either an object with a .name attribute or a dict tool definition."""
+ if isinstance(tool, dict):
+ func = tool.get("function")
+ if isinstance(func, dict):
+ return func.get("name")
+ return None
+ return getattr(tool, "name", None)
+
+
def _merge_options(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
"""Merge two options dicts, with override values taking precedence.
@@ -97,8 +107,8 @@ def _merge_options(base: dict[str, Any], override: dict[str, Any]) -> dict[str,
continue
if key == "tools" and result.get("tools"):
# Combine tool lists, avoiding duplicates by name
- existing_names = {getattr(t, "name", None) for t in result["tools"]}
- unique_new = [t for t in value if getattr(t, "name", None) not in existing_names]
+ existing_names = {_get_tool_name(t) for t in result["tools"]} - {None}
+ unique_new = [t for t in value if _get_tool_name(t) not in existing_names]
result["tools"] = list(result["tools"]) + unique_new
elif key == "logit_bias" and result.get("logit_bias"):
# Merge logit_bias dicts
diff --git a/python/packages/core/tests/core/test_agents.py b/python/packages/core/tests/core/test_agents.py
index b6f84dc970..a857682fe2 100644
--- a/python/packages/core/tests/core/test_agents.py
+++ b/python/packages/core/tests/core/test_agents.py
@@ -25,7 +25,7 @@ from agent_framework import (
SupportsChatGetResponse,
tool,
)
-from agent_framework._agents import _merge_options, _sanitize_agent_name
+from agent_framework._agents import _get_tool_name, _merge_options, _sanitize_agent_name
from agent_framework._mcp import MCPTool
@@ -932,6 +932,152 @@ def test_merge_options_tools_combined():
assert "tool2" in tool_names
+def test_merge_options_dict_tools_combined():
+ """Test _merge_options combines dict-defined tool lists without duplicates."""
+ base = {
+ "tools": [
+ {"type": "function", "function": {"name": "tool_a"}},
+ ]
+ }
+ override = {
+ "tools": [
+ {"type": "function", "function": {"name": "tool_b"}},
+ ]
+ }
+
+ result = _merge_options(base, override)
+
+ assert len(result["tools"]) == 2
+ names = [_get_tool_name(t) for t in result["tools"]]
+ assert "tool_a" in names
+ assert "tool_b" in names
+
+
+def test_merge_options_dict_tools_deduplicates():
+ """Test _merge_options deduplicates dict-defined tools by function name."""
+ base = {
+ "tools": [
+ {"type": "function", "function": {"name": "tool_a"}},
+ ]
+ }
+ override = {
+ "tools": [
+ {"type": "function", "function": {"name": "tool_a"}},
+ {"type": "function", "function": {"name": "tool_b"}},
+ ]
+ }
+
+ result = _merge_options(base, override)
+
+ assert len(result["tools"]) == 2
+ names = [_get_tool_name(t) for t in result["tools"]]
+ assert names.count("tool_a") == 1
+ assert "tool_b" in names
+
+
+def test_merge_options_mixed_tools_combined():
+ """Test _merge_options combines object and dict-defined tools."""
+
+ class MockTool:
+ def __init__(self, name):
+ self.name = name
+
+ base = {"tools": [MockTool("tool_a")]}
+ override = {
+ "tools": [
+ {"type": "function", "function": {"name": "tool_b"}},
+ ]
+ }
+
+ result = _merge_options(base, override)
+
+ assert len(result["tools"]) == 2
+ names = [_get_tool_name(t) for t in result["tools"]]
+ assert "tool_a" in names
+ assert "tool_b" in names
+
+
+def test_merge_options_mixed_tools_deduplicates():
+ """Test _merge_options deduplicates when a dict tool and object tool share the same name."""
+
+ class MockTool:
+ def __init__(self, name):
+ self.name = name
+
+ base = {"tools": [MockTool("tool_a")]}
+ override = {
+ "tools": [
+ {"type": "function", "function": {"name": "tool_a"}},
+ ]
+ }
+
+ result = _merge_options(base, override)
+
+ assert len(result["tools"]) == 1
+ assert _get_tool_name(result["tools"][0]) == "tool_a"
+
+
+def test_merge_options_nameless_tools_not_deduplicated():
+ """Test that tools with no extractable name (None) are not falsely deduplicated."""
+ base = {
+ "tools": [
+ {"type": "function"}, # no 'function.name' -> _get_tool_name returns None
+ ]
+ }
+ override = {
+ "tools": [
+ {"type": "function"}, # also returns None
+ ]
+ }
+
+ result = _merge_options(base, override)
+
+ # Both nameless tools should be kept (None is excluded from dedup set)
+ assert len(result["tools"]) == 2
+
+
+def test_get_tool_name_dict_no_function_key():
+ """_get_tool_name returns None for a dict without a 'function' key."""
+ assert _get_tool_name({"type": "function"}) is None
+
+
+def test_get_tool_name_dict_function_not_dict():
+ """_get_tool_name returns None when 'function' value is not a dict."""
+ assert _get_tool_name({"function": "not_a_dict"}) is None
+
+
+def test_get_tool_name_dict_function_no_name():
+ """_get_tool_name returns None when 'function' dict has no 'name' key."""
+ assert _get_tool_name({"function": {"description": "does stuff"}}) is None
+
+
+def test_get_tool_name_object_no_name_attr():
+ """_get_tool_name returns None for an object without a 'name' attribute."""
+ assert _get_tool_name(object()) is None
+
+
+def test_get_tool_name_non_dict_non_object():
+ """_get_tool_name returns None for non-dict inputs like int or string."""
+ assert _get_tool_name(42) is None
+ assert _get_tool_name("tool_name") is None
+
+
+def test_get_tool_name_valid_dict():
+ """_get_tool_name extracts name from a well-formed dict tool."""
+ tool_dict = {"type": "function", "function": {"name": "my_tool"}}
+ assert _get_tool_name(tool_dict) == "my_tool"
+
+
+def test_get_tool_name_valid_object():
+ """_get_tool_name extracts name from an object with a name attribute."""
+
+ class MockTool:
+ def __init__(self, name):
+ self.name = name
+
+ assert _get_tool_name(MockTool("my_tool")) == "my_tool"
+
+
def test_merge_options_logit_bias_merged():
"""Test _merge_options merges logit_bias dicts."""
base = {"logit_bias": {"token1": 1.0}}
From c45d47d4b24b59e23bceb0625ca2cd8f7259b88b Mon Sep 17 00:00:00 2001
From: Tao Chen
Date: Thu, 26 Feb 2026 18:45:10 -0800
Subject: [PATCH 13/24] Python: Tuning auto sample validation workflow (#4218)
* Tuning validate-01-get-started
* Add gh token
* Add model
* enable debug log
* bump up timeout for testing purposes
* Test cli is working
* Fix end quote
* Run gh auth
* Run gh auth trail 2
* Run gh auth trail 3
* Test token
* Add zcure login
* Add zcure login 2
* Add zcure login 3
* Add zcure login 4
* Extract common actions
* Extract common actions 2
* Correct env vars
* Print outputs to action console
* Disable end-to-end samples
* Fix ruff errors
* Fix ruff errors 2
* Revert workflow changes to fix tests
* Revert workflow changes to fix tests 2
* Revert workflow changes to fix tests 3
* Revert workflow changes to fix tests 4
---
.../sample-validation-setup/action.yml | 48 +++++
.../workflows/python-sample-validation.yml | 190 +++++++++---------
.../agent_framework_azurefunctions/_app.py | 6 +-
.../packages/core/agent_framework/_types.py | 12 +-
.../agent_framework/_workflows/_workflow.py | 1 -
.../agent_framework_devui/_deployment.py | 3 +-
python/pyproject.toml | 2 +
.../create_dynamic_workflow_executor.py | 5 +-
python/samples/_sample_validation/report.py | 16 +-
9 files changed, 171 insertions(+), 112 deletions(-)
create mode 100644 .github/actions/sample-validation-setup/action.yml
diff --git a/.github/actions/sample-validation-setup/action.yml b/.github/actions/sample-validation-setup/action.yml
new file mode 100644
index 0000000000..3736348579
--- /dev/null
+++ b/.github/actions/sample-validation-setup/action.yml
@@ -0,0 +1,48 @@
+name: Sample Validation Setup
+description: Sets up the environment for sample validation (checkout, Node.js, Copilot CLI, Azure login, Python)
+
+inputs:
+ azure-client-id:
+ description: Azure Client ID for OIDC login
+ required: true
+ azure-tenant-id:
+ description: Azure Tenant ID for OIDC login
+ required: true
+ azure-subscription-id:
+ description: Azure Subscription ID for OIDC login
+ required: true
+ python-version:
+ description: The Python version to set up
+ required: false
+ default: "3.12"
+ os:
+ description: The operating system to set up
+ required: false
+ default: "Linux"
+
+runs:
+ using: "composite"
+ steps:
+ - name: Set up Node.js environment
+ uses: actions/setup-node@v4
+
+ - name: Install Copilot CLI
+ shell: bash
+ run: npm install -g @github/copilot
+
+ - name: Test Copilot CLI
+ shell: bash
+ run: copilot -p "What can you do in one sentence?"
+
+ - name: Azure CLI Login
+ uses: azure/login@v2
+ with:
+ client-id: ${{ inputs.azure-client-id }}
+ tenant-id: ${{ inputs.azure-tenant-id }}
+ subscription-id: ${{ inputs.azure-subscription-id }}
+
+ - name: Set up python and install the project
+ uses: ./.github/actions/python-setup
+ with:
+ python-version: ${{ inputs.python-version }}
+ os: ${{ inputs.os }}
diff --git a/.github/workflows/python-sample-validation.yml b/.github/workflows/python-sample-validation.yml
index ba43394483..1ada1ab113 100644
--- a/.github/workflows/python-sample-validation.yml
+++ b/.github/workflows/python-sample-validation.yml
@@ -8,32 +8,38 @@ on:
env:
# Configure a constant location for the uv cache
UV_CACHE_DIR: /tmp/.uv-cache
+ # GitHub Copilot configuration
+ GITHUB_COPILOT_MODEL: claude-opus-4.6
+ COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+
+permissions:
+ contents: read
+ id-token: write
jobs:
validate-01-get-started:
name: Validate 01-get-started
runs-on: ubuntu-latest
- permissions:
- contents: read
+ environment: integration
env:
- # Azure AI configuration for get-started samples
- AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZURE_AI_PROJECT_ENDPOINT }}
- AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ secrets.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
- # GitHub Copilot configuration
- GITHUB_COPILOT_MODEL: ${{ vars.GITHUB_COPILOT_MODEL }}
+ # Required configuration for get-started samples
+ AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+ AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+ AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
defaults:
run:
working-directory: python
steps:
- uses: actions/checkout@v6
- - name: Set up python and install the project
- uses: ./.github/actions/python-setup
+ - name: Setup environment
+ uses: ./.github/actions/sample-validation-setup
with:
- python-version: "3.12"
+ azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
os: ${{ runner.os }}
- env:
- UV_CACHE_DIR: /tmp/.uv-cache
- name: Run sample validation
run: |
@@ -49,37 +55,34 @@ jobs:
validate-02-agents:
name: Validate 02-agents
runs-on: ubuntu-latest
- permissions:
- contents: read
+ environment: integration
env:
# Azure AI configuration
- AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZURE_AI_PROJECT_ENDPOINT }}
- AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ secrets.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+ AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+ AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# Azure OpenAI configuration
- AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
- AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_CHAT_DEPLOYMENT_NAME }}
- AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME }}
+ AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+ AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# OpenAI configuration
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
- OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI_CHAT_MODEL_ID }}
- OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI_RESPONSES_MODEL_ID }}
+ OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
+ OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
# Observability
ENABLE_INSTRUMENTATION: "true"
- # GitHub Copilot configuration
- GITHUB_COPILOT_MODEL: ${{ vars.GITHUB_COPILOT_MODEL }}
defaults:
run:
working-directory: python
steps:
- uses: actions/checkout@v6
- - name: Set up python and install the project
- uses: ./.github/actions/python-setup
+ - name: Setup environment
+ uses: ./.github/actions/sample-validation-setup
with:
- python-version: "3.12"
+ azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
os: ${{ runner.os }}
- env:
- UV_CACHE_DIR: /tmp/.uv-cache
- name: Run sample validation
run: |
@@ -95,31 +98,28 @@ jobs:
validate-03-workflows:
name: Validate 03-workflows
runs-on: ubuntu-latest
- permissions:
- contents: read
+ environment: integration
env:
# Azure AI configuration
- AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZURE_AI_PROJECT_ENDPOINT }}
- AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ secrets.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+ AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+ AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# Azure OpenAI configuration
- AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
- AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_CHAT_DEPLOYMENT_NAME }}
- AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME }}
- # GitHub Copilot configuration
- GITHUB_COPILOT_MODEL: ${{ vars.GITHUB_COPILOT_MODEL }}
+ AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+ AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
defaults:
run:
working-directory: python
steps:
- uses: actions/checkout@v6
- - name: Set up python and install the project
- uses: ./.github/actions/python-setup
+ - name: Setup environment
+ uses: ./.github/actions/sample-validation-setup
with:
- python-version: "3.12"
+ azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
os: ${{ runner.os }}
- env:
- UV_CACHE_DIR: /tmp/.uv-cache
- name: Run sample validation
run: |
@@ -134,31 +134,31 @@ jobs:
validate-04-hosting:
name: Validate 04-hosting
+ if: false # Temporarily disabled because of sample complexity
runs-on: ubuntu-latest
- permissions:
- contents: read
+ environment: integration
env:
# Azure AI configuration
- AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZURE_AI_PROJECT_ENDPOINT }}
- AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ secrets.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+ AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+ AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# Azure OpenAI configuration
- AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
- AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME }}
- # GitHub Copilot configuration
- GITHUB_COPILOT_MODEL: ${{ vars.GITHUB_COPILOT_MODEL }}
+ AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+ AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+ # A2A configuration
+ A2A_AGENT_HOST: http://localhost:5001/
defaults:
run:
working-directory: python
steps:
- uses: actions/checkout@v6
- - name: Set up python and install the project
- uses: ./.github/actions/python-setup
+ - name: Setup environment
+ uses: ./.github/actions/sample-validation-setup
with:
- python-version: "3.12"
+ azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
os: ${{ runner.os }}
- env:
- UV_CACHE_DIR: /tmp/.uv-cache
- name: Run sample validation
run: |
@@ -173,36 +173,36 @@ jobs:
validate-05-end-to-end:
name: Validate 05-end-to-end
+ if: false # Temporarily disabled because of sample complexity
runs-on: ubuntu-latest
- permissions:
- contents: read
+ environment: integration
env:
# Azure AI configuration
- AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZURE_AI_PROJECT_ENDPOINT }}
- AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ secrets.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+ AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+ AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# Azure OpenAI configuration
- AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
- AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_CHAT_DEPLOYMENT_NAME }}
- AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME }}
+ AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+ AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# Azure AI Search (for evaluation samples)
AZURE_SEARCH_ENDPOINT: ${{ secrets.AZURE_SEARCH_ENDPOINT }}
AZURE_SEARCH_API_KEY: ${{ secrets.AZURE_SEARCH_API_KEY }}
AZURE_SEARCH_INDEX_NAME: ${{ secrets.AZURE_SEARCH_INDEX_NAME }}
- # GitHub Copilot configuration
- GITHUB_COPILOT_MODEL: ${{ vars.GITHUB_COPILOT_MODEL }}
+ # Evaluation sample
+ AZURE_AI_MODEL_DEPLOYMENT_NAME_WORKFLOW: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
defaults:
run:
working-directory: python
steps:
- uses: actions/checkout@v6
- - name: Set up python and install the project
- uses: ./.github/actions/python-setup
+ - name: Setup environment
+ uses: ./.github/actions/sample-validation-setup
with:
- python-version: "3.12"
+ azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
os: ${{ runner.os }}
- env:
- UV_CACHE_DIR: /tmp/.uv-cache
- name: Run sample validation
run: |
@@ -218,30 +218,31 @@ jobs:
validate-autogen-migration:
name: Validate autogen-migration
runs-on: ubuntu-latest
- permissions:
- contents: read
+ environment: integration
env:
# Azure AI configuration
- AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZURE_AI_PROJECT_ENDPOINT }}
- AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ secrets.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+ AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+ AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# Azure OpenAI configuration
- AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
- AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_CHAT_DEPLOYMENT_NAME }}
- # GitHub Copilot configuration
- GITHUB_COPILOT_MODEL: ${{ vars.GITHUB_COPILOT_MODEL }}
+ AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+ # OpenAI configuration
+ OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+ OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
+ OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
defaults:
run:
working-directory: python
steps:
- uses: actions/checkout@v6
- - name: Set up python and install the project
- uses: ./.github/actions/python-setup
+ - name: Setup environment
+ uses: ./.github/actions/sample-validation-setup
with:
- python-version: "3.12"
+ azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
os: ${{ runner.os }}
- env:
- UV_CACHE_DIR: /tmp/.uv-cache
- name: Run sample validation
run: |
@@ -257,16 +258,15 @@ jobs:
validate-semantic-kernel-migration:
name: Validate semantic-kernel-migration
runs-on: ubuntu-latest
- permissions:
- contents: read
+ environment: integration
env:
# Azure AI configuration
- AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZURE_AI_PROJECT_ENDPOINT }}
- AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ secrets.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+ AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+ AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# Azure OpenAI configuration
- AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
- AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_CHAT_DEPLOYMENT_NAME }}
- AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME }}
+ AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+ AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# OpenAI configuration
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI_CHAT_MODEL_ID }}
@@ -276,21 +276,19 @@ jobs:
COPILOTSTUDIOAGENT__SCHEMANAME: ${{ secrets.COPILOTSTUDIOAGENT__SCHEMANAME }}
COPILOTSTUDIOAGENT__TENANTID: ${{ secrets.COPILOTSTUDIOAGENT__TENANTID }}
COPILOTSTUDIOAGENT__AGENTAPPID: ${{ secrets.COPILOTSTUDIOAGENT__AGENTAPPID }}
- # GitHub Copilot configuration
- GITHUB_COPILOT_MODEL: ${{ vars.GITHUB_COPILOT_MODEL }}
defaults:
run:
working-directory: python
steps:
- uses: actions/checkout@v6
- - name: Set up python and install the project
- uses: ./.github/actions/python-setup
+ - name: Setup environment
+ uses: ./.github/actions/sample-validation-setup
with:
- python-version: "3.12"
+ azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
+ azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+ azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
os: ${{ runner.os }}
- env:
- UV_CACHE_DIR: /tmp/.uv-cache
- name: Run sample validation
run: |
diff --git a/python/packages/azurefunctions/agent_framework_azurefunctions/_app.py b/python/packages/azurefunctions/agent_framework_azurefunctions/_app.py
index 01735e28d1..c7d8552b24 100644
--- a/python/packages/azurefunctions/agent_framework_azurefunctions/_app.py
+++ b/python/packages/azurefunctions/agent_framework_azurefunctions/_app.py
@@ -612,11 +612,11 @@ class AgentFunctionApp(DFAppBase):
context: Durable Functions orchestration context invoking the agent.
agent_name: Name of the agent registered on this app.
- Raises:
- ValueError: If the requested agent has not been registered.
-
Returns:
DurableAIAgent[AgentTask] wrapper bound to the orchestration context.
+
+ Raises:
+ ValueError: If the requested agent has not been registered.
"""
normalized_name = str(agent_name)
diff --git a/python/packages/core/agent_framework/_types.py b/python/packages/core/agent_framework/_types.py
index 37ee9f1138..3df0bb20fb 100644
--- a/python/packages/core/agent_framework/_types.py
+++ b/python/packages/core/agent_framework/_types.py
@@ -93,13 +93,13 @@ def detect_media_type_from_base64(
This will look at the actual data to determine the media_type and not at the URI prefix.
Will also not compare those two values.
- Raises:
- ValueError: If not exactly 1 of data_bytes, data_str, or data_uri is provided, or if base64 decoding fails.
-
Returns:
The detected media type (e.g., 'image/png', 'audio/wav', 'application/pdf')
or None if the format is not recognized.
+ Raises:
+ ValueError: If not exactly 1 of data_bytes, data_str, or data_uri is provided, or if base64 decoding fails.
+
Examples:
.. code-block:: python
@@ -670,6 +670,9 @@ class Content:
additional_properties: Optional additional properties.
raw_representation: Optional raw representation from an underlying implementation.
+ Returns:
+ A Content instance with type="data" for data URIs or type="uri" for external URIs.
+
Raises:
ContentError: If the URI is not valid.
@@ -693,9 +696,6 @@ class Content:
raw_base64_string
}"
)
-
- Returns:
- A Content instance with type="data" for data URIs or type="uri" for external URIs.
"""
return cls(
**_validate_uri(uri, media_type),
diff --git a/python/packages/core/agent_framework/_workflows/_workflow.py b/python/packages/core/agent_framework/_workflows/_workflow.py
index f545fbe5d8..8c6b5fe1fb 100644
--- a/python/packages/core/agent_framework/_workflows/_workflow.py
+++ b/python/packages/core/agent_framework/_workflows/_workflow.py
@@ -374,7 +374,6 @@ class Workflow(DictConvertible):
with _framework_event_origin():
pending_status = WorkflowEvent.status(WorkflowRunState.IN_PROGRESS_PENDING_REQUESTS)
yield pending_status
-
# Workflow runs until idle - emit final status based on whether requests are pending
if saw_request:
with _framework_event_origin():
diff --git a/python/packages/devui/agent_framework_devui/_deployment.py b/python/packages/devui/agent_framework_devui/_deployment.py
index 45f99a315a..db2de27ecf 100644
--- a/python/packages/devui/agent_framework_devui/_deployment.py
+++ b/python/packages/devui/agent_framework_devui/_deployment.py
@@ -92,8 +92,7 @@ class DeploymentManager:
break
# Get event from queue with short timeout
- event = await asyncio.wait_for(event_queue.get(), timeout=0.1)
- yield event
+ yield await asyncio.wait_for(event_queue.get(), timeout=0.1)
except asyncio.TimeoutError:
# No event in queue, continue waiting
continue
diff --git a/python/pyproject.toml b/python/pyproject.toml
index a03123e9a2..e4e45f0290 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -148,6 +148,8 @@ ignore = [
"**/tests/**" = ["D", "INP", "TD", "ERA001", "RUF", "S"]
"samples/**" = ["D", "INP", "ERA001", "RUF", "S", "T201", "CPY"]
"*.ipynb" = ["CPY", "E501"]
+# RUF070: Assignment before yield is intentional - context manager must exit before yielding
+"**/agent_framework/_workflows/_workflow.py" = ["RUF070"]
[tool.ruff.format]
docstring-code-format = true
diff --git a/python/samples/_sample_validation/create_dynamic_workflow_executor.py b/python/samples/_sample_validation/create_dynamic_workflow_executor.py
index a8fd2011b4..bff720130d 100644
--- a/python/samples/_sample_validation/create_dynamic_workflow_executor.py
+++ b/python/samples/_sample_validation/create_dynamic_workflow_executor.py
@@ -53,9 +53,10 @@ class BatchCompletion:
AgentInstruction = (
"You are validating exactly one Python sample.\n"
- "Analyze the sample code and execute it. Determine if it runs successfully, fails, or times out.\n"
+ "Analyze the sample code and execute it. Based on the execution result, determine if it "
+ "runs successfully, fails, or times out. Feel free to install any required dependencies.\n"
"The sample can be interactive. If it is interactive, respond to the sample when prompted "
- "based on your analysis of the code. You do not need to consult human on what to respond\n"
+ "based on your analysis of the code. You do not need to consult human on what to respond.\n"
"Return ONLY valid JSON with this schema:\n"
"{\n"
' "status": "success|failure|timeout|error",\n'
diff --git a/python/samples/_sample_validation/report.py b/python/samples/_sample_validation/report.py
index d6083f44f6..9d02d342d4 100644
--- a/python/samples/_sample_validation/report.py
+++ b/python/samples/_sample_validation/report.py
@@ -21,6 +21,14 @@ def generate_report(results: list[RunResult]) -> Report:
Returns:
Report object with aggregated statistics
"""
+ # Sort results: failures, timeouts, errors first, then successes
+ status_priority = {
+ RunStatus.FAILURE: 0,
+ RunStatus.TIMEOUT: 1,
+ RunStatus.ERROR: 2,
+ RunStatus.SUCCESS: 3,
+ }
+ sorted_results = sorted(results, key=lambda r: status_priority[r.status])
return Report(
timestamp=datetime.now(),
@@ -29,7 +37,7 @@ def generate_report(results: list[RunResult]) -> Report:
failure_count=sum(1 for r in results if r.status == RunStatus.FAILURE),
timeout_count=sum(1 for r in results if r.status == RunStatus.TIMEOUT),
error_count=sum(1 for r in results if r.status == RunStatus.ERROR),
- results=results,
+ results=sorted_results,
)
@@ -84,9 +92,13 @@ def print_summary(report: Report) -> None:
print(f" [PASS] Success: {report.success_count}")
print(f" [FAIL] Failure: {report.failure_count}")
print(f" [TIMEOUT] Timeout: {report.timeout_count}")
- print(f" [ERROR] Error: {report.error_count}")
+ print(f" [ERR] Errors: {report.error_count}")
print("=" * 80)
+ # Print JSON output for GitHub Actions visibility
+ print("\nJSON Report:")
+ print(json.dumps(report.to_dict(), indent=2))
+
class GenerateReportExecutor(Executor):
"""Executor that generates the final validation report."""
From 0d6b9d61a5a7b02a8ca5e60daebc95478bf918aa Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Fri, 27 Feb 2026 11:59:57 +0900
Subject: [PATCH 14/24] Python: Fix executor handler type resolution when using
`from __future__ import annotations` (#4317)
* Python: Fix Executor handler type checking with __future__ annotations (#3898)
Use typing.get_type_hints() in _validate_handler_signature to resolve
string annotations from `from __future__ import annotations`. This
mirrors the fix applied to FunctionExecutor in #2308.
When __future__ annotations are enabled, type annotations are stored as
strings. The handler decorator was passing these strings directly to
validate_workflow_context_annotation, which uses typing.get_origin and
returns None for strings, causing a ValueError.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address PR review feedback for #3898: improve error handling and test coverage
- Wrap typing.get_type_hints() in try/except to provide a descriptive
ValueError mentioning the handler name when annotations cannot be resolved
- Strengthen bare context test to assert output_types and workflow_output_types
- Add test for @handler(input=..., output=...) with future annotations
covering the skip_message_annotation branch
- Add test for union-type context annotations with future annotations
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Narrow exception catch and add test for unresolvable annotations (#3898)
- Narrow except clause from bare Exception to (NameError, AttributeError,
TypeError) to avoid masking unexpected errors.
- Add test_handler_unresolvable_annotation_raises to verify that a handler
with a forward-reference to a non-existent type raises ValueError with
the expected message.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix #3898: fall back to raw annotations when get_type_hints fails
When typing.get_type_hints(func) raises NameError (unresolvable forward
ref), AttributeError, RecursionError, or any other exception, fall back
to the raw parameter annotations instead of raising a ValueError.
This matches the suggestion from @moonbox3 on PR #4317.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix test to match new fallback behavior when get_type_hints fails (#3898)
The code now falls back to raw string annotations instead of raising
'Failed to resolve type annotations'. A ValueError is still raised when
the raw string ctx annotation is not a valid WorkflowContext type, so
update the test to match on ValueError without checking the message.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Apply pyupgrade: remove unnecessary string annotation quote
* Add noqa for intentionally undefined name in annotation test
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../agent_framework/_workflows/_executor.py | 19 ++-
.../tests/workflow/test_executor_future.py | 124 ++++++++++++++++++
2 files changed, 139 insertions(+), 4 deletions(-)
create mode 100644 python/packages/core/tests/workflow/test_executor_future.py
diff --git a/python/packages/core/agent_framework/_workflows/_executor.py b/python/packages/core/agent_framework/_workflows/_executor.py
index f219c0c28f..d2bb2ac598 100644
--- a/python/packages/core/agent_framework/_workflows/_executor.py
+++ b/python/packages/core/agent_framework/_workflows/_executor.py
@@ -6,6 +6,7 @@ import functools
import inspect
import logging
import types
+import typing
from collections.abc import Awaitable, Callable
from typing import Any, TypeVar, overload
@@ -722,20 +723,30 @@ def _validate_handler_signature(
if not skip_message_annotation and message_param.annotation == inspect.Parameter.empty:
raise ValueError(f"Handler {func.__name__} must have a type annotation for the message parameter")
+ # Resolve string annotations from `from __future__ import annotations`.
+ # Fall back to raw annotations if resolution fails (e.g. unresolvable forward refs,
+ # AttributeError, or RecursionError), so registration failures are easier to diagnose.
+ try:
+ type_hints = typing.get_type_hints(func)
+ except Exception:
+ type_hints = {p.name: p.annotation for p in params}
+
# Validate ctx parameter is WorkflowContext and extract type args
ctx_param = params[2]
- if skip_message_annotation and ctx_param.annotation == inspect.Parameter.empty:
+ ctx_annotation = type_hints.get(ctx_param.name, ctx_param.annotation)
+ if skip_message_annotation and ctx_annotation == inspect.Parameter.empty:
# When explicit types are provided via @handler(input=..., output=...),
# the ctx parameter doesn't need a type annotation - types come from the decorator.
output_types: list[type[Any] | types.UnionType] = []
workflow_output_types: list[type[Any] | types.UnionType] = []
else:
output_types, workflow_output_types = validate_workflow_context_annotation(
- ctx_param.annotation, f"parameter '{ctx_param.name}'", "Handler"
+ ctx_annotation, f"parameter '{ctx_param.name}'", "Handler"
)
- message_type = message_param.annotation if message_param.annotation != inspect.Parameter.empty else None
- ctx_annotation = ctx_param.annotation
+ message_type = type_hints.get(message_param.name, message_param.annotation)
+ if message_type == inspect.Parameter.empty:
+ message_type = None
return message_type, ctx_annotation, output_types, workflow_output_types
diff --git a/python/packages/core/tests/workflow/test_executor_future.py b/python/packages/core/tests/workflow/test_executor_future.py
new file mode 100644
index 0000000000..c0916b9cf7
--- /dev/null
+++ b/python/packages/core/tests/workflow/test_executor_future.py
@@ -0,0 +1,124 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from pydantic import BaseModel
+
+from agent_framework import Executor, WorkflowContext, handler
+
+
+class MyTypeA(BaseModel):
+ pass
+
+
+class MyTypeB(BaseModel):
+ pass
+
+
+class MyTypeC(BaseModel):
+ pass
+
+
+class TestExecutorFutureAnnotations:
+ """Test suite for Executor with from __future__ import annotations."""
+
+ def test_handler_decorator_future_annotations(self):
+ """Test @handler decorator works with stringified annotations (issue #3898)."""
+
+ class MyExecutor(Executor):
+ @handler
+ async def example(self, input: str, ctx: WorkflowContext[MyTypeA, MyTypeB]) -> None:
+ pass
+
+ exec_instance = MyExecutor(id="test")
+ assert str in exec_instance._handlers
+ spec = exec_instance._handler_specs[0]
+ assert spec["message_type"] is str
+ assert spec["output_types"] == [MyTypeA]
+ assert spec["workflow_output_types"] == [MyTypeB]
+
+ def test_handler_decorator_future_annotations_single_type_arg(self):
+ """Test @handler with single type argument and future annotations."""
+
+ class MyExecutor(Executor):
+ @handler
+ async def example(self, input: int, ctx: WorkflowContext[MyTypeA]) -> None:
+ pass
+
+ exec_instance = MyExecutor(id="test")
+ assert int in exec_instance._handlers
+ spec = exec_instance._handler_specs[0]
+ assert spec["message_type"] is int
+ assert spec["output_types"] == [MyTypeA]
+
+ def test_handler_decorator_future_annotations_complex(self):
+ """Test @handler with complex type annotations and future annotations."""
+
+ class MyExecutor(Executor):
+ @handler
+ async def example(self, data: dict[str, Any], ctx: WorkflowContext[list[str]]) -> None:
+ pass
+
+ exec_instance = MyExecutor(id="test")
+ spec = exec_instance._handler_specs[0]
+ assert spec["message_type"] == dict[str, Any]
+ assert spec["output_types"] == [list[str]]
+
+ def test_handler_decorator_future_annotations_bare_context(self):
+ """Test @handler with bare WorkflowContext and future annotations."""
+
+ class MyExecutor(Executor):
+ @handler
+ async def example(self, input: str, ctx: WorkflowContext) -> None:
+ pass
+
+ exec_instance = MyExecutor(id="test")
+ assert str in exec_instance._handlers
+ spec = exec_instance._handler_specs[0]
+ assert spec["output_types"] == []
+ assert spec["workflow_output_types"] == []
+
+ def test_handler_decorator_future_annotations_explicit_types(self):
+ """Test @handler with explicit type parameters under future annotations."""
+
+ class MyExecutor(Executor):
+ @handler(input=str, output=MyTypeA)
+ async def example(self, input, ctx) -> None:
+ pass
+
+ exec_instance = MyExecutor(id="test")
+ assert str in exec_instance._handlers
+ spec = exec_instance._handler_specs[0]
+ assert spec["message_type"] is str
+ assert spec["output_types"] == [MyTypeA]
+
+ def test_handler_decorator_future_annotations_union_context(self):
+ """Test @handler with union type context annotations and future annotations."""
+
+ class MyExecutor(Executor):
+ @handler
+ async def example(self, input: str, ctx: WorkflowContext[MyTypeA | MyTypeB, MyTypeC]) -> None:
+ pass
+
+ exec_instance = MyExecutor(id="test")
+ assert str in exec_instance._handlers
+ spec = exec_instance._handler_specs[0]
+ assert spec["output_types"] == [MyTypeA, MyTypeB]
+ assert spec["workflow_output_types"] == [MyTypeC]
+
+ def test_handler_unresolvable_annotation_raises(self):
+ """Test that an unresolvable forward-reference annotation raises ValueError.
+
+ When get_type_hints fails (e.g. NameError for NonExistentType), the code falls back
+ to raw string annotations. The ctx parameter's raw string annotation is then not
+ recognised as a valid WorkflowContext type, so a ValueError is still raised.
+ """
+ with pytest.raises(ValueError):
+
+ class Bad(Executor):
+ @handler
+ async def example(self, input: NonExistentType, ctx: WorkflowContext[MyTypeA, MyTypeB]) -> None: # noqa: F821
+ pass
From 9124d51e0eda5f3bc790a6c5f8fc5c7605c62f02 Mon Sep 17 00:00:00 2001
From: Victor Dibia
Date: Mon, 2 Mar 2026 02:34:25 -0800
Subject: [PATCH 15/24] Python: .NET: Fix .NET conversation memory in DevUI
(#3484) (#4294)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* Fix .NET conversation memory in DevUI (#3484)
* formatting fixes
* fix memory regression in python devui , fix for #4123
* Fix for #3983: Added _get_event_type() helper that safely accesses event type on both objects (.type) and dicts (.get("type")). Replaced all 4 bare event.type accesses in _executor.py (lines 267, 477, 499, 523).
Root cause: PR #3690 changed event.__class__.__name__ == "RequestInfoEvent" (safe) to event.type == "request_info" (crashes on dicts), but _execute_workflow still yields raw dicts on error paths.
Test: test_workflow_error_yields_dict_event_without_crash — mocks a workflow that raises, verifies execute_entity consumes the dict error events without crashing.
* format fixes
* lint fixes
---
.../Responses/AIAgentResponseExecutor.cs | 8 +-
.../Converters/ItemResourceConversions.cs | 113 ++++++++++++++++++
.../Responses/HostedAgentResponseExecutor.cs | 6 +
.../Responses/IResponseExecutor.cs | 3 +
.../Responses/InMemoryResponsesService.cs | 19 ++-
.../OpenAIResponsesIntegrationTests.cs | 92 ++++++++++++++
.../TestHelpers.cs | 80 +++++++++++++
.../devui/agent_framework_devui/_executor.py | 38 +++---
.../devui/tests/devui/test_execution.py | 45 +++++++
9 files changed, 388 insertions(+), 16 deletions(-)
create mode 100644 dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Converters/ItemResourceConversions.cs
diff --git a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/AIAgentResponseExecutor.cs b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/AIAgentResponseExecutor.cs
index e3706bee1c..e2e07d00b7 100644
--- a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/AIAgentResponseExecutor.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/AIAgentResponseExecutor.cs
@@ -31,6 +31,7 @@ internal sealed class AIAgentResponseExecutor : IResponseExecutor
public async IAsyncEnumerable ExecuteAsync(
AgentInvocationContext context,
CreateResponse request,
+ IReadOnlyList? conversationHistory = null,
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
// Create options with properties from the request
@@ -51,9 +52,14 @@ internal sealed class AIAgentResponseExecutor : IResponseExecutor
};
var options = new ChatClientAgentRunOptions(chatOptions);
- // Convert input to chat messages
+ // Convert input to chat messages, prepending conversation history if available
var messages = new List();
+ if (conversationHistory is not null)
+ {
+ messages.AddRange(conversationHistory);
+ }
+
foreach (var inputMessage in request.Input.GetInputMessages())
{
messages.Add(inputMessage.ToChatMessage());
diff --git a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Converters/ItemResourceConversions.cs b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Converters/ItemResourceConversions.cs
new file mode 100644
index 0000000000..b9a935d54d
--- /dev/null
+++ b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/Converters/ItemResourceConversions.cs
@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Text.Json;
+using Microsoft.Agents.AI.Hosting.OpenAI.Responses.Models;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.Hosting.OpenAI.Responses.Converters;
+
+///
+/// Converts stored objects back to objects
+/// for injecting conversation history into agent execution.
+///
+internal static class ItemResourceConversions
+{
+ ///
+ /// Converts a sequence of items to a list of objects.
+ /// Only converts message, function call, and function result items. Other item types are skipped.
+ ///
+ public static List ToChatMessages(IEnumerable items)
+ {
+ var messages = new List();
+
+ foreach (var item in items)
+ {
+ switch (item)
+ {
+ case ResponsesUserMessageItemResource userMsg:
+ messages.Add(new ChatMessage(ChatRole.User, ConvertContents(userMsg.Content)));
+ break;
+
+ case ResponsesAssistantMessageItemResource assistantMsg:
+ messages.Add(new ChatMessage(ChatRole.Assistant, ConvertContents(assistantMsg.Content)));
+ break;
+
+ case ResponsesSystemMessageItemResource systemMsg:
+ messages.Add(new ChatMessage(ChatRole.System, ConvertContents(systemMsg.Content)));
+ break;
+
+ case ResponsesDeveloperMessageItemResource developerMsg:
+ messages.Add(new ChatMessage(new ChatRole("developer"), ConvertContents(developerMsg.Content)));
+ break;
+
+ case FunctionToolCallItemResource funcCall:
+ var arguments = ParseArguments(funcCall.Arguments);
+ messages.Add(new ChatMessage(ChatRole.Assistant,
+ [
+ new FunctionCallContent(funcCall.CallId, funcCall.Name, arguments)
+ ]));
+ break;
+
+ case FunctionToolCallOutputItemResource funcOutput:
+ messages.Add(new ChatMessage(ChatRole.Tool,
+ [
+ new FunctionResultContent(funcOutput.CallId, funcOutput.Output)
+ ]));
+ break;
+
+ // Skip all other item types (reasoning, executor_action, web_search, etc.)
+ // They are not relevant for conversation context.
+ }
+ }
+
+ return messages;
+ }
+
+ private static List ConvertContents(List contents)
+ {
+ var result = new List();
+ foreach (var content in contents)
+ {
+ var aiContent = ItemContentConverter.ToAIContent(content);
+ if (aiContent is not null)
+ {
+ result.Add(aiContent);
+ }
+ }
+
+ return result;
+ }
+
+ private static Dictionary? ParseArguments(string? argumentsJson)
+ {
+ if (string.IsNullOrEmpty(argumentsJson))
+ {
+ return null;
+ }
+
+ try
+ {
+ using var doc = JsonDocument.Parse(argumentsJson);
+ var result = new Dictionary();
+ foreach (var property in doc.RootElement.EnumerateObject())
+ {
+ result[property.Name] = property.Value.ValueKind switch
+ {
+ JsonValueKind.String => property.Value.GetString(),
+ JsonValueKind.Number => property.Value.GetDouble(),
+ JsonValueKind.True => true,
+ JsonValueKind.False => false,
+ JsonValueKind.Null => null,
+ _ => property.Value.GetRawText()
+ };
+ }
+
+ return result;
+ }
+ catch (JsonException)
+ {
+ return null;
+ }
+ }
+}
diff --git a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/HostedAgentResponseExecutor.cs b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/HostedAgentResponseExecutor.cs
index 78cf89b970..ad98e9e755 100644
--- a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/HostedAgentResponseExecutor.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/HostedAgentResponseExecutor.cs
@@ -82,6 +82,7 @@ internal sealed class HostedAgentResponseExecutor : IResponseExecutor
public async IAsyncEnumerable ExecuteAsync(
AgentInvocationContext context,
CreateResponse request,
+ IReadOnlyList? conversationHistory = null,
[EnumeratorCancellation] CancellationToken cancellationToken = default)
{
string agentName = GetAgentName(request)!;
@@ -105,6 +106,11 @@ internal sealed class HostedAgentResponseExecutor : IResponseExecutor
var options = new ChatClientAgentRunOptions(chatOptions);
var messages = new List();
+ if (conversationHistory is not null)
+ {
+ messages.AddRange(conversationHistory);
+ }
+
foreach (var inputMessage in request.Input.GetInputMessages())
{
messages.Add(inputMessage.ToChatMessage());
diff --git a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/IResponseExecutor.cs b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/IResponseExecutor.cs
index b96879f4cc..84f47af3ed 100644
--- a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/IResponseExecutor.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/IResponseExecutor.cs
@@ -4,6 +4,7 @@ using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Agents.AI.Hosting.OpenAI.Responses.Models;
+using Microsoft.Extensions.AI;
namespace Microsoft.Agents.AI.Hosting.OpenAI.Responses;
@@ -28,10 +29,12 @@ internal interface IResponseExecutor
///
/// The agent invocation context containing the ID generator and other context information.
/// The create response request.
+ /// Optional prior conversation messages to prepend to the agent's input.
/// Cancellation token.
/// An async enumerable of streaming response events.
IAsyncEnumerable ExecuteAsync(
AgentInvocationContext context,
CreateResponse request,
+ IReadOnlyList? conversationHistory = null,
CancellationToken cancellationToken = default);
}
diff --git a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/InMemoryResponsesService.cs b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/InMemoryResponsesService.cs
index 2f5b3f4660..6224120ac9 100644
--- a/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/InMemoryResponsesService.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Hosting.OpenAI/Responses/InMemoryResponsesService.cs
@@ -425,11 +425,28 @@ internal sealed class InMemoryResponsesService : IResponsesService, IDisposable
// Create agent invocation context
var context = new AgentInvocationContext(new IdGenerator(responseId: responseId, conversationId: state.Response?.Conversation?.Id));
+ // Load conversation history if a conversation ID is provided
+ IReadOnlyList? conversationHistory = null;
+ if (this._conversationStorage is not null && request.Conversation?.Id is not null)
+ {
+ var itemsResult = await this._conversationStorage.ListItemsAsync(
+ request.Conversation.Id,
+ limit: 100,
+ order: SortOrder.Ascending,
+ cancellationToken: linkedCts.Token).ConfigureAwait(false);
+
+ var history = ItemResourceConversions.ToChatMessages(itemsResult.Data);
+ if (history.Count > 0)
+ {
+ conversationHistory = history;
+ }
+ }
+
// Collect output items for conversation storage
List outputItems = [];
// Execute using the injected executor
- await foreach (var streamingEvent in this._executor.ExecuteAsync(context, request, linkedCts.Token).ConfigureAwait(false))
+ await foreach (var streamingEvent in this._executor.ExecuteAsync(context, request, conversationHistory, linkedCts.Token).ConfigureAwait(false))
{
state.AddStreamingEvent(streamingEvent);
diff --git a/dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/OpenAIResponsesIntegrationTests.cs b/dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/OpenAIResponsesIntegrationTests.cs
index 2dd5b85e5f..0b9441d633 100644
--- a/dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/OpenAIResponsesIntegrationTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/OpenAIResponsesIntegrationTests.cs
@@ -1201,6 +1201,75 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
Assert.Null(mockChatClient.LastChatOptions.ConversationId);
}
+ ///
+ /// Verifies that conversation history is passed to the agent on subsequent requests.
+ /// This test reproduces the bug described in GitHub issue #3484.
+ ///
+ [Fact]
+ public async Task CreateResponse_WithConversation_SecondRequestIncludesPriorMessagesAsync()
+ {
+ // Arrange
+ const string AgentName = "memory-agent";
+ const string Instructions = "You are a helpful assistant.";
+ const string AgentResponse = "Nice to meet you Alice";
+
+ var mockChatClient = new TestHelpers.ConversationMemoryMockChatClient(AgentResponse);
+ this._httpClient = await this.CreateTestServerWithCustomClientAndConversationsAsync(
+ AgentName, Instructions, mockChatClient);
+
+ // Create a conversation
+ string createConvJson = System.Text.Json.JsonSerializer.Serialize(
+ new { metadata = new { agent_id = AgentName } });
+ using StringContent createConvContent = new(createConvJson, Encoding.UTF8, "application/json");
+ HttpResponseMessage createConvResponse = await this._httpClient.PostAsync(
+ new Uri("/v1/conversations", UriKind.Relative), createConvContent);
+ Assert.True(createConvResponse.IsSuccessStatusCode);
+
+ string convJson = await createConvResponse.Content.ReadAsStringAsync();
+ using var convDoc = System.Text.Json.JsonDocument.Parse(convJson);
+ string conversationId = convDoc.RootElement.GetProperty("id").GetString()!;
+
+ // Act - First message
+ await this.SendRawResponseAsync(AgentName, "My name is Alice", conversationId, stream: false);
+
+ // Act - Second message in same conversation
+ await this.SendRawResponseAsync(AgentName, "What is my name?", conversationId, stream: false);
+
+ // Assert
+ Assert.Equal(2, mockChatClient.CallHistory.Count);
+
+ // First call: should have 1 message (just the user input)
+ Assert.Single(mockChatClient.CallHistory[0]);
+ Assert.Equal(ChatRole.User, mockChatClient.CallHistory[0][0].Role);
+
+ // Second call: should have 3 messages (prior user + prior assistant + new user)
+ Assert.Equal(3, mockChatClient.CallHistory[1].Count);
+ Assert.Equal(ChatRole.User, mockChatClient.CallHistory[1][0].Role);
+ Assert.Equal(ChatRole.Assistant, mockChatClient.CallHistory[1][1].Role);
+ Assert.Equal(ChatRole.User, mockChatClient.CallHistory[1][2].Role);
+ }
+
+ private async Task SendRawResponseAsync(
+ string agentName, string input, string conversationId, bool stream)
+ {
+ var requestBody = new
+ {
+ input,
+ agent = new { name = agentName },
+ conversation = conversationId,
+ stream
+ };
+ string json = System.Text.Json.JsonSerializer.Serialize(requestBody);
+ using StringContent content = new(json, Encoding.UTF8, "application/json");
+ HttpResponseMessage response = await this._httpClient!.PostAsync(
+ new Uri($"/{agentName}/v1/responses", UriKind.Relative), content);
+ Assert.True(response.IsSuccessStatusCode, $"Response failed: {response.StatusCode}");
+
+ // Consume the full response body to ensure execution completes
+ await response.Content.ReadAsStringAsync();
+ return response;
+ }
+
private ResponsesClient CreateResponseClient(string agentName)
{
return new ResponsesClient(
@@ -1272,6 +1341,29 @@ public sealed class OpenAIResponsesIntegrationTests : IAsyncDisposable
return testServer.CreateClient();
}
+ private async Task CreateTestServerWithCustomClientAndConversationsAsync(string agentName, string instructions, IChatClient chatClient)
+ {
+ WebApplicationBuilder builder = WebApplication.CreateBuilder();
+ builder.WebHost.UseTestServer();
+
+ builder.Services.AddKeyedSingleton($"chat-client-{agentName}", chatClient);
+ builder.AddAIAgent(agentName, instructions, chatClientServiceKey: $"chat-client-{agentName}");
+ builder.AddOpenAIResponses();
+ builder.AddOpenAIConversations();
+
+ this._app = builder.Build();
+ AIAgent agent = this._app.Services.GetRequiredKeyedService(agentName);
+ this._app.MapOpenAIResponses(agent);
+ this._app.MapOpenAIConversations();
+
+ await this._app.StartAsync();
+
+ TestServer testServer = this._app.Services.GetRequiredService() as TestServer
+ ?? throw new InvalidOperationException("TestServer not found");
+
+ return testServer.CreateClient();
+ }
+
private async Task CreateTestServerWithCustomClientAsync(string agentName, string instructions, IChatClient chatClient)
{
WebApplicationBuilder builder = WebApplication.CreateBuilder();
diff --git a/dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/TestHelpers.cs b/dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/TestHelpers.cs
index 191da528a4..198e65629e 100644
--- a/dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/TestHelpers.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/TestHelpers.cs
@@ -597,6 +597,86 @@ internal static class TestHelpers
}
}
+ ///
+ /// Mock IChatClient that captures the full message list on each call.
+ /// Used to verify conversation history is passed correctly.
+ ///
+ internal sealed class ConversationMemoryMockChatClient : IChatClient
+ {
+ private readonly string _responseText;
+
+ /// Each entry is the messages list received for that call.
+ public List> CallHistory { get; } = [];
+
+ public ConversationMemoryMockChatClient(string responseText = "Test response")
+ {
+ this._responseText = responseText;
+ }
+
+ public ChatClientMetadata Metadata { get; } = new("Test", new Uri("https://test.example.com"), "test-model");
+
+ public Task GetResponseAsync(
+ IEnumerable messages,
+ ChatOptions? options = null,
+ CancellationToken cancellationToken = default)
+ {
+ this.CallHistory.Add(messages.ToList());
+
+ ChatMessage message = new(ChatRole.Assistant, this._responseText);
+ ChatResponse response = new([message])
+ {
+ ModelId = "test-model",
+ FinishReason = ChatFinishReason.Stop,
+ Usage = new UsageDetails
+ {
+ InputTokenCount = 10,
+ OutputTokenCount = 5,
+ TotalTokenCount = 15
+ }
+ };
+ return Task.FromResult(response);
+ }
+
+ public async IAsyncEnumerable GetStreamingResponseAsync(
+ IEnumerable messages,
+ ChatOptions? options = null,
+ [EnumeratorCancellation] CancellationToken cancellationToken = default)
+ {
+ this.CallHistory.Add(messages.ToList());
+ await Task.Delay(1, cancellationToken);
+
+ string[] words = this._responseText.Split(' ');
+ for (int i = 0; i < words.Length; i++)
+ {
+ string content = i < words.Length - 1 ? words[i] + " " : words[i];
+ ChatResponseUpdate update = new()
+ {
+ Contents = [new TextContent(content)],
+ Role = ChatRole.Assistant
+ };
+
+ if (i == words.Length - 1)
+ {
+ update.Contents.Add(new UsageContent(new UsageDetails
+ {
+ InputTokenCount = 10,
+ OutputTokenCount = 5,
+ TotalTokenCount = 15
+ }));
+ }
+
+ yield return update;
+ }
+ }
+
+ public object? GetService(Type serviceType, object? serviceKey = null) =>
+ serviceType.IsInstanceOfType(this) ? this : null;
+
+ public void Dispose()
+ {
+ }
+ }
+
///
/// Custom content mock implementation of IChatClient that returns custom content based on a provider function.
///
diff --git a/python/packages/devui/agent_framework_devui/_executor.py b/python/packages/devui/agent_framework_devui/_executor.py
index e019917630..1b1b77162a 100644
--- a/python/packages/devui/agent_framework_devui/_executor.py
+++ b/python/packages/devui/agent_framework_devui/_executor.py
@@ -21,6 +21,13 @@ from .models._discovery_models import EntityInfo
logger = logging.getLogger(__name__)
+def _get_event_type(event: Any) -> str | None:
+ """Safely get the type of an event, handling both objects and dicts."""
+ if isinstance(event, dict):
+ return event.get("type")
+ return getattr(event, "type", None)
+
+
class EntityNotFoundError(Exception):
"""Raised when an entity is not found."""
@@ -264,7 +271,7 @@ class AgentFrameworkExecutor:
elif entity_info.type == "workflow":
async for event in self._execute_workflow(entity_obj, request, trace_collector):
# Log request_info event (type='request_info') for debugging HIL flow
- if event.type == "request_info":
+ if _get_event_type(event) == "request_info":
logger.info(
"🔔 [EXECUTOR] request_info event (type='request_info') detected from workflow!"
)
@@ -330,19 +337,22 @@ class AgentFrameworkExecutor:
# Agent must have run() method - use stream=True for streaming
if hasattr(agent, "run") and callable(agent.run):
- # Use Agent Framework's run() with stream=True for streaming
+ # Capture the stream reference so we can call get_final_response()
+ # after iteration. This triggers result hooks (after_run providers
+ # like InMemoryHistoryProvider) that persist conversation history.
+ run_kwargs: dict[str, Any] = {"stream": True}
if session:
- async for update in agent.run(user_message, stream=True, session=session):
- for trace_event in trace_collector.get_pending_events():
- yield trace_event
+ run_kwargs["session"] = session
- yield update
- else:
- async for update in agent.run(user_message, stream=True):
- for trace_event in trace_collector.get_pending_events():
- yield trace_event
+ stream = agent.run(user_message, **run_kwargs)
+ async for update in stream:
+ for trace_event in trace_collector.get_pending_events():
+ yield trace_event
- yield update
+ yield update
+
+ # Finalize stream to trigger result hooks (saves conversation history)
+ await stream.get_final_response()
else:
raise ValueError("Agent must implement run() method")
@@ -471,7 +481,7 @@ class AgentFrameworkExecutor:
checkpoint_storage=checkpoint_storage,
):
# Enrich new request_info events that may come from subsequent HIL requests
- if event.type == "request_info":
+ if _get_event_type(event) == "request_info":
self._enrich_request_info_event_with_response_schema(event, workflow)
for trace_event in trace_collector.get_pending_events():
@@ -493,7 +503,7 @@ class AgentFrameworkExecutor:
checkpoint_id=checkpoint_id,
checkpoint_storage=checkpoint_storage,
):
- if event.type == "request_info":
+ if _get_event_type(event) == "request_info":
self._enrich_request_info_event_with_response_schema(event, workflow)
for trace_event in trace_collector.get_pending_events():
@@ -517,7 +527,7 @@ class AgentFrameworkExecutor:
parsed_input = await self._parse_workflow_input(workflow, request.input)
async for event in workflow.run(parsed_input, stream=True, checkpoint_storage=checkpoint_storage):
- if event.type == "request_info":
+ if _get_event_type(event) == "request_info":
self._enrich_request_info_event_with_response_schema(event, workflow)
for trace_event in trace_collector.get_pending_events():
diff --git a/python/packages/devui/tests/devui/test_execution.py b/python/packages/devui/tests/devui/test_execution.py
index a7ac622c75..4d0436a314 100644
--- a/python/packages/devui/tests/devui/test_execution.py
+++ b/python/packages/devui/tests/devui/test_execution.py
@@ -741,6 +741,51 @@ async def test_full_pipeline_workflow_output_event_serialization():
assert len(output_events) >= 3, f"Expected 3+ output events for yield_output calls, got {len(output_events)}"
+async def test_workflow_error_yields_dict_event_without_crash():
+ """Test that workflow errors don't crash execute_entity (#3983).
+
+ When a workflow raises an exception, _execute_workflow yields a raw dict
+ {"type": "error", ...}. The execute_entity caller must handle both dict
+ events and object events without crashing on attribute access.
+ """
+ from unittest.mock import AsyncMock, MagicMock
+
+ from agent_framework_devui.models._discovery_models import EntityInfo
+
+ discovery = MagicMock(spec=EntityDiscovery)
+ mapper = MessageMapper()
+ executor = AgentFrameworkExecutor(discovery, mapper)
+
+ entity_info = EntityInfo(id="bad_wf", name="bad_wf", type="workflow", framework="agent_framework")
+ discovery.get_entity_info.return_value = entity_info
+
+ # Mock workflow whose run() raises
+ mock_workflow = MagicMock()
+ mock_workflow.name = "bad_wf"
+
+ def failing_run(*args, **kwargs):
+ raise RuntimeError("Sorry, something went wrong.")
+
+ mock_workflow.run = failing_run
+ discovery.load_entity = AsyncMock(return_value=mock_workflow)
+
+ request = AgentFrameworkRequest(
+ model="test",
+ input="hello",
+ metadata={"entity_id": "bad_wf"},
+ )
+
+ events = []
+ # This should NOT raise AttributeError: 'dict' object has no attribute 'type'
+ async for event in executor.execute_entity("bad_wf", request):
+ events.append(event)
+
+ # Should get at least one error event
+ assert len(events) > 0
+ error_events = [e for e in events if isinstance(e, dict) and e.get("type") == "error"]
+ assert len(error_events) > 0, f"Expected error dict events, got: {events}"
+
+
if __name__ == "__main__":
# Simple test runner
async def run_tests():
From de791fb8a9be05d494aa086e1b35510036943f8e Mon Sep 17 00:00:00 2001
From: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
Date: Mon, 2 Mar 2026 10:56:28 +0000
Subject: [PATCH 16/24] .Net: Add additional Hosted Agent Samples (#4325)
* Add 3 new hosted agent samples: AgentWithTools, AgentWithLocalTools, AgentThreadAndHITL
- AgentWithTools: Foundry tools (MCP + code interpreter) via UseFoundryTools
- AgentWithLocalTools: Local C# function tool (Seattle hotel search) with AIProjectClient
- AgentThreadAndHITL: Human-in-the-loop with ApprovalRequiredAIFunction and thread persistence
All samples follow agent-framework conventions (net10.0, AzureCliCredential, CPM disabled).
AgentWithTools includes comprehensive README with setup guide and troubleshooting.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add root HostedAgents README, replace test_requests.py with .http, update sample READMEs
- Create root README.md with shared prerequisites, Azure AI Foundry setup,
troubleshooting, and samples index
- Replace test_requests.py with run-requests.http in AgentThreadAndHITL
- Add pointer to root README in all 6 sample READMEs
- Trim AgentWithTools README to concise style
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix dotnet format issues in AgentWithLocalTools/Program.cs
- Add UTF-8 BOM (CHARSET)
- Sort System.ClientModel.Primitives import alphabetically (IMPORTS)
- Use target-typed new for AIProjectClient (IDE0090)
- Add internal accessibility modifier to Hotel record (IDE0040)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address PR review: align model names and package versions
- Change default model from gpt-4.1-mini to gpt-4o-mini in AgentWithLocalTools
(Program.cs, agent.yaml, README.md) to match existing samples
- Change README example from gpt-5.2 to gpt-4o-mini in AgentWithTools and root README
- Align AgentWithLocalTools package versions with other samples:
Azure.AI.AgentServer.AgentFramework beta.6 -> beta.8
Azure.AI.OpenAI 2.8.0-beta.1 -> 2.7.0-beta.2
Microsoft.Extensions.AI.OpenAI 10.2.0-preview -> 10.1.1-preview
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Upgrade new samples to latest package versions
- Azure.AI.OpenAI: 2.7.0-beta.2 -> 2.8.0-beta.1
- Microsoft.Extensions.AI.OpenAI: 10.1.1-preview -> 10.3.0
Aligns with AgentWithHostedMCP which uses the latest versions.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Pin AgentThreadAndHITL to Microsoft.Extensions.AI.OpenAI 10.1.1
Azure.AI.AgentServer.AgentFramework beta.8 was compiled against
Microsoft.Extensions.AI.Abstractions with the single-param
FunctionApprovalRequestContent.CreateResponse(bool). Version 10.3.0
changed the signature to include an optional reason parameter, causing
a binary incompatibility at runtime. Pin to 10.1.1 until the framework
is recompiled against the newer abstractions.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../AgentThreadAndHITL.csproj | 70 ++++++++++
.../AgentThreadAndHITL/Dockerfile | 20 +++
.../AgentThreadAndHITL/Program.cs | 38 ++++++
.../HostedAgents/AgentThreadAndHITL/README.md | 46 +++++++
.../AgentThreadAndHITL/agent.yaml | 28 ++++
.../AgentThreadAndHITL/run-requests.http | 70 ++++++++++
.../HostedAgents/AgentWithHostedMCP/README.md | 2 +
.../AgentWithLocalTools/.dockerignore | 24 ++++
.../AgentWithLocalTools.csproj | 70 ++++++++++
.../AgentWithLocalTools/Dockerfile | 20 +++
.../AgentWithLocalTools/Program.cs | 129 ++++++++++++++++++
.../AgentWithLocalTools/README.md | 39 ++++++
.../AgentWithLocalTools/agent.yaml | 29 ++++
.../AgentWithLocalTools/run-requests.http | 52 +++++++
.../AgentWithTextSearchRag/README.md | 2 +
.../AgentWithTools/AgentWithTools.csproj | 69 ++++++++++
.../HostedAgents/AgentWithTools/Dockerfile | 20 +++
.../HostedAgents/AgentWithTools/Program.cs | 43 ++++++
.../HostedAgents/AgentWithTools/README.md | 45 ++++++
.../HostedAgents/AgentWithTools/agent.yaml | 31 +++++
.../AgentWithTools/run-requests.http | 30 ++++
.../HostedAgents/AgentsInWorkflows/README.md | 2 +
.../05-end-to-end/HostedAgents/README.md | 125 +++++++++++++++++
23 files changed, 1004 insertions(+)
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/AgentThreadAndHITL.csproj
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/Dockerfile
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/Program.cs
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/README.md
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/agent.yaml
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/run-requests.http
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/.dockerignore
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/AgentWithLocalTools.csproj
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/Dockerfile
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/Program.cs
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/README.md
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/agent.yaml
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/run-requests.http
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/AgentWithTools.csproj
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/Dockerfile
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/Program.cs
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/README.md
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/agent.yaml
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/run-requests.http
create mode 100644 dotnet/samples/05-end-to-end/HostedAgents/README.md
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/AgentThreadAndHITL.csproj b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/AgentThreadAndHITL.csproj
new file mode 100644
index 0000000000..17b90fd6e2
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/AgentThreadAndHITL.csproj
@@ -0,0 +1,70 @@
+
+
+
+ Exe
+ net10.0
+
+ enable
+ enable
+ $(NoWarn);MEAI001
+
+
+ false
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+
+
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/Dockerfile b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/Dockerfile
new file mode 100644
index 0000000000..004bd49fa8
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/Dockerfile
@@ -0,0 +1,20 @@
+# Build the application
+FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
+WORKDIR /src
+
+# Copy files from the current directory on the host to the working directory in the container
+COPY . .
+
+RUN dotnet restore
+RUN dotnet build -c Release --no-restore
+RUN dotnet publish -c Release --no-build -o /app -f net10.0
+
+# Run the application
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+
+# Copy everything needed to run the app from the "build" stage.
+COPY --from=build /app .
+
+EXPOSE 8088
+ENTRYPOINT ["dotnet", "AgentThreadAndHITL.dll"]
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/Program.cs b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/Program.cs
new file mode 100644
index 0000000000..305b9835ed
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/Program.cs
@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates Human-in-the-Loop (HITL) capabilities with thread persistence.
+// The agent wraps function tools with ApprovalRequiredAIFunction to require user approval
+// before invoking them. Users respond with 'approve' or 'reject' when prompted.
+
+using System.ComponentModel;
+using Azure.AI.AgentServer.AgentFramework.Extensions;
+using Azure.AI.AgentServer.AgentFramework.Persistence;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+[Description("Get the weather for a given location.")]
+static string GetWeather([Description("The location to get the weather for.")] string location)
+ => $"The weather in {location} is cloudy with a high of 15°C.";
+
+// Create the chat client and agent.
+// Note: ApprovalRequiredAIFunction wraps the tool to require user approval before invocation.
+// User should reply with 'approve' or 'reject' when prompted.
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+AIAgent agent = new AzureOpenAIClient(
+ new Uri(endpoint),
+ new AzureCliCredential())
+ .GetChatClient(deploymentName)
+ .AsIChatClient()
+ .CreateAIAgent(
+ instructions: "You are a helpful assistant",
+ tools: [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(GetWeather))]
+ );
+#pragma warning restore MEAI001
+
+var threadRepository = new InMemoryAgentThreadRepository(agent);
+await agent.RunAIAgentAsync(telemetrySourceName: "Agents", threadRepository: threadRepository);
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/README.md b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/README.md
new file mode 100644
index 0000000000..f2d9a65103
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/README.md
@@ -0,0 +1,46 @@
+# What this sample demonstrates
+
+This sample demonstrates Human-in-the-Loop (HITL) capabilities with thread persistence. The agent wraps function tools with `ApprovalRequiredAIFunction` so that every tool invocation requires explicit user approval before execution. Thread state is maintained across requests using `InMemoryAgentThreadRepository`.
+
+Key features:
+- Requiring human approval before executing function calls
+- Persisting conversation threads across multiple requests
+- Approving or rejecting tool invocations at runtime
+
+> For common prerequisites and setup instructions, see the [Hosted Agent Samples README](../README.md).
+
+## Prerequisites
+
+Before running this sample, ensure you have:
+
+1. .NET 10 SDK installed
+2. An Azure OpenAI endpoint configured
+3. A deployment of a chat model (e.g., gpt-4o-mini)
+4. Azure CLI installed and authenticated (`az login`)
+
+## Environment Variables
+
+Set the following environment variables:
+
+```powershell
+# Replace with your Azure OpenAI endpoint
+$env:AZURE_OPENAI_ENDPOINT="https://your-openai-resource.openai.azure.com/"
+
+# Optional, defaults to gpt-4o-mini
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+```
+
+## How It Works
+
+The sample uses `ApprovalRequiredAIFunction` to wrap standard AI function tools. When the model decides to call a tool, the wrapper intercepts the invocation and returns a HITL approval request to the caller instead of executing the function immediately.
+
+1. The user sends a message (e.g., "What is the weather in Vancouver?")
+2. The model determines a function call is needed and selects the `GetWeather` tool
+3. `ApprovalRequiredAIFunction` intercepts the call and returns an approval request containing the function name and arguments
+4. The user responds with `approve` or `reject`
+5. If approved, the function executes and the model generates a response using the result
+6. If rejected, the model generates a response without the function result
+
+Thread persistence is handled by `InMemoryAgentThreadRepository`, which stores conversation history keyed by `conversation.id`. This means the HITL flow works across multiple HTTP requests as long as each request includes the same `conversation.id`.
+
+> **Note:** HITL requires a stable `conversation.id` in every request so the agent can correlate the approval response with the original function call. Use the `run-requests.http` file in this directory to test the full approval flow.
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/agent.yaml b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/agent.yaml
new file mode 100644
index 0000000000..aa78734283
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/agent.yaml
@@ -0,0 +1,28 @@
+name: AgentThreadAndHITL
+displayName: "Weather Assistant Agent"
+description: >
+ A Weather Assistant Agent that provides weather information and forecasts. It
+ demonstrates how to use Azure AI AgentServer with Human-in-the-Loop (HITL)
+ capabilities to get human approval for functional calls.
+metadata:
+ authors:
+ - Microsoft Agent Framework Team
+ tags:
+ - Azure AI AgentServer
+ - Microsoft Agent Framework
+ - Human-in-the-Loop
+template:
+ kind: hosted
+ name: AgentThreadAndHITL
+ protocols:
+ - protocol: responses
+ version: v1
+ environment_variables:
+ - name: AZURE_OPENAI_ENDPOINT
+ value: ${AZURE_OPENAI_ENDPOINT}
+ - name: AZURE_OPENAI_DEPLOYMENT_NAME
+ value: gpt-4o-mini
+resources:
+ - name: "gpt-4o-mini"
+ kind: model
+ id: gpt-4o-mini
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/run-requests.http b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/run-requests.http
new file mode 100644
index 0000000000..196a30a542
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/run-requests.http
@@ -0,0 +1,70 @@
+@host = http://localhost:8088
+@endpoint = {{host}}/responses
+
+### Health Check
+GET {{host}}/readiness
+
+###
+# HITL (Human-in-the-Loop) Flow
+#
+# This sample requires a multi-turn conversation to demonstrate the approval flow:
+# 1. Send a request that triggers a tool call (e.g., asking about the weather)
+# 2. The agent responds with a function_call named "__hosted_agent_adapter_hitl__"
+# containing the call_id and the tool details
+# 3. Send a follow-up request with a function_call_output to approve or reject
+#
+# IMPORTANT: You must use the same conversation.id across all requests in a flow,
+# and update the call_id from step 2 into step 3.
+###
+
+### Step 1: Send initial request (triggers HITL approval)
+# @name initialRequest
+POST {{endpoint}}
+Content-Type: application/json
+
+{
+ "input": "What is the weather like in Vancouver?",
+ "stream": false,
+ "conversation": {
+ "id": "conv_test0000000000000000000000000000000000000000000000"
+ }
+}
+
+### Step 2: Approve the function call
+# Copy the call_id from the Step 1 response output and replace below.
+# The response will contain: "name": "__hosted_agent_adapter_hitl__" with a "call_id" value.
+POST {{endpoint}}
+Content-Type: application/json
+
+{
+ "input": [
+ {
+ "type": "function_call_output",
+ "call_id": "REPLACE_WITH_CALL_ID_FROM_STEP_1",
+ "output": "approve"
+ }
+ ],
+ "stream": false,
+ "conversation": {
+ "id": "conv_test0000000000000000000000000000000000000000000000"
+ }
+}
+
+### Step 3 (alternative): Reject the function call
+# Use this instead of Step 2 to deny the tool execution.
+POST {{endpoint}}
+Content-Type: application/json
+
+{
+ "input": [
+ {
+ "type": "function_call_output",
+ "call_id": "REPLACE_WITH_CALL_ID_FROM_STEP_1",
+ "output": "reject"
+ }
+ ],
+ "stream": false,
+ "conversation": {
+ "id": "conv_test0000000000000000000000000000000000000000000000"
+ }
+}
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/README.md b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/README.md
index a5648d7ac9..8d8ddba330 100644
--- a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/README.md
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/README.md
@@ -8,6 +8,8 @@ Key features:
- Filtering available tools from an MCP server
- Using Azure OpenAI Responses with MCP tools
+> For common prerequisites and setup instructions, see the [Hosted Agent Samples README](../README.md).
+
## Prerequisites
Before running this sample, ensure you have:
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/.dockerignore b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/.dockerignore
new file mode 100644
index 0000000000..2afa2c2601
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/.dockerignore
@@ -0,0 +1,24 @@
+**/.dockerignore
+**/.env
+**/.git
+**/.gitignore
+**/.project
+**/.settings
+**/.toolstarget
+**/.vs
+**/.vscode
+**/*.*proj.user
+**/*.dbmdl
+**/*.jfm
+**/azds.yaml
+**/bin
+**/charts
+**/docker-compose*
+**/Dockerfile*
+**/node_modules
+**/npm-debug.log
+**/obj
+**/secrets.dev.yaml
+**/values.dev.yaml
+LICENSE
+README.md
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/AgentWithLocalTools.csproj b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/AgentWithLocalTools.csproj
new file mode 100644
index 0000000000..43cdbfb025
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/AgentWithLocalTools.csproj
@@ -0,0 +1,70 @@
+
+
+
+ Exe
+ net10.0
+
+ enable
+ enable
+ true
+
+
+ false
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+
+
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/Dockerfile b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/Dockerfile
new file mode 100644
index 0000000000..c2461965a4
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/Dockerfile
@@ -0,0 +1,20 @@
+# Build the application
+FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
+WORKDIR /src
+
+# Copy files from the current directory on the host to the working directory in the container
+COPY . .
+
+RUN dotnet restore
+RUN dotnet build -c Release --no-restore
+RUN dotnet publish -c Release --no-build -o /app -f net10.0
+
+# Run the application
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+
+# Copy everything needed to run the app from the "build" stage.
+COPY --from=build /app .
+
+EXPOSE 8088
+ENTRYPOINT ["dotnet", "AgentWithLocalTools.dll"]
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/Program.cs b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/Program.cs
new file mode 100644
index 0000000000..72eb938047
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/Program.cs
@@ -0,0 +1,129 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Seattle Hotel Agent - A simple agent with a tool to find hotels in Seattle.
+// Uses Microsoft Agent Framework with Azure AI Foundry.
+// Ready for deployment to Foundry Hosted Agent service.
+
+using System.ClientModel.Primitives;
+using System.ComponentModel;
+using System.Globalization;
+using System.Text;
+using Azure.AI.AgentServer.AgentFramework.Extensions;
+using Azure.AI.OpenAI;
+using Azure.AI.Projects;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
+ ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+Console.WriteLine($"Project Endpoint: {endpoint}");
+Console.WriteLine($"Model Deployment: {deploymentName}");
+
+var seattleHotels = new[]
+{
+ new Hotel("Contoso Suites", 189, 4.5, "Downtown"),
+ new Hotel("Fabrikam Residences", 159, 4.2, "Pike Place Market"),
+ new Hotel("Alpine Ski House", 249, 4.7, "Seattle Center"),
+ new Hotel("Margie's Travel Lodge", 219, 4.4, "Waterfront"),
+ new Hotel("Northwind Inn", 139, 4.0, "Capitol Hill"),
+ new Hotel("Relecloud Hotel", 99, 3.8, "University District"),
+};
+
+[Description("Get available hotels in Seattle for the specified dates. This simulates a call to a hotel availability API.")]
+string GetAvailableHotels(
+ [Description("Check-in date in YYYY-MM-DD format")] string checkInDate,
+ [Description("Check-out date in YYYY-MM-DD format")] string checkOutDate,
+ [Description("Maximum price per night in USD (optional, defaults to 500)")] int maxPrice = 500)
+{
+ try
+ {
+ if (!DateTime.TryParseExact(checkInDate, "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var checkIn))
+ {
+ return "Error parsing check-in date. Please use YYYY-MM-DD format.";
+ }
+
+ if (!DateTime.TryParseExact(checkOutDate, "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var checkOut))
+ {
+ return "Error parsing check-out date. Please use YYYY-MM-DD format.";
+ }
+
+ if (checkOut <= checkIn)
+ {
+ return "Error: Check-out date must be after check-in date.";
+ }
+
+ var nights = (checkOut - checkIn).Days;
+ var availableHotels = seattleHotels.Where(h => h.PricePerNight <= maxPrice).ToList();
+
+ if (availableHotels.Count == 0)
+ {
+ return $"No hotels found in Seattle within your budget of ${maxPrice}/night.";
+ }
+
+ var result = new StringBuilder();
+ result.AppendLine($"Available hotels in Seattle from {checkInDate} to {checkOutDate} ({nights} nights):");
+ result.AppendLine();
+
+ foreach (var hotel in availableHotels)
+ {
+ var totalCost = hotel.PricePerNight * nights;
+ result.AppendLine($"**{hotel.Name}**");
+ result.AppendLine($" Location: {hotel.Location}");
+ result.AppendLine($" Rating: {hotel.Rating}/5");
+ result.AppendLine($" ${hotel.PricePerNight}/night (Total: ${totalCost})");
+ result.AppendLine();
+ }
+
+ return result.ToString();
+ }
+ catch (Exception ex)
+ {
+ return $"Error processing request. Details: {ex.Message}";
+ }
+}
+
+var credential = new AzureCliCredential();
+AIProjectClient projectClient = new(new Uri(endpoint), credential);
+
+ClientConnection connection = projectClient.GetConnection(typeof(AzureOpenAIClient).FullName!);
+
+if (!connection.TryGetLocatorAsUri(out Uri? openAiEndpoint) || openAiEndpoint is null)
+{
+ throw new InvalidOperationException("Failed to get OpenAI endpoint from project connection.");
+}
+openAiEndpoint = new Uri($"https://{openAiEndpoint.Host}");
+Console.WriteLine($"OpenAI Endpoint: {openAiEndpoint}");
+
+var chatClient = new AzureOpenAIClient(openAiEndpoint, credential)
+ .GetChatClient(deploymentName)
+ .AsIChatClient()
+ .AsBuilder()
+ .UseOpenTelemetry(sourceName: "Agents", configure: cfg => cfg.EnableSensitiveData = false)
+ .Build();
+
+var agent = new ChatClientAgent(chatClient,
+ name: "SeattleHotelAgent",
+ instructions: """
+ You are a helpful travel assistant specializing in finding hotels in Seattle, Washington.
+
+ When a user asks about hotels in Seattle:
+ 1. Ask for their check-in and check-out dates if not provided
+ 2. Ask about their budget preferences if not mentioned
+ 3. Use the GetAvailableHotels tool to find available options
+ 4. Present the results in a friendly, informative way
+ 5. Offer to help with additional questions about the hotels or Seattle
+
+ Be conversational and helpful. If users ask about things outside of Seattle hotels,
+ politely let them know you specialize in Seattle hotel recommendations.
+ """,
+ tools: [AIFunctionFactory.Create(GetAvailableHotels)])
+ .AsBuilder()
+ .UseOpenTelemetry(sourceName: "Agents", configure: cfg => cfg.EnableSensitiveData = false)
+ .Build();
+
+Console.WriteLine("Seattle Hotel Agent Server running on http://localhost:8088");
+await agent.RunAIAgentAsync(telemetrySourceName: "Agents");
+
+internal sealed record Hotel(string Name, int PricePerNight, double Rating, string Location);
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/README.md b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/README.md
new file mode 100644
index 0000000000..c080331a87
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/README.md
@@ -0,0 +1,39 @@
+# What this sample demonstrates
+
+This sample demonstrates how to build a hosted agent that uses local C# function tools — a key advantage of code-based hosted agents over prompt agents. The agent acts as a Seattle travel assistant with a `GetAvailableHotels` tool that simulates querying a hotel availability API.
+
+Key features:
+- Defining local C# functions as agent tools using `AIFunctionFactory`
+- Using `AIProjectClient` to discover the OpenAI connection from the Azure AI Foundry project
+- Building a `ChatClientAgent` with custom instructions and tools
+- Deploying to the Foundry Hosted Agent service
+
+> For common prerequisites and setup instructions, see the [Hosted Agent Samples README](../README.md).
+
+## Prerequisites
+
+Before running this sample, ensure you have:
+
+1. .NET 10 SDK installed
+2. An Azure AI Foundry Project with a chat model deployed (e.g., gpt-4o-mini)
+3. Azure CLI installed and authenticated (`az login`)
+
+## Environment Variables
+
+Set the following environment variables:
+
+```powershell
+# Replace with your Azure AI Foundry project endpoint
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project-name"
+
+# Optional, defaults to gpt-4o-mini
+$env:MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
+```
+
+## How It Works
+
+1. The agent uses `AIProjectClient` to discover the Azure OpenAI connection from the project endpoint
+2. A local C# function `GetAvailableHotels` is registered as a tool using `AIFunctionFactory.Create`
+3. When users ask about hotels, the model invokes the local tool to search simulated hotel data
+4. The tool filters hotels by price and calculates total costs based on the requested dates
+5. Results are returned to the model, which presents them in a conversational format
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/agent.yaml b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/agent.yaml
new file mode 100644
index 0000000000..e60d9ccadf
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/agent.yaml
@@ -0,0 +1,29 @@
+name: seattle-hotel-agent
+description: >
+ A travel assistant agent that helps users find hotels in Seattle.
+ Demonstrates local C# tool execution - a key advantage of code-based
+ hosted agents over prompt agents.
+metadata:
+ authors:
+ - Microsoft
+ tags:
+ - Azure AI AgentServer
+ - Microsoft Agent Framework
+ - Local Tools
+ - Travel Assistant
+ - Hotel Search
+template:
+ name: seattle-hotel-agent
+ kind: hosted
+ protocols:
+ - protocol: responses
+ version: v1
+ environment_variables:
+ - name: AZURE_AI_PROJECT_ENDPOINT
+ value: ${AZURE_AI_PROJECT_ENDPOINT}
+ - name: MODEL_DEPLOYMENT_NAME
+ value: gpt-4o-mini
+resources:
+ - kind: model
+ id: gpt-4o-mini
+ name: chat
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/run-requests.http b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/run-requests.http
new file mode 100644
index 0000000000..4f2e87e097
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithLocalTools/run-requests.http
@@ -0,0 +1,52 @@
+@host = http://localhost:8088
+@endpoint = {{host}}/responses
+
+### Health Check
+GET {{host}}/readiness
+
+### Simple hotel search - budget under $200
+POST {{endpoint}}
+Content-Type: application/json
+
+{
+ "input": "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under $200 per night",
+ "stream": false
+}
+
+### Hotel search with higher budget
+POST {{endpoint}}
+Content-Type: application/json
+
+{
+ "input": "Find me hotels in Seattle for March 20-23, 2025 under $250 per night",
+ "stream": false
+}
+
+### Ask for recommendations without dates (agent should ask for clarification)
+POST {{endpoint}}
+Content-Type: application/json
+
+{
+ "input": "What hotels do you recommend in Seattle?",
+ "stream": false
+}
+
+### Explicit input format
+POST {{endpoint}}
+Content-Type: application/json
+
+{
+ "input": [
+ {
+ "type": "message",
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "I'm looking for a hotel in Seattle from 2025-04-01 to 2025-04-05, my budget is $150 per night maximum"
+ }
+ ]
+ }
+ ],
+ "stream": false
+}
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/README.md b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/README.md
index 614597bed9..396bc1bc9b 100644
--- a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/README.md
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/README.md
@@ -8,6 +8,8 @@ Key features:
- Managing conversation memory with a rolling window approach
- Citing source documents in AI responses
+> For common prerequisites and setup instructions, see the [Hosted Agent Samples README](../README.md).
+
## Prerequisites
Before running this sample, ensure you have:
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/AgentWithTools.csproj b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/AgentWithTools.csproj
new file mode 100644
index 0000000000..ce8a739757
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/AgentWithTools.csproj
@@ -0,0 +1,69 @@
+
+
+
+ Exe
+ net10.0
+
+ enable
+ enable
+
+
+ false
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+ all
+ runtime; build; native; contentfiles; analyzers; buildtransitive
+
+
+
+
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/Dockerfile b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/Dockerfile
new file mode 100644
index 0000000000..c9f39f9574
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/Dockerfile
@@ -0,0 +1,20 @@
+# Build the application
+FROM mcr.microsoft.com/dotnet/sdk:10.0-alpine AS build
+WORKDIR /src
+
+# Copy files from the current directory on the host to the working directory in the container
+COPY . .
+
+RUN dotnet restore
+RUN dotnet build -c Release --no-restore
+RUN dotnet publish -c Release --no-build -o /app -f net10.0
+
+# Run the application
+FROM mcr.microsoft.com/dotnet/aspnet:10.0-alpine AS final
+WORKDIR /app
+
+# Copy everything needed to run the app from the "build" stage.
+COPY --from=build /app .
+
+EXPOSE 8088
+ENTRYPOINT ["dotnet", "AgentWithTools.dll"]
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/Program.cs b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/Program.cs
new file mode 100644
index 0000000000..3bb68d6e31
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/Program.cs
@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use Foundry tools (MCP and code interpreter)
+// with an AI agent hosted using the Azure AI AgentServer SDK.
+
+using Azure.AI.AgentServer.AgentFramework.Extensions;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+var openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+var toolConnectionId = Environment.GetEnvironmentVariable("MCP_TOOL_CONNECTION_ID") ?? throw new InvalidOperationException("MCP_TOOL_CONNECTION_ID is not set.");
+
+var credential = new AzureCliCredential();
+
+var chatClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential)
+ .GetChatClient(deploymentName)
+ .AsIChatClient()
+ .AsBuilder()
+ .UseFoundryTools(new { type = "mcp", project_connection_id = toolConnectionId }, new { type = "code_interpreter" })
+ .UseOpenTelemetry(sourceName: "Agents", configure: (cfg) => cfg.EnableSensitiveData = true)
+ .Build();
+
+var agent = new ChatClientAgent(chatClient,
+ name: "AgentWithTools",
+ instructions: @"You are a helpful assistant with access to tools for fetching Microsoft documentation.
+
+ IMPORTANT: When the user asks about Microsoft Learn articles or documentation:
+ 1. You MUST use the microsoft_docs_fetch tool to retrieve the actual content
+ 2. Do NOT rely on your training data
+ 3. Always fetch the latest information from the provided URL
+
+ Available tools:
+ - microsoft_docs_fetch: Fetches and converts Microsoft Learn documentation
+ - microsoft_docs_search: Searches Microsoft/Azure documentation
+ - microsoft_code_sample_search: Searches for code examples")
+ .AsBuilder()
+ .UseOpenTelemetry(sourceName: "Agents", configure: (cfg) => cfg.EnableSensitiveData = true)
+ .Build();
+
+await agent.RunAIAgentAsync(telemetrySourceName: "Agents");
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/README.md b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/README.md
new file mode 100644
index 0000000000..5a80ecda9f
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/README.md
@@ -0,0 +1,45 @@
+# What this sample demonstrates
+
+This sample demonstrates how to use Foundry tools with an AI agent via the `UseFoundryTools` extension. The agent is configured with two tool types: an MCP (Model Context Protocol) connection for fetching Microsoft Learn documentation and a code interpreter for running code when needed.
+
+Key features:
+
+- Configuring Foundry tools using `UseFoundryTools` with MCP and code interpreter
+- Connecting to an external MCP tool via a Foundry project connection
+- Using `AzureCliCredential` for Azure authentication
+- OpenTelemetry instrumentation for both the chat client and agent
+
+> For common prerequisites and setup instructions, see the [Hosted Agent Samples README](../README.md).
+
+## Prerequisites
+
+In addition to the common prerequisites:
+
+1. An **Azure AI Foundry project** with a chat model deployed (e.g., `gpt-5.2`, `gpt-4o-mini`)
+2. The **Azure AI Developer** role assigned on the Foundry resource (includes the `agents/write` data action required by `UseFoundryTools`)
+3. An **MCP tool connection** configured in your Foundry project pointing to `https://learn.microsoft.com/api/mcp`
+
+## Environment Variables
+
+In addition to the common environment variables in the root README:
+
+```powershell
+# Your Azure AI Foundry project endpoint (required by UseFoundryTools)
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-resource.services.ai.azure.com/api/projects/your-project"
+
+# Chat model deployment name (defaults to gpt-4o-mini if not set)
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+
+# The MCP tool connection name (just the name, not the full ARM resource ID)
+$env:MCP_TOOL_CONNECTION_ID="SampleMCPTool"
+```
+
+## How It Works
+
+1. An `AzureOpenAIClient` is created with `AzureCliCredential` and used to get a chat client
+2. The chat client is wrapped with `UseFoundryTools` which registers two Foundry tool types:
+ - **MCP connection**: Connects to an external MCP server (Microsoft Learn) via the project connection name, providing documentation fetch and search capabilities
+ - **Code interpreter**: Allows the agent to execute code snippets when needed
+3. `UseFoundryTools` resolves the connection using `AZURE_AI_PROJECT_ENDPOINT` internally
+4. A `ChatClientAgent` is created with instructions guiding it to use the MCP tools for documentation queries
+5. The agent is hosted using `RunAIAgentAsync` which exposes the OpenAI Responses-compatible API endpoint
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/agent.yaml b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/agent.yaml
new file mode 100644
index 0000000000..5d2b1f8d8d
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/agent.yaml
@@ -0,0 +1,31 @@
+name: AgentWithTools
+displayName: "Agent with Tools"
+description: >
+ An AI agent that uses Foundry tools (MCP and code interpreter) with Azure OpenAI.
+ The agent can fetch Microsoft Learn documentation and run code when needed.
+metadata:
+ authors:
+ - Microsoft Agent Framework Team
+ tags:
+ - Azure AI AgentServer
+ - Microsoft Agent Framework
+ - Tools
+ - MCP
+ - Code Interpreter
+template:
+ kind: hosted
+ name: AgentWithTools
+ protocols:
+ - protocol: responses
+ version: v1
+ environment_variables:
+ - name: AZURE_OPENAI_ENDPOINT
+ value: ${AZURE_OPENAI_ENDPOINT}
+ - name: AZURE_OPENAI_DEPLOYMENT_NAME
+ value: gpt-4o-mini
+ - name: MCP_TOOL_CONNECTION_ID
+ value: ${MCP_TOOL_CONNECTION_ID}
+resources:
+ - name: "gpt-4o-mini"
+ kind: model
+ id: gpt-4o-mini
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/run-requests.http b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/run-requests.http
new file mode 100644
index 0000000000..22a37ff54e
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentWithTools/run-requests.http
@@ -0,0 +1,30 @@
+@host = http://localhost:8088
+@endpoint = {{host}}/responses
+
+### Health Check
+GET {{host}}/readiness
+
+### Simple string input
+POST {{endpoint}}
+Content-Type: application/json
+{
+ "input": "Please use the microsoft_docs_fetch tool to fetch and summarize the Microsoft Learn article at https://learn.microsoft.com/azure/ai-services/openai/overview"
+}
+
+### Explicit input
+POST {{endpoint}}
+Content-Type: application/json
+{
+ "input": [
+ {
+ "type": "message",
+ "role": "user",
+ "content": [
+ {
+ "type": "input_text",
+ "text": "Please use the microsoft_docs_fetch tool to fetch and summarize the Microsoft Learn article at https://learn.microsoft.com/azure/ai-services/openai/overview"
+ }
+ ]
+ }
+ ]
+}
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/AgentsInWorkflows/README.md b/dotnet/samples/05-end-to-end/HostedAgents/AgentsInWorkflows/README.md
index 5f6babc755..72019bbf22 100644
--- a/dotnet/samples/05-end-to-end/HostedAgents/AgentsInWorkflows/README.md
+++ b/dotnet/samples/05-end-to-end/HostedAgents/AgentsInWorkflows/README.md
@@ -9,6 +9,8 @@ This workflow uses three translation agents:
The agents are connected sequentially, creating a translation chain that demonstrates how AI-powered components can be seamlessly integrated into workflow pipelines.
+> For common prerequisites and setup instructions, see the [Hosted Agent Samples README](../README.md).
+
## Prerequisites
Before you begin, ensure you have the following prerequisites:
diff --git a/dotnet/samples/05-end-to-end/HostedAgents/README.md b/dotnet/samples/05-end-to-end/HostedAgents/README.md
new file mode 100644
index 0000000000..f7a3bdc94b
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/HostedAgents/README.md
@@ -0,0 +1,125 @@
+# Hosted Agent Samples
+
+These samples demonstrate how to build and host AI agents using the [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme). Each sample can be run locally and deployed to Microsoft Foundry as a hosted agent.
+
+## Samples
+
+| Sample | Description |
+|--------|-------------|
+| [`AgentWithTools`](./AgentWithTools/) | Foundry tools (MCP + code interpreter) via `UseFoundryTools` |
+| [`AgentWithLocalTools`](./AgentWithLocalTools/) | Local C# function tool execution (Seattle hotel search) |
+| [`AgentThreadAndHITL`](./AgentThreadAndHITL/) | Human-in-the-loop with `ApprovalRequiredAIFunction` and thread persistence |
+| [`AgentWithHostedMCP`](./AgentWithHostedMCP/) | Hosted MCP server tool (Microsoft Learn search) |
+| [`AgentWithTextSearchRag`](./AgentWithTextSearchRag/) | RAG with `TextSearchProvider` (Contoso Outdoors) |
+| [`AgentsInWorkflows`](./AgentsInWorkflows/) | Sequential workflow pipeline (translation chain) |
+
+## Common Prerequisites
+
+Before running any sample, ensure you have:
+
+1. **.NET 10 SDK** or later — [Download](https://dotnet.microsoft.com/download/dotnet/10.0)
+2. **Azure CLI** installed — [Install guide](https://learn.microsoft.com/cli/azure/install-azure-cli)
+3. **Azure OpenAI** or **Azure AI Foundry project** with a chat model deployed (e.g., `gpt-4o-mini`)
+
+### Authenticate with Azure CLI
+
+All samples use `AzureCliCredential` for authentication. Make sure you're logged in:
+
+```powershell
+az login
+az account show # Verify the correct subscription
+```
+
+### Common Environment Variables
+
+Most samples require one or more of these environment variables:
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `AZURE_OPENAI_ENDPOINT` | Most samples | Your Azure OpenAI resource endpoint URL |
+| `AZURE_OPENAI_DEPLOYMENT_NAME` | Most samples | Chat model deployment name (defaults to `gpt-4o-mini`) |
+| `AZURE_AI_PROJECT_ENDPOINT` | AgentWithTools, AgentWithLocalTools | Azure AI Foundry project endpoint |
+| `MCP_TOOL_CONNECTION_ID` | AgentWithTools | Foundry MCP tool connection name |
+| `MODEL_DEPLOYMENT_NAME` | AgentWithLocalTools | Chat model deployment name (defaults to `gpt-4o-mini`) |
+
+See each sample's README for the specific variables required.
+
+## Azure AI Foundry Setup (for samples that use Foundry)
+
+Some samples (`AgentWithTools`, `AgentWithLocalTools`) connect to an Azure AI Foundry project. If you're using these samples, you'll need additional setup.
+
+### Azure AI Developer Role
+
+The `UseFoundryTools` extension requires the **Azure AI Developer** role on the Cognitive Services resource. Even if you created the project, you may not have this role by default.
+
+```powershell
+az role assignment create `
+ --role "Azure AI Developer" `
+ --assignee "your-email@microsoft.com" `
+ --scope "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.CognitiveServices/accounts/{account-name}"
+```
+
+> **Note**: You need **Owner** or **User Access Administrator** permissions on the resource to assign roles. If you don't have this, you may need to request JIT (Just-In-Time) elevated access via [Azure PIM](https://portal.azure.com/#view/Microsoft_Azure_PIMCommon/ActivationMenuBlade/~/aadmigratedresource).
+
+For more details on permissions, see [Azure AI Foundry Permissions](https://aka.ms/FoundryPermissions).
+
+### Creating an MCP Tool Connection
+
+The `AgentWithTools` sample requires an MCP tool connection configured in your Foundry project:
+
+1. Go to the [Azure AI Foundry portal](https://ai.azure.com)
+2. Navigate to your project
+3. Go to **Connected resources** → **+ New connection** → **Model Context Protocol tool**
+4. Fill in:
+ - **Name**: `SampleMCPTool` (or any name you prefer)
+ - **Remote MCP Server endpoint**: `https://learn.microsoft.com/api/mcp`
+ - **Authentication**: `Unauthenticated`
+5. Click **Connect**
+
+The connection **name** (e.g., `SampleMCPTool`) is used as the `MCP_TOOL_CONNECTION_ID` environment variable.
+
+> **Important**: Use only the connection **name**, not the full ARM resource ID.
+
+## Running a Sample
+
+Each sample runs as a standalone hosted agent on `http://localhost:8088/`:
+
+```powershell
+cd
+dotnet run
+```
+
+### Interacting with the Agent
+
+Each sample includes a `run-requests.http` file for testing with the [VS Code REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) extension, or you can use PowerShell:
+
+```powershell
+$body = @{ input = "Your question here" } | ConvertTo-Json
+Invoke-RestMethod -Uri "http://localhost:8088/responses" -Method Post -Body $body -ContentType "application/json"
+```
+
+## Deploying to Microsoft Foundry
+
+Each sample includes a `Dockerfile` and `agent.yaml` for deployment. To deploy your agent to Microsoft Foundry, follow the [hosted agents deployment guide](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents).
+
+## Troubleshooting
+
+### `PermissionDenied` — lacks `agents/write` data action
+
+Assign the **Azure AI Developer** role to your user. See [Azure AI Developer Role](#azure-ai-developer-role) above.
+
+### `Project connection ... was not found`
+
+Make sure `MCP_TOOL_CONNECTION_ID` contains only the connection **name** (e.g., `SampleMCPTool`), not the full ARM resource ID path.
+
+### `AZURE_AI_PROJECT_ENDPOINT must be set`
+
+The `UseFoundryTools` extension requires `AZURE_AI_PROJECT_ENDPOINT`. Set it to your Foundry project endpoint (e.g., `https://your-resource.services.ai.azure.com/api/projects/your-project`).
+
+### Multi-framework error when running `dotnet run`
+
+If you see "Your project targets multiple frameworks", specify the framework:
+
+```powershell
+dotnet run --framework net10.0
+```
From 26cef555ce1481ff25c3c7b62b30dd27b9eed167 Mon Sep 17 00:00:00 2001
From: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>
Date: Mon, 2 Mar 2026 12:50:44 +0000
Subject: [PATCH 17/24] Revert ".NET: Support hosted code interpreter for skill
script execution (#4192)" (#4385)
This reverts commit c9cd067be6b2981791a9d93b1c832390a39b507a.
---
dotnet/agent-framework-dotnet.slnx | 1 -
.../Agent_Step01_BasicSkills/Program.cs | 3 -
..._ScriptExecutionWithCodeInterpreter.csproj | 28 ---
.../Program.cs | 49 -----
.../README.md | 72 --------
.../skills/password-generator/SKILL.md | 16 --
.../references/PASSWORD_GUIDELINES.md | 24 ---
.../password-generator/scripts/generate.py | 11 --
.../samples/02-agents/AgentSkills/README.md | 1 -
.../Skills/FileAgentSkill.cs | 23 ++-
.../Skills/FileAgentSkillLoader.cs | 22 +--
.../FileAgentSkillScriptExecutionContext.cs | 35 ----
.../FileAgentSkillScriptExecutionDetails.cs | 25 ---
.../Skills/FileAgentSkillScriptExecutor.cs | 42 -----
.../Skills/FileAgentSkillsProvider.cs | 49 ++---
.../Skills/FileAgentSkillsProviderOptions.cs | 14 +-
...InterpreterFileAgentSkillScriptExecutor.cs | 35 ----
...killFrontmatter.cs => SkillFrontmatter.cs} | 9 +-
.../AgentSkills/FileAgentSkillLoaderTests.cs | 50 +-----
.../FileAgentSkillScriptExecutorTests.cs | 170 ------------------
.../FileAgentSkillsProviderTests.cs | 17 +-
...preterFileAgentSkillScriptExecutorTests.cs | 72 --------
22 files changed, 66 insertions(+), 702 deletions(-)
delete mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj
delete mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Program.cs
delete mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/README.md
delete mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/SKILL.md
delete mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/references/PASSWORD_GUIDELINES.md
delete mode 100644 dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/scripts/generate.py
delete mode 100644 dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionContext.cs
delete mode 100644 dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionDetails.cs
delete mode 100644 dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutor.cs
delete mode 100644 dotnet/src/Microsoft.Agents.AI/Skills/HostedCodeInterpreterFileAgentSkillScriptExecutor.cs
rename dotnet/src/Microsoft.Agents.AI/Skills/{FileAgentSkillFrontmatter.cs => SkillFrontmatter.cs} (70%)
delete mode 100644 dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillScriptExecutorTests.cs
delete mode 100644 dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/HostedCodeInterpreterFileAgentSkillScriptExecutorTests.cs
diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx
index 1ab73c2b8b..b96b891b00 100644
--- a/dotnet/agent-framework-dotnet.slnx
+++ b/dotnet/agent-framework-dotnet.slnx
@@ -82,7 +82,6 @@
-
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs b/dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs
index eef57e840a..290c3f9b6b 100644
--- a/dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs
+++ b/dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs
@@ -22,9 +22,6 @@ string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYM
var skillsProvider = new FileAgentSkillsProvider(skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));
// --- Agent Setup ---
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
.GetResponsesClient(deploymentName)
.AsAIAgent(new ChatClientAgentOptions
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj
deleted file mode 100644
index 2a503bbfb2..0000000000
--- a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj
+++ /dev/null
@@ -1,28 +0,0 @@
-
-
-
- Exe
- net10.0
-
- enable
- enable
- $(NoWarn);MAAI001
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- PreserveNewest
-
-
-
-
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Program.cs b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Program.cs
deleted file mode 100644
index 2835ec70ab..0000000000
--- a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/Program.cs
+++ /dev/null
@@ -1,49 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use Agent Skills with script execution via the hosted code interpreter.
-// When FileAgentSkillScriptExecutor.HostedCodeInterpreter() is configured, the agent can load and execute scripts
-// from skill resources using the LLM provider's built-in code interpreter.
-//
-// This sample includes the password-generator skill:
-// - A Python script for generating secure passwords
-
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using OpenAI.Responses;
-
-// --- Configuration ---
-string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
- ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// --- Skills Provider with Script Execution ---
-// Discovers skills and enables script execution via the hosted code interpreter
-var skillsProvider = new FileAgentSkillsProvider(
- skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
- options: new FileAgentSkillsProviderOptions
- {
- ScriptExecutor = FileAgentSkillScriptExecutor.HostedCodeInterpreter()
- });
-
-// --- Agent Setup ---
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
- .GetResponsesClient(deploymentName)
- .AsAIAgent(new ChatClientAgentOptions
- {
- Name = "SkillsAgent",
- ChatOptions = new()
- {
- Instructions = "You are a helpful assistant that can generate secure passwords.",
- },
- AIContextProviders = [skillsProvider],
- });
-
-// --- Example: Password generation with script execution ---
-Console.WriteLine("Example: Generating a password with a skill script");
-Console.WriteLine("---------------------------------------------------");
-AgentResponse response = await agent.RunAsync("Generate a secure password for my database account.");
-Console.WriteLine($"Agent: {response.Text}\n");
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/README.md b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/README.md
deleted file mode 100644
index f5bf63c44a..0000000000
--- a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/README.md
+++ /dev/null
@@ -1,72 +0,0 @@
-# Script Execution with Code Interpreter
-
-This sample demonstrates how to use **Agent Skills** with **script execution** via the hosted code interpreter.
-
-## What's Different from Step01?
-
-In the [basic skills sample](../Agent_Step01_BasicSkills/), skills only provide instructions and resources as text. This sample adds **script execution** — the agent can load Python scripts from skill resources and execute them using the LLM provider's built-in code interpreter.
-
-This is enabled by configuring `FileAgentSkillScriptExecutor.HostedCodeInterpreter()` on the skills provider options:
-
-```csharp
-var skillsProvider = new FileAgentSkillsProvider(
- skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
- options: new FileAgentSkillsProviderOptions
- {
- ScriptExecutor = FileAgentSkillScriptExecutor.HostedCodeInterpreter()
- });
-```
-
-## Skills Included
-
-### password-generator
-Generates secure passwords using a Python script with configurable length and complexity.
-- `scripts/generate.py` — Password generation script
-- `references/PASSWORD_GUIDELINES.md` — Recommended length and symbol sets by use case
-
-## Project Structure
-
-```
-Agent_Step02_ScriptExecutionWithCodeInterpreter/
-├── Program.cs
-├── Agent_Step02_ScriptExecutionWithCodeInterpreter.csproj
-└── skills/
- └── password-generator/
- ├── SKILL.md
- ├── scripts/
- │ └── generate.py
- └── references/
- └── PASSWORD_GUIDELINES.md
-```
-
-## Running the Sample
-
-### Prerequisites
-- .NET 10.0 SDK
-- Azure OpenAI endpoint with a deployed model that supports code interpreter
-
-### Setup
-1. Set environment variables:
- ```bash
- export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
- export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
- ```
-
-2. Run the sample:
- ```bash
- dotnet run
- ```
-
-### Example
-
-The sample asks the agent to generate a secure password. The agent:
-1. Loads the password-generator skill
-2. Reads the `generate.py` script via `read_skill_resource`
-3. Executes the script using the code interpreter with appropriate parameters
-4. Returns the generated password
-
-## Learn More
-
-- [Agent Skills Specification](https://agentskills.io/)
-- [Step01: Basic Skills](../Agent_Step01_BasicSkills/) — Skills without script execution
-- [Microsoft Agent Framework Documentation](../../../../../docs/)
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/SKILL.md b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/SKILL.md
deleted file mode 100644
index c3ef67401b..0000000000
--- a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/SKILL.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-name: password-generator
-description: Generate secure passwords using a Python script. Use when asked to create passwords or credentials.
----
-
-# Password Generator
-
-This skill generates secure passwords using a Python script.
-
-## Usage
-
-When the user requests a password:
-1. First, review `references/PASSWORD_GUIDELINES.md` to determine the recommended password length and character sets for the user's use case
-2. Load `scripts/generate.py` and adjust its parameters (length, character set) based on the guidelines and user's requirements
-3. Execute the script
-4. Present the generated password clearly
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/references/PASSWORD_GUIDELINES.md b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/references/PASSWORD_GUIDELINES.md
deleted file mode 100644
index be9145a4dd..0000000000
--- a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/references/PASSWORD_GUIDELINES.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# Password Generation Guidelines
-
-## General Rules
-
-- Never reuse passwords across services.
-- Always use cryptographically secure randomness (e.g., `random.SystemRandom()`).
-- Avoid dictionary words, keyboard patterns, and personal information.
-
-## Recommended Settings by Use Case
-
-| Use Case | Min Length | Character Set | Example |
-|-----------------------|-----------|----------------------------------------|--------------------------|
-| Web account | 16 | Upper + lower + digits + symbols | `G7!kQp@2xM#nW9$z` |
-| Database credential | 24 | Upper + lower + digits + symbols | `aR3$vK8!mN2@pQ7&xL5#wY` |
-| Wi-Fi / network key | 20 | Upper + lower + digits + symbols | `Ht4&jL9!rP2#mK7@xQ` |
-| API key / token | 32 | Upper + lower + digits (no symbols) | `k8Rm3xQ7nW2pL9vT4jH6yA` |
-| Encryption passphrase | 32 | Upper + lower + digits + symbols | `Xp4!kR8@mN2#vQ7&jL9$wT` |
-
-## Symbol Sets
-
-- **Standard symbols**: `!@#$%^&*()-_=+`
-- **Extended symbols**: `~`{}[]|;:'",.<>?/\`
-- **Safe symbols** (URL/shell-safe): `!@#$&*-_=+`
-- If the target system restricts symbols, use only the **safe** set.
diff --git a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/scripts/generate.py b/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/scripts/generate.py
deleted file mode 100644
index b44f3d9731..0000000000
--- a/dotnet/samples/02-agents/AgentSkills/Agent_Step02_ScriptExecutionWithCodeInterpreter/skills/password-generator/scripts/generate.py
+++ /dev/null
@@ -1,11 +0,0 @@
-# Password generator script
-# Usage: Adjust 'length' as needed, then run
-
-import random
-import string
-
-length = 16 # desired length
-
-pool = string.ascii_lowercase + string.ascii_uppercase + string.digits + string.punctuation
-password = "".join(random.SystemRandom().choice(pool) for _ in range(length))
-print(f"Generated password ({length} chars): {password}")
diff --git a/dotnet/samples/02-agents/AgentSkills/README.md b/dotnet/samples/02-agents/AgentSkills/README.md
index 477a738fb8..8488ec9eed 100644
--- a/dotnet/samples/02-agents/AgentSkills/README.md
+++ b/dotnet/samples/02-agents/AgentSkills/README.md
@@ -5,4 +5,3 @@ Samples demonstrating Agent Skills capabilities.
| Sample | Description |
|--------|-------------|
| [Agent_Step01_BasicSkills](Agent_Step01_BasicSkills/) | Using Agent Skills with a ChatClientAgent, including progressive disclosure and skill resources |
-| [Agent_Step02_ScriptExecutionWithCodeInterpreter](Agent_Step02_ScriptExecutionWithCodeInterpreter/) | Using Agent Skills with script execution via the hosted code interpreter |
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkill.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkill.cs
index da0d0b83dd..f28bad3ab0 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkill.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkill.cs
@@ -1,8 +1,6 @@
// Copyright (c) Microsoft. All rights reserved.
using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
using Microsoft.Shared.Diagnostics;
namespace Microsoft.Agents.AI;
@@ -15,8 +13,7 @@ namespace Microsoft.Agents.AI;
/// and a markdown body with instructions. Resource files referenced in the body are validated at
/// discovery time and read from disk on demand.
///
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class FileAgentSkill
+internal sealed class FileAgentSkill
{
///
/// Initializes a new instance of the class.
@@ -25,8 +22,8 @@ public sealed class FileAgentSkill
/// The SKILL.md content after the closing --- delimiter.
/// Absolute path to the directory containing this skill.
/// Relative paths of resource files referenced in the skill body.
- internal FileAgentSkill(
- FileAgentSkillFrontmatter frontmatter,
+ public FileAgentSkill(
+ SkillFrontmatter frontmatter,
string body,
string sourcePath,
IReadOnlyList? resourceNames = null)
@@ -40,20 +37,20 @@ public sealed class FileAgentSkill
///
/// Gets the parsed YAML frontmatter (name and description).
///
- public FileAgentSkillFrontmatter Frontmatter { get; }
+ public SkillFrontmatter Frontmatter { get; }
+
+ ///
+ /// Gets the SKILL.md body content (without the YAML frontmatter).
+ ///
+ public string Body { get; }
///
/// Gets the directory path where the skill was discovered.
///
public string SourcePath { get; }
- ///
- /// Gets the SKILL.md body content (without the YAML frontmatter).
- ///
- internal string Body { get; }
-
///
/// Gets the relative paths of resource files referenced in the skill body (e.g., "references/FAQ.md").
///
- internal IReadOnlyList ResourceNames { get; }
+ public IReadOnlyList ResourceNames { get; }
}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillLoader.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillLoader.cs
index 8f55fc93c3..8c034b3122 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillLoader.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillLoader.cs
@@ -2,7 +2,6 @@
using System;
using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
using System.IO;
using System.Linq;
using System.Text;
@@ -10,7 +9,6 @@ using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;
-using Microsoft.Shared.DiagnosticIds;
namespace Microsoft.Agents.AI;
@@ -22,8 +20,7 @@ namespace Microsoft.Agents.AI;
/// Each file is validated for YAML frontmatter and resource integrity. Invalid skills are excluded
/// with logged warnings. Resource paths are checked against path traversal and symlink escape attacks.
///
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed partial class FileAgentSkillLoader
+internal sealed partial class FileAgentSkillLoader
{
private const string SkillFileName = "SKILL.md";
private const int MaxSearchDepth = 2;
@@ -36,16 +33,13 @@ public sealed partial class FileAgentSkillLoader
// Example: "---\nname: foo\n---\nBody" → Group 1: "name: foo\n"
private static readonly Regex s_frontmatterRegex = new(@"\A\uFEFF?^---\s*$(.+?)^---\s*$", RegexOptions.Multiline | RegexOptions.Singleline | RegexOptions.Compiled, TimeSpan.FromSeconds(5));
- // Matches resource file references in skill markdown. Group 1 = relative file path.
- // Supports two forms:
- // 1. Markdown links: [text](path/file.ext)
- // 2. Backtick-quoted paths: `path/file.ext`
+ // Matches markdown links to local resource files. Group 1 = relative file path.
// Supports optional ./ or ../ prefixes; excludes URLs (no ":" in the path character class).
// Intentionally conservative: only matches paths with word characters, hyphens, dots,
// and forward slashes. Paths with spaces or special characters are not supported.
- // Examples: [doc](refs/FAQ.md) → "refs/FAQ.md", `./scripts/run.py` → "./scripts/run.py",
+ // Examples: [doc](refs/FAQ.md) → "refs/FAQ.md", [s](./s.json) → "./s.json",
// [p](../shared/doc.txt) → "../shared/doc.txt"
- private static readonly Regex s_resourceLinkRegex = new(@"(?:\[.*?\]\(|`)(\.?\.?/?[\w][\w\-./]*\.\w+)(?:\)|`)", RegexOptions.Compiled, TimeSpan.FromSeconds(5));
+ private static readonly Regex s_resourceLinkRegex = new(@"\[.*?\]\((\.?\.?/?[\w][\w\-./]*\.\w+)\)", RegexOptions.Compiled, TimeSpan.FromSeconds(5));
// Matches YAML "key: value" lines. Group 1 = key, Group 2 = quoted value, Group 3 = unquoted value.
// Accepts single or double quotes; the lazy quantifier trims trailing whitespace on unquoted values.
@@ -117,7 +111,7 @@ public sealed partial class FileAgentSkillLoader
///
/// The resource is not registered, resolves outside the skill directory, or does not exist.
///
- public async Task ReadSkillResourceAsync(FileAgentSkill skill, string resourceName, CancellationToken cancellationToken = default)
+ internal async Task ReadSkillResourceAsync(FileAgentSkill skill, string resourceName, CancellationToken cancellationToken = default)
{
resourceName = NormalizeResourcePath(resourceName);
@@ -195,7 +189,7 @@ public sealed partial class FileAgentSkillLoader
string content = File.ReadAllText(skillFilePath, Encoding.UTF8);
- if (!this.TryParseSkillDocument(content, skillFilePath, out FileAgentSkillFrontmatter frontmatter, out string body))
+ if (!this.TryParseSkillDocument(content, skillFilePath, out SkillFrontmatter frontmatter, out string body))
{
return null;
}
@@ -214,7 +208,7 @@ public sealed partial class FileAgentSkillLoader
resourceNames: resourceNames);
}
- private bool TryParseSkillDocument(string content, string skillFilePath, out FileAgentSkillFrontmatter frontmatter, out string body)
+ private bool TryParseSkillDocument(string content, string skillFilePath, out SkillFrontmatter frontmatter, out string body)
{
frontmatter = null!;
body = null!;
@@ -270,7 +264,7 @@ public sealed partial class FileAgentSkillLoader
return false;
}
- frontmatter = new FileAgentSkillFrontmatter(name, description);
+ frontmatter = new SkillFrontmatter(name, description);
body = content.Substring(match.Index + match.Length).TrimStart();
return true;
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionContext.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionContext.cs
deleted file mode 100644
index c28333a715..0000000000
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionContext.cs
+++ /dev/null
@@ -1,35 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
-
-namespace Microsoft.Agents.AI;
-
-///
-/// Provides access to loaded skills and the skill loader for use by implementations.
-///
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class FileAgentSkillScriptExecutionContext
-{
- ///
- /// Initializes a new instance of the class.
- ///
- /// The loaded skills dictionary.
- /// The skill loader for reading resources.
- internal FileAgentSkillScriptExecutionContext(Dictionary skills, FileAgentSkillLoader loader)
- {
- this.Skills = skills;
- this.Loader = loader;
- }
-
- ///
- /// Gets the loaded skills keyed by name.
- ///
- public IReadOnlyDictionary Skills { get; }
-
- ///
- /// Gets the skill loader for reading resources.
- ///
- public FileAgentSkillLoader Loader { get; }
-}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionDetails.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionDetails.cs
deleted file mode 100644
index 4c12848386..0000000000
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutionDetails.cs
+++ /dev/null
@@ -1,25 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Extensions.AI;
-using Microsoft.Shared.DiagnosticIds;
-
-namespace Microsoft.Agents.AI;
-
-///
-/// Represents the tools and instructions contributed by a .
-///
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class FileAgentSkillScriptExecutionDetails
-{
- ///
- /// Gets the additional instructions to provide to the agent for script execution.
- ///
- public string? Instructions { get; set; }
-
- ///
- /// Gets the additional tools to provide to the agent for script execution.
- ///
- public IReadOnlyList? Tools { get; set; }
-}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutor.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutor.cs
deleted file mode 100644
index 1171940e72..0000000000
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillScriptExecutor.cs
+++ /dev/null
@@ -1,42 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
-
-namespace Microsoft.Agents.AI;
-
-///
-/// Defines the contract for skill script execution modes.
-///
-///
-///
-/// A provides the instructions and tools needed to enable
-/// script execution within an agent skill. Concrete implementations determine how scripts
-/// are executed (e.g., via the LLM's hosted code interpreter, an external executor, or a hybrid approach).
-///
-///
-/// Use the static factory methods to create instances:
-///
-/// — executes scripts using the LLM provider's built-in code interpreter.
-///
-///
-///
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public abstract class FileAgentSkillScriptExecutor
-{
- ///
- /// Creates a that uses the LLM provider's hosted code interpreter for script execution.
- ///
- /// A instance configured for hosted code interpreter execution.
- public static FileAgentSkillScriptExecutor HostedCodeInterpreter() => new HostedCodeInterpreterFileAgentSkillScriptExecutor();
-
- ///
- /// Returns the tools and instructions contributed by this executor.
- ///
- ///
- /// The execution context provided by the skills provider, containing the loaded skills
- /// and the skill loader for reading resources.
- ///
- /// A containing the executor's tools and instructions.
- protected internal abstract FileAgentSkillScriptExecutionDetails GetExecutionDetails(FileAgentSkillScriptExecutionContext context);
-}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
index 7acec160d4..847bf36a52 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
@@ -48,21 +48,21 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
Each skill provides specialized instructions, reference documents, and assets for specific tasks.
- {skills}
+ {0}
When a task aligns with a skill's domain:
- - Use `load_skill` to retrieve the skill's instructions
- - Follow the provided guidance
- - Use `read_skill_resource` to read any references or other files mentioned by the skill, always using the full path as written (e.g. `references/FAQ.md`, not just `FAQ.md`)
- {executor_instructions}
+ 1. Use `load_skill` to retrieve the skill's instructions
+ 2. Follow the provided guidance
+ 3. Use `read_skill_resource` to read any references or other files mentioned by the skill
+
Only load what is needed, when it is needed.
""";
private readonly Dictionary _skills;
private readonly ILogger _logger;
private readonly FileAgentSkillLoader _loader;
- private readonly IEnumerable _tools;
+ private readonly AITool[] _tools;
private readonly string? _skillsInstructionPrompt;
///
@@ -91,13 +91,9 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
this._loader = new FileAgentSkillLoader(this._logger);
this._skills = this._loader.DiscoverAndLoadSkills(skillPaths);
- var executionDetails = options?.ScriptExecutor is { } executor
- ? executor.GetExecutionDetails(new(this._skills, this._loader))
- : null;
+ this._skillsInstructionPrompt = BuildSkillsInstructionPrompt(options, this._skills);
- this._skillsInstructionPrompt = BuildSkillsInstructionPrompt(options, this._skills, executionDetails?.Instructions);
-
- AITool[] baseTools =
+ this._tools =
[
AIFunctionFactory.Create(
this.LoadSkill,
@@ -108,10 +104,6 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
name: "read_skill_resource",
description: "Reads a file associated with a skill, such as references or assets."),
];
-
- this._tools = executionDetails?.Tools is { Count: > 0 } executorTools
- ? baseTools.Concat(executorTools)
- : baseTools;
}
///
@@ -125,7 +117,7 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
return new ValueTask(new AIContext
{
Instructions = this._skillsInstructionPrompt,
- Tools = this._tools,
+ Tools = this._tools
});
}
@@ -174,9 +166,24 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
}
}
- private static string? BuildSkillsInstructionPrompt(FileAgentSkillsProviderOptions? options, Dictionary skills, string? instructions)
+ private static string? BuildSkillsInstructionPrompt(FileAgentSkillsProviderOptions? options, Dictionary skills)
{
- string promptTemplate = options?.SkillsInstructionPrompt ?? DefaultSkillsInstructionPrompt;
+ string promptTemplate = DefaultSkillsInstructionPrompt;
+
+ if (options?.SkillsInstructionPrompt is { } optionsInstructions)
+ {
+ try
+ {
+ promptTemplate = string.Format(optionsInstructions, string.Empty);
+ }
+ catch (FormatException ex)
+ {
+ throw new ArgumentException(
+ "The provided SkillsInstructionPrompt is not a valid format string. It must contain a '{0}' placeholder and escape any literal '{' or '}' by doubling them ('{{' or '}}').",
+ nameof(options),
+ ex);
+ }
+ }
if (skills.Count == 0)
{
@@ -195,9 +202,7 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
sb.AppendLine(" ");
}
- return promptTemplate
- .Replace("{skills}", sb.ToString().TrimEnd())
- .Replace("{executor_instructions}", instructions ?? "\n");
+ return string.Format(promptTemplate, sb.ToString().TrimEnd());
}
[LoggerMessage(LogLevel.Information, "Loading skill: {SkillName}")]
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProviderOptions.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProviderOptions.cs
index 7d86d3b4ae..a47841c260 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProviderOptions.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProviderOptions.cs
@@ -13,20 +13,8 @@ public sealed class FileAgentSkillsProviderOptions
{
///
/// Gets or sets a custom system prompt template for advertising skills.
- /// Use {skills} as the placeholder for the generated skills list and
- /// {executor_instructions} for executor-provided instructions.
+ /// Use {0} as the placeholder for the generated skills list.
/// When , a default template is used.
///
public string? SkillsInstructionPrompt { get; set; }
-
- ///
- /// Gets or sets the skill executor that enables script execution for loaded skills.
- ///
- ///
- /// When (the default), script execution is disabled and skills only provide
- /// instructions and resources. Set this to a instance (e.g.,
- /// ) to enable script execution with
- /// mode-specific instructions and tools.
- ///
- public FileAgentSkillScriptExecutor? ScriptExecutor { get; set; }
}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/HostedCodeInterpreterFileAgentSkillScriptExecutor.cs b/dotnet/src/Microsoft.Agents.AI/Skills/HostedCodeInterpreterFileAgentSkillScriptExecutor.cs
deleted file mode 100644
index 88fb1f86a2..0000000000
--- a/dotnet/src/Microsoft.Agents.AI/Skills/HostedCodeInterpreterFileAgentSkillScriptExecutor.cs
+++ /dev/null
@@ -1,35 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Extensions.AI;
-
-namespace Microsoft.Agents.AI;
-
-///
-/// A that uses the LLM provider's hosted code interpreter for script execution.
-///
-///
-/// This executor directs the LLM to load scripts via read_skill_resource and execute them
-/// using the provider's built-in code interpreter. A is
-/// registered to signal the provider to enable its code interpreter sandbox.
-///
-internal sealed class HostedCodeInterpreterFileAgentSkillScriptExecutor : FileAgentSkillScriptExecutor
-{
- private static readonly FileAgentSkillScriptExecutionDetails s_contribution = new()
- {
- Instructions =
- """
-
- Some skills include executable scripts (e.g., Python files) in their resources.
- When a skill's instructions reference a script:
- 1. Use `read_skill_resource` to load the script content
- 2. Execute the script using the code interpreter
-
- """,
- Tools = [new HostedCodeInterpreterTool()],
- };
-
- ///
-#pragma warning disable RCS1168 // Parameter name differs from base name
- protected internal override FileAgentSkillScriptExecutionDetails GetExecutionDetails(FileAgentSkillScriptExecutionContext _) => s_contribution;
-#pragma warning restore RCS1168 // Parameter name differs from base name
-}
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillFrontmatter.cs b/dotnet/src/Microsoft.Agents.AI/Skills/SkillFrontmatter.cs
similarity index 70%
rename from dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillFrontmatter.cs
rename to dotnet/src/Microsoft.Agents.AI/Skills/SkillFrontmatter.cs
index c369ad319f..123a6c43f4 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillFrontmatter.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/SkillFrontmatter.cs
@@ -1,7 +1,5 @@
// Copyright (c) Microsoft. All rights reserved.
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
using Microsoft.Shared.Diagnostics;
namespace Microsoft.Agents.AI;
@@ -9,15 +7,14 @@ namespace Microsoft.Agents.AI;
///
/// Parsed YAML frontmatter from a SKILL.md file, containing the skill's name and description.
///
-[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class FileAgentSkillFrontmatter
+internal sealed class SkillFrontmatter
{
///
- /// Initializes a new instance of the class.
+ /// Initializes a new instance of the class.
///
/// Skill name.
/// Skill description.
- internal FileAgentSkillFrontmatter(string name, string description)
+ public SkillFrontmatter(string name, string description)
{
this.Name = Throw.IfNullOrWhitespace(name);
this.Description = Throw.IfNullOrWhitespace(description);
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
index c9e154a277..c34eb6d7f2 100644
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs
@@ -501,7 +501,7 @@ public sealed class FileAgentSkillLoaderTests : IDisposable
}
// Manually construct a skill that bypasses discovery validation
- var frontmatter = new FileAgentSkillFrontmatter("symlink-read-skill", "A skill");
+ var frontmatter = new SkillFrontmatter("symlink-read-skill", "A skill");
var skill = new FileAgentSkill(
frontmatter: frontmatter,
body: "See [doc](refs/data.md).",
@@ -532,54 +532,6 @@ public sealed class FileAgentSkillLoaderTests : IDisposable
Assert.Equal("Body content.", skills["bom-skill"].Body);
}
- [Theory]
- [InlineData("No resource references.", new string[0])]
- [InlineData("Review `refs/FAQ.md` for details.", new[] { "refs/FAQ.md" })]
- [InlineData("See [guide](refs/guide.md) then run `scripts/run.py`.", new[] { "refs/guide.md", "scripts/run.py" })]
- public void DiscoverAndLoadSkills_ResourceReferences_ExtractsExpectedResourceNames(string body, string[] expectedResources)
- {
- // Arrange — create skill with resource files on disk so validation passes
- string skillDir = Path.Combine(this._testRoot, "res-skill");
- Directory.CreateDirectory(skillDir);
- foreach (string resource in expectedResources)
- {
- string resourcePath = Path.Combine(skillDir, resource.Replace('/', Path.DirectorySeparatorChar));
- Directory.CreateDirectory(Path.GetDirectoryName(resourcePath)!);
- File.WriteAllText(resourcePath, "content");
- }
-
- File.WriteAllText(
- Path.Combine(skillDir, "SKILL.md"),
- $"---\nname: res-skill\ndescription: Resource test\n---\n{body}");
-
- // Act
- var skills = this._loader.DiscoverAndLoadSkills(new[] { this._testRoot });
-
- // Assert
- Assert.Single(skills);
- var skill = skills["res-skill"];
- Assert.Equal(expectedResources.Length, skill.ResourceNames.Count);
- foreach (string expected in expectedResources)
- {
- Assert.Contains(expected, skill.ResourceNames);
- }
- }
-
- [Fact]
- public async Task ReadSkillResourceAsync_BacktickResourcePath_ReturnsContentAsync()
- {
- // Arrange — skill body uses backtick-quoted path
- _ = this.CreateSkillDirectoryWithResource("backtick-read", "A skill", "Load `refs/doc.md` first.", "refs/doc.md", "Backtick content.");
- var skills = this._loader.DiscoverAndLoadSkills(new[] { this._testRoot });
- var skill = skills["backtick-read"];
-
- // Act
- string content = await this._loader.ReadSkillResourceAsync(skill, "refs/doc.md");
-
- // Assert
- Assert.Equal("Backtick content.", content);
- }
-
private string CreateSkillDirectory(string name, string description, string body)
{
string skillDir = Path.Combine(this._testRoot, name);
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillScriptExecutorTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillScriptExecutorTests.cs
deleted file mode 100644
index 1be56e49c9..0000000000
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillScriptExecutorTests.cs
+++ /dev/null
@@ -1,170 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.Collections.Generic;
-using System.IO;
-using System.Linq;
-using System.Threading;
-using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.Logging.Abstractions;
-
-namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
-
-///
-/// Unit tests for and its integration with .
-///
-public sealed class FileAgentSkillScriptExecutorTests : IDisposable
-{
- private readonly string _testRoot;
- private readonly TestAIAgent _agent = new();
- private static readonly FileAgentSkillScriptExecutionContext s_emptyContext = new(
- new Dictionary(StringComparer.OrdinalIgnoreCase),
- new FileAgentSkillLoader(NullLogger.Instance));
-
- public FileAgentSkillScriptExecutorTests()
- {
- this._testRoot = Path.Combine(Path.GetTempPath(), "skill-executor-tests-" + Guid.NewGuid().ToString("N"));
- Directory.CreateDirectory(this._testRoot);
- }
-
- public void Dispose()
- {
- if (Directory.Exists(this._testRoot))
- {
- Directory.Delete(this._testRoot, recursive: true);
- }
- }
-
- [Fact]
- public void HostedCodeInterpreter_ReturnsNonNullInstance()
- {
- // Act
- var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
-
- // Assert
- Assert.NotNull(executor);
- }
-
- [Fact]
- public void HostedCodeInterpreter_GetExecutionDetails_ReturnsNonNullInstructions()
- {
- // Arrange
- var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
-
- // Act
- var details = executor.GetExecutionDetails(s_emptyContext);
-
- // Assert
- Assert.NotNull(details);
- Assert.NotNull(details.Instructions);
- Assert.NotEmpty(details.Instructions);
- }
-
- [Fact]
- public void HostedCodeInterpreter_GetExecutionDetails_ReturnsNonEmptyToolsList()
- {
- // Arrange
- var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
-
- // Act
- var details = executor.GetExecutionDetails(s_emptyContext);
-
- // Assert
- Assert.NotNull(details);
- Assert.NotNull(details.Tools);
- Assert.NotEmpty(details.Tools);
- }
-
- [Fact]
- public async Task Provider_WithExecutor_IncludesExecutorInstructionsInPromptAsync()
- {
- // Arrange
- CreateSkill(this._testRoot, "exec-skill", "Executor test", "Body.");
- var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
- var options = new FileAgentSkillsProviderOptions { ScriptExecutor = executor };
- var provider = new FileAgentSkillsProvider(this._testRoot, options);
- var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
-
- // Act
- var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
-
- // Assert — executor instructions should be merged into the prompt
- Assert.NotNull(result.Instructions);
- Assert.Contains("code interpreter", result.Instructions, StringComparison.OrdinalIgnoreCase);
- }
-
- [Fact]
- public async Task Provider_WithExecutor_IncludesExecutorToolsAsync()
- {
- // Arrange
- CreateSkill(this._testRoot, "tools-exec-skill", "Executor tools test", "Body.");
- var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
- var options = new FileAgentSkillsProviderOptions { ScriptExecutor = executor };
- var provider = new FileAgentSkillsProvider(this._testRoot, options);
- var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
-
- // Act
- var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
-
- // Assert — should have 3 tools: load_skill, read_skill_resource, and HostedCodeInterpreterTool
- Assert.NotNull(result.Tools);
- Assert.Equal(3, result.Tools!.Count());
- var toolNames = result.Tools!.Select(t => t.Name).ToList();
- Assert.Contains("load_skill", toolNames);
- Assert.Contains("read_skill_resource", toolNames);
- Assert.Single(result.Tools!, t => t is HostedCodeInterpreterTool);
- }
-
- [Fact]
- public async Task Provider_WithoutExecutor_DoesNotIncludeExecutorToolsAsync()
- {
- // Arrange
- CreateSkill(this._testRoot, "no-exec-skill", "No executor test", "Body.");
- var provider = new FileAgentSkillsProvider(this._testRoot);
- var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
-
- // Act
- var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
-
- // Assert — should only have the two base tools
- Assert.NotNull(result.Tools);
- Assert.Equal(2, result.Tools!.Count());
- }
-
- [Fact]
- public async Task Provider_WithHostedCodeInterpreter_MergesScriptInstructionsIntoPromptAsync()
- {
- // Arrange
- CreateSkill(this._testRoot, "merge-skill", "Merge test", "Body.");
- var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
- var options = new FileAgentSkillsProviderOptions { ScriptExecutor = executor };
- var provider = new FileAgentSkillsProvider(this._testRoot, options);
- var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
-
- // Act
- var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
-
- // Assert — prompt should contain both the skill listing and the executor's script instructions
- Assert.NotNull(result.Instructions);
- string instructions = result.Instructions!;
-
- // Skill listing is present
- Assert.Contains("merge-skill", instructions);
- Assert.Contains("Merge test", instructions);
-
- // Hosted code interpreter script instructions are merged into the prompt
- Assert.Contains("executable scripts", instructions);
- Assert.Contains("read_skill_resource", instructions);
- Assert.Contains("Execute the script using the code interpreter", instructions);
- }
-
- private static void CreateSkill(string root, string name, string description, string body)
- {
- string skillDir = Path.Combine(root, name);
- Directory.CreateDirectory(skillDir);
- File.WriteAllText(
- Path.Combine(skillDir, "SKILL.md"),
- $"---\nname: {name}\ndescription: {description}\n---\n{body}");
- }
-}
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
index f95f3a7080..6bfaf1b546 100644
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
@@ -96,7 +96,7 @@ public sealed class FileAgentSkillsProviderTests : IDisposable
this.CreateSkill("custom-prompt-skill", "Custom prompt", "Body.");
var options = new FileAgentSkillsProviderOptions
{
- SkillsInstructionPrompt = "Custom template: {skills}"
+ SkillsInstructionPrompt = "Custom template: {0}"
};
var provider = new FileAgentSkillsProvider(this._testRoot, options);
var inputContext = new AIContext();
@@ -110,6 +110,21 @@ public sealed class FileAgentSkillsProviderTests : IDisposable
Assert.StartsWith("Custom template:", result.Instructions);
}
+ [Fact]
+ public void Constructor_InvalidPromptTemplate_ThrowsArgumentException()
+ {
+ // Arrange — template with unescaped braces and no valid {0} placeholder
+ var options = new FileAgentSkillsProviderOptions
+ {
+ SkillsInstructionPrompt = "Bad template with {unescaped} braces"
+ };
+
+ // Act & Assert
+ var ex = Assert.Throws(() => new FileAgentSkillsProvider(this._testRoot, options));
+ Assert.Contains("SkillsInstructionPrompt", ex.Message);
+ Assert.Equal("options", ex.ParamName);
+ }
+
[Fact]
public async Task InvokingCoreAsync_SkillNamesAreXmlEscapedAsync()
{
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/HostedCodeInterpreterFileAgentSkillScriptExecutorTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/HostedCodeInterpreterFileAgentSkillScriptExecutorTests.cs
deleted file mode 100644
index 84a4446779..0000000000
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/HostedCodeInterpreterFileAgentSkillScriptExecutorTests.cs
+++ /dev/null
@@ -1,72 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.Collections.Generic;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.Logging.Abstractions;
-
-namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
-
-///
-/// Unit tests for .
-///
-public sealed class HostedCodeInterpreterFileAgentSkillScriptExecutorTests
-{
- private static readonly FileAgentSkillScriptExecutionContext s_emptyContext = new(
- new Dictionary(StringComparer.OrdinalIgnoreCase),
- new FileAgentSkillLoader(NullLogger.Instance));
-
- [Fact]
- public void GetExecutionDetails_ReturnsScriptExecutionGuidance()
- {
- // Arrange
- var executor = new HostedCodeInterpreterFileAgentSkillScriptExecutor();
-
- // Act
- var details = executor.GetExecutionDetails(s_emptyContext);
-
- // Assert
- Assert.NotNull(details.Instructions);
- Assert.Contains("read_skill_resource", details.Instructions);
- Assert.Contains("code interpreter", details.Instructions);
- }
-
- [Fact]
- public void GetExecutionDetails_ReturnsSingleHostedCodeInterpreterTool()
- {
- // Arrange
- var executor = new HostedCodeInterpreterFileAgentSkillScriptExecutor();
-
- // Act
- var details = executor.GetExecutionDetails(s_emptyContext);
-
- // Assert
- Assert.NotNull(details.Tools);
- Assert.Single(details.Tools!);
- Assert.IsType(details.Tools![0]);
- }
-
- [Fact]
- public void GetExecutionDetails_ReturnsSameInstanceOnMultipleCalls()
- {
- // Arrange
- var executor = new HostedCodeInterpreterFileAgentSkillScriptExecutor();
-
- // Act
- var details1 = executor.GetExecutionDetails(s_emptyContext);
- var details2 = executor.GetExecutionDetails(s_emptyContext);
-
- // Assert — static details should be reused
- Assert.Same(details1, details2);
- }
-
- [Fact]
- public void FactoryMethod_ReturnsHostedCodeInterpreterFileAgentSkillScriptExecutor()
- {
- // Act
- var executor = FileAgentSkillScriptExecutor.HostedCodeInterpreter();
-
- // Assert
- Assert.IsType(executor);
- }
-}
From c4f643a750605fdc53770cad0ac53c0386f6486c Mon Sep 17 00:00:00 2001
From: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Date: Mon, 2 Mar 2026 23:06:58 +0900
Subject: [PATCH 18/24] Python: Fix walrus operator precedence for model_id
kwarg in AzureOpenAIResponsesClient (#4310)
* Fix walrus operator precedence for model_id in AzureOpenAIResponsesClient (#4299)
Add parentheses around the walrus assignment so model_id receives the
actual string value instead of the boolean result of
`kwargs.pop(...) and not deployment_name`.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address review: replace walrus with explicit None check, add edge-case tests (#4299)
- Replace walrus operator with explicit assignment and 'is not None'
check to avoid boolean-coercion pitfalls (empty string now correctly
surfaces as ValueError instead of silently falling back)
- Add test: deployment_name takes precedence over model_id kwarg
- Add test: model_id='' raises ValueError
- Add test: model_id=None falls back to env var
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add explicit validation for empty model_id in AzureOpenAIResponsesClient
Reject empty or whitespace-only model_id with ValueError instead of
silently passing an empty deployment name downstream. This ensures the
test_init_model_id_kwarg_empty_string test correctly validates behavior
defined in production code rather than relying on downstream validation.
Addresses PR review feedback for #4299.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Simplify model_id handling using walrus operator
Addresses review comment on PR #4310.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Restore explicit model_id validation to fix test failures (#4299)
The walrus operator refactor silently dropped the empty-string validation,
causing test_init_model_id_kwarg_empty_string to fail. Restore the explicit
None check and ValueError raise for empty model_id.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Revert "Restore explicit model_id validation to fix test failures (#4299)"
This reverts commit 1d2965fff6575bccadc5150ab224d66f9676e3e1.
* Revert to walrus operator fix per review feedback
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../azure/_responses_client.py | 2 +-
.../azure/test_azure_responses_client.py | 23 +++++++++++++++++++
2 files changed, 24 insertions(+), 1 deletion(-)
diff --git a/python/packages/core/agent_framework/azure/_responses_client.py b/python/packages/core/agent_framework/azure/_responses_client.py
index b5b0ca1b5e..2debbd7b21 100644
--- a/python/packages/core/agent_framework/azure/_responses_client.py
+++ b/python/packages/core/agent_framework/azure/_responses_client.py
@@ -180,7 +180,7 @@ class AzureOpenAIResponsesClient( # type: ignore[misc]
client: AzureOpenAIResponsesClient[MyOptions] = AzureOpenAIResponsesClient()
response = await client.get_response("Hello", options={"my_custom_option": "value"})
"""
- if model_id := kwargs.pop("model_id", None) and not deployment_name:
+ if (model_id := kwargs.pop("model_id", None)) and not deployment_name:
deployment_name = str(model_id)
# Project client path: create OpenAI client from an Azure AI Foundry project
diff --git a/python/packages/core/tests/azure/test_azure_responses_client.py b/python/packages/core/tests/azure/test_azure_responses_client.py
index 4e9b25ca6a..37efff16ca 100644
--- a/python/packages/core/tests/azure/test_azure_responses_client.py
+++ b/python/packages/core/tests/azure/test_azure_responses_client.py
@@ -90,6 +90,29 @@ def test_init_model_id_constructor(azure_openai_unit_test_env: dict[str, str]) -
assert isinstance(azure_responses_client, SupportsChatGetResponse)
+def test_init_model_id_kwarg(azure_openai_unit_test_env: dict[str, str]) -> None:
+ """Test that model_id kwarg correctly sets the deployment name (issue #4299)."""
+ azure_responses_client = AzureOpenAIResponsesClient(model_id="gpt-4o")
+
+ assert azure_responses_client.model_id == "gpt-4o"
+ assert isinstance(azure_responses_client, SupportsChatGetResponse)
+
+
+def test_init_model_id_kwarg_does_not_override_deployment_name(azure_openai_unit_test_env: dict[str, str]) -> None:
+ """Test that deployment_name takes precedence over model_id kwarg (issue #4299)."""
+ azure_responses_client = AzureOpenAIResponsesClient(deployment_name="my-deployment", model_id="gpt-4o")
+
+ assert azure_responses_client.model_id == "my-deployment"
+ assert isinstance(azure_responses_client, SupportsChatGetResponse)
+
+
+def test_init_model_id_kwarg_none(azure_openai_unit_test_env: dict[str, str]) -> None:
+ """Test that model_id=None does not override the env-var deployment name."""
+ azure_responses_client = AzureOpenAIResponsesClient(model_id=None)
+
+ assert azure_responses_client.model_id == azure_openai_unit_test_env["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"]
+
+
def test_init_with_default_header(azure_openai_unit_test_env: dict[str, str]) -> None:
default_headers = {"X-Unit-Test": "test-guid"}
From 7d374f00bbf08843e4262c45a0056991e0162e9f Mon Sep 17 00:00:00 2001
From: Tao Chen
Date: Mon, 2 Mar 2026 08:24:20 -0800
Subject: [PATCH 19/24] Python: Fix samples discovered by auto validation
pipeline (#4355)
* Fix samples discovered by auto validation pipeline
* Update python/samples/02-agents/devui/in_memory_mode.py
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
.../workflows/python-sample-validation.yml | 6 +++---
agent-samples/openai/OpenAIResponses.yaml | 2 +-
.../chat_client/custom_chat_client.py | 6 ++++--
.../samples/02-agents/devui/in_memory_mode.py | 21 ++++++++++++++-----
4 files changed, 24 insertions(+), 11 deletions(-)
diff --git a/.github/workflows/python-sample-validation.yml b/.github/workflows/python-sample-validation.yml
index 1ada1ab113..2a5a0b6596 100644
--- a/.github/workflows/python-sample-validation.yml
+++ b/.github/workflows/python-sample-validation.yml
@@ -65,7 +65,7 @@ jobs:
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# OpenAI configuration
- OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+ OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
# Observability
@@ -227,7 +227,7 @@ jobs:
AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
# OpenAI configuration
- OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+ OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
defaults:
@@ -268,7 +268,7 @@ jobs:
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
# OpenAI configuration
- OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+ OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI_CHAT_MODEL_ID }}
OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI_RESPONSES_MODEL_ID }}
# Copilot Studio
diff --git a/agent-samples/openai/OpenAIResponses.yaml b/agent-samples/openai/OpenAIResponses.yaml
index bdc04d4a13..08fc9efe05 100644
--- a/agent-samples/openai/OpenAIResponses.yaml
+++ b/agent-samples/openai/OpenAIResponses.yaml
@@ -11,7 +11,7 @@ model:
topP: 0.95
connection:
kind: key
- apiKey: =Env.OPENAI_APIKEY
+ apiKey: =Env.OPENAI_API_KEY
outputSchema:
properties:
language:
diff --git a/python/samples/02-agents/chat_client/custom_chat_client.py b/python/samples/02-agents/chat_client/custom_chat_client.py
index aaeed76ced..cb63c74597 100644
--- a/python/samples/02-agents/chat_client/custom_chat_client.py
+++ b/python/samples/02-agents/chat_client/custom_chat_client.py
@@ -94,7 +94,9 @@ class EchoingChatClient(BaseChatClient[OptionsT]):
response_text = f"{response_text} {suffix}"
stream_delay_seconds = float(options.get("stream_delay_seconds", 0.05))
- response_message = Message(role="assistant", contents=[Content.from_text(response_text)])
+ response_message = Message(
+ role="assistant", contents=[Content.from_text(response_text)]
+ )
response = ChatResponse(
messages=[response_message],
@@ -146,7 +148,7 @@ async def main() -> None:
# Use the chat client directly
print("Using chat client directly:")
direct_response = await echo_client.get_response(
- "Hello, custom chat client!",
+ [Message(role="user", text="Hello, custom chat client!")],
options={
"uppercase": True,
"suffix": "(CUSTOM OPTIONS)",
diff --git a/python/samples/02-agents/devui/in_memory_mode.py b/python/samples/02-agents/devui/in_memory_mode.py
index 62a2800315..8914bf8e8e 100644
--- a/python/samples/02-agents/devui/in_memory_mode.py
+++ b/python/samples/02-agents/devui/in_memory_mode.py
@@ -10,7 +10,14 @@ import logging
import os
from typing import Annotated
-from agent_framework import Agent, Executor, WorkflowBuilder, WorkflowContext, handler, tool
+from agent_framework import (
+ Agent,
+ Executor,
+ WorkflowBuilder,
+ WorkflowContext,
+ handler,
+ tool,
+)
from agent_framework.azure import AzureOpenAIChatClient
from agent_framework.devui import serve
from dotenv import load_dotenv
@@ -30,7 +37,9 @@ def get_weather(
"""Get the weather for a given location."""
conditions = ["sunny", "cloudy", "rainy", "stormy"]
temperature = 53
- return f"The weather in {location} is {conditions[0]} with a high of {temperature}°C."
+ return (
+ f"The weather in {location} is {conditions[0]} with a high of {temperature}°C."
+ )
@tool(approval_mode="never_require")
@@ -59,7 +68,9 @@ class AddExclamation(Executor):
"""Add exclamation mark to text."""
@handler
- async def add_exclamation(self, text: str, ctx: WorkflowContext[Never, str]) -> None:
+ async def add_exclamation(
+ self, text: str, ctx: WorkflowContext[Never, str]
+ ) -> None:
"""Add exclamation and yield as workflow output."""
result = f"{text}!"
await ctx.yield_output(result)
@@ -74,9 +85,9 @@ def main():
# Create Azure OpenAI chat client
client = AzureOpenAIChatClient(
api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
- azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
+ deployment_name=os.environ["AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"],
+ endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
api_version=os.environ.get("AZURE_OPENAI_API_VERSION", "2024-10-21"),
- model_id=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME", "gpt-4o"),
)
# Create agents
From db48f8ce092026614ce8841b1674901f1047dade Mon Sep 17 00:00:00 2001
From: Ben Thomas
Date: Mon, 2 Mar 2026 08:26:14 -0800
Subject: [PATCH 20/24] .NET: Fixing issue with invalid node Ids when
visualizing dotnet workflows. (#4269)
* Fix Mermaid rendering errors in WorkflowVisualizer.ToMermaidString
Fix two bugs in the Mermaid diagram output:
1. Use safe node aliases (node_0, node_1, ...) instead of raw executor IDs
as Mermaid node identifiers. Raw IDs containing spaces, dots, or
non-ASCII characters (e.g. Japanese) caused Mermaid parse errors.
2. Fix conditional edge arrow syntax from '.--> ' (invalid) to '.-> '
(valid Mermaid dotted arrow syntax).
Fixes #1406
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Use recognizable sanitized IDs for Mermaid node identifiers\n\nReplace generic node_0/node_1 aliases with IDs derived from the original\nexecutor names. ASCII letters, digits, and underscores are preserved;\nother characters become underscores (collapsed, trimmed). Leading digits\nget an n_ prefix. Collisions are resolved with a numeric suffix.\n\nThis keeps node IDs readable in the Mermaid source while the display\nlabels continue to show the full original names."
* Remove issue number references from test names and comments"
* Address PR review feedback from Copilot\n\n- Add Throw.IfNull(id) guard to SanitizeMermaidNodeId\n- Add safety limit (10,000) to collision resolution loop\n- Restore missing edge assertions (middle1/middle2 --> end)\n- Fix comment to show actual sanitized ID (n_1_User_input)\n- Use stricter regex in Unicode test (must start with letter/underscore)"
* Address second round of PR review feedback\n\n- Escape node display labels via EscapeMermaidLabel to handle quotes,\n brackets, and newlines in executor IDs\n- Fix XML doc on SanitizeMermaidNodeId to accurately describe that\n existing consecutive underscores in input are preserved\n- Restore specific edge assertion (mid --> end) in conditional edge test\n- Restore fan-in routing assertions (s1/s2 through intermediate node,\n no direct edges to t) in fan-in test"
---------
Co-authored-by: alliscode
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../Visualization/WorkflowVisualizer.cs | 96 ++++++++++--
.../WorkflowVisualizerTests.cs | 146 +++++++++++++++---
2 files changed, 215 insertions(+), 27 deletions(-)
diff --git a/dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs b/dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs
index e1b69e9f9e..d09273fbc1 100644
--- a/dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs
+++ b/dotnet/src/Microsoft.Agents.AI.Workflows/Visualization/WorkflowVisualizer.cs
@@ -153,18 +153,52 @@ public static class WorkflowVisualizer
private static void EmitWorkflowMermaid(Workflow workflow, List lines, string indent, string? ns = null)
{
- string MapId(string id) => ns != null ? $"{ns}/{id}" : id;
+ // Build a mapping from raw IDs to Mermaid-safe node aliases that preserve
+ // as much of the original ID as possible for readability.
+ // Mermaid node IDs cannot contain spaces, dots, pipes, or most special characters.
+ var aliasMap = new Dictionary();
+ var usedAliases = new HashSet(StringComparer.Ordinal);
+
+ string GetSafeId(string id)
+ {
+ var key = ns != null ? $"{ns}/{id}" : id;
+ if (!aliasMap.TryGetValue(key, out var alias))
+ {
+ alias = SanitizeMermaidNodeId(key);
+
+ // Handle collisions by appending a numeric suffix
+ if (!usedAliases.Add(alias))
+ {
+ var i = 2;
+ while (!usedAliases.Add($"{alias}_{i}"))
+ {
+ if (i >= 10_000)
+ {
+ throw new InvalidOperationException($"Unable to generate a unique Mermaid node ID for '{key}'.");
+ }
+
+ i++;
+ }
+
+ alias = $"{alias}_{i}";
+ }
+
+ aliasMap[key] = alias;
+ }
+
+ return alias;
+ }
// Add start node
var startExecutorId = workflow.StartExecutorId;
- lines.Add($"{indent}{MapId(startExecutorId)}[\"{startExecutorId} (Start)\"];");
+ lines.Add($"{indent}{GetSafeId(startExecutorId)}[\"{EscapeMermaidLabel(startExecutorId)} (Start)\"];");
// Add other executor nodes
foreach (var executorId in workflow.ExecutorBindings.Keys)
{
if (executorId != startExecutorId)
{
- lines.Add($"{indent}{MapId(executorId)}[\"{executorId}\"];");
+ lines.Add($"{indent}{GetSafeId(executorId)}[\"{EscapeMermaidLabel(executorId)}\"];");
}
}
@@ -175,7 +209,7 @@ public static class WorkflowVisualizer
lines.Add("");
foreach (var (nodeId, _, _) in fanInDescriptors)
{
- lines.Add($"{indent}{MapId(nodeId)}((fan-in))");
+ lines.Add($"{indent}{GetSafeId(nodeId)}((fan-in))");
}
}
@@ -184,9 +218,9 @@ public static class WorkflowVisualizer
{
foreach (var src in sources)
{
- lines.Add($"{indent}{MapId(src)} --> {MapId(nodeId)};");
+ lines.Add($"{indent}{GetSafeId(src)} --> {GetSafeId(nodeId)};");
}
- lines.Add($"{indent}{MapId(nodeId)} --> {MapId(target)};");
+ lines.Add($"{indent}{GetSafeId(nodeId)} --> {GetSafeId(target)};");
}
// Emit normal edges
@@ -197,17 +231,17 @@ public static class WorkflowVisualizer
string effectiveLabel = label != null ? EscapeMermaidLabel(label) : "conditional";
// Conditional edge, with user label or default
- lines.Add($"{indent}{MapId(src)} -. {effectiveLabel} .--> {MapId(target)};");
+ lines.Add($"{indent}{GetSafeId(src)} -. {effectiveLabel} .-> {GetSafeId(target)};");
}
else if (label != null)
{
// Regular edge with label
- lines.Add($"{indent}{MapId(src)} -->|{EscapeMermaidLabel(label)}| {MapId(target)};");
+ lines.Add($"{indent}{GetSafeId(src)} -->|{EscapeMermaidLabel(label)}| {GetSafeId(target)};");
}
else
{
// Regular edge without label
- lines.Add($"{indent}{MapId(src)} --> {MapId(target)};");
+ lines.Add($"{indent}{GetSafeId(src)} --> {GetSafeId(target)};");
}
}
}
@@ -301,6 +335,50 @@ public static class WorkflowVisualizer
return false;
}
+ ///
+ /// Converts a raw node ID into a Mermaid-safe identifier that preserves as much
+ /// of the original text as possible. ASCII letters, digits, and underscores are kept
+ /// as-is (including existing consecutive underscores). All other characters (including
+ /// non-ASCII letters) are replaced with underscores, with consecutive invalid characters
+ /// collapsed into a single underscore. A leading digit gets a prefix.
+ ///
+ private static string SanitizeMermaidNodeId(string id)
+ {
+ Throw.IfNull(id);
+
+ var sb = new StringBuilder(id.Length);
+ bool lastWasUnderscore = false;
+ foreach (var ch in id)
+ {
+ bool isAsciiSafe = (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || (ch >= '0' && ch <= '9') || ch == '_';
+ if (isAsciiSafe)
+ {
+ sb.Append(ch);
+ lastWasUnderscore = ch == '_';
+ }
+ else if (!lastWasUnderscore)
+ {
+ sb.Append('_');
+ lastWasUnderscore = true;
+ }
+ }
+
+ // Trim trailing underscore
+ while (sb.Length > 0 && sb[sb.Length - 1] == '_')
+ {
+ sb.Length--;
+ }
+
+ // Mermaid IDs must not start with a digit
+ if (sb.Length > 0 && sb[0] >= '0' && sb[0] <= '9')
+ {
+ sb.Insert(0, "n_");
+ }
+
+ // Guard against empty result (e.g. id was all special chars)
+ return sb.Length == 0 ? "node" : sb.ToString();
+ }
+
// Helper method to escape special characters in DOT labels
private static string EscapeDotLabel(string label)
{
diff --git a/dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs b/dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs
index f6740cc48e..c8cf2cf214 100644
--- a/dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/WorkflowVisualizerTests.cs
@@ -292,11 +292,14 @@ public class WorkflowVisualizerTests
var mermaidContent = workflow.ToMermaidString();
- // Conditional edge should be dotted with label
- mermaidContent.Should().Contain("start -. conditional .--> mid");
- // Non-conditional edge should be solid
+ // Conditional edge should be dotted with label (using .-> not .-->)
+ mermaidContent.Should().Contain("-. conditional .-> ");
+ // Non-conditional edge should be a specific solid arrow
mermaidContent.Should().Contain("mid --> end");
- mermaidContent.Should().NotContain("end -. conditional");
+ // Display labels should be present
+ mermaidContent.Should().Contain("\"start (Start)\"");
+ mermaidContent.Should().Contain("\"mid\"");
+ mermaidContent.Should().Contain("\"end\"");
}
[Fact]
@@ -320,7 +323,7 @@ public class WorkflowVisualizerTests
var fanInLines = Array.FindAll(lines, line => line.Contains("((fan-in))"));
fanInLines.Should().HaveCount(1);
- // Extract the intermediate node id from the line
+ // Extract the intermediate fan-in node id from the line
var fanInLine = fanInLines[0].Trim();
var fanInNodeId = fanInLine.Substring(0, fanInLine.IndexOf("((fan-in))", StringComparison.Ordinal)).Trim();
fanInNodeId.Should().NotBeNullOrEmpty();
@@ -333,6 +336,24 @@ public class WorkflowVisualizerTests
// Ensure direct edges are not present
mermaidContent.Should().NotContain("s1 --> t");
mermaidContent.Should().NotContain("s2 --> t");
+
+ // Display labels should be present
+ mermaidContent.Should().Contain("\"start (Start)\"");
+ mermaidContent.Should().Contain("\"s1\"");
+ mermaidContent.Should().Contain("\"s2\"");
+ mermaidContent.Should().Contain("\"t\"");
+
+ // All node IDs should be safe aliases (ASCII-only identifiers)
+ foreach (var line in mermaidContent.Split('\n'))
+ {
+ var trimmed = line.Trim();
+ if (trimmed.Contains("[\"") || trimmed.Contains("(("))
+ {
+ var bracketIdx = trimmed.IndexOfAny(['[', '(']);
+ var nodeId = trimmed.Substring(0, bracketIdx);
+ nodeId.Should().MatchRegex("^[a-zA-Z_][a-zA-Z0-9_]*$");
+ }
+ }
}
[Fact]
@@ -353,13 +374,14 @@ public class WorkflowVisualizerTests
var mermaidContent = workflow.ToMermaidString();
- // Check all executors are present
- mermaidContent.Should().Contain("start[\"start (Start)\"]");
- mermaidContent.Should().Contain("middle1[\"middle1\"]");
- mermaidContent.Should().Contain("middle2[\"middle2\"]");
- mermaidContent.Should().Contain("end[\"end\"]");
+ // Check display labels are present
+ mermaidContent.Should().Contain("\"start (Start)\"");
+ mermaidContent.Should().Contain("\"middle1\"");
+ mermaidContent.Should().Contain("\"middle2\"");
+ mermaidContent.Should().Contain("\"end\"");
- // Check all edges are present
+ // Check that sanitized IDs are used and all edges connect them
+ mermaidContent.Should().Contain("start[\"start (Start)\"]");
mermaidContent.Should().Contain("start --> middle1");
mermaidContent.Should().Contain("start --> middle2");
mermaidContent.Should().Contain("middle1 --> end");
@@ -386,15 +408,19 @@ public class WorkflowVisualizerTests
var mermaidContent = workflow.ToMermaidString();
- // Check conditional edge
- mermaidContent.Should().Contain("start -. conditional .--> a");
-
- // Check fan-out edges
- mermaidContent.Should().Contain("a --> b");
- mermaidContent.Should().Contain("a --> c");
+ // Check conditional edge uses correct syntax (.-> not .-->)
+ mermaidContent.Should().Contain("-. conditional .->");
+ mermaidContent.Should().NotContain(".-->");
// Check fan-in (should have intermediate node)
mermaidContent.Should().Contain("((fan-in))");
+
+ // Display labels should be present
+ mermaidContent.Should().Contain("\"start (Start)\"");
+ mermaidContent.Should().Contain("\"a\"");
+ mermaidContent.Should().Contain("\"b\"");
+ mermaidContent.Should().Contain("\"c\"");
+ mermaidContent.Should().Contain("\"end\"");
}
[Fact]
@@ -411,7 +437,7 @@ public class WorkflowVisualizerTests
var mermaidContent = workflow.ToMermaidString();
// Should escape pipe character
- mermaidContent.Should().Contain("start -->|High | Low Priority| end");
+ mermaidContent.Should().Contain("-->|High | Low Priority|");
// Should not contain unescaped pipe that would break syntax
mermaidContent.Should().NotContain("-->|High | Low");
}
@@ -453,4 +479,88 @@ public class WorkflowVisualizerTests
// Should not contain literal newline in the label (but the overall output has newlines between statements)
mermaidContent.Should().NotContain("Line 1\nLine 2");
}
+
+ [Fact]
+ public void Test_WorkflowViz_Mermaid_ConditionalEdge_ArrowSyntax()
+ {
+ // Conditional edges must use "-. label .->" (not ".-->") which is the correct
+ // Mermaid syntax for dotted arrows with labels.
+ var start = new MockExecutor("start");
+ var mid = new MockExecutor("mid");
+
+ static bool Condition(string? msg) => msg == "foo";
+
+ var workflow = new WorkflowBuilder("start")
+ .AddEdge(start, mid, Condition)
+ .Build();
+
+ var mermaidContent = workflow.ToMermaidString();
+
+ // The output should use ".->" not ".-->" for conditional (dotted) edges
+ mermaidContent.Should().NotContain(".-->", because: "'.-->' is invalid Mermaid syntax for dotted arrows; should be '.->'");
+ mermaidContent.Should().Contain("-. conditional .->", because: "'-. label .->' is the correct Mermaid syntax for dotted arrows with labels");
+ }
+
+ [Fact]
+ public void Test_WorkflowViz_Mermaid_IdentifiersWithSpaces()
+ {
+ // Identifiers with spaces must not be used directly as Mermaid node IDs
+ // because spaces cause rendering errors.
+ var executor1 = new MockExecutor("1. User input");
+ var executor2 = new MockExecutor("2. Process data");
+
+ var workflow = new WorkflowBuilder("1. User input")
+ .AddEdge(executor1, executor2)
+ .Build();
+
+ var mermaidContent = workflow.ToMermaidString();
+
+ // Node definitions should use safe aliases as IDs (no spaces), with display names in quotes
+ // Bad: '1. User input["1. User input (Start)"]' — spaces in ID break Mermaid
+ // Good: 'n_1_User_input["1. User input (Start)"]' — alias ID is safe and sanitized
+
+ // Each node definition line (containing ["..."]) should have a space-free ID before the bracket
+ foreach (var line in mermaidContent.Split('\n'))
+ {
+ var trimmed = line.Trim();
+ if (trimmed.Contains("[\""))
+ {
+ var bracketIdx = trimmed.IndexOf('[');
+ var nodeId = trimmed.Substring(0, bracketIdx);
+ nodeId.Should().NotContain(" ", because: $"Mermaid node IDs must not contain spaces, but got '{nodeId}'");
+ }
+ }
+ }
+
+ [Fact]
+ public void Test_WorkflowViz_Mermaid_IdentifiersWithUnicode()
+ {
+ // Non-ASCII characters (e.g. Japanese) in identifiers cause Mermaid rendering errors.
+ var executor1 = new MockExecutor("ユーザー入力");
+ var executor2 = new MockExecutor("データ処理");
+
+ var workflow = new WorkflowBuilder("ユーザー入力")
+ .AddEdge(executor1, executor2)
+ .Build();
+
+ var mermaidContent = workflow.ToMermaidString();
+
+ // The display labels should contain the original names
+ mermaidContent.Should().Contain("ユーザー入力");
+ mermaidContent.Should().Contain("データ処理");
+
+ // But node IDs (before the bracket) should be safe ASCII-only identifiers
+ foreach (var line in mermaidContent.Split('\n'))
+ {
+ var trimmed = line.Trim();
+ if (trimmed.Contains("[\""))
+ {
+ var bracketIdx = trimmed.IndexOf('[');
+ var nodeId = trimmed.Substring(0, bracketIdx);
+ // Node ID should start with a letter or underscore, followed by ASCII alphanumeric or underscores
+ nodeId.Should().MatchRegex("^[a-zA-Z_][a-zA-Z0-9_]*$",
+ because: $"Mermaid node IDs should be ASCII-safe, but got '{nodeId}'");
+ }
+ }
+ }
}
From 8a18f39b367c21908e0f55c43a891490df088ec6 Mon Sep 17 00:00:00 2001
From: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>
Date: Mon, 2 Mar 2026 16:48:10 +0000
Subject: [PATCH 21/24] fix the issue (#4388)
---
.../src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs | 3 ++-
.../AgentSkills/FileAgentSkillsProviderTests.cs | 2 ++
2 files changed, 4 insertions(+), 1 deletion(-)
diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
index 847bf36a52..ad1ef752ee 100644
--- a/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
+++ b/dotnet/src/Microsoft.Agents.AI/Skills/FileAgentSkillsProvider.cs
@@ -174,7 +174,8 @@ public sealed partial class FileAgentSkillsProvider : AIContextProvider
{
try
{
- promptTemplate = string.Format(optionsInstructions, string.Empty);
+ _ = string.Format(optionsInstructions, string.Empty);
+ promptTemplate = optionsInstructions;
}
catch (FormatException ex)
{
diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
index 6bfaf1b546..92dc5a5418 100644
--- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
+++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillsProviderTests.cs
@@ -108,6 +108,8 @@ public sealed class FileAgentSkillsProviderTests : IDisposable
// Assert
Assert.NotNull(result.Instructions);
Assert.StartsWith("Custom template:", result.Instructions);
+ Assert.Contains("custom-prompt-skill", result.Instructions);
+ Assert.Contains("Custom prompt", result.Instructions);
}
[Fact]
From f6b0610a6c5aab4ff15245571711de56b22e2043 Mon Sep 17 00:00:00 2001
From: westey <164392973+westey-m@users.noreply.github.com>
Date: Mon, 2 Mar 2026 18:41:14 +0000
Subject: [PATCH 22/24] .NET: AuthN & AuthZ sample with asp.net service and web
client (#4354)
* Add sample demonstrating authentication and user access in agent tools
* Add fixes to enable running on windows
* Add launchsettings, add docker-compose to slnx and fix formatting
* Switch to Expenses rather than todo based sample and address PR comments
* Rename sample
* Fix formatting
---
dotnet/Directory.Packages.props | 2 +
dotnet/agent-framework-dotnet.slnx | 6 +
.../AspNetAgentAuthorization/README.md | 156 ++++++++++++
.../RazorWebClient/Dockerfile | 29 +++
.../RazorWebClient/Pages/Chat.cshtml | 35 +++
.../RazorWebClient/Pages/Chat.cshtml.cs | 79 ++++++
.../RazorWebClient/Pages/Index.cshtml | 18 ++
.../RazorWebClient/Pages/Index.cshtml.cs | 24 ++
.../Pages/Shared/_Layout.cshtml | 35 +++
.../RazorWebClient/Pages/_ViewImports.cshtml | 3 +
.../RazorWebClient/Program.cs | 142 +++++++++++
.../Properties/launchSettings.json | 12 +
.../RazorWebClient/RazorWebClient.csproj | 15 ++
.../RazorWebClient/appsettings.json | 15 ++
.../Service/Dockerfile | 34 +++
.../Service/ExpenseService.cs | 110 +++++++++
.../Service/Program.cs | 125 ++++++++++
.../Service/Properties/launchSettings.json | 12 +
.../Service/Service.csproj | 20 ++
.../Service/UserContext.cs | 69 ++++++
.../Service/appsettings.json | 12 +
.../docker-compose.yml | 80 ++++++
.../keycloak/dev-realm.json | 232 ++++++++++++++++++
.../keycloak/setup-redirect-uris.sh | 50 ++++
24 files changed, 1315 insertions(+)
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/README.md
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Dockerfile
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Chat.cshtml
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Chat.cshtml.cs
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Index.cshtml
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Index.cshtml.cs
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Shared/_Layout.cshtml
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/_ViewImports.cshtml
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Program.cs
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Properties/launchSettings.json
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/RazorWebClient.csproj
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/appsettings.json
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/Service/Dockerfile
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/Service/ExpenseService.cs
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/Service/Program.cs
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/Service/Properties/launchSettings.json
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/Service/Service.csproj
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/Service/UserContext.cs
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/Service/appsettings.json
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/docker-compose.yml
create mode 100644 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/keycloak/dev-realm.json
create mode 100755 dotnet/samples/05-end-to-end/AspNetAgentAuthorization/keycloak/setup-redirect-uris.sh
diff --git a/dotnet/Directory.Packages.props b/dotnet/Directory.Packages.props
index 396a316575..1b1e0daa08 100644
--- a/dotnet/Directory.Packages.props
+++ b/dotnet/Directory.Packages.props
@@ -58,6 +58,8 @@
+
+
diff --git a/dotnet/agent-framework-dotnet.slnx b/dotnet/agent-framework-dotnet.slnx
index b96b891b00..9801ccc105 100644
--- a/dotnet/agent-framework-dotnet.slnx
+++ b/dotnet/agent-framework-dotnet.slnx
@@ -287,6 +287,12 @@
+
+
+
+
+
+
diff --git a/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/README.md b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/README.md
new file mode 100644
index 0000000000..c84dd125c3
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/README.md
@@ -0,0 +1,156 @@
+# Auth Client-Server Sample
+
+This sample demonstrates how to authorize AI agents and their tools using OAuth 2.0 scopes. It shows two levels of access control: an endpoint-level scope (`agent.chat`) that gates access to the agent, and tool-level scopes (`expenses.view`, `expenses.approve`) that control what the agent can do on behalf of each user.
+
+While this sample uses Keycloak to avoid complex setup in order to run the sample, Keycloak can easily be replaced with any OIDC compatible provider, including [Microsoft Entra Id](https://www.microsoft.com/security/business/identity-access/microsoft-entra-id).
+
+## Overview
+
+The sample has three components, all launched with a single `docker compose up`:
+
+| Service | Port | Description |
+|---------|------|-------------|
+| **WebClient** | `http://localhost:8080` | Razor Pages web app with OIDC login and a chat UI that calls the AgentService |
+| **AgentService** | `http://localhost:5001` | ASP.NET Minimal API hosting an expense approval agent with scope-authorized tools |
+| **Keycloak** | `http://localhost:5002` | OIDC identity provider, auto-provisioned with realm, clients, scopes, and test users |
+
+```
+┌──────────────┐ OIDC login ┌───────────┐
+│ WebClient │ ◄──────────────────► │ Keycloak │
+│ (Razor app) │ (browser flow) │ (Docker) │
+│ :8080 │ │ :5002 │
+└──────┬───────┘ └─────┬─────┘
+ │ REST + Bearer token │
+ ▼ │
+┌───────────────┐ JWT validation ──────┘
+│ AgentService │ ◄──── (jwks from Keycloak)
+│ (Minimal API) │
+│ :5001 │
+└───────────────┘
+```
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
+
+## Configuring Environment Variables
+
+The AgentService requires an OpenAI-compatible endpoint. Set these environment variables before running:
+
+```bash
+export OPENAI_API_KEY=""
+export OPENAI_MODEL="gpt-4.1-mini"
+```
+
+## Running the Sample
+
+### Option 1: Docker Compose (Recommended)
+
+```bash
+cd dotnet/samples/05-end-to-end/AspNetAgentAuthorization
+docker compose up
+```
+
+This starts Keycloak, the AgentService, and the WebClient. Wait for Keycloak to finish importing the realm (you'll see `Running the server` in the logs).
+
+#### Running in GitHub Codespaces
+
+This sample has been built in such a way that it can be run from GitHub Codespaces.
+The Agent Framework repository has a C# specific dev container, named "C# (.NET)", that is configured for Codespaces.
+
+When running in Codespaces, the sample auto-detects the environment via
+`CODESPACE_NAME` and `GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN` and configures
+Keycloak and the web client accordingly. Just make the required ports public:
+
+```bash
+# Make Keycloak and WebClient ports publicly accessible
+gh codespace ports visibility 5002:public 8080:public -c $CODESPACE_NAME
+
+# Start the containers (Codespaces is auto-detected)
+docker compose up
+```
+
+Then open the Codespaces-forwarded URL for port 8080 (shown in the **Ports** tab) in your browser.
+
+### Option 2: Run Locally
+
+1. Start Keycloak:
+ ```bash
+ docker compose up keycloak
+ ```
+
+2. In a new terminal, start the AgentService:
+ ```bash
+ cd Service
+ dotnet run --urls "http://localhost:5001"
+ ```
+
+3. In another terminal, start the WebClient:
+ ```bash
+ cd RazorWebClient
+ dotnet run --urls "http://localhost:8080"
+ ```
+
+## Using the Sample
+
+1. Open `http://localhost:8080` in your browser
+2. Click **Login** — you'll be redirected to Keycloak
+3. Sign in with one of the pre-configured users:
+ - **`testuser` / `password`** — can chat, view expenses, and approve expenses (up to €1,000)
+ - **`viewer` / `password`** — can chat and view expenses, but **cannot approve** them
+4. Try asking the agent:
+ - _"Show me the pending expenses"_ — both users can do this
+ - _"Approve expense #1"_ — only `testuser` can do this; `viewer` will be denied
+ - _"Approve expense #3"_ — even `testuser` will be denied (€4,500 exceeds the €1,000 limit)
+
+## Pre-Configured Keycloak Realm
+
+The `keycloak/dev-realm.json` file auto-provisions:
+
+| Resource | Details |
+|----------|---------|
+| **Realm** | `dev` |
+| **Client: agent-service** | Confidential client (the API audience) |
+| **Client: web-client** | Public client for the Razor app's OIDC login |
+| **Scope: agent.chat** | Required to call the `/chat` endpoint |
+| **Scope: expenses.view** | Required to list pending expenses |
+| **Scope: expenses.approve** | Required to approve expenses |
+| **User: testuser** | Has `agent.chat`, `expenses.view`, and `expenses.approve` scopes |
+| **User: viewer** | Has `agent.chat` and `expenses.view` scopes (no approval) |
+
+### Pre-Seeded Expenses
+
+The service starts with five demo expenses:
+
+| # | Description | Amount | Status |
+|---|-------------|--------|--------|
+| 1 | Conference travel — Berlin | €850 | Pending |
+| 2 | Team dinner — Q4 celebration | €320 | Pending |
+| 3 | Cloud infrastructure — annual renewal | €4,500 | Pending (over limit) |
+| 4 | Office supplies — ergonomic keyboards | €675 | Pending |
+| 5 | Client gift baskets — holiday season | €980 | Pending |
+
+Keycloak admin console: `http://localhost:5002` (login: `admin` / `admin`).
+
+## API Endpoints
+
+### POST /chat (requires `agent.chat` scope)
+
+```bash
+# Get a token for testuser
+TOKEN=$(curl -s -X POST http://localhost:5002/realms/dev/protocol/openid-connect/token \
+ -d "grant_type=password&client_id=web-client&username=testuser&password=password&scope=openid agent.chat expenses.view expenses.approve" \
+ | jq -r '.access_token')
+
+# Chat with the agent
+curl -X POST http://localhost:5001/chat \
+ -H "Authorization: Bearer $TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"message": "Show me the pending expenses"}'
+```
+
+## Key Concepts Demonstrated
+
+- **Endpoint-Level Authorization** — The `/chat` endpoint requires the `agent.chat` scope, gating access to the agent itself
+- **Tool-Level Authorization** — Each agent tool checks its own scope (`expenses.view`, `expenses.approve`) at runtime, so different users have different capabilities within the same chat session
+- **Scope-Based Role Mapping** — Keycloak realm roles map to OAuth scopes, allowing administrators to control which users can access which agent capabilities
diff --git a/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Dockerfile b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Dockerfile
new file mode 100644
index 0000000000..8e15ba2425
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Dockerfile
@@ -0,0 +1,29 @@
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /repo
+
+# Copy solution-level files for restore
+COPY Directory.Build.props Directory.Build.targets Directory.Packages.props global.json nuget.config ./
+COPY eng/ eng/
+COPY src/Shared/ src/Shared/
+COPY samples/Directory.Build.props samples/
+
+# Create sentinel file so $(RepoRoot) resolves correctly inside the container.
+# RepoRoot is the parent of the dir containing CODE_OF_CONDUCT.md,
+# and src projects import $(RepoRoot)/dotnet/nuget/nuget-package.props.
+RUN touch /CODE_OF_CONDUCT.md
+
+# Copy project file for restore
+COPY samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/RazorWebClient.csproj samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/
+
+RUN dotnet restore samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/RazorWebClient.csproj -p:TargetFramework=net10.0 -p:TreatWarningsAsErrors=false
+
+# Copy everything and build
+COPY samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/ samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/
+RUN dotnet publish samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/RazorWebClient.csproj -c Release -f net10.0 -o /app -p:TreatWarningsAsErrors=false
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0
+WORKDIR /app
+COPY --from=build /app .
+ENV ASPNETCORE_URLS=http://+:8080
+EXPOSE 8080
+ENTRYPOINT ["dotnet", "RazorWebClient.dll"]
diff --git a/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Chat.cshtml b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Chat.cshtml
new file mode 100644
index 0000000000..edccf4c34e
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Chat.cshtml
@@ -0,0 +1,35 @@
+@page
+@using Microsoft.AspNetCore.Authorization
+@attribute [Authorize]
+@model AspNetAgentAuthorization.RazorWebClient.Pages.ChatModel
+@{
+ Layout = "_Layout";
+}
+
+
Chat with the Agent
+
+
+
+@if (Model.Error is not null)
+{
+
+ Error: @Model.Error
+
+}
+
+@if (Model.Reply is not null)
+{
+
+
Agent (responding to @Model.ReplyUser):
+
@Model.Reply
+
+}
diff --git a/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Chat.cshtml.cs b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Chat.cshtml.cs
new file mode 100644
index 0000000000..5326e7ae9d
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Chat.cshtml.cs
@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Net.Http.Headers;
+using System.Text;
+using System.Text.Json;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+namespace AspNetAgentAuthorization.RazorWebClient.Pages;
+
+public class ChatModel : PageModel
+{
+ private readonly IHttpClientFactory _httpClientFactory;
+
+ public ChatModel(IHttpClientFactory httpClientFactory)
+ {
+ this._httpClientFactory = httpClientFactory;
+ }
+
+ [BindProperty]
+ public string? Message { get; set; }
+
+ public string? Reply { get; set; }
+ public string? ReplyUser { get; set; }
+ public string? Error { get; set; }
+
+ public void OnGet()
+ {
+ }
+
+ public async Task OnPostAsync()
+ {
+ if (string.IsNullOrWhiteSpace(this.Message))
+ {
+ return;
+ }
+
+ try
+ {
+ // Get the access token stored during OIDC login
+ string? accessToken = await this.HttpContext.GetTokenAsync("access_token");
+ if (accessToken is null)
+ {
+ this.Error = "No access token available. Please log in again.";
+ return;
+ }
+
+ // Call the AgentService with the Bearer token
+ var client = this._httpClientFactory.CreateClient("AgentService");
+ client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
+
+ var payload = JsonSerializer.Serialize(new { message = this.Message });
+ var content = new StringContent(payload, Encoding.UTF8, "application/json");
+
+ var response = await client.PostAsync(new Uri("/chat", UriKind.Relative), content);
+
+ if (response.IsSuccessStatusCode)
+ {
+ using var json = await JsonDocument.ParseAsync(await response.Content.ReadAsStreamAsync());
+ this.Reply = json.RootElement.GetProperty("reply").GetString();
+ this.ReplyUser = json.RootElement.GetProperty("user").GetString();
+ }
+ else
+ {
+ this.Error = response.StatusCode switch
+ {
+ System.Net.HttpStatusCode.Unauthorized => "Authentication failed (401). Your session may have expired.",
+ System.Net.HttpStatusCode.Forbidden => "Access denied (403). Your account does not have the required 'agent.chat' scope.",
+ _ => $"AgentService returned {(int)response.StatusCode} {response.ReasonPhrase}."
+ };
+ }
+ }
+ catch (Exception ex)
+ {
+ this.Error = $"Failed to contact the AgentService: {ex.Message}";
+ }
+ }
+}
diff --git a/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Index.cshtml b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Index.cshtml
new file mode 100644
index 0000000000..ab1d7cb1dc
--- /dev/null
+++ b/dotnet/samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/Pages/Index.cshtml
@@ -0,0 +1,18 @@
+@page
+@model AspNetAgentAuthorization.RazorWebClient.Pages.IndexModel
+@{
+ Layout = "_Layout";
+}
+
+
Welcome
+
This sample demonstrates securing an AI agent API with OAuth 2.0 / OpenID Connect.