docs: refine README intro paragraph

Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>

.github/scripts/check_team_membership.js

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+/**
+ * Resolve the issue author and check their team membership.
+ *
+ * @param {object} opts
+ * @param {object} opts.github - Octokit REST client from actions/github-script
+ * @param {object} opts.context - GitHub Actions context
+ * @param {object} opts.core - GitHub Actions core toolkit
+ * @param {string} opts.teamSlug - Team slug to check membership against
+ * @param {string|number} opts.issueNumber - Issue number to resolve author for
+ * @returns {Promise<{author: string|null, isTeamMember: boolean}>}
+ */
+async function checkTeamMembership({ github, context, core, teamSlug, issueNumber }) {
+  let author = context.payload.issue?.user?.login;
+  if (!author) {
+    const { data: issue } = await github.rest.issues.get({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+      issue_number: Number(issueNumber),
+    });
+    author = issue.user?.login;
+  }
+
+  if (!author) {
+    core.setFailed('Could not determine issue author (user may be deleted).');
+    return { author: null, isTeamMember: false };
+  }
+
+  try {
+    await github.rest.teams.getByName({
+      org: context.repo.owner,
+      team_slug: teamSlug,
+    });
+  } catch (error) {
+    core.setFailed(`Team lookup failed for ${teamSlug}: ${error.message}`);
+    throw error;
+  }
+
+  let isTeamMember = false;
+  try {
+    const teamMembership = await github.rest.teams.getMembershipForUserInOrg({
+      org: context.repo.owner,
+      team_slug: teamSlug,
+      username: author,
+    });
+    isTeamMember = teamMembership.data.state === 'active';
+  } catch (error) {
+    if (error.status === 404) {
+      core.info(`Author ${author} is not a member of team ${teamSlug}.`);
+      isTeamMember = false;
+    } else {
+      core.setFailed(`Team membership lookup failed for ${author}: ${error.message}`);
+      throw error;
+    }
+  }
+
+  return { author, isTeamMember };
+}
+
+module.exports = checkTeamMembership;

.github/tests/test_check_team_membership.js

@@ -0,0 +1,178 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+/**
+ * Tests for check_team_membership.js.
+ *
+ * Run with: node --test .github/tests/test_check_team_membership.js
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+
+const checkTeamMembership = require('../scripts/check_team_membership.js');
+
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createMocks({ payloadIssue = undefined, apiUser = 'api-user', teamState = 'active' } = {}) {
+  const core = {
+    _infoMessages: [],
+    _failedMessages: [],
+    info(msg) { this._infoMessages.push(msg); },
+    setFailed(msg) { this._failedMessages.push(msg); },
+  };
+
+  const context = {
+    payload: { issue: payloadIssue },
+    repo: { owner: 'test-org', repo: 'test-repo' },
+  };
+
+  const github = {
+    rest: {
+      issues: {
+        get: async () => ({
+          data: { user: apiUser ? { login: apiUser } : null },
+        }),
+      },
+      teams: {
+        getByName: async () => ({}),
+        getMembershipForUserInOrg: async () => ({
+          data: { state: teamState },
+        }),
+      },
+    },
+  };
+
+  return { core, context, github };
+}
+
+const BASE_OPTS = { teamSlug: 'my-team', issueNumber: '123' };
+
+
+// ---------------------------------------------------------------------------
+// Author resolution
+// ---------------------------------------------------------------------------
+
+describe('author resolution', () => {
+  it('resolves author from event payload', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'payload-user' } },
+    });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, 'payload-user');
+  });
+
+  it('resolves author via API when payload issue is absent', async () => {
+    const { github, context, core } = createMocks({ apiUser: 'api-user' });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, 'api-user');
+  });
+
+  it('resolves author via API when payload issue user is null (deleted account)', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: null },
+      apiUser: 'fetched-user',
+    });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, 'fetched-user');
+  });
+
+  it('handles deleted account when API also returns null user', async () => {
+    const { github, context, core } = createMocks({ apiUser: null });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.author, null);
+    assert.equal(result.isTeamMember, false);
+    assert.ok(core._failedMessages.some(m => m.includes('deleted')));
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Team lookup
+// ---------------------------------------------------------------------------
+
+describe('team lookup', () => {
+  it('fails the job when team lookup errors', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'user1' } },
+    });
+    const error = new Error('Bad credentials');
+    github.rest.teams.getByName = async () => { throw error; };
+
+    await assert.rejects(
+      () => checkTeamMembership({ github, context, core, ...BASE_OPTS }),
+      (err) => err === error,
+    );
+    assert.ok(core._failedMessages.some(m => m.includes('Team lookup failed')));
+  });
+});
+
+
+// ---------------------------------------------------------------------------
+// Team membership
+// ---------------------------------------------------------------------------
+
+describe('team membership', () => {
+  it('returns true for active team member', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'member' } },
+      teamState: 'active',
+    });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.isTeamMember, true);
+  });
+
+  it('returns false for pending team member', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'pending-user' } },
+      teamState: 'pending',
+    });
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.isTeamMember, false);
+  });
+
+  it('treats 404 membership response as non-member without failing', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'outsider' } },
+    });
+    const notFoundError = new Error('Not Found');
+    notFoundError.status = 404;
+    github.rest.teams.getMembershipForUserInOrg = async () => { throw notFoundError; };
+
+    const result = await checkTeamMembership({ github, context, core, ...BASE_OPTS });
+    assert.equal(result.isTeamMember, false);
+    assert.equal(core._failedMessages.length, 0);
+    assert.ok(core._infoMessages.some(m => m.includes('not a member')));
+  });
+
+  it('fails the job on non-404 membership errors', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'user1' } },
+    });
+    const serverError = new Error('Internal Server Error');
+    serverError.status = 500;
+    github.rest.teams.getMembershipForUserInOrg = async () => { throw serverError; };
+
+    await assert.rejects(
+      () => checkTeamMembership({ github, context, core, ...BASE_OPTS }),
+      (err) => err === serverError,
+    );
+    assert.ok(core._failedMessages.some(m => m.includes('membership lookup failed')));
+  });
+
+  it('fails the job on membership errors without status code', async () => {
+    const { github, context, core } = createMocks({
+      payloadIssue: { user: { login: 'user1' } },
+    });
+    const networkError = new Error('ECONNREFUSED');
+    github.rest.teams.getMembershipForUserInOrg = async () => { throw networkError; };
+
+    await assert.rejects(
+      () => checkTeamMembership({ github, context, core, ...BASE_OPTS }),
+      (err) => err === networkError,
+    );
+    assert.ok(core._failedMessages.some(m => m.includes('membership lookup failed')));
+  });
+});

.github/workflows/issue-triage.yml

@@ -0,0 +1,199 @@
+name: Issue Triage
+
+on:
+  workflow_dispatch:
+    inputs:
+      issue_number:
+        description: Issue number to triage
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+  id-token: write
+
+concurrency:
+  group: issue-triage-${{ github.repository }}-${{ github.event.issue.number || inputs.issue_number || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  DEVFLOW_REPOSITORY: ${{ vars.DF_REPO }}
+  DEVFLOW_REF: main
+  TARGET_REPO_PATH: ${{ github.workspace }}/target-repo
+  DEVFLOW_PATH: ${{ github.workspace }}/devflow
+
+jobs:
+  team_check:
+    runs-on: ubuntu-latest
+    outputs:
+      is_team_member: ${{ steps.check.outputs.is_team_member }}
+      issue_number: ${{ steps.issue.outputs.issue_number }}
+      repo: ${{ steps.issue.outputs.repo }}
+    steps:
+      - name: Resolve issue metadata
+        id: issue
+        shell: bash
+        env:
+          ISSUE_NUMBER_EVENT: ${{ github.event.issue.number }}
+          ISSUE_NUMBER_INPUT: ${{ inputs.issue_number }}
+        run: |
+          set -euo pipefail
+
+          if [[ "${GITHUB_EVENT_NAME}" == "issues" ]]; then
+            issue_number="${ISSUE_NUMBER_EVENT}"
+          else
+            issue_number="${ISSUE_NUMBER_INPUT}"
+          fi
+
+          if [[ ! "$issue_number" =~ ^[1-9][0-9]*$ ]]; then
+            echo "Could not determine issue number; for workflow_dispatch runs, the 'issue_number' input is required." >&2
+            exit 1
+          fi
+
+          echo "issue_number=${issue_number}" >> "$GITHUB_OUTPUT"
+          echo "repo=${GITHUB_REPOSITORY}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout scripts
+        uses: actions/checkout@v6
+        with:
+          sparse-checkout: .github/scripts
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Check issue author team membership
+        id: check
+        uses: actions/github-script@v8
+        env:
+          TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}
+          ISSUE_NUMBER: ${{ steps.issue.outputs.issue_number }}
+        with:
+          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          script: |
+            const checkTeamMembership = require('./.github/scripts/check_team_membership.js');
+            const { author, isTeamMember } = await checkTeamMembership({
+              github,
+              context,
+              core,
+              teamSlug: process.env.TEAM_NAME,
+              issueNumber: process.env.ISSUE_NUMBER,
+            });
+            core.setOutput('is_team_member', isTeamMember ? 'true' : 'false');
+            if (isTeamMember) {
+              core.info(`Author ${author} is a team member; skipping auto-triage.`);
+            } else {
+              core.info(`Author ${author} is not a team member; proceeding with triage.`);
+            }
+
+  triage:
+    runs-on: ubuntu-latest
+    needs: team_check
+    if: ${{ needs.team_check.outputs.is_team_member == 'false' }}
+    environment: integration
+    timeout-minutes: 60
+
+    steps:
+      # Safe checkout: base repo only.
+      - name: Checkout target repo base
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          path: target-repo
+
+      # Private DevFlow (maf-dashboard) checkout.
+      - name: Checkout DevFlow
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ env.DEVFLOW_REPOSITORY }}
+          ref: ${{ env.DEVFLOW_REF }}
+          token: ${{ secrets.DEVFLOW_TOKEN }}
+          fetch-depth: 1
+          persist-credentials: false
+          path: devflow
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "0.11.x"
+          enable-cache: true
+
+      - name: Install DevFlow dependencies
+        working-directory: ${{ env.DEVFLOW_PATH }}
+        run: uv sync --frozen
+
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Classify issue relevance
+        id: spam
+        working-directory: ${{ env.DEVFLOW_PATH }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          ISSUE_REPO: ${{ needs.team_check.outputs.repo }}
+          ISSUE_NUMBER: ${{ needs.team_check.outputs.issue_number }}
+        run: |
+          uv run python scripts/classify_issue_spam.py \
+            --repo "$ISSUE_REPO" \
+            --issue-number "$ISSUE_NUMBER" \
+            --repo-path "${TARGET_REPO_PATH}" \
+            --apply-labels
+
+      - name: Stop after spam gate
+        if: ${{ steps.spam.outputs.decision != 'allow' }}
+        shell: bash
+        env:
+          SPAM_DECISION: ${{ steps.spam.outputs.decision }}
+        run: |
+          echo "Stopping: spam gate decided: ${SPAM_DECISION}"
+          exit 1
+
+      - name: Reproduce reported issue
+        if: ${{ steps.spam.outputs.decision == 'allow' }}
+        id: repro
+        working-directory: ${{ env.DEVFLOW_PATH }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_COPILOT_TOKEN: ${{ secrets.GH_COPILOT_TOKEN }}
+          SK_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          AGENT_REPO_PATH: ${{ env.TARGET_REPO_PATH }}
+          ISSUE_REPO: ${{ needs.team_check.outputs.repo }}
+          ISSUE_NUMBER: ${{ needs.team_check.outputs.issue_number }}
+          # Model-provider settings for generated repro code. Never enter the
+          # agent prompt; consumed by SDK constructors via os.environ. Azure
+          # OpenAI and Foundry auth via AAD from the azure/login step above.
+          OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+          OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+          OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+          OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+          OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+          AZURE_OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+          AZURE_OPENAI_CHAT_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+          AZURE_OPENAI_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+          AZURE_OPENAI_EMBEDDING_MODEL: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
+          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+          FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
+          FOUNDRY_AGENT_NAME: ${{ vars.FOUNDRY_AGENT_NAME }}
+          FOUNDRY_AGENT_VERSION: ${{ vars.FOUNDRY_AGENT_VERSION }}
+          FOUNDRY_MODELS_ENDPOINT: ${{ vars.FOUNDRY_MODELS_ENDPOINT || '' }}
+          FOUNDRY_MODELS_API_KEY: ${{ secrets.FOUNDRY_MODELS_API_KEY || '' }}
+          FOUNDRY_EMBEDDING_MODEL: ${{ vars.FOUNDRY_EMBEDDING_MODEL || '' }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          ANTHROPIC_CHAT_MODEL: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+        run: |
+          uv run python scripts/trigger_issue_repro.py \
+            --repo "$ISSUE_REPO" \
+            --issue-number "$ISSUE_NUMBER" \
+            --github-username "$GITHUB_ACTOR"

README.md

@@ -6,8 +6,12 @@
 [![MS Learn Documentation](https://img.shields.io/badge/MS%20Learn-Documentation-blue)](https://learn.microsoft.com/en-us/agent-framework/)
 [![PyPI](https://img.shields.io/pypi/v/agent-framework)](https://pypi.org/project/agent-framework/)
 [![NuGet](https://img.shields.io/nuget/v/Microsoft.Agents.AI)](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
+[![GitHub stars](https://img.shields.io/github/stars/microsoft/agent-framework?style=social)](https://github.com/microsoft/agent-framework/stargazers)
 
-Welcome to Microsoft's comprehensive multi-language framework for building, orchestrating, and deploying AI agents with support for both .NET and Python implementations. This framework provides everything from simple chat agents to complex multi-agent workflows with graph-based orchestration.
+
+Microsoft Agent Framework (MAF) is an open, multi-language framework for building **production-grade AI agents and multi-agent workflows** in **.NET and Python**.
+
+Microsoft Agent Framework is built for teams taking agents from prototype to production. It provides a consistent foundation for building, orchestrating, and operating agent systems across Python and .NET, while keeping architecture choices open as requirements evolve, and supports a broad ecosystem including Microsoft Foundry, Azure OpenAI, OpenAI, and the GitHub Copilot SDK, with samples and hosting patterns for both local development and cloud deployment.
 
 <p align="center">
   <a href="https://www.youtube.com/watch?v=AAgdMhftj8w" title="Watch the full Agent Framework introduction (30 min)">
@@ -21,10 +25,54 @@ Welcome to Microsoft's comprehensive multi-language framework for building, orch
   </a>
 </p>
 
-## 📋 Getting Started
+## Is this the right framework for you?
 
-### 📦 Installation
+MAF is a strong fit if you:
+- are building agents and workflows you expect to run in production,
+- need orchestration beyond a single prompt or stateless chat loop,
+- want graph-based patterns such as sequential, concurrent, handoff, and group collaboration,
+- care about durability, restartability, observability, governance, or human-in-the-loop control,
+- need provider flexibility so your architecture can evolve without major rewrites.
 
+## Key Features
+Explore new MAF capabilities and real implementation patterns on the [official blog](https://devblogs.microsoft.com/agent-framework/).
+
+- **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
+  - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
+- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
+  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/02-agents/AgentProviders/)
+- **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
+  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/)
+- **Orchestration Patterns & Workflows**: Build multi-agent systems with graph-based workflows supporting sequential, concurrent, handoff, and group collaboration patterns; includes checkpointing, streaming, human-in-the-loop, and time-travel
+  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/03-workflows/)
+- **Foundry Hosted Agents (new)**: Deploy and host your agents to Foundry-hosted infrastructure with just 2 additional lines of code
+  - [Python samples](./python/samples/04-hosting/foundry-hosted-agents/) | [.NET samples](./dotnet/samples/04-hosting/FoundryHostedAgents/)
+- **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
+  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/02-agents/AgentOpenTelemetry/)
+- **Declarative Agents**: Define agents using YAML for faster setup and versioning
+  - [Declarative agent samples](./declarative-agents/)
+- **Agent Skills**: Build domain-specific knowledge bases from multiple sources—files, inline code, class libraries—for agents to discover and use
+  - [Skills design](./docs/decisions/0021-agent-skills-design.md)
+- **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
+  - [Labs directory](./python/packages/lab/)
+- **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
+  - [See the DevUI in action](https://www.youtube.com/watch?v=mOAaGY4WPvc)
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Learning Resources](#learning-resources)
+  - [Quickstart](#quickstart)
+    - [Basic Agent - Python](#basic-agent---python)
+    - [Basic Agent - .NET](#basic-agent---net)
+- [More Examples & Samples](#more-examples--samples)
+- [Community & Feedback](#community--feedback)
+- [Troubleshooting](#troubleshooting)
+- [Contributor Resources](#contributor-resources)
+
+## Getting Started
+### Installation
 Python
 
 ```bash
@@ -37,9 +85,13 @@ pip install agent-framework
 
 ```bash
 dotnet add package Microsoft.Agents.AI
+# For Foundry integration (used in the .NET quickstart below):
+dotnet add package Microsoft.Agents.AI.Foundry
+dotnet add package Azure.AI.Projects
+dotnet add package Azure.Identity
 ```
 
-### 📚 Documentation
+### Learning Resources
 
 - **[Overview](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)** - High level overview of the framework
 - **[Quick Start](https://learn.microsoft.com/agent-framework/tutorials/quick-start)** - Get started with a simple agent
@@ -48,44 +100,9 @@ dotnet add package Microsoft.Agents.AI
 - **[Migration from Semantic Kernel](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-semantic-kernel)** - Guide to migrate from Semantic Kernel
 - **[Migration from AutoGen](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen)** - Guide to migrate from AutoGen
 
-Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-community-office-hours) or ask questions in our [Discord channel](https://discord.gg/b5zjErwbQM) to get help from the team and other users.
+### Quickstart
 
-### ✨ **Highlights**
-
-- **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities
-  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/03-workflows/)
-- **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
-  - [Labs directory](./python/packages/lab/)
-- **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
-  - [DevUI package](./python/packages/devui/)
-
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=mOAaGY4WPvc">
-    <img src="https://img.youtube.com/vi/mOAaGY4WPvc/hqdefault.jpg" alt="See the DevUI in action" width="480">
-  </a>
-</p>
-<p align="center">
-  <a href="https://www.youtube.com/watch?v=mOAaGY4WPvc">
-    See the DevUI in action (1 min)
-  </a>
-</p>
-
-- **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
-  - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
-- **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
-  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/02-agents/AgentOpenTelemetry/)
-- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
-  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/02-agents/AgentProviders/)
-- **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
-  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/)
-
-### 💬 **We want your feedback!**
-
-- For bugs, please file a [GitHub issue](https://github.com/microsoft/agent-framework/issues).
-
-## Quickstart
-
-### Basic Agent - Python
+#### Basic Agent - Python
 
 Create a simple Azure Responses Agent that writes a haiku about the Microsoft Agent Framework
 
@@ -109,7 +126,7 @@ async def main():
           # project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
           # model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
       ),
-      name="HaikuBot",
+      name="HaikuAgent",
       instructions="You are an upbeat assistant that writes beautifully.",
     )
 
@@ -119,40 +136,24 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-### Basic Agent - .NET
-Create a simple Agent, using Microsoft Foundry with token-based auth, that writes a haiku about the Microsoft Agent Framework
+#### Basic Agent - .NET
+Create a simple Agent, using Microsoft Foundry that writes a haiku about the Microsoft Agent Framework
 
 ```c#
-// dotnet add package Microsoft.Agents.AI.Foundry
-// Use `az login` to authenticate with Azure CLI
-using Azure.AI.Projects;
-using Azure.Identity;
-using System;
+// This sample shows how to create and run a basic agent with AIProjectClient.AsAIAgent(...).
+
 using Azure.AI.Projects;
 using Azure.Identity;
+using Microsoft.Agents.AI;
 
-var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
 
-var agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
-    .AsAIAgent(model: deploymentName, name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
-
-Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
-```
-
-Create a simple Agent, using OpenAI Responses, that writes a haiku about the Microsoft Agent Framework
-
-```c#
-// dotnet add package Microsoft.Agents.AI.OpenAI
-using System;
-using OpenAI;
-using OpenAI.Responses;
-
-// Replace the <apikey> with your OpenAI API key.
-var agent = new OpenAIClient("<apikey>")
-    .GetResponsesClient()
-    .AsAIAgent(model: "gpt-5.4-mini", name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+AIAgent agent =
+    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: deploymentName, instructions: "You are an upbeat assistant that writes beautifully.", name: "HaikuAgent");
 
+// Once you have the agent, you can invoke it like any other AIAgent.
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
 
@@ -175,6 +176,12 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 - [Hosting](./dotnet/samples/04-hosting): A2A, Durable Agents, Durable Workflows
 - [End-to-End](./dotnet/samples/05-end-to-end): full applications and demos
 
+## Community & Feedback
+
+- **Found a bug?** File a [GitHub issue](https://github.com/microsoft/agent-framework/issues) to help us improve.
+- **Enjoying MAF?** [![GitHub stars](https://img.shields.io/badge/Star-us%20on%20GitHub-yellow)](https://github.com/microsoft/agent-framework) to show your support and help others discover the project.
+- **Have questions?** Join our [Discord](https://discord.gg/b5zjErwbQM) or visit [weekly office hours](./COMMUNITY.md#public-community-office-hours).
+
 ## Troubleshooting
 
 ### Authentication
@@ -187,16 +194,7 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 > **Tip:** `DefaultAzureCredential` is convenient for development but in production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 
 ### Environment Variables
-
-The samples typically read configuration from environment variables. Common required variables:
-
-| Variable | Used by | Purpose |
-|----------|---------|---------|
-| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI samples | Your Azure OpenAI resource URL |
-| `AZURE_OPENAI_DEPLOYMENT_NAME` | Azure OpenAI samples | Model deployment name (e.g. `gpt-4o-mini`) |
-| `AZURE_AI_PROJECT_ENDPOINT` | Microsoft Foundry samples | Your Microsoft Foundry project endpoint |
-| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Microsoft Foundry samples | Model deployment name |
-| `OPENAI_API_KEY` | OpenAI (non-Azure) samples | Your OpenAI platform API key |
+For environment variable configuration specific to each sample, refer to the README in the sample directory ([Python samples](./python/samples/) | [.NET samples](./dotnet/samples/)).
 
 ## Contributor Resources
 

dotnet/Directory.Packages.props

@@ -22,9 +22,9 @@
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
     <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.22" />
-    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.1" />
-    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.3" />
+    <PackageVersion Include="Azure.AI.AgentServer.Core" Version="1.0.0-beta.23" />
+    <PackageVersion Include="Azure.AI.AgentServer.Invocations" Version="1.0.0-beta.3" />
+    <PackageVersion Include="Azure.AI.AgentServer.Responses" Version="1.0.0-beta.4" />
     <PackageVersion Include="Azure.AI.Projects" Version="2.0.0" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
@@ -56,15 +56,15 @@
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
     <!-- OpenTelemetry -->
-    <PackageVersion Include="OpenTelemetry" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Api" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.0" />
-    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.14.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.14.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.14.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Api" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.15.3" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.15.2" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.15.1" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.15.1" />
     <!-- Microsoft.AspNetCore.* -->
     <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
@@ -188,4 +188,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/agent-framework-dotnet.slnx

@@ -4,9 +4,6 @@
     <BuildType Name="Publish" />
     <BuildType Name="Release" />
   </Configurations>
-  <Folder Name="/src/Aspire.Hosting.AgentFramework.DevUI/">
-    <Project Path="src/Aspire.Hosting.AgentFramework.DevUI/Aspire.Hosting.AgentFramework.DevUI.csproj" />
-  </Folder>
   <Folder Name="/Samples/">
     <File Path="samples/AGENTS.md" />
     <File Path="samples/README.md" />
@@ -67,6 +64,7 @@
     <Project Path="samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Agent_Step17_AdditionalAIContext.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Agent_Step18_CompactionPipeline.csproj" />
     <Project Path="samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing/Agent_Step19_InFunctionLoopCheckpointing.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/Agent_Step20_DynamicFunctionTools.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/DeclarativeAgents/">
     <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
@@ -162,6 +160,7 @@
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step22_MemorySearch/Agent_Step22_MemorySearch.csproj" />
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step23_LocalMCP/Agent_Step23_LocalMCP.csproj" />
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step24_CodeInterpreterFileDownload/Agent_Step24_CodeInterpreterFileDownload.csproj" />
+    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/Agent_Step25_ToolboxServerSideTools.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/Evaluation/">
     <Project Path="samples/02-agents/Evaluation/Evaluation_SimpleEval/Evaluation_SimpleEval.csproj" />
@@ -533,6 +532,7 @@
     <File Path="tests/Directory.Build.props" />
   </Folder>
   <Folder Name="/src/">
+    <Project Path="src/Aspire.Hosting.AgentFramework.DevUI/Aspire.Hosting.AgentFramework.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.A2A/Microsoft.Agents.AI.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />

dotnet/nuget/nuget-package.props

@@ -1,14 +1,14 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.2.0</VersionPrefix>
+    <VersionPrefix>1.3.0</VersionPrefix>
     <RCNumber>1</RCNumber>
-    <DateSuffix>260421</DateSuffix>
+    <DateSuffix>260423</DateSuffix>
     <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
     <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).$(DateSuffix).1</PackageVersion>
     <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.$(DateSuffix).1</PackageVersion>
     <PackageVersion Condition="'$(IsReleased)' == 'true'">$(VersionPrefix)</PackageVersion>
-    <GitTag>1.2.0</GitTag>
+    <GitTag>1.3.0</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/02-agents/AgentSkills/SubprocessScriptRunner.cs

@@ -5,16 +5,16 @@
 // This is provided for demonstration purposes only.
 
 using System.Diagnostics;
+using System.Text.Json;
 using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
 
 /// <summary>
 /// Executes file-based skill scripts as local subprocesses.
 /// </summary>
 /// <remarks>
-/// This runner uses the script's absolute path, converts the arguments
-/// to CLI flags, and returns captured output. It is intended for
-/// demonstration purposes only.
+/// This runner uses the script's absolute path and converts the arguments
+/// to CLI arguments. When the LLM sends a JSON array, each element is used
+/// as a positional argument. It is intended for demonstration purposes only.
 /// </remarks>
 internal static class SubprocessScriptRunner
 {
@@ -24,7 +24,8 @@ internal static class SubprocessScriptRunner
     public static async Task<object?> RunAsync(
         AgentFileSkill skill,
         AgentFileSkillScript script,
-        AIFunctionArguments arguments,
+        JsonElement? arguments,
+        IServiceProvider? serviceProvider,
         CancellationToken cancellationToken)
     {
         if (!File.Exists(script.FullPath))
@@ -61,24 +62,27 @@ internal static class SubprocessScriptRunner
             startInfo.FileName = script.FullPath;
         }
 
-        if (arguments is not null)
+        if (arguments is { ValueKind: JsonValueKind.Array } json)
         {
-            foreach (var (key, value) in arguments)
+            // Positional CLI arguments
+            foreach (var element in json.EnumerateArray())
             {
-                if (value is bool boolValue)
+                if (element.ValueKind != JsonValueKind.String)
                 {
-                    if (boolValue)
-                    {
-                        startInfo.ArgumentList.Add(NormalizeKey(key));
-                    }
-                }
-                else if (value is not null)
-                {
-                    startInfo.ArgumentList.Add(NormalizeKey(key));
-                    startInfo.ArgumentList.Add(value.ToString()!);
+                    throw new InvalidOperationException(
+                        $"File-based skill scripts only accept string CLI arguments but received a JSON element of kind '{element.ValueKind}'. " +
+                        "All array elements must be JSON strings.");
                 }
+
+                startInfo.ArgumentList.Add(element.GetString()!);
             }
         }
+        else if (arguments is not null && arguments.Value.ValueKind != JsonValueKind.Null && arguments.Value.ValueKind != JsonValueKind.Undefined)
+        {
+            throw new InvalidOperationException(
+                $"Expected a JSON array of CLI arguments but received {arguments.Value.ValueKind}. " +
+                "File-based skill scripts expect positional arguments as a JSON array of strings.");
+        }
 
         Process? process = null;
         try
@@ -128,10 +132,4 @@ internal static class SubprocessScriptRunner
             process?.Dispose();
         }
     }
-
-    /// <summary>
-    /// Normalizes a parameter key to a consistent --flag format.
-    /// Models may return keys with or without leading dashes (e.g., "value" vs "--value").
-    /// </summary>
-    private static string NormalizeKey(string key) => "--" + key.TrimStart('-');
 }

dotnet/samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/Agent_Step20_DynamicFunctionTools.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/Program.cs

@@ -0,0 +1,281 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to dynamically expand the set of function tools available to an
+// agent during a function-calling loop. The agent starts with a single "RequestTools" function.
+// When the model calls RequestTools with a description of the capabilities needed, the function
+// uses the ambient FunctionInvocationContext to add new tools to ChatOptions.Tools. The agent
+// can then use the newly added tools in subsequent iterations of the same function-calling loop.
+
+using System.ComponentModel;
+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-5.4-mini";
+
+// Pre-defined tool implementations that can be loaded on demand.
+[Description("Get the current weather for a city.")]
+static string GetWeather([Description("The city name.")] string city) =>
+    city.ToUpperInvariant() switch
+    {
+        "SEATTLE" => "Seattle: 55°F, cloudy with light rain.",
+        "NEW YORK" => "New York: 72°F, sunny and warm.",
+        "LONDON" => "London: 48°F, overcast with fog.",
+        _ => $"{city}: weather data not available, please provide one of the following city names: 'Seattle', 'New York', 'London'."
+    };
+
+[Description("Get the current local time for a city.")]
+static string GetTime([Description("The city name.")] string city) =>
+    city.ToUpperInvariant() switch
+    {
+        "SEATTLE" => "Seattle: 9:00 AM PST",
+        "NEW YORK" => "New York: 12:00 PM EST",
+        "LONDON" => "London: 5:00 PM GMT",
+        _ => $"{city}: time data not available, please provide one of the following city names: 'Seattle', 'New York', 'London'."
+    };
+
+[Description("Convert a temperature from Fahrenheit to Celsius.")]
+static string ConvertFahrenheitToCelsius([Description("The temperature in Fahrenheit.")] double fahrenheit) =>
+    $"{fahrenheit}°F = {(fahrenheit - 32) * 5 / 9:F1}°C";
+
+// A registry of tool sets that can be loaded by description keyword.
+Dictionary<string, List<AITool>> toolCatalog = new(StringComparer.OrdinalIgnoreCase)
+{
+    ["weather"] = [AIFunctionFactory.Create(GetWeather, name: "GetWeather")],
+    ["time"] = [AIFunctionFactory.Create(GetTime, name: "GetTime")],
+    ["temperature"] = [AIFunctionFactory.Create(ConvertFahrenheitToCelsius, name: "ConvertFahrenheitToCelsius")],
+};
+
+// The RequestTools function uses the ambient FunctionInvocationContext to add tools dynamically.
+AIFunction requestToolsFunction = AIFunctionFactory.Create(
+    [Description("Request additional tools to be loaded based on a description of the functionality needed. " +
+                 "Call this when you need capabilities that are not yet available in your current tool set.")] (
+        [Description("A description of the functionality required, e.g. 'weather', 'time', or 'temperature conversion'.")] string description
+    ) =>
+    {
+        // Access the ambient FunctionInvocationContext provided by FunctionInvokingChatClient.
+        var context = FunctionInvokingChatClient.CurrentContext
+            ?? throw new InvalidOperationException("No ambient FunctionInvocationContext available.");
+
+        var tools = context.Options?.Tools;
+        if (tools is null)
+        {
+            return "Unable to register new tools: ChatOptions.Tools is not available.";
+        }
+
+        // Find matching tool sets from the catalog.
+        List<string> addedToolNames = [];
+        foreach (var kvp in toolCatalog)
+        {
+            var keyword = kvp.Key;
+            var catalogTools = kvp.Value;
+            if (description.Contains(keyword, StringComparison.OrdinalIgnoreCase))
+            {
+                foreach (var tool in catalogTools)
+                {
+                    // Avoid adding duplicates.
+                    if (tool is AIFunction fn && !tools.Any(t => t is AIFunction existing && existing.Name == fn.Name))
+                    {
+                        tools.Add(tool);
+                        addedToolNames.Add(fn.Name);
+                    }
+                }
+            }
+        }
+
+        return addedToolNames.Count > 0
+            ? "Successfully loaded tools"
+            : $"No tools matched the description '{description}'. Available categories: {string.Join(", ", toolCatalog.Keys)}.";
+    },
+    name: "RequestTools");
+
+// Create the agent with only the RequestTools function initially.
+// Insert chat client middleware that logs the tools available on each LLM call,
+// making the dynamic expansion visible in the console output.
+// 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())
+    .GetChatClient(deploymentName)
+    .AsIChatClient()
+    .AsBuilder()
+    .Use(getResponseFunc: ToolLoggingMiddleware, getStreamingResponseFunc: ToolLoggingStreamingMiddleware)
+    .BuildAIAgent(
+        instructions: """
+            You are a helpful assistant. You start with limited tools.
+            When you need functionality that you don't currently have, call RequestTools with a description
+            of what you need. After new tools are loaded, use them to answer the user's question.
+            """,
+        tools: [requestToolsFunction]);
+
+// Run a conversation that triggers dynamic tool expansion.
+Console.WriteLine("=== Dynamic Function Tools Sample ===\n");
+
+string[] prompts =
+[
+    "What's the weather like in Seattle and London?",
+    "What time is it in New York?",
+    "Can you convert those temperatures to Celsius?"
+];
+
+// --- Non-Streaming Mode ---
+Console.ForegroundColor = ConsoleColor.Yellow;
+Console.WriteLine("=== Non-Streaming Mode ===");
+Console.ResetColor();
+Console.WriteLine();
+
+AgentSession session = await agent.CreateSessionAsync();
+
+foreach (var prompt in prompts)
+{
+    Console.ForegroundColor = ConsoleColor.Green;
+    Console.Write("[User] ");
+    Console.ResetColor();
+    Console.WriteLine(prompt);
+
+    var response = await agent.RunAsync(prompt, session);
+
+    // Print all message contents including tool calls, tool results, and text.
+    foreach (var message in response.Messages)
+    {
+        foreach (var content in message.Contents)
+        {
+            switch (content)
+            {
+                case FunctionCallContent functionCall:
+                    Console.ForegroundColor = ConsoleColor.Yellow;
+                    Console.WriteLine($"  [Tool Call] {functionCall.Name}({string.Join(", ", functionCall.Arguments?.Select(a => $"{a.Key}: {a.Value}") ?? [])})");
+                    Console.ResetColor();
+                    break;
+
+                case FunctionResultContent functionResult:
+                    Console.ForegroundColor = ConsoleColor.DarkYellow;
+                    Console.WriteLine($"  [Tool Result] {functionResult.CallId} => {functionResult.Result}");
+                    Console.ResetColor();
+                    break;
+
+                case TextContent textContent when !string.IsNullOrWhiteSpace(textContent.Text):
+                    Console.ForegroundColor = ConsoleColor.Cyan;
+                    Console.Write("[Agent] ");
+                    Console.ResetColor();
+                    Console.WriteLine(textContent.Text);
+                    break;
+            }
+        }
+    }
+
+    Console.WriteLine();
+}
+
+// --- Streaming Mode ---
+Console.ForegroundColor = ConsoleColor.Yellow;
+Console.WriteLine("=== Streaming Mode ===");
+Console.ResetColor();
+Console.WriteLine();
+
+AgentSession streamingSession = await agent.CreateSessionAsync();
+
+foreach (var prompt in prompts)
+{
+    Console.ForegroundColor = ConsoleColor.Green;
+    Console.Write("[User] ");
+    Console.ResetColor();
+    Console.WriteLine(prompt);
+
+    bool inAgentText = false;
+
+    await foreach (var update in agent.RunStreamingAsync(prompt, streamingSession))
+    {
+        foreach (var content in update.Contents)
+        {
+            switch (content)
+            {
+                case FunctionCallContent functionCall:
+                    if (inAgentText)
+                    {
+                        Console.WriteLine();
+                        inAgentText = false;
+                    }
+
+                    Console.ForegroundColor = ConsoleColor.Yellow;
+                    Console.WriteLine($"  [Tool Call] {functionCall.Name}({string.Join(", ", functionCall.Arguments?.Select(a => $"{a.Key}: {a.Value}") ?? [])})");
+                    Console.ResetColor();
+                    break;
+
+                case FunctionResultContent functionResult:
+                    Console.ForegroundColor = ConsoleColor.DarkYellow;
+                    Console.WriteLine($"  [Tool Result] {functionResult.CallId} => {functionResult.Result}");
+                    Console.ResetColor();
+                    break;
+
+                case TextContent textContent when !string.IsNullOrWhiteSpace(textContent.Text):
+                    if (!inAgentText)
+                    {
+                        Console.ForegroundColor = ConsoleColor.Cyan;
+                        Console.Write("[Agent] ");
+                        Console.ResetColor();
+                        inAgentText = true;
+                    }
+
+                    Console.Write(textContent.Text);
+                    break;
+            }
+        }
+    }
+
+    if (inAgentText)
+    {
+        Console.WriteLine();
+    }
+
+    Console.WriteLine();
+}
+
+// Chat client middleware that logs the number and names of tools on each LLM request.
+async Task<ChatResponse> ToolLoggingMiddleware(
+    IEnumerable<ChatMessage> messages,
+    ChatOptions? options,
+    IChatClient innerChatClient,
+    CancellationToken cancellationToken)
+{
+    LogTools(options);
+
+    return await innerChatClient.GetResponseAsync(messages, options, cancellationToken);
+}
+
+// Streaming version of the tool logging middleware.
+async IAsyncEnumerable<ChatResponseUpdate> ToolLoggingStreamingMiddleware(
+    IEnumerable<ChatMessage> messages,
+    ChatOptions? options,
+    IChatClient innerChatClient,
+    [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken)
+{
+    LogTools(options);
+
+    await foreach (var update in innerChatClient.GetStreamingResponseAsync(messages, options, cancellationToken))
+    {
+        yield return update;
+    }
+}
+
+// Shared helper to log the current tool set.
+void LogTools(ChatOptions? options)
+{
+    if (options?.Tools is { Count: > 0 } tools)
+    {
+        var toolNames = tools.OfType<AIFunction>().Select(t => t.Name);
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine($"  [Middleware] LLM call with {tools.Count} tool(s): {string.Join(", ", toolNames)}");
+        Console.ResetColor();
+    }
+    else
+    {
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine("  [Middleware] LLM call with 0 tools");
+        Console.ResetColor();
+    }
+}

dotnet/samples/02-agents/Agents/Agent_Step20_DynamicFunctionTools/README.md

@@ -0,0 +1,38 @@
+# Dynamic Function Tools
+
+This sample demonstrates how to dynamically expand the set of function tools available to an agent during a function-calling loop.
+
+## What it demonstrates
+
+- The agent starts with only a single `RequestTools` function
+- When the model needs capabilities it doesn't have, it calls `RequestTools` with a description of the functionality needed
+- The `RequestTools` function uses the ambient `FunctionInvokingChatClient.CurrentContext` to access `ChatOptions.Tools` and add new tools at runtime
+- The agent then uses the newly added tools in subsequent iterations of the same function-calling loop
+
+## How it works
+
+1. A tool catalog maps keywords (e.g. "weather", "time", "temperature") to pre-built `AIFunction` instances
+2. The `RequestTools` function matches the description against catalog keywords and adds matching tools to `ChatOptions.Tools`
+3. `FunctionInvokingChatClient` automatically picks up the new tools on the next iteration of its loop
+
+## Prerequisites
+
+- .NET 10 SDK or later
+- Azure OpenAI service endpoint and deployment configured
+- Azure CLI installed and authenticated (for Azure credential authentication)
+- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource
+
+## Running the sample
+
+Set the required environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
+```
+
+Run the sample:
+
+```powershell
+dotnet run
+```

dotnet/samples/02-agents/Agents/README.md

@@ -46,6 +46,7 @@ Before you begin, ensure you have the following prerequisites:
 |[Providing additional AI Context to an agent using multiple AIContextProviders](./Agent_Step17_AdditionalAIContext/)|This sample demonstrates how to inject additional AI context into a ChatClientAgent using multiple custom AIContextProvider components that are attached to the agent.|
 |[Using compaction pipeline with an agent](./Agent_Step18_CompactionPipeline/)|This sample demonstrates how to use a compaction pipeline to efficiently limit the size of the conversation history for an agent.|
 |[In-function-loop checkpointing](./Agent_Step19_InFunctionLoopCheckpointing/)|This sample demonstrates how to persist chat history after each service call during a tool-calling loop, enabling crash recovery and mid-run observability.|
+|[Dynamic function tools](./Agent_Step20_DynamicFunctionTools/)|This sample demonstrates how to dynamically expand the set of function tools available to an agent during a function-calling loop using the ambient FunctionInvocationContext.|
 
 ## Running the samples from the console
 

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/Agent_Step25_ToolboxServerSideTools.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/Program.cs

@@ -0,0 +1,148 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to load a Foundry toolbox and pass its tools as server-side
+// tools when creating an agent. The Foundry platform handles tool execution — the agent
+// process does not invoke tools locally.
+
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001 // Experimental API
+#pragma warning disable AAIP001  // AgentToolboxes is experimental
+#pragma warning disable CS8321   // Local functions may be commented-out alternatives
+
+// Replace with your own Foundry toolbox name.
+const string ToolboxName = "research_toolbox";
+// Used only by CombineToolboxes — swap in a second toolbox you own.
+const string SecondToolboxName = "analysis_toolbox";
+// Replace with any question that exercises the tools configured in your toolbox.
+const string Query = "Introduce yourself and briefly describe the tools you can use to help me.";
+
+string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
+    ?? throw new InvalidOperationException("Set FOUNDRY_PROJECT_ENDPOINT to your Foundry project endpoint.");
+string model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";
+
+// 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.
+var projectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());
+
+await Main(projectClient, model, endpoint);
+// await CombineToolboxes(projectClient, model, endpoint);
+
+// ---------------------------------------------------------------------------
+// Main: single toolbox
+// ---------------------------------------------------------------------------
+static async Task Main(AIProjectClient projectClient, string model, string endpoint)
+{
+    Console.WriteLine("=== Foundry Toolbox Server-Side Tools Example ===");
+
+    // Comment out if the toolbox already exists in your Foundry project.
+    await CreateSampleToolboxAsync(ToolboxName, endpoint);
+
+    // Omit the version to resolve the toolbox's current default version at runtime.
+    var tools = await projectClient.GetToolboxToolsAsync(ToolboxName);
+
+    AIAgent agent = projectClient
+        .AsAIAgent(
+            model: model,
+            instructions: "You are a research assistant. Use the available tools to answer questions.",
+            tools: tools.ToList());
+
+    Console.WriteLine($"User: {Query}");
+    Console.WriteLine($"Result: {await agent.RunAsync(Query)}\n");
+}
+
+// ---------------------------------------------------------------------------
+// Alternative: combine tools from multiple toolboxes
+// ---------------------------------------------------------------------------
+static async Task CombineToolboxes(AIProjectClient projectClient, string model, string endpoint)
+{
+    Console.WriteLine("=== Combine Toolboxes Example ===");
+
+    // Comment out if the toolboxes already exist in your Foundry project.
+    await CreateSampleToolboxAsync(ToolboxName, endpoint);
+    await CreateSampleToolboxAsync(SecondToolboxName, endpoint);
+
+    var toolboxA = await projectClient.GetToolboxToolsAsync(ToolboxName);
+    var toolboxB = await projectClient.GetToolboxToolsAsync(SecondToolboxName);
+
+    var allTools = toolboxA.Concat(toolboxB).ToList();
+
+    AIAgent agent = projectClient
+        .AsAIAgent(
+            model: model,
+            instructions: "You are a research assistant. Use all available tools to answer questions.",
+            tools: allTools);
+
+    Console.WriteLine($"User: {Query}");
+    Console.WriteLine($"Combined-toolbox result: {await agent.RunAsync(Query)}\n");
+}
+
+// ---------------------------------------------------------------------------
+// Helper: create (or replace) a sample toolbox so the sample works out-of-the-box
+// ---------------------------------------------------------------------------
+static async Task CreateSampleToolboxAsync(string name, string endpoint)
+{
+    // Toolboxes are normally configured in the Foundry portal or a deployment
+    // script, not the application itself. This helper exists so the sample can
+    // be run end-to-end without first setting a toolbox up by hand.
+
+    // The Foundry-Features header is currently required for toolbox CRUD operations.
+    var options = new AgentAdministrationClientOptions();
+    options.AddPolicy(new FoundryFeaturesPolicy("Toolboxes=V1Preview"), PipelinePosition.PerCall);
+    var adminClient = new AgentAdministrationClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential(),
+        options);
+    var toolboxClient = adminClient.GetAgentToolboxes();
+
+    // Delete existing toolbox if present (ignore 404).
+    try
+    {
+        await toolboxClient.DeleteToolboxAsync(name);
+        Console.WriteLine($"Deleted existing toolbox '{name}'");
+    }
+    catch (ClientResultException ex) when (ex.Status == 404)
+    {
+        // Toolbox does not exist — nothing to delete.
+    }
+
+    // Create a fresh version with a single MCP tool.
+    ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
+        serverLabel: "api-specs",
+        serverUri: new Uri("https://gitmcp.io/Azure/azure-rest-api-specs"),
+        toolCallApprovalPolicy: new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval)));
+
+    var created = (await toolboxClient.CreateToolboxVersionAsync(
+        name: name,
+        tools: [mcpTool],
+        description: "Sample toolbox with an MCP tool — created by Agent_Step25 sample.")).Value;
+
+    Console.WriteLine($"Created toolbox '{created.Name}' v{created.Version} ({created.Tools.Count} tool(s))");
+}
+
+// ---------------------------------------------------------------------------
+// Pipeline policy that adds the Foundry-Features header for toolbox CRUD
+// ---------------------------------------------------------------------------
+internal sealed class FoundryFeaturesPolicy(string feature) : PipelinePolicy
+{
+    private const string FeatureHeader = "Foundry-Features";
+
+    public override void Process(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        message.Request.Headers.Add(FeatureHeader, feature);
+        ProcessNext(message, pipeline, currentIndex);
+    }
+
+    public override ValueTask ProcessAsync(PipelineMessage message, IReadOnlyList<PipelinePolicy> pipeline, int currentIndex)
+    {
+        message.Request.Headers.Add(FeatureHeader, feature);
+        return ProcessNextAsync(message, pipeline, currentIndex);
+    }
+}

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/README.md

@@ -0,0 +1,46 @@
+# Agent_Step25_ToolboxServerSideTools
+
+This sample demonstrates loading a named Foundry toolbox and passing its tools as
+**server-side tools** when creating an agent via `AsAIAgent()`.
+
+When tools from a toolbox are passed this way, they are sent as tool definitions in
+the Responses API request. The Foundry platform handles tool execution — the agent
+process does not invoke tools locally.
+
+This is the dotnet equivalent of the Python sample:
+`python/samples/02-agents/providers/foundry/foundry_chat_client_with_toolbox.py`
+
+## Prerequisites
+
+- A Microsoft Foundry project
+- `AZURE_AI_PROJECT_ENDPOINT` environment variable set to your Foundry project endpoint
+- `AZURE_AI_MODEL_DEPLOYMENT_NAME` environment variable set (defaults to `gpt-5.4-mini`)
+
+The sample recreates the toolbox on each run, replacing any existing toolbox with
+the same name. Comment out the `CreateSampleToolboxAsync` call if you want to keep
+an existing toolbox unchanged.
+
+## How it works
+
+1. `projectClient.GetToolboxVersionAsync(name)` fetches the toolbox definition from the
+   Foundry project API (resolving the default version if none is specified)
+2. `ToolboxVersion.ToAITools()` converts each tool definition to an `AITool` instance
+3. The tools are passed to `AsAIAgent(tools: ...)` which includes them in the Responses
+   API request as server-side tool definitions
+
+For a one-liner, use `projectClient.GetToolboxToolsAsync(name)` to fetch and convert in one call.
+
+## Sample flows
+
+| Flow | Description |
+|------|-------------|
+| `Main` (default) | Loads a single toolbox and runs an agent with its tools |
+| `CombineToolboxes` | Loads two toolboxes and merges their tools into one agent |
+
+Uncomment the desired flow in the top-level statements to try each one.
+
+## Running the sample
+
+```bash
+dotnet run
+```

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/01_SequentialWorkflow/README.md

@@ -65,6 +65,53 @@ Workflow orchestration started for CancelOrder. Orchestration runId: abc123def45
 >
 > If not provided, a unique run ID is auto-generated.
 
+### Wait for the Workflow Result
+
+By default, the HTTP endpoint returns `202 Accepted` immediately with the run ID. If you want to wait for the workflow to complete and get the result in the response, add the `x-ms-wait-for-response: true` header:
+
+Bash (Linux/macOS/WSL):
+
+```bash
+curl -X POST http://localhost:7071/api/workflows/CancelOrder/run \
+    -H "Content-Type: text/plain" \
+    -H "x-ms-wait-for-response: true" \
+    -d "12345"
+```
+
+PowerShell:
+
+```powershell
+Invoke-RestMethod -Method Post `
+    -Uri http://localhost:7071/api/workflows/CancelOrder/run `
+    -ContentType text/plain `
+    -Headers @{ "x-ms-wait-for-response" = "true" } `
+    -Body "12345"
+```
+
+The response will contain the workflow result as plain text (200 OK):
+
+```text
+Cancellation email sent for order 12345 to jerry@example.com.
+```
+
+To get the result as JSON, also include the `Accept: application/json` header:
+
+```bash
+curl -X POST http://localhost:7071/api/workflows/CancelOrder/run \
+    -H "Content-Type: text/plain" \
+    -H "x-ms-wait-for-response: true" \
+    -H "Accept: application/json" \
+    -d "12345"
+```
+
+```json
+{
+    "runId": "abc123def456",
+    "workflowStatus": "Completed",
+    "result": "Cancellation email sent for order 12345 to jerry@example.com."
+}
+```
+
 In the function app logs, you will see the sequential execution of each executor:
 
 ```text

dotnet/samples/04-hosting/DurableWorkflows/AzureFunctions/01_SequentialWorkflow/demo.http

@@ -7,6 +7,21 @@ Content-Type: text/plain
 
 12345
 
+### Cancel an order and wait for the result
+POST {{authority}}/api/workflows/CancelOrder/run
+Content-Type: text/plain
+x-ms-wait-for-response: true
+
+12345
+
+### Cancel an order and wait for the result (JSON response)
+POST {{authority}}/api/workflows/CancelOrder/run
+Content-Type: text/plain
+Accept: application/json
+x-ms-wait-for-response: true
+
+12345
+
 ### Cancel an order with a custom run ID
 POST {{authority}}/api/workflows/CancelOrder/run?runId=my-custom-id-123
 Content-Type: text/plain
@@ -19,6 +34,13 @@ Content-Type: text/plain
 
 12345
 
+### Get order status and wait for the result
+POST {{authority}}/api/workflows/OrderStatus/run
+Content-Type: text/plain
+x-ms-wait-for-response: true
+
+12345
+
 ### Batch cancel orders with a complex JSON input
 POST {{authority}}/api/workflows/BatchCancelOrders/run
 Content-Type: application/json

dotnet/samples/04-hosting/FoundryHostedAgents/invocations/Hosted-Invocations-EchoAgent/Hosted-Invocations-EchoAgent.csproj

@@ -13,6 +13,8 @@
   <ItemGroup>
     <PackageReference Include="Azure.AI.AgentServer.Invocations" />
     <PackageReference Include="DotNetEnv" />
+    <PackageReference Include="OpenTelemetry.Api" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
   </ItemGroup>
 
   <!-- For contributors: uses ProjectReference to build against local source -->

dotnet/src/Aspire.Hosting.AgentFramework.DevUI/Aspire.Hosting.AgentFramework.DevUI.csproj

@@ -2,14 +2,22 @@
 
   <PropertyGroup>
     <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
-    <IsPackable>true</IsPackable>
-    <PackageTags>aspire integration hosting agent-framework devui ai agents</PackageTags>
-    <Description>Microsoft Agent Framework DevUI support for Aspire.</Description>
+    <VersionSuffix>preview</VersionSuffix>
     <!-- Suppress analyzer warnings for Aspire integration code -->
     <!-- IL2026/IL3050: Suppress trimming/AOT warnings - DevUI is a dev-only tool not intended for AOT -->
     <NoWarn>$(NoWarn);CA1873;RCS1061;VSTHRD002;IL2026;IL3050</NoWarn>
   </PropertyGroup>
 
+  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
+
+  <PropertyGroup>
+    <!-- NuGet Package Settings -->
+    <Title>Microsoft Agent Framework DevUI for Aspire</Title>
+    <PackageTags>aspire integration hosting agent-framework devui ai agents</PackageTags>
+    <Description>Microsoft Agent Framework DevUI support for Aspire.</Description>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+  </PropertyGroup>
+
   <ItemGroup>
     <InternalsVisibleTo Include="Aspire.Hosting.AgentFramework.DevUI.UnitTests" />
   </ItemGroup>
@@ -22,4 +30,7 @@
     <PackageReference Include="Aspire.Hosting" />
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="/" />
+  </ItemGroup>
 </Project>

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/AIProjectClientToolboxExtensions.cs

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+#pragma warning disable OPENAI001
+#pragma warning disable AAIP001 // AgentToolboxes is experimental in Azure.AI.Projects.Agents
+
+namespace Azure.AI.Projects;
+
+/// <summary>
+/// Provides extension methods on <see cref="AIProjectClient"/> for fetching
+/// Foundry toolbox definitions as server-side tools.
+/// </summary>
+/// <remarks>
+/// These extensions mirror Python's <c>FoundryChatClient.get_toolbox()</c> pattern,
+/// allowing a single call on the project client to retrieve tools ready for use
+/// with <c>AsAIAgent(model, instructions, tools: ...)</c>.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public static class AIProjectClientToolboxExtensions
+{
+    /// <summary>
+    /// Fetches a toolbox from the Foundry project and returns its tools as <see cref="AITool"/> instances
+    /// ready for use as server-side tools in the Responses API.
+    /// </summary>
+    /// <param name="projectClient">The <see cref="AIProjectClient"/> to use. Cannot be <see langword="null"/>.</param>
+    /// <param name="name">The name of the toolbox to fetch.</param>
+    /// <param name="version">
+    /// The specific toolbox version to fetch. When <see langword="null"/>, the toolbox's
+    /// default version is resolved automatically.
+    /// </param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A read-only list of <see cref="AITool"/> instances from the toolbox.</returns>
+    /// <exception cref="System.ArgumentNullException">
+    /// Thrown when <paramref name="projectClient"/> or <paramref name="name"/> is <see langword="null"/>.
+    /// </exception>
+    public static async Task<IReadOnlyList<AITool>> GetToolboxToolsAsync(
+        this AIProjectClient projectClient,
+        string name,
+        string? version = null,
+        CancellationToken cancellationToken = default)
+    {
+        Throw.IfNull(projectClient);
+        Throw.IfNullOrWhitespace(name);
+
+        var toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();
+        var toolboxVersion = await FoundryToolbox.GetToolboxVersionCoreAsync(toolboxClient, name, version, cancellationToken).ConfigureAwait(false);
+        return toolboxVersion.ToAITools();
+    }
+}

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/FoundryToolbox.cs

@@ -0,0 +1,223 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Text.Json.Nodes;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.AI.Projects.Agents;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+using OpenAI.Responses;
+
+#pragma warning disable OPENAI001
+#pragma warning disable AAIP001 // AgentToolboxes is experimental in Azure.AI.Projects.Agents
+#pragma warning disable IL2026 // ModelReaderWriter.Read<ResponseTool> uses reflection; suppressed for Azure SDK model types.
+#pragma warning disable IL3050 // ModelReaderWriter.Read<ResponseTool> requires dynamic code; suppressed for Azure SDK model types.
+
+namespace Microsoft.Agents.AI.Foundry.Hosting;
+
+/// <summary>
+/// Provides methods for fetching Foundry toolbox definitions and converting their tools
+/// to <see cref="AITool"/> instances for use as server-side tools in the Responses API.
+/// </summary>
+/// <remarks>
+/// <para>
+/// When tools from a toolbox are passed to a Foundry agent (e.g. via <c>AsAIAgent(model, instructions, tools: ...)</c>),
+/// they are sent as server-side tool definitions in the Responses API request. The Foundry platform
+/// handles tool execution — the agent process does not invoke tools locally.
+/// </para>
+/// <para>
+/// This is the dotnet equivalent of Python's <c>FoundryChatClient.get_toolbox()</c> pattern.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
+public static class FoundryToolbox
+{
+    /// <summary>
+    /// Fetches a toolbox version from the Foundry project and returns the raw SDK <see cref="ToolboxVersion"/>.
+    /// </summary>
+    /// <param name="projectEndpoint">The Foundry project endpoint URI.</param>
+    /// <param name="credential">The authentication credential used to access the Foundry project.</param>
+    /// <param name="name">The name of the toolbox to fetch.</param>
+    /// <param name="version">
+    /// The specific toolbox version to fetch. When <see langword="null"/>, the toolbox's
+    /// default version is resolved automatically (requires an additional API call).
+    /// </param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>The <see cref="ToolboxVersion"/> containing tool definitions.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="projectEndpoint"/>, <paramref name="credential"/>, or <paramref name="name"/> is <see langword="null"/>.
+    /// </exception>
+    /// <exception cref="ClientResultException">Thrown when the Foundry project API returns an error.</exception>
+    public static async Task<ToolboxVersion> GetToolboxVersionAsync(
+        Uri projectEndpoint,
+        AuthenticationTokenProvider credential,
+        string name,
+        string? version = null,
+        CancellationToken cancellationToken = default)
+    {
+        Throw.IfNull(projectEndpoint);
+        Throw.IfNull(credential);
+        Throw.IfNullOrWhitespace(name);
+
+        var toolboxClient = CreateToolboxClient(projectEndpoint, credential);
+        return await GetToolboxVersionCoreAsync(toolboxClient, name, version, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Fetches a toolbox from the Foundry project and returns its tools as <see cref="AITool"/> instances
+    /// ready for use as server-side tools in the Responses API.
+    /// </summary>
+    /// <param name="projectEndpoint">The Foundry project endpoint URI.</param>
+    /// <param name="credential">The authentication credential used to access the Foundry project.</param>
+    /// <param name="name">The name of the toolbox to fetch.</param>
+    /// <param name="version">
+    /// The specific toolbox version to fetch. When <see langword="null"/>, the toolbox's
+    /// default version is resolved automatically.
+    /// </param>
+    /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+    /// <returns>A read-only list of <see cref="AITool"/> instances from the toolbox.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="projectEndpoint"/>, <paramref name="credential"/>, or <paramref name="name"/> is <see langword="null"/>.
+    /// </exception>
+    /// <exception cref="ClientResultException">Thrown when the Foundry project API returns an error.</exception>
+    public static async Task<IReadOnlyList<AITool>> GetToolsAsync(
+        Uri projectEndpoint,
+        AuthenticationTokenProvider credential,
+        string name,
+        string? version = null,
+        CancellationToken cancellationToken = default)
+    {
+        var toolboxVersion = await GetToolboxVersionAsync(projectEndpoint, credential, name, version, cancellationToken).ConfigureAwait(false);
+        return toolboxVersion.ToAITools();
+    }
+
+    /// <summary>
+    /// Converts the tools in a <see cref="ToolboxVersion"/> to <see cref="AITool"/> instances
+    /// suitable for use as server-side tools in the Responses API.
+    /// </summary>
+    /// <param name="toolboxVersion">The toolbox version whose tools to convert.</param>
+    /// <returns>A read-only list of <see cref="AITool"/> instances.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="toolboxVersion"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <para>
+    /// Each <see cref="ProjectsAgentTool"/> in the toolbox is cast to <see cref="ResponseTool"/>
+    /// and converted via <c>AsAITool()</c>. Non-function hosted tools (MCP, web_search,
+    /// code_interpreter, etc.) are included as server-side tool definitions — the Foundry
+    /// platform handles their execution.
+    /// </para>
+    /// <para>
+    /// Non-function tools are sanitized to remove decoration fields (<c>name</c>, <c>description</c>)
+    /// that the toolbox API returns but the Responses API rejects.
+    /// </para>
+    /// </remarks>
+    public static IReadOnlyList<AITool> ToAITools(this ToolboxVersion toolboxVersion)
+    {
+        Throw.IfNull(toolboxVersion);
+
+        if (toolboxVersion.Tools?.Any() != true)
+        {
+            return [];
+        }
+
+        return toolboxVersion.Tools
+            .Select(SanitizeAndConvert)
+            .ToList();
+    }
+
+    #region Internal helpers (visible to unit tests via InternalsVisibleTo)
+
+    /// <summary>
+    /// Sanitizes a <see cref="ProjectsAgentTool"/> by removing decoration fields that the
+    /// toolbox API returns but the Responses API rejects, then converts to <see cref="AITool"/>.
+    /// </summary>
+    /// <remarks>
+    /// The Azure AI Projects toolbox API may return <c>name</c> and <c>description</c> on
+    /// hosted tool objects (MCP, code_interpreter, file_search, etc.). The Responses API
+    /// rejects at least <c>name</c> with "Unknown parameter: 'tools[0].name'". We strip
+    /// these decoration fields for non-function tools. Function tools keep them since
+    /// <c>name</c> and <c>description</c> are expected parts of the function schema.
+    /// </remarks>
+    internal static AITool SanitizeAndConvert(ProjectsAgentTool tool)
+    {
+        var toolJson = ModelReaderWriter.Write(tool, new ModelReaderWriterOptions("J"));
+        var node = JsonNode.Parse(toolJson.ToString());
+        if (node is not JsonObject obj)
+        {
+            return ((ResponseTool)tool).AsAITool();
+        }
+
+        var toolType = obj["type"]?.GetValue<string>();
+
+        // Function tools need name/description — don't strip
+        if (toolType is "function" or "custom")
+        {
+            return ((ResponseTool)tool).AsAITool();
+        }
+
+        // Strip decoration fields that the Responses API rejects
+        bool modified = false;
+        modified |= obj.Remove("name");
+        modified |= obj.Remove("description");
+
+        if (!modified)
+        {
+            return ((ResponseTool)tool).AsAITool();
+        }
+
+        var sanitizedJson = obj.ToJsonString();
+        var sanitizedTool = ModelReaderWriter.Read<ResponseTool>(BinaryData.FromString(sanitizedJson))!;
+        return sanitizedTool.AsAITool();
+    }
+
+    internal static async Task<ToolboxVersion> GetToolboxVersionAsync(
+        Uri projectEndpoint,
+        AuthenticationTokenProvider credential,
+        string name,
+        string? version,
+        AgentAdministrationClientOptions? clientOptions,
+        CancellationToken cancellationToken)
+    {
+        Throw.IfNull(projectEndpoint);
+        Throw.IfNull(credential);
+        Throw.IfNullOrWhitespace(name);
+
+        var toolboxClient = CreateToolboxClient(projectEndpoint, credential, clientOptions);
+        return await GetToolboxVersionCoreAsync(toolboxClient, name, version, cancellationToken).ConfigureAwait(false);
+    }
+
+    internal static AgentToolboxes CreateToolboxClient(
+        Uri projectEndpoint,
+        AuthenticationTokenProvider credential,
+        AgentAdministrationClientOptions? clientOptions = null)
+    {
+        clientOptions ??= new AgentAdministrationClientOptions();
+        var adminClient = new AgentAdministrationClient(projectEndpoint, credential, clientOptions);
+        return adminClient.GetAgentToolboxes();
+    }
+
+    internal static async Task<ToolboxVersion> GetToolboxVersionCoreAsync(
+        AgentToolboxes toolboxClient,
+        string name,
+        string? version,
+        CancellationToken cancellationToken)
+    {
+        if (version is null)
+        {
+            var record = await toolboxClient.GetToolboxAsync(name, cancellationToken).ConfigureAwait(false);
+            version = record.Value.DefaultVersion
+                ?? throw new InvalidOperationException($"Toolbox '{name}' does not have a default version. Specify an explicit version.");
+        }
+
+        var result = await toolboxClient.GetToolboxVersionAsync(name, version, cancellationToken).ConfigureAwait(false);
+        return result.Value;
+    }
+
+    #endregion
+}

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/InputConverter.cs

@@ -237,7 +237,7 @@ internal static class InputConverter
         {
             OutputItemMessage msg => ConvertOutputItemMessageToChat(msg),
             OutputItemFunctionToolCall funcCall => ConvertOutputItemFunctionCall(funcCall),
-            FunctionToolCallOutputResource funcOutput => ConvertFunctionToolCallOutputResource(funcOutput),
+            OutputItemFunctionToolCallOutput funcOutput => ConvertFunctionToolCallOutput(funcOutput),
             OutputItemReasoningItem => null,
             _ => null
         };
@@ -332,7 +332,7 @@ internal static class InputConverter
             [new FunctionCallContent(funcCall.CallId, funcCall.Name, arguments)]);
     }
 
-    private static ChatMessage ConvertFunctionToolCallOutputResource(FunctionToolCallOutputResource funcOutput)
+    private static ChatMessage ConvertFunctionToolCallOutput(OutputItemFunctionToolCallOutput funcOutput)
     {
         return new ChatMessage(
             ChatRole.Tool,

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/Microsoft.Agents.AI.Foundry.Hosting.csproj

@@ -34,6 +34,7 @@
     <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="ModelContextProtocol" />
+    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
   </ItemGroup>
 
   <ItemGroup>

dotnet/src/Microsoft.Agents.AI.Foundry.Hosting/OutputConverter.cs

@@ -251,16 +251,25 @@ internal static class OutputConverter
         var outputTokens = details.OutputTokenCount ?? 0;
         var totalTokens = details.TotalTokenCount ?? 0;
 
+        var cachedTokens = details.AdditionalCounts?.TryGetValue("InputTokenDetails.CachedTokenCount", out var cached) ?? false
+            ? cached : 0;
+        var reasoningTokens = details.AdditionalCounts?.TryGetValue("OutputTokenDetails.ReasoningTokenCount", out var reasoning) ?? false
+            ? reasoning : 0;
+
         if (existing is not null)
         {
             inputTokens += existing.InputTokens;
             outputTokens += existing.OutputTokens;
             totalTokens += existing.TotalTokens;
+            cachedTokens += existing.InputTokensDetails?.CachedTokens ?? 0;
+            reasoningTokens += existing.OutputTokensDetails?.ReasoningTokens ?? 0;
         }
 
-        return AzureAIAgentServerResponsesModelFactory.ResponseUsage(
+        return new ResponseUsage(
             inputTokens: inputTokens,
+            inputTokensDetails: new ResponseUsageInputTokensDetails(cachedTokens),
             outputTokens: outputTokens,
+            outputTokensDetails: new ResponseUsageOutputTokensDetails(reasoningTokens),
             totalTokens: totalTokens);
     }
 

dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AAgentHandler.cs

@@ -42,11 +42,19 @@ internal sealed class A2AAgentHandler : IAgentHandler
     /// <inheritdoc/>
     public Task ExecuteAsync(RequestContext context, AgentEventQueue eventQueue, CancellationToken cancellationToken)
     {
+        // Handle task updates
         if (context.IsContinuation)
         {
             return this.HandleTaskUpdateAsync(context, eventQueue, cancellationToken);
         }
 
+        // Handle messages received via streaming endpoint
+        if (context.StreamingResponse)
+        {
+            return this.HandleNewMessageStreamingAsync(context, eventQueue, cancellationToken);
+        }
+
+        // Handle new messages received via non-streaming endpoint
         return this.HandleNewMessageAsync(context, eventQueue, cancellationToken);
     }
 
@@ -80,13 +88,19 @@ internal sealed class A2AAgentHandler : IAgentHandler
             ? new AgentRunOptions { AllowBackgroundResponses = allowBackgroundResponses }
             : new AgentRunOptions { AllowBackgroundResponses = allowBackgroundResponses, AdditionalProperties = context.Metadata.ToAdditionalProperties() };
 
-        var response = await this._hostAgent.RunAsync(
-            chatMessages,
-            session: session,
-            options: options,
-            cancellationToken: cancellationToken).ConfigureAwait(false);
-
-        await this._hostAgent.SaveSessionAsync(contextId, session, cancellationToken).ConfigureAwait(false);
+        AgentResponse response;
+        try
+        {
+            response = await this._hostAgent.RunAsync(
+                chatMessages,
+                session: session,
+                options: options,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+        finally
+        {
+            await this._hostAgent.SaveSessionAsync(contextId, session, CancellationToken.None).ConfigureAwait(false);
+        }
 
         if (response.ContinuationToken is null)
         {
@@ -108,6 +122,39 @@ internal sealed class A2AAgentHandler : IAgentHandler
         }
     }
 
+    private async Task HandleNewMessageStreamingAsync(RequestContext context, AgentEventQueue eventQueue, CancellationToken cancellationToken)
+    {
+        var contextId = context.ContextId ?? Guid.NewGuid().ToString("N");
+        var session = await this._hostAgent.GetOrCreateSessionAsync(contextId, cancellationToken).ConfigureAwait(false);
+
+        // AIAgent does not support resuming from arbitrary prior tasks.
+        // Throw explicitly so the client gets a clear error rather than a response
+        // that silently ignores the referenced task context.
+        if (context.Message?.ReferenceTaskIds is { Count: > 0 })
+        {
+            throw new NotSupportedException("ReferenceTaskIds is not supported. AIAgent cannot resume from arbitrary prior task context.");
+        }
+
+        List<ChatMessage> chatMessages = context.Message is not null ? [context.Message.ToChatMessage()] : [];
+
+        var options = context.Metadata is { Count: > 0 }
+            ? new AgentRunOptions { AdditionalProperties = context.Metadata.ToAdditionalProperties() }
+            : null;
+
+        try
+        {
+            await foreach (var update in this._hostAgent.RunStreamingAsync(chatMessages, session, options, cancellationToken).ConfigureAwait(false))
+            {
+                var message = CreateMessageFromUpdate(contextId, update);
+                await eventQueue.EnqueueMessageAsync(message, cancellationToken).ConfigureAwait(false);
+            }
+        }
+        finally
+        {
+            await this._hostAgent.SaveSessionAsync(contextId, session, CancellationToken.None).ConfigureAwait(false);
+        }
+    }
+
     private async Task HandleTaskUpdateAsync(RequestContext context, AgentEventQueue eventQueue, CancellationToken cancellationToken)
     {
         var contextId = context.ContextId ?? Guid.NewGuid().ToString("N");
@@ -141,8 +188,10 @@ internal sealed class A2AAgentHandler : IAgentHandler
             await failUpdater.FailAsync(message: null, CancellationToken.None).ConfigureAwait(false);
             throw;
         }
-
-        await this._hostAgent.SaveSessionAsync(contextId, session, cancellationToken).ConfigureAwait(false);
+        finally
+        {
+            await this._hostAgent.SaveSessionAsync(contextId, session, CancellationToken.None).ConfigureAwait(false);
+        }
 
         if (response.ContinuationToken is null)
         {
@@ -174,6 +223,16 @@ internal sealed class A2AAgentHandler : IAgentHandler
             Metadata = response.AdditionalProperties?.ToA2AMetadata()
         };
 
+    private static Message CreateMessageFromUpdate(string contextId, AgentResponseUpdate update) =>
+        new()
+        {
+            MessageId = update.ResponseId ?? Guid.NewGuid().ToString("N"),
+            ContextId = contextId,
+            Role = Role.Agent,
+            Parts = update.ToParts(),
+            Metadata = update.AdditionalProperties?.ToA2AMetadata()
+        };
+
     private static List<ChatMessage> ExtractChatMessagesFromTaskHistory(AgentTask? agentTask)
     {
         if (agentTask?.History is not { Count: > 0 })

dotnet/src/Microsoft.Agents.AI.Hosting.A2A/Converters/MessageConverter.cs

@@ -8,6 +8,26 @@ namespace Microsoft.Agents.AI.Hosting.A2A.Converters;
 
 internal static class MessageConverter
 {
+    public static List<Part> ToParts(this AgentResponseUpdate update)
+    {
+        if (update is null || update.Contents is not { Count: > 0 })
+        {
+            return [];
+        }
+
+        var parts = new List<Part>();
+        foreach (var content in update.Contents)
+        {
+            var part = content.ToPart();
+            if (part is not null)
+            {
+                parts.Add(part);
+            }
+        }
+
+        return parts;
+    }
+
     public static List<Part> ToParts(this IList<ChatMessage> chatMessages)
     {
         if (chatMessages is null || chatMessages.Count == 0)

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/BuiltInFunctions.cs

@@ -21,6 +21,8 @@ internal static class BuiltInFunctions
     internal const string HttpPrefix = "http-";
     internal const string McpToolPrefix = "mcptool-";
 
+    private const string WaitForResponseHeaderName = "x-ms-wait-for-response";
+
     internal static readonly string RunAgentHttpFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(RunAgentHttpAsync)}";
     internal static readonly string RunAgentEntityFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(InvokeAgentAsync)}";
     internal static readonly string RunAgentMcpToolFunctionEntryPoint = $"{typeof(BuiltInFunctions).FullName!}.{nameof(RunMcpToolAsync)}";
@@ -62,6 +64,11 @@ internal static class BuiltInFunctions
         StartOrchestrationOptions? options = instanceId is not null ? new StartOrchestrationOptions(instanceId) : null;
         string resolvedInstanceId = await client.ScheduleNewOrchestrationInstanceAsync(orchestrationFunctionName, orchestrationInput, options);
 
+        if (ShouldWaitForResponse(req, defaultValue: false))
+        {
+            return await WaitForWorkflowCompletionAsync(req, client, context, resolvedInstanceId);
+        }
+
         HttpResponseData response = req.CreateResponse(HttpStatusCode.Accepted);
         await response.WriteStringAsync($"Workflow orchestration started for {workflowName}. Orchestration runId: {resolvedInstanceId}");
         return response;
@@ -304,15 +311,7 @@ internal static class BuiltInFunctions
         }
 
         // Check if we should wait for response (default is true)
-        bool waitForResponse = true;
-        if (req.Headers.TryGetValues("x-ms-wait-for-response", out IEnumerable<string>? waitForResponseValues))
-        {
-            string? waitForResponseValue = waitForResponseValues.FirstOrDefault();
-            if (!string.IsNullOrEmpty(waitForResponseValue) && bool.TryParse(waitForResponseValue, out bool parsedValue))
-            {
-                waitForResponse = parsedValue;
-            }
-        }
+        bool waitForResponse = ShouldWaitForResponse(req, defaultValue: true);
 
         AIAgent agentProxy = client.AsDurableAgentProxy(context, agentName);
 
@@ -428,6 +427,95 @@ internal static class BuiltInFunctions
         return metadata.ReadOutputAs<DurableWorkflowResult>()?.Result;
     }
 
+    /// <summary>
+    /// Waits for a workflow orchestration to complete and returns an appropriate HTTP response.
+    /// </summary>
+    private static async Task<HttpResponseData> WaitForWorkflowCompletionAsync(
+        HttpRequestData req,
+        DurableTaskClient client,
+        FunctionContext context,
+        string instanceId)
+    {
+        bool acceptsJson = AcceptsJson(req);
+
+        OrchestrationMetadata? metadata = await client.WaitForInstanceCompletionAsync(
+            instanceId,
+            getInputsAndOutputs: true,
+            cancellation: context.CancellationToken);
+
+        if (metadata is null)
+        {
+            return await CreateErrorResponseAsync(req, context, HttpStatusCode.NotFound,
+                $"No workflow orchestration with ID '{instanceId}' was found.", acceptsJson);
+        }
+
+        if (metadata.RuntimeStatus is OrchestrationRuntimeStatus.Failed)
+        {
+            string errorMessage = metadata.FailureDetails?.ErrorMessage ?? "Unknown error";
+            HttpResponseData failedResponse = req.CreateResponse(HttpStatusCode.OK);
+
+            if (acceptsJson)
+            {
+                await failedResponse.WriteAsJsonAsync(
+                    new WorkflowRunResponse(instanceId, metadata.RuntimeStatus.ToString(), Result: null, Error: errorMessage),
+                    context.CancellationToken);
+            }
+            else
+            {
+                failedResponse.Headers.Add("Content-Type", "text/plain");
+                await failedResponse.WriteStringAsync(errorMessage, context.CancellationToken);
+            }
+
+            return failedResponse;
+        }
+
+        if (metadata.RuntimeStatus is not OrchestrationRuntimeStatus.Completed)
+        {
+            return await CreateErrorResponseAsync(req, context, HttpStatusCode.InternalServerError,
+                $"Workflow orchestration '{instanceId}' ended with unexpected status '{metadata.RuntimeStatus}'.", acceptsJson);
+        }
+
+        string? result = metadata.ReadOutputAs<DurableWorkflowResult>()?.Result;
+
+        HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
+
+        if (acceptsJson)
+        {
+            JsonElement? resultElement = null;
+            if (!string.IsNullOrEmpty(result))
+            {
+                try
+                {
+                    using JsonDocument doc = JsonDocument.Parse(result);
+                    resultElement = doc.RootElement.Clone();
+                }
+                catch (JsonException)
+                {
+                    // Result is a plain string (not valid JSON) — serialize it as a JSON string element.
+                    var buffer = new System.Buffers.ArrayBufferWriter<byte>();
+                    using (var writer = new Utf8JsonWriter(buffer))
+                    {
+                        writer.WriteStringValue(result);
+                    }
+
+                    using JsonDocument fallbackDoc = JsonDocument.Parse(buffer.WrittenMemory);
+                    resultElement = fallbackDoc.RootElement.Clone();
+                }
+            }
+
+            await response.WriteAsJsonAsync(
+                new WorkflowRunResponse(instanceId, metadata.RuntimeStatus.ToString(), resultElement),
+                context.CancellationToken);
+        }
+        else
+        {
+            response.Headers.Add("Content-Type", "text/plain");
+            await response.WriteStringAsync(result ?? string.Empty, context.CancellationToken);
+        }
+
+        return response;
+    }
+
     /// <summary>
     /// Creates an error response with the specified status code and error message.
     /// </summary>
@@ -435,18 +523,18 @@ internal static class BuiltInFunctions
     /// <param name="context">The function context.</param>
     /// <param name="statusCode">The HTTP status code.</param>
     /// <param name="errorMessage">The error message.</param>
+    /// <param name="acceptsJson">Optional pre-computed value indicating whether the client accepts JSON. When <see langword="null"/>, the value is determined from the request's <c>Accept</c> header.</param>
     /// <returns>The HTTP response data containing the error.</returns>
     private static async Task<HttpResponseData> CreateErrorResponseAsync(
         HttpRequestData req,
         FunctionContext context,
         HttpStatusCode statusCode,
-        string errorMessage)
+        string errorMessage,
+        bool? acceptsJson = null)
     {
         HttpResponseData response = req.CreateResponse(statusCode);
-        bool acceptsJson = req.Headers.TryGetValues("Accept", out IEnumerable<string>? acceptValues) &&
-            acceptValues.Contains("application/json", StringComparer.OrdinalIgnoreCase);
 
-        if (acceptsJson)
+        if (acceptsJson ?? AcceptsJson(req))
         {
             ErrorResponse errorResponse = new((int)statusCode, errorMessage);
             await response.WriteAsJsonAsync(errorResponse, context.CancellationToken);
@@ -479,10 +567,7 @@ internal static class BuiltInFunctions
         HttpResponseData response = req.CreateResponse(statusCode);
         response.Headers.Add("x-ms-thread-id", sessionId);
 
-        bool acceptsJson = req.Headers.TryGetValues("Accept", out IEnumerable<string>? acceptValues) &&
-            acceptValues.Contains("application/json", StringComparer.OrdinalIgnoreCase);
-
-        if (acceptsJson)
+        if (AcceptsJson(req))
         {
             AgentRunSuccessResponse successResponse = new((int)statusCode, sessionId, agentResponse);
             await response.WriteAsJsonAsync(successResponse, context.CancellationToken);
@@ -511,10 +596,7 @@ internal static class BuiltInFunctions
         HttpResponseData response = req.CreateResponse(HttpStatusCode.Accepted);
         response.Headers.Add("x-ms-thread-id", sessionId);
 
-        bool acceptsJson = req.Headers.TryGetValues("Accept", out IEnumerable<string>? acceptValues) &&
-            acceptValues.Contains("application/json", StringComparer.OrdinalIgnoreCase);
-
-        if (acceptsJson)
+        if (AcceptsJson(req))
         {
             AgentRunAcceptedResponse acceptedResponse = new((int)HttpStatusCode.Accepted, sessionId);
             await response.WriteAsJsonAsync(acceptedResponse, context.CancellationToken);
@@ -528,6 +610,34 @@ internal static class BuiltInFunctions
         return response;
     }
 
+    /// <summary>
+    /// Returns <see langword="true"/> when the caller has requested waiting for the workflow/agent to complete,
+    /// as indicated by the <c>x-ms-wait-for-response</c> header. Falls back to <paramref name="defaultValue"/>
+    /// when the header is absent or not a valid boolean.
+    /// </summary>
+    private static bool ShouldWaitForResponse(HttpRequestData req, bool defaultValue)
+    {
+        if (req.Headers.TryGetValues(WaitForResponseHeaderName, out IEnumerable<string>? values) &&
+            bool.TryParse(values.FirstOrDefault(), out bool parsed))
+        {
+            return parsed;
+        }
+
+        return defaultValue;
+    }
+
+    /// <summary>
+    /// Returns <see langword="true"/> when the request accepts the <c>application/json</c> media type.
+    /// </summary>
+    private static bool AcceptsJson(HttpRequestData req)
+    {
+        return req.Headers.TryGetValues("Accept", out IEnumerable<string>? acceptValues) &&
+            acceptValues
+                .SelectMany(v => v.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
+                .Select(v => v.Split(';', 2)[0].Trim())
+                .Contains("application/json", StringComparer.OrdinalIgnoreCase);
+    }
+
     private static string GetAgentName(FunctionContext context)
     {
         // Check if the function name starts with the HttpPrefix
@@ -591,6 +701,19 @@ internal static class BuiltInFunctions
         [property: JsonPropertyName("eventName")] string? EventName,
         [property: JsonPropertyName("response")] JsonElement Response);
 
+    /// <summary>
+    /// Represents a workflow run response when waiting for completion.
+    /// </summary>
+    /// <param name="RunId">The orchestration run ID.</param>
+    /// <param name="WorkflowStatus">The orchestration runtime status (e.g., "Completed", "Failed").</param>
+    /// <param name="Result">The workflow result as a JSON element so POCOs serialize as nested objects rather than escaped strings.</param>
+    /// <param name="Error">An optional error message when the workflow has failed.</param>
+    private sealed record WorkflowRunResponse(
+        [property: JsonPropertyName("runId")] string RunId,
+        [property: JsonPropertyName("workflowStatus")] string WorkflowStatus,
+        [property: JsonPropertyName("result")] JsonElement? Result,
+        [property: JsonPropertyName("error"), JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] string? Error = null);
+
     /// <summary>
     /// A service provider that combines the original service provider with an additional DurableTaskClient instance.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Support returning workflow results from HTTP trigger endpoint ([#5321](https://github.com/microsoft/agent-framework/pull/5321))
 - Added MCP tool trigger support for durable workflows ([#4768](https://github.com/microsoft/agent-framework/pull/4768))
 - Added Azure Functions hosting support for durable workflows ([#4436](https://github.com/microsoft/agent-framework/pull/4436))
 

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/StreamingRunEventStream.cs

@@ -77,12 +77,13 @@ internal sealed class StreamingRunEventStream : IRunEventStream
 
         try
         {
-            // Wait for the first input before starting
-            // The consumer will call EnqueueMessageAsync which signals the run loop
+            // Wait for the first input before starting.
+            // The consumer will call EnqueueMessageAsync which signals the run loop.
+            // Note: AsyncRunHandle also signals here on checkpoint resume when there are
+            // already pending requests, so the first iteration can emit a PendingRequests
+            // halt signal even without unprocessed messages.
             await this._inputWaiter.WaitForInputAsync(cancellationToken: linkedSource.Token).ConfigureAwait(false);
 
-            this._runStatus = RunStatus.Running;
-
             while (!linkedSource.Token.IsCancellationRequested)
             {
                 // Start a new run-stage activity for this input→processing→halt cycle
@@ -95,6 +96,13 @@ internal sealed class StreamingRunEventStream : IRunEventStream
                 // Events are streamed out in real-time as they happen via the event handler
                 if (this._stepRunner.HasUnprocessedMessages)
                 {
+                    // Flip to Running only when there's actual work to process.
+                    // This is intentionally inside the HasUnprocessedMessages branch so
+                    // that stale input signals cannot transiently flip status back to
+                    // Running after a prior halt has already been observed by callers
+                    // (e.g. Run.ResumeAsync returning after reading an Idle halt signal).
+                    this._runStatus = RunStatus.Running;
+
                     // Emit WorkflowStartedEvent only when there's actual work to process
                     // This avoids spurious events on timeout-only loop iterations
                     await this._eventChannel.Writer.WriteAsync(new WorkflowStartedEvent(), linkedSource.Token).ConfigureAwait(false);
@@ -129,9 +137,6 @@ internal sealed class StreamingRunEventStream : IRunEventStream
                 // Wait for next input from the consumer
                 // Works for both Idle (no work) and PendingRequests (waiting for responses)
                 await this._inputWaiter.WaitForInputAsync(linkedSource.Token).ConfigureAwait(false);
-
-                // When signaled, resume running
-                this._runStatus = RunStatus.Running;
             }
         }
         catch (OperationCanceledException)

dotnet/src/Microsoft.Agents.AI/CompatibilitySuppressions.xml

@@ -1,6 +1,20 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- https://learn.microsoft.com/dotnet/fundamentals/package-validation/diagnostic-ids -->
 <Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -29,6 +43,13 @@
     <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -43,6 +64,20 @@
     <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -71,6 +106,13 @@
     <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -85,6 +127,20 @@
     <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -113,6 +169,13 @@
     <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -127,6 +190,20 @@
     <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -155,6 +232,13 @@
     <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -169,6 +253,20 @@
     <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.BeginInvoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken,System.AsyncCallback,System.Object)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentFileSkillScriptRunner.Invoke(Microsoft.Agents.AI.AgentFileSkill,Microsoft.Agents.AI.AgentFileSkillScript,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentInlineSkill.#ctor(Microsoft.Agents.AI.AgentSkillFrontmatter,System.String)</Target>
@@ -197,6 +295,13 @@
     <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0002</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,Microsoft.Extensions.AI.AIFunctionArguments,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
   <Suppression>
     <DiagnosticId>CP0002</DiagnosticId>
     <Target>M:Microsoft.Agents.AI.AgentSkillsProvider.#ctor(Microsoft.Agents.AI.AgentInlineSkill[])</Target>
@@ -211,4 +316,39 @@
     <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
     <IsBaselineSuppression>true</IsBaselineSuppression>
   </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net10.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net10.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net472/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net472/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net8.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net8.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/net9.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/net9.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
+  <Suppression>
+    <DiagnosticId>CP0005</DiagnosticId>
+    <Target>M:Microsoft.Agents.AI.AgentSkillScript.RunAsync(Microsoft.Agents.AI.AgentSkill,System.Nullable{System.Text.Json.JsonElement},System.IServiceProvider,System.Threading.CancellationToken)</Target>
+    <Left>lib/netstandard2.0/Microsoft.Agents.AI.dll</Left>
+    <Right>lib/netstandard2.0/Microsoft.Agents.AI.dll</Right>
+    <IsBaselineSuppression>true</IsBaselineSuppression>
+  </Suppression>
 </Suppressions>

dotnet/src/Microsoft.Agents.AI/Skills/AgentSkill.cs

@@ -35,7 +35,8 @@ public abstract class AgentSkill
     /// Gets the full skill content.
     /// </summary>
     /// <remarks>
-    /// For file-based skills this is the raw SKILL.md file content.
+    /// For file-based skills this is the raw SKILL.md file content, optionally
+    /// augmented with a synthesized scripts block when scripts are present.
     /// For code-defined skills this is a synthesized XML document
     /// containing name, description, and body (instructions, resources, scripts).
     /// </remarks>

dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillScript.cs

@@ -1,10 +1,10 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
 using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
@@ -46,8 +46,9 @@ public abstract class AgentSkillScript
     /// Runs the script with the given arguments.
     /// </summary>
     /// <param name="skill">The skill that owns this script.</param>
-    /// <param name="arguments">Arguments for script execution.</param>
+    /// <param name="arguments">Raw JSON arguments for script execution, preserving the original format (object or array) sent by the caller.</param>
+    /// <param name="serviceProvider">Optional service provider for dependency injection.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
     /// <returns>The script execution result.</returns>
-    public abstract Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, CancellationToken cancellationToken = default);
+    public abstract Task<object?> RunAsync(AgentSkill skill, JsonElement? arguments, IServiceProvider? serviceProvider, CancellationToken cancellationToken = default);
 }

dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs

@@ -6,6 +6,7 @@ using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 using System.Security;
 using System.Text;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
@@ -243,7 +244,7 @@ public sealed partial class AgentSkillsProvider : AIContextProvider
         }
 
         AIFunction scriptFunction = AIFunctionFactory.Create(
-            (string skillName, string scriptName, IDictionary<string, object?>? arguments = null, IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default) =>
+            (string skillName, string scriptName, JsonElement? arguments = null, IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default) =>
                 this.RunSkillScriptAsync(skills, skillName, scriptName, arguments, serviceProvider, cancellationToken),
             name: "run_skill_script",
             description: "Runs a script associated with a skill.");
@@ -340,7 +341,7 @@ public sealed partial class AgentSkillsProvider : AIContextProvider
         }
     }
 
-    private async Task<object?> RunSkillScriptAsync(IList<AgentSkill> skills, string skillName, string scriptName, IDictionary<string, object?>? arguments = null, IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default)
+    private async Task<object?> RunSkillScriptAsync(IList<AgentSkill> skills, string skillName, string scriptName, JsonElement? arguments = null, IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default)
     {
         if (string.IsNullOrWhiteSpace(skillName))
         {
@@ -366,7 +367,7 @@ public sealed partial class AgentSkillsProvider : AIContextProvider
 
         try
         {
-            return await script.RunAsync(skill, new AIFunctionArguments(arguments) { Services = serviceProvider }, cancellationToken).ConfigureAwait(false);
+            return await script.RunAsync(skill, arguments, serviceProvider, cancellationToken).ConfigureAwait(false);
         }
         catch (Exception ex)
         {

dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkill.cs

@@ -15,6 +15,8 @@ public sealed class AgentFileSkill : AgentSkill
 {
     private readonly IReadOnlyList<AgentSkillResource> _resources;
     private readonly IReadOnlyList<AgentSkillScript> _scripts;
+    private readonly string _originalContent;
+    private string? _content;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="AgentFileSkill"/> class.
@@ -32,7 +34,7 @@ public sealed class AgentFileSkill : AgentSkill
         IReadOnlyList<AgentSkillScript>? scripts = null)
     {
         this.Frontmatter = Throw.IfNull(frontmatter);
-        this.Content = Throw.IfNull(content);
+        this._originalContent = Throw.IfNull(content);
         this.Path = Throw.IfNullOrWhitespace(path);
         this._resources = resources ?? [];
         this._scripts = scripts ?? [];
@@ -42,7 +44,18 @@ public sealed class AgentFileSkill : AgentSkill
     public override AgentSkillFrontmatter Frontmatter { get; }
 
     /// <inheritdoc/>
-    public override string Content { get; }
+    /// <remarks>
+    /// Returns the raw SKILL.md content. When the skill has scripts, a
+    /// <c>&lt;scripts&gt;&lt;script name="..."&gt;&lt;parameters_schema&gt;...&lt;/parameters_schema&gt;&lt;/script&gt;&lt;/scripts&gt;</c>
+    /// block is appended with a per-script entry describing the expected argument format.
+    /// The result is cached after the first access.
+    /// </remarks>
+    public override string Content
+    {
+        get => this._content ??= this._scripts is { Count: > 0 }
+            ? this._originalContent + AgentInlineSkillContentBuilder.BuildScriptsBlock(this._scripts)
+            : this._originalContent;
+    }
 
     /// <summary>
     /// Gets the directory path where the skill was discovered.

dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillScript.cs

@@ -2,9 +2,9 @@
 
 using System;
 using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
 using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
@@ -16,6 +16,11 @@ namespace Microsoft.Agents.AI;
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
 public sealed class AgentFileSkillScript : AgentSkillScript
 {
+    /// <summary>
+    /// Cached JSON schema element describing the expected argument format: a string array of CLI arguments.
+    /// </summary>
+    private static readonly JsonElement s_defaultSchema = CreateDefaultSchema();
+
     private readonly AgentFileSkillScriptRunner? _runner;
 
     /// <summary>
@@ -37,7 +42,14 @@ public sealed class AgentFileSkillScript : AgentSkillScript
     public string FullPath { get; }
 
     /// <inheritdoc/>
-    public override async Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, CancellationToken cancellationToken = default)
+    /// <remarks>
+    /// Returns a fixed schema describing a string array of CLI arguments:
+    /// <c>{"type":"array","items":{"type":"string"}}</c>.
+    /// </remarks>
+    public override JsonElement? ParametersSchema => s_defaultSchema;
+
+    /// <inheritdoc/>
+    public override async Task<object?> RunAsync(AgentSkill skill, JsonElement? arguments, IServiceProvider? serviceProvider, CancellationToken cancellationToken = default)
     {
         if (skill is not AgentFileSkill fileSkill)
         {
@@ -51,6 +63,12 @@ public sealed class AgentFileSkillScript : AgentSkillScript
                 $"Supply a script runner when constructing {nameof(AgentFileSkillsSource)} to enable script execution.");
         }
 
-        return await this._runner(fileSkill, this, arguments, cancellationToken).ConfigureAwait(false);
+        return await this._runner(fileSkill, this, arguments, serviceProvider, cancellationToken).ConfigureAwait(false);
+    }
+
+    private static JsonElement CreateDefaultSchema()
+    {
+        using JsonDocument document = JsonDocument.Parse("""{"type":"array","items":{"type":"string"}}""");
+        return document.RootElement.Clone();
     }
 }

dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillScriptRunner.cs

@@ -1,9 +1,10 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
 using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
 using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Agents.AI;
@@ -13,15 +14,19 @@ namespace Microsoft.Agents.AI;
 /// </summary>
 /// <remarks>
 /// Implementations determine the execution strategy (e.g., local subprocess, hosted code execution environment).
+/// The <paramref name="arguments"/> parameter preserves the raw JSON sent by the caller, in the shape
+/// described by <see cref="AgentFileSkillScript.ParametersSchema"/>.
 /// </remarks>
 /// <param name="skill">The skill that owns the script.</param>
 /// <param name="script">The file-based script to run.</param>
-/// <param name="arguments">Optional arguments for the script, provided by the agent/LLM.</param>
+/// <param name="arguments">Raw JSON arguments for the script, in the shape described by <see cref="AgentFileSkillScript.ParametersSchema"/>.</param>
+/// <param name="serviceProvider">Optional service provider for dependency injection.</param>
 /// <param name="cancellationToken">Cancellation token.</param>
 /// <returns>The script execution result.</returns>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
 public delegate Task<object?> AgentFileSkillScriptRunner(
     AgentFileSkill skill,
     AgentFileSkillScript script,
-    AIFunctionArguments arguments,
+    JsonElement? arguments,
+    IServiceProvider? serviceProvider,
     CancellationToken cancellationToken);

dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillContentBuilder.cs

@@ -59,36 +59,60 @@ internal static class AgentInlineSkillContentBuilder
 
         if (scripts is { Count: > 0 })
         {
-            sb.Append("\n\n<scripts>\n");
-            foreach (var script in scripts)
-            {
-                var parametersSchema = script.ParametersSchema;
-
-                if (script.Description is null && parametersSchema is null)
-                {
-                    sb.Append($"  <script name=\"{EscapeXmlString(script.Name)}\"/>\n");
-                }
-                else
-                {
-                    sb.Append(script.Description is not null
-                        ? $"  <script name=\"{EscapeXmlString(script.Name)}\" description=\"{EscapeXmlString(script.Description)}\">\n"
-                        : $"  <script name=\"{EscapeXmlString(script.Name)}\">\n");
-
-                    if (parametersSchema is not null)
-                    {
-                        sb.Append($"    <parameters_schema>{EscapeXmlString(parametersSchema.Value.GetRawText(), preserveQuotes: true)}</parameters_schema>\n");
-                    }
-
-                    sb.Append("  </script>\n");
-                }
-            }
-
-            sb.Append("</scripts>");
+            sb.Append('\n');
+            sb.Append(BuildScriptsBlock(scripts));
         }
 
         return sb.ToString();
     }
 
+    /// <summary>
+    /// Builds a <c>&lt;scripts&gt;...&lt;/scripts&gt;</c> XML block for the given scripts.
+    /// Each script is emitted as a <c>&lt;script name="..."&gt;</c> element with optional
+    /// <c>description</c> attribute and <c>&lt;parameters_schema&gt;</c> child element.
+    /// </summary>
+    /// <param name="scripts">The scripts to include in the block.</param>
+    /// <returns>An XML string starting with <c>\n&lt;scripts&gt;</c>, or an empty string if the list is empty.</returns>
+    public static string BuildScriptsBlock(IReadOnlyList<AgentSkillScript> scripts)
+    {
+        _ = Throw.IfNull(scripts);
+
+        if (scripts.Count == 0)
+        {
+            return string.Empty;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append("\n<scripts>\n");
+
+        foreach (var script in scripts)
+        {
+            var parametersSchema = script.ParametersSchema;
+
+            if (script.Description is null && parametersSchema is null)
+            {
+                sb.Append($"  <script name=\"{EscapeXmlString(script.Name)}\"/>\n");
+            }
+            else
+            {
+                sb.Append(script.Description is not null
+                    ? $"  <script name=\"{EscapeXmlString(script.Name)}\" description=\"{EscapeXmlString(script.Description)}\">\n"
+                    : $"  <script name=\"{EscapeXmlString(script.Name)}\">\n");
+
+                if (parametersSchema is not null)
+                {
+                    sb.Append($"    <parameters_schema>{EscapeXmlString(parametersSchema.Value.GetRawText(), preserveQuotes: true)}</parameters_schema>\n");
+                }
+
+                sb.Append("  </script>\n");
+            }
+        }
+
+        sb.Append("</scripts>");
+
+        return sb.ToString();
+    }
+
     /// <summary>
     /// Escapes XML special characters: always escapes <c>&amp;</c>, <c>&lt;</c>, <c>&gt;</c>,
     /// <c>&quot;</c>, and <c>&apos;</c>. When <paramref name="preserveQuotes"/> is <see langword="true"/>,

dotnet/src/Microsoft.Agents.AI/Skills/Programmatic/AgentInlineSkillScript.cs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Reflection;
 using System.Text.Json;
@@ -67,8 +68,42 @@ internal sealed class AgentInlineSkillScript : AgentSkillScript
     public override JsonElement? ParametersSchema => this._function.JsonSchema;
 
     /// <inheritdoc/>
-    public override async Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, CancellationToken cancellationToken = default)
+    public override async Task<object?> RunAsync(AgentSkill skill, JsonElement? arguments, IServiceProvider? serviceProvider, CancellationToken cancellationToken = default)
     {
-        return await this._function.InvokeAsync(arguments, cancellationToken).ConfigureAwait(false);
+        var funcArgs = ConvertToFunctionArguments(arguments);
+        funcArgs.Services = serviceProvider;
+
+        return await this._function.InvokeAsync(funcArgs, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Converts a raw <see cref="JsonElement"/> to <see cref="AIFunctionArguments"/> for delegate invocation.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when <paramref name="arguments"/> is provided but is not a JSON object.
+    /// Inline skill scripts expect arguments as a JSON object whose properties map to the delegate's parameters.
+    /// </exception>
+    private static AIFunctionArguments ConvertToFunctionArguments(JsonElement? arguments)
+    {
+        if (arguments is null ||
+            arguments.Value.ValueKind == JsonValueKind.Null ||
+            arguments.Value.ValueKind == JsonValueKind.Undefined)
+        {
+            return [];
+        }
+
+        if (arguments.Value.ValueKind != JsonValueKind.Object)
+        {
+            throw new InvalidOperationException(
+                $"Inline skill scripts expect arguments as a JSON object but received a JSON element of kind '{arguments.Value.ValueKind}'.");
+        }
+
+        var dict = new Dictionary<string, object?>();
+        foreach (var property in arguments.Value.EnumerateObject())
+        {
+            dict[property.Name] = property.Value;
+        }
+
+        return new AIFunctionArguments(dict);
     }
 }

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Hosting/AgentFrameworkResponseHandlerTelemetryTests.cs

@@ -164,10 +164,8 @@ public class AgentFrameworkResponseHandlerTelemetryTests
     private static (CreateResponse request, ResponseContext context) BuildRequest(string? agentKey = null)
     {
         var request = agentKey is null
-            ? AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test")
-            : AzureAIAgentServerResponsesModelFactory.CreateResponse(
-                model: "test",
-                agentReference: new AgentReference(agentKey));
+            ? new CreateResponse { Model = "test" }
+            : new CreateResponse { Model = "test", AgentReference = new AgentReference(agentKey) };
 
         request.Input = BinaryData.FromObjectAsJson(new[]
         {

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Hosting/AgentFrameworkResponseHandlerTests.cs

@@ -34,7 +34,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -72,9 +72,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(
-            model: "test",
-            agentReference: new AgentReference("my-agent"));
+        var request = new CreateResponse { Model = "test", AgentReference = new AgentReference("my-agent") };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -109,7 +107,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -158,7 +156,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "my-agent");
+        var request = new CreateResponse { Model = "my-agent" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -195,7 +193,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "");
+        var request = new CreateResponse { Model = "" };
         var metadata = new Metadata();
         metadata.AdditionalProperties["entity_id"] = "entity-agent";
         request.Metadata = metadata;
@@ -235,9 +233,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(
-            model: "test",
-            agentReference: new AgentReference("nonexistent-agent"));
+        var request = new CreateResponse { Model = "test", AgentReference = new AgentReference("nonexistent-agent") };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -272,9 +268,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(
-            model: "test",
-            agentReference: new AgentReference("missing-agent"));
+        var request = new CreateResponse { Model = "test", AgentReference = new AgentReference("missing-agent") };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -308,7 +302,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "");
+        var request = new CreateResponse { Model = "" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -342,7 +336,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -387,7 +381,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -435,7 +429,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -478,7 +472,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -517,9 +511,11 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(
-            model: "test",
-            instructions: "You are a helpful assistant.");
+        var request = new CreateResponse
+        {
+            Model = "test",
+            Instructions = "You are a helpful assistant.",
+        };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -557,7 +553,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -598,9 +594,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(
-            model: "test",
-            agentReference: new AgentReference("agent-2"));
+        var request = new CreateResponse { Model = "test", AgentReference = new AgentReference("agent-2") };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -637,7 +631,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",
@@ -674,7 +668,7 @@ public class AgentFrameworkResponseHandlerTests
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
 
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = BinaryData.FromObjectAsJson(new[]
         {
             new { type = "message", id = "msg_1", status = "completed", role = "user",

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Hosting/FoundryToolboxTests.cs

@@ -0,0 +1,329 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Threading.Tasks;
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Microsoft.Agents.AI.Foundry.Hosting;
+using Microsoft.Extensions.AI;
+
+#pragma warning disable OPENAI001
+#pragma warning disable AAIP001
+
+namespace Microsoft.Agents.AI.Foundry.UnitTests;
+
+/// <summary>
+/// Unit tests for the <see cref="FoundryToolbox"/> class.
+/// </summary>
+public class FoundryToolboxTests
+{
+    private static readonly Uri s_testEndpoint = new("https://test.services.ai.azure.com/api/projects/test-project");
+
+    #region Parameter validation tests
+
+    [Fact]
+    public async Task GetToolboxVersionAsync_NullEndpoint_ThrowsAsync()
+    {
+        await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            FoundryToolbox.GetToolboxVersionAsync(
+                projectEndpoint: null!,
+                credential: new FakeAuthenticationTokenProvider(),
+                name: "test-toolbox"));
+    }
+
+    [Fact]
+    public async Task GetToolboxVersionAsync_NullCredential_ThrowsAsync()
+    {
+        await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            FoundryToolbox.GetToolboxVersionAsync(
+                projectEndpoint: s_testEndpoint,
+                credential: null!,
+                name: "test-toolbox"));
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public async Task GetToolboxVersionAsync_InvalidName_ThrowsAsync(string? name)
+    {
+        await Assert.ThrowsAnyAsync<ArgumentException>(() =>
+            FoundryToolbox.GetToolboxVersionAsync(
+                projectEndpoint: s_testEndpoint,
+                credential: new FakeAuthenticationTokenProvider(),
+                name: name!));
+    }
+
+    [Fact]
+    public async Task GetToolsAsync_NullEndpoint_ThrowsAsync()
+    {
+        await Assert.ThrowsAsync<ArgumentNullException>(() =>
+            FoundryToolbox.GetToolsAsync(
+                projectEndpoint: null!,
+                credential: new FakeAuthenticationTokenProvider(),
+                name: "test-toolbox"));
+    }
+
+    [Fact]
+    public void ToAITools_NullToolboxVersion_Throws()
+    {
+        Assert.Throws<ArgumentNullException>(() =>
+            FoundryToolbox.ToAITools(null!));
+    }
+
+    #endregion
+
+    #region ToAITools conversion tests
+
+    [Fact]
+    public void ToAITools_EmptyTools_ReturnsEmptyList()
+    {
+        var version = ProjectsAgentsModelFactory.ToolboxVersion(
+            metadata: null,
+            id: "ver-1",
+            name: "empty-toolbox",
+            version: "v1",
+            description: "Empty",
+            createdAt: DateTimeOffset.UtcNow,
+            tools: Array.Empty<ProjectsAgentTool>(),
+            policies: null);
+
+        var tools = version.ToAITools();
+
+        Assert.Empty(tools);
+    }
+
+    [Fact]
+    public void ToAITools_NullTools_ReturnsEmptyList()
+    {
+        var version = ProjectsAgentsModelFactory.ToolboxVersion(
+            metadata: null,
+            id: "ver-1",
+            name: "null-tools-toolbox",
+            version: "v1",
+            description: "Null tools",
+            createdAt: DateTimeOffset.UtcNow,
+            tools: null,
+            policies: null);
+
+        var tools = version.ToAITools();
+
+        Assert.Empty(tools);
+    }
+
+    [Fact]
+    public void ToAITools_WithCodeInterpreterTool_ReturnsAITool()
+    {
+        var json = TestDataUtil.GetToolboxVersionResponseJson();
+        var version = ModelReaderWriter.Read<ToolboxVersion>(BinaryData.FromString(json))!;
+
+        var tools = version.ToAITools();
+
+        Assert.Single(tools);
+        Assert.IsAssignableFrom<AITool>(tools[0]);
+    }
+
+    [Fact]
+    public void ToAITools_SanitizesDecorationFieldsOnNonFunctionTools()
+    {
+        var json = TestDataUtil.GetToolboxVersionWithDecorationFieldsJson();
+        var version = ModelReaderWriter.Read<ToolboxVersion>(BinaryData.FromString(json))!;
+
+        var tools = version.ToAITools();
+
+        Assert.Single(tools);
+        Assert.IsAssignableFrom<AITool>(tools[0]);
+    }
+
+    [Fact]
+    public void SanitizeAndConvert_FunctionTool_PreservesNameAndDescription()
+    {
+        const string ToolJson = @"{""type"":""function"",""name"":""get_weather"",""description"":""Get weather"",""parameters"":{""type"":""object"",""properties"":{}}}";
+        var tool = ModelReaderWriter.Read<ProjectsAgentTool>(BinaryData.FromString(ToolJson))!;
+
+        var aiTool = FoundryToolbox.SanitizeAndConvert(tool);
+
+        Assert.NotNull(aiTool);
+        Assert.IsAssignableFrom<AITool>(aiTool);
+    }
+
+    [Fact]
+    public void SanitizeAndConvert_CodeInterpreterWithExtraFields_StripsDecorationFields()
+    {
+        const string ToolJson = @"{""type"":""code_interpreter"",""name"":""code_interpreter"",""description"":""Execute code""}";
+        var tool = ModelReaderWriter.Read<ProjectsAgentTool>(BinaryData.FromString(ToolJson))!;
+
+        var aiTool = FoundryToolbox.SanitizeAndConvert(tool);
+
+        Assert.NotNull(aiTool);
+    }
+
+    #endregion
+
+    #region Integration tests with mock HTTP
+
+    [Fact]
+    public async Task GetToolboxVersionAsync_WithExplicitVersion_FetchesVersionDirectlyAsync()
+    {
+        var versionJson = TestDataUtil.GetToolboxVersionResponseJson();
+        using var httpHandler = new HttpHandlerAssert((request) =>
+        {
+            Assert.Contains("/toolboxes/research_tools/versions/v5", request.RequestUri!.PathAndQuery);
+
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(versionJson, Encoding.UTF8, "application/json")
+            };
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+        var clientOptions = new AgentAdministrationClientOptions { Transport = new HttpClientPipelineTransport(httpClient) };
+
+        var result = await FoundryToolbox.GetToolboxVersionAsync(
+            s_testEndpoint,
+            new FakeAuthenticationTokenProvider(),
+            "research_tools",
+            version: "v5",
+            clientOptions: clientOptions,
+            cancellationToken: default);
+
+        Assert.Equal("research_tools", result.Name);
+        Assert.Equal("v5", result.Version);
+        Assert.Single(result.Tools);
+    }
+
+    [Fact]
+    public async Task GetToolboxVersionAsync_WithoutVersion_ResolvesDefaultThenFetchesAsync()
+    {
+        var recordJson = TestDataUtil.GetToolboxRecordResponseJson();
+        var versionJson = TestDataUtil.GetToolboxVersionResponseJson();
+        var callCount = 0;
+
+        using var httpHandler = new HttpHandlerAssert((request) =>
+        {
+            callCount++;
+            var path = request.RequestUri!.PathAndQuery;
+
+            if (!path.Contains("/versions/"))
+            {
+                Assert.Contains("/toolboxes/research_tools", path);
+                return new HttpResponseMessage(HttpStatusCode.OK)
+                {
+                    Content = new StringContent(recordJson, Encoding.UTF8, "application/json")
+                };
+            }
+
+            Assert.Contains("/toolboxes/research_tools/versions/v5", path);
+            return new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(versionJson, Encoding.UTF8, "application/json")
+            };
+        });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+        var clientOptions = new AgentAdministrationClientOptions { Transport = new HttpClientPipelineTransport(httpClient) };
+
+        var result = await FoundryToolbox.GetToolboxVersionAsync(
+            s_testEndpoint,
+            new FakeAuthenticationTokenProvider(),
+            "research_tools",
+            version: null,
+            clientOptions: clientOptions,
+            cancellationToken: default);
+
+        Assert.Equal(2, callCount);
+        Assert.Equal("research_tools", result.Name);
+        Assert.Equal("v5", result.Version);
+    }
+
+    [Fact]
+    public async Task GetToolboxVersionAsync_ApiError_ThrowsClientResultExceptionAsync()
+    {
+        using var httpHandler = new HttpHandlerAssert((_) =>
+            new HttpResponseMessage(HttpStatusCode.NotFound)
+            {
+                Content = new StringContent("{\"error\":\"not found\"}", Encoding.UTF8, "application/json")
+            });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+        var clientOptions = new AgentAdministrationClientOptions { Transport = new HttpClientPipelineTransport(httpClient) };
+
+        await Assert.ThrowsAsync<ClientResultException>(() =>
+            FoundryToolbox.GetToolboxVersionAsync(
+                s_testEndpoint,
+                new FakeAuthenticationTokenProvider(),
+                "nonexistent-toolbox",
+                version: "v1",
+                clientOptions: clientOptions,
+                cancellationToken: default));
+    }
+
+    [Fact]
+    public async Task GetToolsAsync_ReturnsConvertedAIToolsAsync()
+    {
+        var versionJson = TestDataUtil.GetToolboxVersionResponseJson();
+        using var httpHandler = new HttpHandlerAssert((_) =>
+            new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(versionJson, Encoding.UTF8, "application/json")
+            });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+        var clientOptions = new AgentAdministrationClientOptions { Transport = new HttpClientPipelineTransport(httpClient) };
+
+        var result = await FoundryToolbox.GetToolboxVersionAsync(
+            s_testEndpoint,
+            new FakeAuthenticationTokenProvider(),
+            "research_tools",
+            version: "v5",
+            clientOptions: clientOptions,
+            cancellationToken: default);
+
+        var tools = result.ToAITools();
+
+        Assert.Single(tools);
+        Assert.IsAssignableFrom<AITool>(tools[0]);
+    }
+
+    #endregion
+
+    #region AIProjectClient extension tests
+
+    [Fact]
+    public async Task AIProjectClientExtension_GetToolboxToolsAsync_ReturnsAIToolsAsync()
+    {
+        var versionJson = TestDataUtil.GetToolboxVersionResponseJson();
+        using var httpHandler = new HttpHandlerAssert((_) =>
+            new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent(versionJson, Encoding.UTF8, "application/json")
+            });
+
+#pragma warning disable CA5399
+        using var httpClient = new HttpClient(httpHandler);
+#pragma warning restore CA5399
+        var clientOptions = new AIProjectClientOptions();
+        clientOptions.Transport = new HttpClientPipelineTransport(httpClient);
+        var client = new AIProjectClient(s_testEndpoint, new FakeAuthenticationTokenProvider(), clientOptions);
+
+        var tools = await client.GetToolboxToolsAsync("research_tools", version: "v5");
+
+        Assert.Single(tools);
+        Assert.IsAssignableFrom<AITool>(tools[0]);
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Hosting/InputConverterTests.cs

@@ -2,7 +2,6 @@
 
 using System;
 using System.Linq;
-using Azure.AI.AgentServer.Responses;
 using Azure.AI.AgentServer.Responses.Models;
 using Microsoft.Agents.AI.Foundry.Hosting;
 using Microsoft.Extensions.AI;
@@ -146,11 +145,7 @@ public class InputConverterTests
     [Fact]
     public void ConvertToChatOptions_SetsTemperatureAndTopP()
     {
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(
-            temperature: 0.7,
-            topP: 0.9,
-            maxOutputTokens: 1000,
-            model: "gpt-4o");
+        var request = new CreateResponse { Temperature = 0.7, TopP = 0.9, MaxOutputTokens = 1000, Model = "gpt-4o" };
 
         var options = InputConverter.ConvertToChatOptions(request);
 
@@ -211,9 +206,9 @@ public class InputConverterTests
     }
 
     [Fact]
-    public void ConvertOutputItemsToMessages_FunctionToolCallOutputResource_ReturnsToolMessage()
+    public void ConvertOutputItemsToMessages_FunctionToolCallOutput_ReturnsToolMessage()
     {
-        var funcOutput = new FunctionToolCallOutputResource(
+        var funcOutput = new OutputItemFunctionToolCallOutput(
             callId: "call_def",
             output: BinaryData.FromString("result data"));
 
@@ -229,8 +224,7 @@ public class InputConverterTests
     [Fact]
     public void ConvertOutputItemsToMessages_ReasoningItem_ReturnsNull()
     {
-        var reasoning = AzureAIAgentServerResponsesModelFactory.OutputItemReasoningItem(
-            id: "reason_001");
+        var reasoning = new OutputItemReasoningItem("reason_001", []);
 
         var messages = InputConverter.ConvertOutputItemsToMessages([reasoning]);
 
@@ -661,7 +655,7 @@ public class InputConverterTests
     [Fact]
     public void ConvertToChatOptions_ModelId_NotSetFromRequest()
     {
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "my-model");
+        var request = new CreateResponse { Model = "my-model" };
 
         var options = InputConverter.ConvertToChatOptions(request);
 

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Hosting/OutputConverterTests.cs

@@ -20,7 +20,7 @@ public class OutputConverterTests
     private static (ResponseEventStream stream, Mock<ResponseContext> mockContext) CreateTestStream()
     {
         var mockContext = new Mock<ResponseContext>("resp_" + new string('0', 46)) { CallBase = true };
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test-model");
+        var request = new CreateResponse { Model = "test-model" };
         var stream = new ResponseEventStream(mockContext.Object, request);
         return (stream, mockContext);
     }

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Hosting/WorkflowIntegrationTests.cs

@@ -160,9 +160,7 @@ public class WorkflowIntegrationTests
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(
-            model: "test",
-            agentReference: new AgentReference("my-workflow"));
+        var request = new CreateResponse { Model = "test", AgentReference = new AgentReference("my-workflow") };
         request.Input = CreateUserInput("Test keyed workflow");
         var mockContext = CreateMockContext();
 
@@ -363,7 +361,7 @@ public class WorkflowIntegrationTests
         var sp = services.BuildServiceProvider();
 
         var handler = new AgentFrameworkResponseHandler(sp, NullLogger<AgentFrameworkResponseHandler>.Instance);
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test");
+        var request = new CreateResponse { Model = "test" };
         request.Input = CreateUserInput(userMessage);
         var mockContext = CreateMockContext();
 
@@ -393,7 +391,7 @@ public class WorkflowIntegrationTests
     private static (ResponseEventStream stream, Mock<ResponseContext> mockContext) CreateTestStream()
     {
         var mockContext = new Mock<ResponseContext>("resp_" + new string('0', 46)) { CallBase = true };
-        var request = AzureAIAgentServerResponsesModelFactory.CreateResponse(model: "test-model");
+        var request = new CreateResponse { Model = "test-model" };
         var stream = new ResponseEventStream(mockContext.Object, request);
         return (stream, mockContext);
     }

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj

@@ -10,7 +10,7 @@
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">
-    <PackageReference Include="Azure.AI.Projects" />
+    <PackageReference Include="Azure.AI.Projects" VersionOverride="2.1.0-beta.1" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETCoreApp'">
@@ -34,7 +34,7 @@
     <ProjectReference Include="..\..\src\Microsoft.Agents.AI.Foundry.Hosting\Microsoft.Agents.AI.Foundry.Hosting.csproj" />
   </ItemGroup>
 
-  <!-- Evaluation tests require net8.0+ (MEAI.Evaluation does not support legacy TFMs) -->
+  <!-- FoundryEval tests require net8.0+ (MEAI.Evaluation does not support legacy TFMs) -->
   <ItemGroup Condition="!$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
     <Compile Remove="FoundryEvalConverterTests.cs" />
     <Compile Remove="FoundryEvalsTests.cs" />
@@ -50,6 +50,15 @@
     <None Update="TestData\OpenAIDefaultResponse.json">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
+    <None Update="TestData\ToolboxRecordResponse.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+    <None Update="TestData\ToolboxVersionResponse.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+    <None Update="TestData\ToolboxVersionWithDecorationFields.json">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
   </ItemGroup>
 
 </Project>

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/TestData/ToolboxRecordResponse.json

@@ -0,0 +1,5 @@
+{
+  "id": "tbx-123",
+  "name": "research_tools",
+  "default_version": "v5"
+}

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/TestData/ToolboxVersionResponse.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {},
+  "id": "tbv-research_tools-v5",
+  "name": "research_tools",
+  "version": "v5",
+  "description": "Example research toolbox",
+  "created_at": 1775779200,
+  "tools": [
+    { "type": "code_interpreter" }
+  ]
+}

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/TestData/ToolboxVersionWithDecorationFields.json

@@ -0,0 +1,11 @@
+{
+  "metadata": {},
+  "id": "tbv-dirty-v1",
+  "name": "dirty_toolbox",
+  "version": "v1",
+  "description": "Toolbox with decoration fields on tools",
+  "created_at": 1775779200,
+  "tools": [
+    { "type": "code_interpreter", "name": "code_interpreter", "description": "Execute Python code" }
+  ]
+}

dotnet/tests/Microsoft.Agents.AI.Foundry.UnitTests/TestDataUtil.cs

@@ -14,6 +14,9 @@ internal static class TestDataUtil
     private static readonly string s_agentResponseJson = File.ReadAllText("TestData/AgentResponse.json");
     private static readonly string s_agentVersionResponseJson = File.ReadAllText("TestData/AgentVersionResponse.json");
     private static readonly string s_openAIDefaultResponseJson = File.ReadAllText("TestData/OpenAIDefaultResponse.json");
+    private static readonly string s_toolboxRecordResponseJson = File.ReadAllText("TestData/ToolboxRecordResponse.json");
+    private static readonly string s_toolboxVersionResponseJson = File.ReadAllText("TestData/ToolboxVersionResponse.json");
+    private static readonly string s_toolboxVersionWithDecorationFieldsJson = File.ReadAllText("TestData/ToolboxVersionWithDecorationFields.json");
 
     private const string AgentDefinitionPlaceholder = "\"agent-definition-placeholder\"";
 
@@ -162,4 +165,19 @@ internal static class TestDataUtil
         }
         return json;
     }
+
+    /// <summary>
+    /// Gets the toolbox record response JSON.
+    /// </summary>
+    public static string GetToolboxRecordResponseJson() => s_toolboxRecordResponseJson;
+
+    /// <summary>
+    /// Gets the toolbox version response JSON.
+    /// </summary>
+    public static string GetToolboxVersionResponseJson() => s_toolboxVersionResponseJson;
+
+    /// <summary>
+    /// Gets the toolbox version response JSON with decoration fields on tools.
+    /// </summary>
+    public static string GetToolboxVersionWithDecorationFieldsJson() => s_toolboxVersionWithDecorationFieldsJson;
 }

dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/A2AAgentHandlerTests.cs

@@ -586,6 +586,457 @@ public sealed class A2AAgentHandlerTests
 
 #pragma warning restore MEAI001
 
+    /// <summary>
+    /// Verifies that in streaming mode, each update from RunStreamingAsync produces a message event.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_EnqueuesMessageForEachUpdateAsync()
+    {
+        // Arrange
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "chunk 1") { ResponseId = "r1" },
+            new AgentResponseUpdate(ChatRole.Assistant, "chunk 2") { ResponseId = "r2" }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates));
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Assert.Equal(2, events.Messages.Count);
+        Assert.Equal("chunk 1", events.Messages[0].Parts![0].Text);
+        Assert.Equal("chunk 2", events.Messages[1].Parts![0].Text);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, when metadata is present, options with AdditionalProperties
+    /// are passed to RunStreamingAsync.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WithMetadata_PassesOptionsWithAdditionalPropertiesAsync()
+    {
+        // Arrange
+        AgentRunOptions? capturedOptions = null;
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMockWithOptionsCapture(
+            options => capturedOptions = options));
+
+        // Act
+        await InvokeExecuteAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] },
+            Metadata = new Dictionary<string, JsonElement>
+            {
+                ["key1"] = JsonSerializer.SerializeToElement("value1")
+            }
+        });
+
+        // Assert
+        Assert.NotNull(capturedOptions);
+        Assert.NotNull(capturedOptions.AdditionalProperties);
+        Assert.Equal("value1", capturedOptions.AdditionalProperties["key1"]?.ToString());
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, when metadata is null, null options are passed to RunStreamingAsync.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WithNullMetadata_PassesNullOptionsAsync()
+    {
+        // Arrange
+        AgentRunOptions? capturedOptions = null;
+        bool optionsCaptured = false;
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMockWithOptionsCapture(
+            options => { capturedOptions = options; optionsCaptured = true; }));
+
+        // Act
+        await InvokeExecuteAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Assert.True(optionsCaptured);
+        Assert.Null(capturedOptions);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, ReferenceTaskIds throws NotSupportedException.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WithReferenceTaskIds_ThrowsNotSupportedExceptionAsync()
+    {
+        // Arrange
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock([]));
+
+        // Act & Assert
+        var eventQueue = new AgentEventQueue();
+        await Assert.ThrowsAsync<NotSupportedException>(() =>
+            handler.ExecuteAsync(
+                new RequestContext
+                {
+                    StreamingResponse = true,
+                    TaskId = "",
+                    ContextId = "ctx",
+                    Message = new Message
+                    {
+                        MessageId = "test-id",
+                        Role = Role.User,
+                        Parts = [new Part { Text = "Hello" }],
+                        ReferenceTaskIds = ["other-task-id"]
+                    }
+                },
+                eventQueue,
+                CancellationToken.None));
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, when ContextId is null, a new one is generated.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WhenContextIdIsNull_GeneratesContextIdAsync()
+    {
+        // Arrange
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "Reply") { ResponseId = "r1" }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates));
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = null!,
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Message message = Assert.Single(events.Messages);
+        Assert.NotNull(message.ContextId);
+        Assert.NotEmpty(message.ContextId);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, the provided ContextId is used in the response.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_UsesProvidedContextIdAsync()
+    {
+        // Arrange
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "Reply") { ResponseId = "r1" }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates));
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "my-streaming-ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Message message = Assert.Single(events.Messages);
+        Assert.Equal("my-streaming-ctx", message.ContextId);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, when Message is null, the handler succeeds with empty messages.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WhenMessageIsNull_SucceedsWithEmptyMessagesAsync()
+    {
+        // Arrange
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "Reply") { ResponseId = "r1" }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates));
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = null!
+        });
+
+        // Assert
+        Message message = Assert.Single(events.Messages);
+        Assert.Equal("ctx", message.ContextId);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, the ResponseId from the update is used as the MessageId in the response.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_ResponseIdIsUsedAsMessageIdAsync()
+    {
+        // Arrange
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "chunk") { ResponseId = "resp-42" }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates));
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Message message = Assert.Single(events.Messages);
+        Assert.Equal("resp-42", message.MessageId);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, when ResponseId is null, a MessageId is still generated.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WhenResponseIdIsNull_GeneratesMessageIdAsync()
+    {
+        // Arrange
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "chunk") { ResponseId = null }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates));
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Message message = Assert.Single(events.Messages);
+        Assert.NotNull(message.MessageId);
+        Assert.NotEmpty(message.MessageId);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, when the update has AdditionalProperties, the message has metadata.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WithResponseAdditionalProperties_ReturnsMessageWithMetadataAsync()
+    {
+        // Arrange
+        AdditionalPropertiesDictionary additionalProps = new()
+        {
+            ["streamKey"] = "streamValue"
+        };
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "chunk") { ResponseId = "r1", AdditionalProperties = additionalProps }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates));
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Message message = Assert.Single(events.Messages);
+        Assert.NotNull(message.Metadata);
+        Assert.True(message.Metadata.ContainsKey("streamKey"));
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, when the update has null AdditionalProperties, the message has null metadata.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WithNullAdditionalProperties_ReturnsMessageWithNullMetadataAsync()
+    {
+        // Arrange
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "chunk") { ResponseId = "r1", AdditionalProperties = null }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates));
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Message message = Assert.Single(events.Messages);
+        Assert.Null(message.Metadata);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, the session is saved after all updates are processed.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_SavesSessionAfterProcessingAsync()
+    {
+        // Arrange
+        var mockSessionStore = new Mock<AgentSessionStore>();
+        mockSessionStore
+            .Setup(x => x.GetSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.IsAny<string>(),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new TestAgentSession());
+        mockSessionStore
+            .Setup(x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.IsAny<string>(),
+                It.IsAny<AgentSession>(),
+                It.IsAny<CancellationToken>()))
+            .Returns(ValueTask.CompletedTask);
+
+        AgentResponseUpdate[] updates =
+        [
+            new AgentResponseUpdate(ChatRole.Assistant, "chunk") { ResponseId = "r1" }
+        ];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates), agentSessionStore: mockSessionStore.Object);
+
+        // Act
+        await InvokeExecuteAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx-stream",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert - verify session was saved
+        mockSessionStore.Verify(
+            x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.Is<string>(s => s == "ctx-stream"),
+                It.IsAny<AgentSession>(),
+                It.IsAny<CancellationToken>()),
+            Times.Once);
+    }
+
+    /// <summary>
+    /// Verifies that in streaming mode, when RunStreamingAsync yields no updates,
+    /// no messages are enqueued and the session is still saved.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WhenNoUpdates_EnqueuesNoMessagesAndSavesSessionAsync()
+    {
+        // Arrange
+        var mockSessionStore = new Mock<AgentSessionStore>();
+        mockSessionStore
+            .Setup(x => x.GetSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.IsAny<string>(),
+                It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new TestAgentSession());
+        mockSessionStore
+            .Setup(x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.IsAny<string>(),
+                It.IsAny<AgentSession>(),
+                It.IsAny<CancellationToken>()))
+            .Returns(ValueTask.CompletedTask);
+
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock([]), agentSessionStore: mockSessionStore.Object);
+
+        // Act
+        var events = await CollectEventsAsync(handler, new RequestContext
+        {
+            StreamingResponse = true,
+            TaskId = "",
+            ContextId = "ctx",
+            Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+        });
+
+        // Assert
+        Assert.Empty(events.Messages);
+        mockSessionStore.Verify(
+            x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.Is<string>(s => s == "ctx"),
+                It.IsAny<AgentSession>(),
+                It.IsAny<CancellationToken>()),
+            Times.Once);
+    }
+
+    /// <summary>
+    /// Verifies that the CancellationToken is propagated to RunStreamingAsync in the streaming path.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_CancellationTokenIsPropagatedToRunStreamingAsync()
+    {
+        // Arrange
+        CancellationToken capturedToken = default;
+        using var cts = new CancellationTokenSource();
+
+        Mock<AIAgent> agentMock = new() { CallBase = true };
+        agentMock.SetupGet(x => x.Name).Returns("TestAgent");
+        agentMock
+            .Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(new TestAgentSession());
+        agentMock
+            .Protected()
+            .Setup<IAsyncEnumerable<AgentResponseUpdate>>("RunCoreStreamingAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Callback<IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken>(
+                (_, _, _, ct) => capturedToken = ct)
+            .Returns(() => ToAsyncEnumerableAsync([new AgentResponseUpdate(ChatRole.Assistant, "reply") { ResponseId = "r1" }]));
+
+        A2AAgentHandler handler = CreateHandler(agentMock);
+
+        // Act
+        var eventQueue = new AgentEventQueue();
+        await handler.ExecuteAsync(
+            new RequestContext
+            {
+                TaskId = "",
+                ContextId = "ctx",
+                StreamingResponse = true,
+                Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+            },
+            eventQueue,
+            cts.Token);
+        eventQueue.Complete(null);
+
+        // Assert
+        Assert.Equal(cts.Token, capturedToken);
+    }
+
     /// <summary>
     /// Verifies that when no session store is provided, the handler uses InMemoryAgentSessionStore
     /// and can execute successfully.
@@ -821,6 +1272,308 @@ public sealed class A2AAgentHandlerTests
         Assert.True(capturedOptions.AllowBackgroundResponses);
     }
 
+    /// <summary>
+    /// Verifies that in the non-streaming path, SaveSessionAsync is called with
+    /// CancellationToken.None even when RunAsync throws an exception.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_NonStreaming_WhenRunAsyncThrows_SavesSessionWithUncancelledTokenAsync()
+    {
+        // Arrange
+        var mockSessionStore = new Mock<AgentSessionStore>();
+        mockSessionStore
+            .Setup(x => x.GetSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new TestAgentSession());
+        mockSessionStore
+            .Setup(x => x.SaveSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<AgentSession>(), It.IsAny<CancellationToken>()))
+            .Returns(ValueTask.CompletedTask);
+
+        Mock<AIAgent> agentMock = new() { CallBase = true };
+        agentMock.SetupGet(x => x.Name).Returns("TestAgent");
+        agentMock.Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(new TestAgentSession());
+        agentMock.Protected()
+            .Setup<Task<AgentResponse>>("RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .ThrowsAsync(new InvalidOperationException("Agent failed"));
+
+        using var cts = new CancellationTokenSource();
+        A2AAgentHandler handler = CreateHandler(agentMock, agentSessionStore: mockSessionStore.Object);
+
+        // Act
+        var eventQueue = new AgentEventQueue();
+        await Assert.ThrowsAsync<InvalidOperationException>(() =>
+            handler.ExecuteAsync(
+                new RequestContext
+                {
+                    TaskId = "", ContextId = "ctx", StreamingResponse = false,
+                    Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+                },
+                eventQueue,
+                cts.Token));
+
+        // Assert - SaveSessionAsync was called with CancellationToken.None despite the exception
+        mockSessionStore.Verify(
+            x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.Is<string>(s => s == "ctx"),
+                It.IsAny<AgentSession>(),
+                It.Is<CancellationToken>(ct => ct == CancellationToken.None)),
+            Times.Once);
+    }
+
+    /// <summary>
+    /// Verifies that in the streaming path, SaveSessionAsync is called with
+    /// CancellationToken.None even when RunStreamingAsync throws an exception.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_WhenRunStreamingAsyncThrows_SavesSessionWithUncancelledTokenAsync()
+    {
+        // Arrange
+        var mockSessionStore = new Mock<AgentSessionStore>();
+        mockSessionStore
+            .Setup(x => x.GetSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new TestAgentSession());
+        mockSessionStore
+            .Setup(x => x.SaveSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<AgentSession>(), It.IsAny<CancellationToken>()))
+            .Returns(ValueTask.CompletedTask);
+
+        Mock<AIAgent> agentMock = new() { CallBase = true };
+        agentMock.SetupGet(x => x.Name).Returns("TestAgent");
+        agentMock.Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(new TestAgentSession());
+        agentMock.Protected()
+            .Setup<IAsyncEnumerable<AgentResponseUpdate>>("RunCoreStreamingAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Returns(() => ToThrowingAsyncEnumerableAsync(new InvalidOperationException("Stream failed")));
+
+        using var cts = new CancellationTokenSource();
+        A2AAgentHandler handler = CreateHandler(agentMock, agentSessionStore: mockSessionStore.Object);
+
+        // Act
+        var eventQueue = new AgentEventQueue();
+        await Assert.ThrowsAsync<InvalidOperationException>(() =>
+            handler.ExecuteAsync(
+                new RequestContext
+                {
+                    TaskId = "", ContextId = "ctx-stream", StreamingResponse = true,
+                    Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+                },
+                eventQueue,
+                cts.Token));
+
+        // Assert - SaveSessionAsync was called with CancellationToken.None despite the exception
+        mockSessionStore.Verify(
+            x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.Is<string>(s => s == "ctx-stream"),
+                It.IsAny<AgentSession>(),
+                It.Is<CancellationToken>(ct => ct == CancellationToken.None)),
+            Times.Once);
+    }
+
+    /// <summary>
+    /// Verifies that on the continuation path, SaveSessionAsync is called with
+    /// CancellationToken.None even when RunAsync throws an exception.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_OnContinuation_WhenRunAsyncThrows_SavesSessionWithUncancelledTokenAsync()
+    {
+        // Arrange
+        var mockSessionStore = new Mock<AgentSessionStore>();
+        mockSessionStore
+            .Setup(x => x.GetSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new TestAgentSession());
+        mockSessionStore
+            .Setup(x => x.SaveSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<AgentSession>(), It.IsAny<CancellationToken>()))
+            .Returns(ValueTask.CompletedTask);
+
+        Mock<AIAgent> agentMock = new() { CallBase = true };
+        agentMock.SetupGet(x => x.Name).Returns("TestAgent");
+        agentMock.Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(new TestAgentSession());
+        agentMock.Protected()
+            .Setup<Task<AgentResponse>>("RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .ThrowsAsync(new InvalidOperationException("Agent failed"));
+
+        using var cts = new CancellationTokenSource();
+        A2AAgentHandler handler = CreateHandler(agentMock, agentSessionStore: mockSessionStore.Object);
+
+        // Act
+        var eventQueue = new AgentEventQueue();
+        var events = new EventCollector();
+        var readerTask = ReadEventsAsync(eventQueue, events);
+        await Assert.ThrowsAsync<InvalidOperationException>(() =>
+            handler.ExecuteAsync(
+                new RequestContext
+                {
+                    StreamingResponse = false,
+                    TaskId = "task-1", ContextId = "ctx-cont",
+                    Message = new Message { MessageId = "empty", Role = Role.User, Parts = [] },
+                    Task = new AgentTask { Id = "task-1", ContextId = "ctx-cont", History = [new Message { Role = Role.User, Parts = [new Part { Text = "Hello" }] }] }
+                },
+                eventQueue,
+                cts.Token));
+        eventQueue.Complete(null);
+        await readerTask;
+
+        // Assert - SaveSessionAsync was called with CancellationToken.None despite the exception
+        mockSessionStore.Verify(
+            x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.Is<string>(s => s == "ctx-cont"),
+                It.IsAny<AgentSession>(),
+                It.Is<CancellationToken>(ct => ct == CancellationToken.None)),
+            Times.Once);
+    }
+
+    /// <summary>
+    /// Verifies that in the non-streaming path, SaveSessionAsync is called with
+    /// CancellationToken.None rather than the caller's cancellation token.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_NonStreaming_SavesSessionWithUncancelledTokenAsync()
+    {
+        // Arrange
+        var mockSessionStore = new Mock<AgentSessionStore>();
+        mockSessionStore
+            .Setup(x => x.GetSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new TestAgentSession());
+        mockSessionStore
+            .Setup(x => x.SaveSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<AgentSession>(), It.IsAny<CancellationToken>()))
+            .Returns(ValueTask.CompletedTask);
+
+        AgentResponse response = new([new ChatMessage(ChatRole.Assistant, "Reply")]);
+        A2AAgentHandler handler = CreateHandler(CreateAgentMockWithResponse(response), agentSessionStore: mockSessionStore.Object);
+
+        using var cts = new CancellationTokenSource();
+
+        // Act
+        var eventQueue = new AgentEventQueue();
+        await handler.ExecuteAsync(
+            new RequestContext
+            {
+                TaskId = "", ContextId = "ctx", StreamingResponse = false,
+                Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+            },
+            eventQueue,
+            cts.Token);
+        eventQueue.Complete(null);
+
+        // Assert - SaveSessionAsync was called with CancellationToken.None, not the caller's token
+        mockSessionStore.Verify(
+            x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.Is<string>(s => s == "ctx"),
+                It.IsAny<AgentSession>(),
+                It.Is<CancellationToken>(ct => ct == CancellationToken.None)),
+            Times.Once);
+    }
+
+    /// <summary>
+    /// Verifies that in the streaming path, SaveSessionAsync is called with
+    /// CancellationToken.None rather than the caller's cancellation token.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_Streaming_SavesSessionWithUncancelledTokenAsync()
+    {
+        // Arrange
+        var mockSessionStore = new Mock<AgentSessionStore>();
+        mockSessionStore
+            .Setup(x => x.GetSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new TestAgentSession());
+        mockSessionStore
+            .Setup(x => x.SaveSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<AgentSession>(), It.IsAny<CancellationToken>()))
+            .Returns(ValueTask.CompletedTask);
+
+        AgentResponseUpdate[] updates = [new AgentResponseUpdate(ChatRole.Assistant, "chunk") { ResponseId = "r1" }];
+        A2AAgentHandler handler = CreateHandler(CreateStreamingAgentMock(updates), agentSessionStore: mockSessionStore.Object);
+
+        using var cts = new CancellationTokenSource();
+
+        // Act
+        var eventQueue = new AgentEventQueue();
+        await handler.ExecuteAsync(
+            new RequestContext
+            {
+                TaskId = "", ContextId = "ctx-stream", StreamingResponse = true,
+                Message = new Message { MessageId = "test-id", Role = Role.User, Parts = [new Part { Text = "Hello" }] }
+            },
+            eventQueue,
+            cts.Token);
+        eventQueue.Complete(null);
+
+        // Assert - SaveSessionAsync was called with CancellationToken.None, not the caller's token
+        mockSessionStore.Verify(
+            x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.Is<string>(s => s == "ctx-stream"),
+                It.IsAny<AgentSession>(),
+                It.Is<CancellationToken>(ct => ct == CancellationToken.None)),
+            Times.Once);
+    }
+
+    /// <summary>
+    /// Verifies that on the continuation path, SaveSessionAsync is called with
+    /// CancellationToken.None rather than the caller's cancellation token.
+    /// </summary>
+    [Fact]
+    public async Task ExecuteAsync_OnContinuation_SavesSessionWithUncancelledTokenAsync()
+    {
+        // Arrange
+        var mockSessionStore = new Mock<AgentSessionStore>();
+        mockSessionStore
+            .Setup(x => x.GetSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
+            .ReturnsAsync(new TestAgentSession());
+        mockSessionStore
+            .Setup(x => x.SaveSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<AgentSession>(), It.IsAny<CancellationToken>()))
+            .Returns(ValueTask.CompletedTask);
+
+        AgentResponse response = new([new ChatMessage(ChatRole.Assistant, "Done!")]);
+        A2AAgentHandler handler = CreateHandler(CreateAgentMockWithResponse(response), agentSessionStore: mockSessionStore.Object);
+
+        using var cts = new CancellationTokenSource();
+
+        // Act
+        var eventQueue = new AgentEventQueue();
+        var events = new EventCollector();
+        var readerTask = ReadEventsAsync(eventQueue, events);
+        await handler.ExecuteAsync(
+            new RequestContext
+            {
+                StreamingResponse = false,
+                TaskId = "task-1", ContextId = "ctx-cont",
+                Message = new Message { MessageId = "empty", Role = Role.User, Parts = [] },
+                Task = new AgentTask { Id = "task-1", ContextId = "ctx-cont", History = [new Message { Role = Role.User, Parts = [new Part { Text = "Hello" }] }] }
+            },
+            eventQueue,
+            cts.Token);
+        eventQueue.Complete(null);
+        await readerTask;
+
+        // Assert - SaveSessionAsync was called with CancellationToken.None, not the caller's token
+        mockSessionStore.Verify(
+            x => x.SaveSessionAsync(
+                It.IsAny<AIAgent>(),
+                It.Is<string>(s => s == "ctx-cont"),
+                It.IsAny<AgentSession>(),
+                It.Is<CancellationToken>(ct => ct == CancellationToken.None)),
+            Times.Once);
+    }
+
     private static A2AAgentHandler CreateHandler(
         Mock<AIAgent> agentMock,
         AgentRunMode? runMode = null,
@@ -905,6 +1658,68 @@ public sealed class A2AAgentHandlerTests
         return agentMock;
     }
 
+    private static Mock<AIAgent> CreateStreamingAgentMock(IEnumerable<AgentResponseUpdate> updates)
+    {
+        Mock<AIAgent> agentMock = new() { CallBase = true };
+        agentMock.SetupGet(x => x.Name).Returns("TestAgent");
+        agentMock
+            .Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(new TestAgentSession());
+        agentMock
+            .Protected()
+            .Setup<IAsyncEnumerable<AgentResponseUpdate>>("RunCoreStreamingAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Returns(() => ToAsyncEnumerableAsync(updates));
+
+        return agentMock;
+    }
+
+    private static Mock<AIAgent> CreateStreamingAgentMockWithOptionsCapture(
+        Action<AgentRunOptions?> optionsCallback)
+    {
+        Mock<AIAgent> agentMock = new() { CallBase = true };
+        agentMock.SetupGet(x => x.Name).Returns("TestAgent");
+        agentMock
+            .Protected()
+            .Setup<ValueTask<AgentSession>>("CreateSessionCoreAsync", ItExpr.IsAny<CancellationToken>())
+            .ReturnsAsync(new TestAgentSession());
+        agentMock
+            .Protected()
+            .Setup<IAsyncEnumerable<AgentResponseUpdate>>("RunCoreStreamingAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession?>(),
+                ItExpr.IsAny<AgentRunOptions?>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Callback<IEnumerable<ChatMessage>, AgentSession?, AgentRunOptions?, CancellationToken>(
+                (_, _, options, _) => optionsCallback(options))
+            .Returns(() => ToAsyncEnumerableAsync([new AgentResponseUpdate(ChatRole.Assistant, "reply") { ResponseId = "r1" }]));
+
+        return agentMock;
+    }
+
+    private static async IAsyncEnumerable<T> ToAsyncEnumerableAsync<T>(IEnumerable<T> items)
+    {
+        await Task.Yield();
+        foreach (var item in items)
+        {
+            yield return item;
+        }
+    }
+
+    private static async IAsyncEnumerable<AgentResponseUpdate> ToThrowingAsyncEnumerableAsync(Exception exception)
+    {
+        await Task.Yield();
+        throw exception;
+
+#pragma warning disable CS0162 // Unreachable code detected - yield is required for async iterator
+        yield break;
+#pragma warning restore CS0162
+    }
+
     private static async Task InvokeExecuteAsync(A2AAgentHandler handler, RequestContext context)
     {
         var eventQueue = new AgentEventQueue();

dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Converters/MessageConverterTests.cs

@@ -147,4 +147,67 @@ public class MessageConverterTests
         Assert.Equal("First message", result[0].Text);
         Assert.Equal("Second message", result[1].Text);
     }
+
+    [Fact]
+    public void ToParts_AgentResponseUpdate_WithNoContents_ReturnsEmptyList()
+    {
+        // Arrange
+        var update = new AgentResponseUpdate();
+
+        // Act
+        var result = update.ToParts();
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.Empty(result);
+    }
+
+    [Fact]
+    public void ToParts_AgentResponseUpdate_WithTextContent_ReturnsTextPart()
+    {
+        // Arrange
+        var update = new AgentResponseUpdate(ChatRole.Assistant, "Hello from streaming!");
+
+        // Act
+        var result = update.ToParts();
+
+        // Assert
+        Assert.Single(result);
+        Assert.Equal("Hello from streaming!", result[0].Text);
+    }
+
+    [Fact]
+    public void ToParts_AgentResponseUpdate_WithMultipleContents_ReturnsAllParts()
+    {
+        // Arrange
+        var update = new AgentResponseUpdate(ChatRole.Assistant, [
+            new TextContent("First chunk"),
+            new TextContent("Second chunk")
+        ]);
+
+        // Act
+        var result = update.ToParts();
+
+        // Assert
+        Assert.Equal(2, result.Count);
+        Assert.Equal("First chunk", result[0].Text);
+        Assert.Equal("Second chunk", result[1].Text);
+    }
+
+    [Fact]
+    public void ToParts_AgentResponseUpdate_WithUnsupportedContent_FiltersOutNulls()
+    {
+        // Arrange - FunctionCallContent maps to null Part since it's not a supported A2A content type
+        var update = new AgentResponseUpdate(ChatRole.Assistant, [
+            new TextContent("Supported text"),
+            new FunctionCallContent("call-1", "myFunction")
+        ]);
+
+        // Act
+        var result = update.ToParts();
+
+        // Assert - only the text part should be returned
+        Assert.Single(result);
+        Assert.Equal("Supported text", result[0].Text);
+    }
 }

dotnet/tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/WorkflowSamplesValidation.cs

@@ -3,6 +3,7 @@
 using System.Diagnostics;
 using System.Reflection;
 using System.Text;
+using System.Text.Json;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Logging;
 using ModelContextProtocol.Client;
@@ -125,6 +126,45 @@ public sealed class WorkflowSamplesValidation(ITestOutputHelper outputHelper) :
                 },
                 message: "OrderStatus workflow completed",
                 timeout: s_orchestrationTimeout);
+
+            // Test the CancelOrder workflow with x-ms-wait-for-response header
+            this._outputHelper.WriteLine("Starting CancelOrder workflow with x-ms-wait-for-response: true...");
+
+            using HttpRequestMessage waitRequest = new(HttpMethod.Post, cancelOrderUri);
+            waitRequest.Content = new StringContent("55555", Encoding.UTF8, "text/plain");
+            waitRequest.Headers.Add("x-ms-wait-for-response", "true");
+            using HttpResponseMessage waitResponse = await s_sharedHttpClient.SendAsync(waitRequest);
+
+            Assert.True(waitResponse.IsSuccessStatusCode, $"CancelOrder wait-for-response request failed with status: {waitResponse.StatusCode}");
+            string waitResponseText = await waitResponse.Content.ReadAsStringAsync();
+            this._outputHelper.WriteLine($"CancelOrder wait-for-response result: {waitResponseText}");
+
+            // The response should contain the workflow result (not just "started for CancelOrder")
+            Assert.DoesNotContain("Workflow orchestration started", waitResponseText);
+            Assert.Contains("55555", waitResponseText);
+
+            // Test the wait-for-response with Accept: application/json header
+            this._outputHelper.WriteLine("Starting CancelOrder workflow with x-ms-wait-for-response and Accept: application/json...");
+
+            using HttpRequestMessage jsonWaitRequest = new(HttpMethod.Post, cancelOrderUri);
+            jsonWaitRequest.Content = new StringContent("77777", Encoding.UTF8, "text/plain");
+            jsonWaitRequest.Headers.Add("x-ms-wait-for-response", "true");
+            jsonWaitRequest.Headers.Add("Accept", "application/json");
+
+            using CancellationTokenSource jsonWaitCts = new(s_orchestrationTimeout);
+            using HttpResponseMessage jsonWaitResponse = await s_sharedHttpClient.SendAsync(jsonWaitRequest, jsonWaitCts.Token);
+
+            Assert.True(jsonWaitResponse.IsSuccessStatusCode, $"CancelOrder JSON wait-for-response request failed with status: {jsonWaitResponse.StatusCode}");
+            string jsonWaitResponseText = await jsonWaitResponse.Content.ReadAsStringAsync();
+            this._outputHelper.WriteLine($"CancelOrder JSON wait-for-response result: {jsonWaitResponseText}");
+
+            using JsonDocument jsonDoc = JsonDocument.Parse(jsonWaitResponseText);
+            JsonElement root = jsonDoc.RootElement;
+            Assert.True(root.TryGetProperty("runId", out _), "JSON response missing 'runId' property");
+            Assert.True(root.TryGetProperty("workflowStatus", out JsonElement statusEl), "JSON response missing 'workflowStatus' property");
+            Assert.Equal("Completed", statusEl.GetString());
+            Assert.True(root.TryGetProperty("result", out JsonElement resultEl), "JSON response missing 'result' property");
+            Assert.Contains("77777", resultEl.GetString());
         });
     }
 

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentClassSkillTests.cs

@@ -8,7 +8,6 @@ using System.Reflection;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
 using Microsoft.Extensions.DependencyInjection;
 
 namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
@@ -128,8 +127,9 @@ public sealed class AgentClassSkillTests
         // Act — script with custom type deserialization
         var script = skill.Scripts![0];
         var inputJson = JsonSerializer.SerializeToElement(new LookupRequest { Query = "test", MaxResults = 5 }, jso);
-        var args = new AIFunctionArguments { ["request"] = inputJson };
-        var scriptResult = await script.RunAsync(skill, args, CancellationToken.None);
+        using var argsDoc = JsonDocument.Parse($$"""{ "request": {{inputJson.GetRawText()}} }""");
+        var args = argsDoc.RootElement;
+        var scriptResult = await script.RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert
         Assert.NotNull(scriptResult);
@@ -173,12 +173,14 @@ public sealed class AgentClassSkillTests
 
         // Act & Assert — static method
         var doWorkScript = skill.Scripts!.First(s => s.Name == "do-work");
-        var doWorkResult = await doWorkScript.RunAsync(skill, new AIFunctionArguments { ["input"] = "hello" }, CancellationToken.None);
+        using var doWorkDoc = JsonDocument.Parse("""{"input":"hello"}""");
+        var doWorkResult = await doWorkScript.RunAsync(skill, doWorkDoc.RootElement, null, CancellationToken.None);
         Assert.Equal("HELLO", doWorkResult?.ToString());
 
         // Act & Assert — instance method
         var appendScript = skill.Scripts!.First(s => s.Name == "append");
-        var appendResult = await appendScript.RunAsync(skill, new AIFunctionArguments { ["input"] = "test" }, CancellationToken.None);
+        using var appendDoc = JsonDocument.Parse("""{"input":"test"}""");
+        var appendResult = await appendScript.RunAsync(skill, appendDoc.RootElement, null, CancellationToken.None);
         Assert.Equal("test-suffix", appendResult?.ToString());
     }
 
@@ -367,7 +369,7 @@ public sealed class AgentClassSkillTests
         // Act & Assert — all scripts produce values
         foreach (var script in skill.Scripts!)
         {
-            var result = await script.RunAsync(skill, new AIFunctionArguments(), CancellationToken.None);
+            var result = await script.RunAsync(skill, null, null, CancellationToken.None);
             Assert.NotNull(result);
         }
     }
@@ -382,8 +384,9 @@ public sealed class AgentClassSkillTests
         // Act & Assert — script with custom JSO
         var script = skill.Scripts![0];
         var inputJson = JsonSerializer.SerializeToElement(new LookupRequest { Query = "test", MaxResults = 3 }, jso);
-        var args = new AIFunctionArguments { ["request"] = inputJson };
-        var scriptResult = await script.RunAsync(skill, args, CancellationToken.None);
+        using var argsDoc = JsonDocument.Parse($$"""{ "request": {{inputJson.GetRawText()}} }""");
+        var args = argsDoc.RootElement;
+        var scriptResult = await script.RunAsync(skill, args, null, CancellationToken.None);
         Assert.NotNull(scriptResult);
         Assert.Contains("test", scriptResult!.ToString()!);
         Assert.Contains("3", scriptResult!.ToString()!);
@@ -497,8 +500,9 @@ public sealed class AgentClassSkillTests
         var script = skill.Scripts!.First(s => s.Name == "Lookup");
         var jso = SkillTestJsonContext.Default.Options;
         var inputJson = JsonSerializer.SerializeToElement(new LookupRequest { Query = "fallback", MaxResults = 7 }, jso);
-        var args = new AIFunctionArguments { ["request"] = inputJson };
-        var result = await script.RunAsync(skill, args, CancellationToken.None);
+        using var argsDoc = JsonDocument.Parse($$"""{ "request": {{inputJson.GetRawText()}} }""");
+        var args = argsDoc.RootElement;
+        var result = await script.RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert
         Assert.NotNull(result);
@@ -531,8 +535,9 @@ public sealed class AgentClassSkillTests
         var script = skill.Scripts!.First(s => s.Name == "Lookup");
         var jso = SkillTestJsonContext.Default.Options;
         var inputJson = JsonSerializer.SerializeToElement(new LookupRequest { Query = "explicit", MaxResults = 2 }, jso);
-        var args = new AIFunctionArguments { ["request"] = inputJson };
-        var result = await script.RunAsync(skill, args, CancellationToken.None);
+        using var argsDoc = JsonDocument.Parse($$"""{ "request": {{inputJson.GetRawText()}} }""");
+        var args = argsDoc.RootElement;
+        var result = await script.RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert
         Assert.NotNull(result);

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentFileSkillScriptTests.cs

@@ -1,9 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
 
@@ -16,13 +16,13 @@ public sealed class AgentFileSkillScriptTests
     public async Task RunAsync_SkillIsNotAgentFileSkill_ThrowsInvalidOperationExceptionAsync()
     {
         // Arrange
-        static Task<object?> RunnerAsync(AgentFileSkill s, AgentFileSkillScript sc, AIFunctionArguments a, CancellationToken ct) => Task.FromResult<object?>("result");
+        static Task<object?> RunnerAsync(AgentFileSkill s, AgentFileSkillScript sc, JsonElement? a, IServiceProvider? sp, CancellationToken ct) => Task.FromResult<object?>("result");
         var script = CreateScript("test-script", "/path/to/script.py", RunnerAsync);
         var nonFileSkill = new TestAgentSkill("my-skill", "A skill", "Instructions.");
 
         // Act & Assert
         await Assert.ThrowsAsync<InvalidOperationException>(
-            () => script.RunAsync(nonFileSkill, new AIFunctionArguments(), CancellationToken.None));
+            () => script.RunAsync(nonFileSkill, null, null, CancellationToken.None));
     }
 
     [Fact]
@@ -30,7 +30,7 @@ public sealed class AgentFileSkillScriptTests
     {
         // Arrange
         var runnerCalled = false;
-        Task<object?> runnerAsync(AgentFileSkill skill, AgentFileSkillScript scriptArg, AIFunctionArguments args, CancellationToken ct)
+        Task<object?> runnerAsync(AgentFileSkill skill, AgentFileSkillScript scriptArg, JsonElement? args, IServiceProvider? sp, CancellationToken ct)
         {
             runnerCalled = true;
             return Task.FromResult<object?>("executed");
@@ -42,7 +42,7 @@ public sealed class AgentFileSkillScriptTests
             "/skills/my-skill");
 
         // Act
-        var result = await script.RunAsync(fileSkill, new AIFunctionArguments(), CancellationToken.None);
+        var result = await script.RunAsync(fileSkill, null, null, CancellationToken.None);
 
         // Assert
         Assert.True(runnerCalled);
@@ -55,7 +55,7 @@ public sealed class AgentFileSkillScriptTests
         // Arrange
         AgentFileSkill? capturedSkill = null;
         AgentFileSkillScript? capturedScript = null;
-        Task<object?> runnerAsync(AgentFileSkill skill, AgentFileSkillScript scriptArg, AIFunctionArguments args, CancellationToken ct)
+        Task<object?> runnerAsync(AgentFileSkill skill, AgentFileSkillScript scriptArg, JsonElement? args, IServiceProvider? sp, CancellationToken ct)
         {
             capturedSkill = skill;
             capturedScript = scriptArg;
@@ -68,7 +68,7 @@ public sealed class AgentFileSkillScriptTests
             "/skills/owner-skill");
 
         // Act
-        await script.RunAsync(fileSkill, new AIFunctionArguments(), CancellationToken.None);
+        await script.RunAsync(fileSkill, null, null, CancellationToken.None);
 
         // Assert
         Assert.Same(fileSkill, capturedSkill);
@@ -79,7 +79,7 @@ public sealed class AgentFileSkillScriptTests
     public void Script_HasCorrectNameAndPath()
     {
         // Arrange & Act
-        static Task<object?> RunnerAsync(AgentFileSkill s, AgentFileSkillScript sc, AIFunctionArguments a, CancellationToken ct) => Task.FromResult<object?>(null);
+        static Task<object?> RunnerAsync(AgentFileSkill s, AgentFileSkillScript sc, JsonElement? a, IServiceProvider? sp, CancellationToken ct) => Task.FromResult<object?>(null);
         var script = CreateScript("my-script", "/path/to/my-script.py", RunnerAsync);
 
         // Assert
@@ -87,10 +87,173 @@ public sealed class AgentFileSkillScriptTests
         Assert.Equal("/path/to/my-script.py", script.FullPath);
     }
 
+    [Fact]
+    public void ParametersSchema_ReturnsExpectedArraySchema()
+    {
+        // Arrange
+        static Task<object?> RunnerAsync(AgentFileSkill s, AgentFileSkillScript sc, JsonElement? a, IServiceProvider? sp, CancellationToken ct) => Task.FromResult<object?>(null);
+        var script = CreateScript("my-script", "/path/to/script.py", RunnerAsync);
+
+        // Act
+        var schema = script.ParametersSchema;
+
+        // Assert
+        Assert.NotNull(schema);
+        var raw = schema!.Value.GetRawText();
+        Assert.Contains("\"type\":\"array\"", raw);
+        Assert.Contains("\"items\":{\"type\":\"string\"}", raw);
+    }
+
+    [Fact]
+    public void Content_WithScripts_AppendsPerScriptEntries()
+    {
+        // Arrange
+        static Task<object?> RunnerAsync(AgentFileSkill s, AgentFileSkillScript sc, JsonElement? a, IServiceProvider? sp, CancellationToken ct) => Task.FromResult<object?>(null);
+        var script1 = CreateScript("build", "/scripts/build.sh", RunnerAsync);
+        var script2 = CreateScript("deploy", "/scripts/deploy.sh", RunnerAsync);
+        var fileSkill = new AgentFileSkill(
+            new AgentSkillFrontmatter("my-skill", "A skill"),
+            "Original content",
+            "/skills/my-skill",
+            scripts: [script1, script2]);
+
+        // Act
+        var content = fileSkill.Content;
+
+        // Assert — content starts with original and appends per-script entries
+        Assert.StartsWith("Original content", content);
+        Assert.Contains("<scripts>", content);
+        Assert.Contains("<script name=\"build\">", content);
+        Assert.Contains("<script name=\"deploy\">", content);
+        Assert.Contains("<parameters_schema>", content);
+        Assert.Contains("</scripts>", content);
+    }
+
+    [Fact]
+    public void Content_WithoutScripts_ReturnsOriginalContent()
+    {
+        // Arrange
+        var fileSkill = new AgentFileSkill(
+            new AgentSkillFrontmatter("my-skill", "A skill"),
+            "Original content only",
+            "/skills/my-skill");
+
+        // Act
+        var content = fileSkill.Content;
+
+        // Assert
+        Assert.Equal("Original content only", content);
+    }
+
+    [Fact]
+    public void Content_WithScripts_IsCached()
+    {
+        // Arrange
+        static Task<object?> RunnerAsync(AgentFileSkill s, AgentFileSkillScript sc, JsonElement? a, IServiceProvider? sp, CancellationToken ct) => Task.FromResult<object?>(null);
+        var script = CreateScript("test", "/scripts/test.sh", RunnerAsync);
+        var fileSkill = new AgentFileSkill(
+            new AgentSkillFrontmatter("my-skill", "A skill"),
+            "Content",
+            "/skills/my-skill",
+            scripts: [script]);
+
+        // Act
+        var content1 = fileSkill.Content;
+        var content2 = fileSkill.Content;
+
+        // Assert
+        Assert.Same(content1, content2);
+    }
+
+    [Fact]
+    public async Task RunAsync_ForwardsJsonArrayArgumentsToRunnerAsync()
+    {
+        // Arrange
+        JsonElement? capturedArgs = null;
+        Task<object?> runnerAsync(AgentFileSkill skill, AgentFileSkillScript scriptArg, JsonElement? args, IServiceProvider? sp, CancellationToken ct)
+        {
+            capturedArgs = args;
+            return Task.FromResult<object?>("done");
+        }
+        var script = CreateScript("array-test", "/scripts/test.sh", runnerAsync);
+        var fileSkill = new AgentFileSkill(
+            new AgentSkillFrontmatter("my-skill", "A skill"),
+            "Content",
+            "/skills/my-skill");
+        using var arrayArgsDoc = JsonDocument.Parse("""["arg1","arg2","arg3"]""");
+        var arrayArgs = arrayArgsDoc.RootElement;
+
+        // Act
+        await script.RunAsync(fileSkill, arrayArgs, null, CancellationToken.None);
+
+        // Assert — the raw JSON array is forwarded unchanged
+        Assert.NotNull(capturedArgs);
+        Assert.Equal(JsonValueKind.Array, capturedArgs!.Value.ValueKind);
+        Assert.Equal("""["arg1","arg2","arg3"]""", capturedArgs.Value.GetRawText());
+    }
+
+    [Fact]
+    public async Task RunAsync_ForwardsServiceProviderToRunnerAsync()
+    {
+        // Arrange
+        IServiceProvider? capturedProvider = null;
+        Task<object?> runnerAsync(AgentFileSkill skill, AgentFileSkillScript scriptArg, JsonElement? args, IServiceProvider? sp, CancellationToken ct)
+        {
+            capturedProvider = sp;
+            return Task.FromResult<object?>("done");
+        }
+        var script = CreateScript("sp-test", "/scripts/test.sh", runnerAsync);
+        var fileSkill = new AgentFileSkill(
+            new AgentSkillFrontmatter("my-skill", "A skill"),
+            "Content",
+            "/skills/my-skill");
+        var mockProvider = new TestServiceProvider();
+
+        // Act
+        await script.RunAsync(fileSkill, null, mockProvider, CancellationToken.None);
+
+        // Assert
+        Assert.Same(mockProvider, capturedProvider);
+    }
+
+    [Fact]
+    public async Task RunAsync_NoRunner_ThrowsInvalidOperationExceptionAsync()
+    {
+        // Arrange — create script without a runner
+        var script = CreateScript("no-runner", "/scripts/test.sh", runner: null);
+        var fileSkill = new AgentFileSkill(
+            new AgentSkillFrontmatter("my-skill", "A skill"),
+            "Content",
+            "/skills/my-skill");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<InvalidOperationException>(
+            () => script.RunAsync(fileSkill, null, null, CancellationToken.None));
+    }
+
+    [Fact]
+    public void Content_WithScripts_ContainsDefaultParametersSchema()
+    {
+        // Arrange
+        static Task<object?> RunnerAsync(AgentFileSkill s, AgentFileSkillScript sc, JsonElement? a, IServiceProvider? sp, CancellationToken ct) => Task.FromResult<object?>(null);
+        var script = CreateScript("test", "/scripts/test.sh", RunnerAsync);
+        var fileSkill = new AgentFileSkill(
+            new AgentSkillFrontmatter("my-skill", "A skill"),
+            "Original content",
+            "/skills/my-skill",
+            scripts: [script]);
+
+        // Act
+        var content = fileSkill.Content;
+
+        // Assert — the appended block contains the actual default schema from AgentFileSkillScript
+        Assert.Contains("""{"type":"array","items":{"type":"string"}}""", content);
+    }
+
     /// <summary>
     /// Helper to create an <see cref="AgentFileSkillScript"/> via reflection since the constructor is internal.
     /// </summary>
-    private static AgentFileSkillScript CreateScript(string name, string fullPath, AgentFileSkillScriptRunner executor)
+    private static AgentFileSkillScript CreateScript(string name, string fullPath, AgentFileSkillScriptRunner? runner)
     {
         var ctor = typeof(AgentFileSkillScript).GetConstructor(
             System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance,
@@ -98,6 +261,14 @@ public sealed class AgentFileSkillScriptTests
             [typeof(string), typeof(string), typeof(AgentFileSkillScriptRunner)],
             null) ?? throw new InvalidOperationException("Could not find internal constructor.");
 
-        return (AgentFileSkillScript)ctor.Invoke([name, fullPath, executor]);
+        return (AgentFileSkillScript)ctor.Invoke([name, fullPath, runner]);
+    }
+
+    /// <summary>
+    /// Minimal <see cref="IServiceProvider"/> for testing service forwarding.
+    /// </summary>
+    private sealed class TestServiceProvider : IServiceProvider
+    {
+        public object? GetService(Type serviceType) => null;
     }
 }

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentFileSkillsSourceScriptTests.cs

@@ -3,9 +3,9 @@
 using System;
 using System.IO;
 using System.Linq;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
 
@@ -15,7 +15,7 @@ namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
 public sealed class AgentFileSkillsSourceScriptTests : IDisposable
 {
     private static readonly string[] s_rubyExtension = new[] { ".rb" };
-    private static readonly AgentFileSkillScriptRunner s_noOpExecutor = (skill, script, args, ct) => Task.FromResult<object?>(null);
+    private static readonly AgentFileSkillScriptRunner s_noOpExecutor = (skill, script, args, sp, ct) => Task.FromResult<object?>(null);
 
     private readonly string _testRoot;
 
@@ -139,7 +139,7 @@ public sealed class AgentFileSkillsSourceScriptTests : IDisposable
         var executorCalled = false;
         var source = new AgentFileSkillsSource(
             this._testRoot,
-            (skill, script, args, ct) =>
+            (skill, script, args, sp, ct) =>
             {
                 executorCalled = true;
                 Assert.Equal("exec-skill", skill.Frontmatter.Name);
@@ -150,7 +150,7 @@ public sealed class AgentFileSkillsSourceScriptTests : IDisposable
 
         // Act
         var skills = await source.GetSkillsAsync(CancellationToken.None);
-        var scriptResult = await skills[0].Scripts![0].RunAsync(skills[0], new AIFunctionArguments(), CancellationToken.None);
+        var scriptResult = await skills[0].Scripts![0].RunAsync(skills[0], null, null, CancellationToken.None);
 
         // Assert
         Assert.True(executorCalled);
@@ -178,7 +178,7 @@ public sealed class AgentFileSkillsSourceScriptTests : IDisposable
         var script = skills[0].Scripts![0];
 
         // Assert — running the script throws because no runner was provided
-        await Assert.ThrowsAsync<InvalidOperationException>(() => script.RunAsync(skills[0], new AIFunctionArguments(), CancellationToken.None));
+        await Assert.ThrowsAsync<InvalidOperationException>(() => script.RunAsync(skills[0], null, null, CancellationToken.None));
     }
 
     [Fact]
@@ -204,10 +204,10 @@ public sealed class AgentFileSkillsSourceScriptTests : IDisposable
     {
         // Arrange
         CreateSkillWithScript(this._testRoot, "args-skill", "Args test", "Body.", "scripts/test.py", "print('ok')");
-        AIFunctionArguments? capturedArgs = null;
+        JsonElement? capturedArgs = null;
         var source = new AgentFileSkillsSource(
             this._testRoot,
-            (skill, script, args, ct) =>
+            (skill, script, args, sp, ct) =>
             {
                 capturedArgs = args;
                 return Task.FromResult<object?>("done");
@@ -215,17 +215,15 @@ public sealed class AgentFileSkillsSourceScriptTests : IDisposable
 
         // Act
         var skills = await source.GetSkillsAsync(CancellationToken.None);
-        var arguments = new AIFunctionArguments
-        {
-            ["value"] = 26.2,
-            ["factor"] = 1.60934
-        };
-        await skills[0].Scripts![0].RunAsync(skills[0], arguments, CancellationToken.None);
+        using var argumentsDoc = JsonDocument.Parse("""{"value":26.2,"factor":1.60934}""");
+        var arguments = argumentsDoc.RootElement;
+        await skills[0].Scripts![0].RunAsync(skills[0], arguments, null, CancellationToken.None);
 
         // Assert
         Assert.NotNull(capturedArgs);
-        Assert.Equal(26.2, capturedArgs["value"]);
-        Assert.Equal(1.60934, capturedArgs["factor"]);
+        Assert.Equal(JsonValueKind.Object, capturedArgs!.Value.ValueKind);
+        Assert.Equal(26.2, capturedArgs.Value.GetProperty("value").GetDouble());
+        Assert.Equal(1.60934, capturedArgs.Value.GetProperty("factor").GetDouble());
     }
 
     [Fact]

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentInlineSkillScriptTests.cs

@@ -5,7 +5,6 @@ using System.Reflection;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
 
@@ -22,7 +21,7 @@ public sealed class AgentInlineSkillScriptTests
         var skill = new AgentInlineSkill("test-skill", "Test.", "Instructions.");
 
         // Act
-        var result = await script.RunAsync(skill, new AIFunctionArguments(), CancellationToken.None);
+        var result = await script.RunAsync(skill, null, null, CancellationToken.None);
 
         // Assert
         Assert.Equal("hello", result?.ToString());
@@ -34,10 +33,11 @@ public sealed class AgentInlineSkillScriptTests
         // Arrange
         var script = new AgentInlineSkillScript("add", (int a, int b) => a + b);
         var skill = new AgentInlineSkill("calc-skill", "Calc.", "Instructions.");
-        var args = new AIFunctionArguments { ["a"] = 3, ["b"] = 7 };
+        using var argsDoc = JsonDocument.Parse("""{"a":3,"b":7}""");
+        var args = argsDoc.RootElement;
 
         // Act
-        var result = await script.RunAsync(skill, args, CancellationToken.None);
+        var result = await script.RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert
         Assert.Equal(10, int.Parse(result?.ToString()!));
@@ -129,10 +129,11 @@ public sealed class AgentInlineSkillScriptTests
         }, serializerOptions: jso);
         var skill = new AgentInlineSkill("test-skill", "Test.", "Instructions.");
         var inputJson = JsonSerializer.SerializeToElement(new LookupRequest { Query = "test", MaxResults = 5 }, jso);
-        var args = new AIFunctionArguments { ["request"] = inputJson };
+        using var argsDoc = JsonDocument.Parse($$"""{ "request": {{inputJson.GetRawText()}} }""");
+        var args = argsDoc.RootElement;
 
         // Act
-        var result = await script.RunAsync(skill, args, CancellationToken.None);
+        var result = await script.RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert — the custom input type was deserialized and the response was produced
         Assert.NotNull(result);
@@ -145,10 +146,11 @@ public sealed class AgentInlineSkillScriptTests
         // Arrange
         var script = new AgentInlineSkillScript("echo", (string message) => message);
         var skill = new AgentInlineSkill("test-skill", "Test.", "Instructions.");
-        var args = new AIFunctionArguments { ["message"] = "hello world" };
+        using var argsDoc = JsonDocument.Parse("""{"message":"hello world"}""");
+        var args = argsDoc.RootElement;
 
         // Act
-        var result = await script.RunAsync(skill, args, CancellationToken.None);
+        var result = await script.RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert
         Assert.Equal("hello world", result?.ToString());
@@ -175,10 +177,11 @@ public sealed class AgentInlineSkillScriptTests
         var method = typeof(AgentInlineSkillScriptTests).GetMethod(nameof(StaticScriptHelper), BindingFlags.NonPublic | BindingFlags.Static)!;
         var script = new AgentInlineSkillScript("static-method-script", method, target: null);
         var skill = new AgentInlineSkill("test-skill", "Test.", "Instructions.");
-        var args = new AIFunctionArguments { ["input"] = "hello" };
+        using var argsDoc = JsonDocument.Parse("""{"input":"hello"}""");
+        var args = argsDoc.RootElement;
 
         // Act
-        var result = await script.RunAsync(skill, args, CancellationToken.None);
+        var result = await script.RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert
         Assert.Equal("HELLO", result?.ToString());
@@ -191,10 +194,11 @@ public sealed class AgentInlineSkillScriptTests
         var method = typeof(AgentInlineSkillScriptTests).GetMethod(nameof(InstanceScriptHelper), BindingFlags.NonPublic | BindingFlags.Instance)!;
         var script = new AgentInlineSkillScript("instance-method-script", method, target: this);
         var skill = new AgentInlineSkill("test-skill", "Test.", "Instructions.");
-        var args = new AIFunctionArguments { ["input"] = "test" };
+        using var argsDoc2 = JsonDocument.Parse("""{"input":"test"}""");
+        var args2 = argsDoc2.RootElement;
 
         // Act
-        var result = await script.RunAsync(skill, args, CancellationToken.None);
+        var result = await script.RunAsync(skill, args2, null, CancellationToken.None);
 
         // Assert
         Assert.Equal("test-suffix", result?.ToString());
@@ -223,7 +227,63 @@ public sealed class AgentInlineSkillScriptTests
         Assert.Contains("input", schema!.Value.GetRawText());
     }
 
+    [Fact]
+    public async Task RunAsync_WithNonObjectArguments_ThrowsInvalidOperationExceptionAsync()
+    {
+        // Arrange — inline scripts require a JSON object for arguments
+        var script = new AgentInlineSkillScript("noop", () => "ok");
+        var skill = new AgentInlineSkill("test-skill", "Test.", "Instructions.");
+        using var arrayArgsDoc = JsonDocument.Parse("""["a","b"]""");
+        var arrayArgs = arrayArgsDoc.RootElement;
+
+        // Act & Assert — non-object JSON should fail fast rather than silently dropping arguments
+        await Assert.ThrowsAsync<InvalidOperationException>(
+            () => script.RunAsync(skill, arrayArgs, null, CancellationToken.None));
+    }
+
+    [Fact]
+    public async Task RunAsync_WithNullArguments_TreatsAsNoArgumentsAsync()
+    {
+        // Arrange — a parameterless delegate should succeed when given null arguments
+        var script = new AgentInlineSkillScript("noop", () => "ok");
+        var skill = new AgentInlineSkill("test-skill", "Test.", "Instructions.");
+
+        // Act
+        var result = await script.RunAsync(skill, null, null, CancellationToken.None);
+
+        // Assert
+        Assert.Equal("ok", result?.ToString());
+    }
+
+    [Fact]
+    public async Task RunAsync_ServiceProviderIsForwardedAsync()
+    {
+        // Arrange — delegate that resolves a service from the IServiceProvider
+        IServiceProvider? capturedProvider = null;
+        var script = new AgentInlineSkillScript("svc-test", (IServiceProvider sp) =>
+        {
+            capturedProvider = sp;
+            return "done";
+        });
+        var skill = new AgentInlineSkill("test-skill", "Test.", "Instructions.");
+        var mockProvider = new TestServiceProvider();
+
+        // Act
+        await script.RunAsync(skill, null, mockProvider, CancellationToken.None);
+
+        // Assert
+        Assert.Same(mockProvider, capturedProvider);
+    }
+
     private static string StaticScriptHelper(string input) => input.ToUpperInvariant();
 
     private string InstanceScriptHelper(string input) => input + "-suffix";
+
+    /// <summary>
+    /// Minimal <see cref="IServiceProvider"/> for testing service forwarding.
+    /// </summary>
+    private sealed class TestServiceProvider : IServiceProvider
+    {
+        public object? GetService(Type serviceType) => null;
+    }
 }

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentInlineSkillTests.cs

@@ -433,10 +433,11 @@ public sealed class AgentInlineSkillTests
             TotalCount = request.MaxResults,
         });
         var inputJson = JsonSerializer.SerializeToElement(new LookupRequest { Query = "test", MaxResults = 3 }, jso);
-        var args = new AIFunctionArguments { ["request"] = inputJson };
+        using var argsDoc = JsonDocument.Parse($$"""{ "request": {{inputJson.GetRawText()}} }""");
+        var args = argsDoc.RootElement;
 
         // Act
-        var result = await skill.Scripts![0].RunAsync(skill, args, CancellationToken.None);
+        var result = await skill.Scripts![0].RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert — the custom input was deserialized via skill-level JSO and response was produced
         Assert.NotNull(result);
@@ -456,10 +457,11 @@ public sealed class AgentInlineSkillTests
             TotalCount = request.MaxResults,
         }, serializerOptions: scriptJso);
         var inputJson = JsonSerializer.SerializeToElement(new LookupRequest { Query = "override", MaxResults = 7 }, scriptJso);
-        var args = new AIFunctionArguments { ["request"] = inputJson };
+        using var argsDoc = JsonDocument.Parse($$"""{ "request": {{inputJson.GetRawText()}} }""");
+        var args = argsDoc.RootElement;
 
         // Act
-        var result = await skill.Scripts![0].RunAsync(skill, args, CancellationToken.None);
+        var result = await skill.Scripts![0].RunAsync(skill, args, null, CancellationToken.None);
 
         // Assert — per-script JSO takes effect and custom types are properly marshaled
         Assert.NotNull(result);

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentSkillsProviderTests.cs

@@ -4,6 +4,7 @@ using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
+using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
@@ -15,7 +16,7 @@ namespace Microsoft.Agents.AI.UnitTests.AgentSkills;
 /// </summary>
 public sealed class AgentSkillsProviderTests : IDisposable
 {
-    private static readonly AgentFileSkillScriptRunner s_noOpExecutor = (skill, script, args, ct) => Task.FromResult<object?>(null);
+    private static readonly AgentFileSkillScriptRunner s_noOpExecutor = (skill, script, args, sp, ct) => Task.FromResult<object?>(null);
     private readonly string _testRoot;
     private readonly TestAIAgent _agent = new();
 
@@ -462,7 +463,7 @@ public sealed class AgentSkillsProviderTests : IDisposable
         // Act — call UseFileScriptRunner AFTER UseFileSkill (the bug scenario)
         var provider = new AgentSkillsProviderBuilder()
             .UseFileSkill(this._testRoot)
-            .UseFileScriptRunner((skill, script, args, ct) =>
+            .UseFileScriptRunner((skill, script, args, sp, ct) =>
             {
                 executorCalled = true;
                 return Task.FromResult<object?>("executed");
@@ -487,6 +488,62 @@ public sealed class AgentSkillsProviderTests : IDisposable
         Assert.True(executorCalled);
     }
 
+    [Fact]
+    public async Task RunSkillScript_ForwardsJsonArgumentsAndServiceProviderToRunnerAsync()
+    {
+        // Arrange — create a skill with a script file
+        string skillDir = Path.Combine(this._testRoot, "fwd-skill");
+        Directory.CreateDirectory(Path.Combine(skillDir, "scripts"));
+        File.WriteAllText(
+            Path.Combine(skillDir, "SKILL.md"),
+            "---\nname: fwd-skill\ndescription: Forwarding test\n---\nBody.");
+        File.WriteAllText(
+            Path.Combine(skillDir, "scripts", "run.py"),
+            "print('ok')");
+
+        JsonElement? capturedArgs = null;
+        IServiceProvider? capturedServiceProvider = null;
+
+        var provider = new AgentSkillsProviderBuilder()
+            .UseFileSkill(this._testRoot)
+            .UseFileScriptRunner((skill, script, args, sp, ct) =>
+            {
+                capturedArgs = args;
+                capturedServiceProvider = sp;
+                return Task.FromResult<object?>("executed");
+            })
+            .Build();
+
+        var mockServiceProvider = new TestServiceProvider();
+        var invokingContext = new AIContextProvider.InvokingContext(this._agent, session: null, new AIContext());
+        var result = await provider.InvokingAsync(invokingContext, CancellationToken.None);
+        var runScriptTool = result.Tools!.First(t => t.Name == "run_skill_script") as AIFunction;
+
+        // Act — invoke with JsonElement arguments and a service provider
+        using var argsJsonDoc = JsonDocument.Parse("""["arg1","arg2"]""");
+        var argsJson = argsJsonDoc.RootElement;
+        await runScriptTool!.InvokeAsync(new AIFunctionArguments(new Dictionary<string, object?>
+        {
+            ["skillName"] = "fwd-skill",
+            ["scriptName"] = "scripts/run.py",
+            ["arguments"] = argsJson,
+        })
+        {
+            Services = mockServiceProvider,
+        });
+
+        // Assert — JsonElement arguments and service provider are forwarded to the runner
+        Assert.NotNull(capturedArgs);
+        Assert.Equal(JsonValueKind.Array, capturedArgs!.Value.ValueKind);
+        Assert.Equal("""["arg1","arg2"]""", capturedArgs.Value.GetRawText());
+        Assert.Same(mockServiceProvider, capturedServiceProvider);
+    }
+
+    private sealed class TestServiceProvider : IServiceProvider
+    {
+        public object? GetService(Type serviceType) => null;
+    }
+
     private static void CreateSkillIn(string root, string name, string description, string body)
     {
         string skillDir = Path.Combine(root, name);

dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs

@@ -15,7 +15,7 @@ public sealed class FileAgentSkillLoaderTests : IDisposable
     private static readonly string[] s_customExtensions = [".custom"];
     private static readonly string[] s_validExtensions = [".md", ".json", ".custom"];
     private static readonly string[] s_mixedValidInvalidExtensions = [".md", "json"];
-    private static readonly AgentFileSkillScriptRunner s_noOpExecutor = (skill, script, args, ct) => Task.FromResult<object?>(null);
+    private static readonly AgentFileSkillScriptRunner s_noOpExecutor = (skill, script, args, sp, ct) => Task.FromResult<object?>(null);
 
     private readonly string _testRoot;
 

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/SampleSmokeTest.cs

@@ -269,6 +269,29 @@ public class SampleSmokeTest
         _ = await Step9EntryPoint.RunAsync(writer, environment.ToWorkflowExecutionEnvironment());
     }
 
+    /// <summary>
+    /// Stress regression for the off-thread run-status race: after
+    /// <c>Run.ResumeAsync</c> returns at a halt boundary,
+    /// callers must observe a stable terminal status and never a transient
+    /// <see cref="RunStatus.Running"/>. Step9 is the canonical multi-response resume
+    /// sample; prior to the fix in <see cref="Execution.StreamingRunEventStream"/>,
+    /// its `runStatus.Should().Be(RunStatus.Idle)` assertion failed intermittently
+    /// on roughly 1-in-10 iterations under InProcess_OffThread.
+    /// </summary>
+    [Fact]
+    internal async Task Test_RunSample_Step9_OffThread_MultiResponseResume_StatusIsStableAsync()
+    {
+        const int Iterations = 50;
+
+        for (int i = 0; i < Iterations; i++)
+        {
+            using StringWriter writer = new();
+            _ = await Step9EntryPoint.RunAsync(
+                writer,
+                ExecutionEnvironment.InProcess_OffThread.ToWorkflowExecutionEnvironment());
+        }
+    }
+
     [Theory]
     [InlineData(ExecutionEnvironment.InProcess_Lockstep)]
     [InlineData(ExecutionEnvironment.InProcess_OffThread)]

python/CHANGELOG.md

@@ -7,16 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-04-24
+
+### Added
+- **agent-framework-core**: Add functional workflow API ([#4238](https://github.com/microsoft/agent-framework/pull/4238))
+- **agent-framework-core**, **agent-framework-github-copilot**: Add OpenTelemetry integration for `GitHubCopilotAgent` ([#5142](https://github.com/microsoft/agent-framework/pull/5142))
+- **agent-framework-a2a**: Add Agent Framework to A2A bridge support ([#2403](https://github.com/microsoft/agent-framework/pull/2403))
+- **agent-framework-foundry**: Surface `oauth_consent_request` events from Responses API in Foundry clients ([#5070](https://github.com/microsoft/agent-framework/pull/5070))
+
+### Changed
+- **agent-framework-core**, **agent-framework-foundry**: Update `FoundryAgent` for hosted agent sessions ([#5447](https://github.com/microsoft/agent-framework/pull/5447))
+- **agent-framework-foundry-hosting**: Upgrade hosting server dependency and add more type support ([#5459](https://github.com/microsoft/agent-framework/pull/5459))
+
+### Fixed
+- **agent-framework-ag-ui**: Fix reasoning role and multimodal media parsing to follow specification ([#5389](https://github.com/microsoft/agent-framework/pull/5389))
+- **agent-framework-foundry**: Stop emitting `[TOOLBOXES]` warning for every `FoundryChatClient` call ([#5440](https://github.com/microsoft/agent-framework/pull/5440))
+- **agent-framework-anthropic**, **agent-framework-azure-ai-search**, **agent-framework-azure-cosmos**: Fix user agent prefix ([#5455](https://github.com/microsoft/agent-framework/pull/5455))
+
 ## [1.1.1] - 2026-04-23
 
 ### Added
 - **agent-framework-core**: Add `expected_output` ground-truth support to `evaluate_workflow` for similarity evaluators ([#5234](https://github.com/microsoft/agent-framework/pull/5234))
 - **agent-framework-ag-ui**, **agent-framework-a2a**: Propagate `thread_id` and `forwarded_props` through AG-UI to A2A `context_id` ([#5383](https://github.com/microsoft/agent-framework/pull/5383))
 - **samples**: Add second approval-required tool (`set_stop_loss`) to `concurrent_builder_tool_approval` sample ([#4875](https://github.com/microsoft/agent-framework/pull/4875))
+- **agent-framework-core**: Add `SKIP_PARSING` sentinel for `FunctionTool.invoke` to bypass `Content`-wrapping and return raw function results ([#5424](https://github.com/microsoft/agent-framework/pull/5424))
 
 ### Changed
 - **agent-framework-foundry-hosting**: Correct Development Status classifier from Beta (4) to Alpha (3) to match the package's lifecycle stage ([#5387](https://github.com/microsoft/agent-framework/pull/5387))
 - **tests**: Add Python flaky test report workflow ([#5342](https://github.com/microsoft/agent-framework/pull/5342))
+- **agent-framework-hyperlight**: Simplify host callback to pass raw Python results via `SKIP_PARSING`, switch `execute_code` input schema to a plain JSON-schema dict, and tighten public API surface ([#5424](https://github.com/microsoft/agent-framework/pull/5424))
 
 ### Fixed
 - **agent-framework-openai**: Fix OpenAI Responses streaming to propagate `created_at` from the final `response.completed` event ([#5382](https://github.com/microsoft/agent-framework/pull/5382))
@@ -24,6 +43,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **agent-framework-openai**: Exclude null `file_id` from `input_image` payload to prevent schema 400 errors ([#5125](https://github.com/microsoft/agent-framework/pull/5125))
 - **agent-framework-foundry**: Reconcile Toolbox hosted-tool payloads with the Responses API ([#5414](https://github.com/microsoft/agent-framework/pull/5414))
 - **agent-framework-ag-ui**: Pass client `thread_id` as `session_id` when constructing `AgentSession` ([#5384](https://github.com/microsoft/agent-framework/pull/5384))
+- **agent-framework-hyperlight**: Thread-confine `WasmSandbox` interactions via per-entry `ThreadPoolExecutor` to eliminate the PyO3 `unsendable` panic when touched from asyncio worker threads ([#5424](https://github.com/microsoft/agent-framework/pull/5424))
 
 ## [1.1.0] - 2026-04-21
 
@@ -957,7 +977,9 @@ Release candidate for **agent-framework-core** and **agent-framework-azure-ai**
 
 For more information, see the [announcement blog post](https://devblogs.microsoft.com/foundry/introducing-microsoft-agent-framework-the-open-source-engine-for-agentic-ai-apps/).
 
-[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.1.0...HEAD
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.2.0...HEAD
+[1.2.0]: https://github.com/microsoft/agent-framework/compare/python-1.1.1...python-1.2.0
+[1.1.1]: https://github.com/microsoft/agent-framework/compare/python-1.1.0...python-1.1.1
 [1.1.0]: https://github.com/microsoft/agent-framework/compare/python-1.0.1...python-1.1.0
 [1.0.1]: https://github.com/microsoft/agent-framework/compare/python-1.0.0...python-1.0.1
 [1.0.0]: https://github.com/microsoft/agent-framework/compare/python-1.0.0rc6...python-1.0.0

python/packages/a2a/AGENTS.md

@@ -4,20 +4,48 @@ Agent-to-Agent (A2A) protocol support for inter-agent communication.
 
 ## Main Classes
 
-- **`A2AAgent`** - Agent wrapper that exposes an agent via the A2A protocol
+- **`A2AAgent`** - Client to connect to remote A2A-compliant agents.
+- **`A2AExecutor`** - Bridge to expose Agent Framework agents via the A2A protocol.
 
 ## Usage
 
+### A2AAgent (Client)
+
 ```python
 from agent_framework.a2a import A2AAgent
 
-a2a_agent = A2AAgent(agent=my_agent)
+# Connect to a remote A2A agent
+a2a_agent = A2AAgent(url="http://remote-agent/a2a")
+response = await a2a_agent.run("Hello!")
+```
+
+### A2AExecutor (Server/Bridge)
+
+```python
+from agent_framework.a2a import A2AExecutor
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+
+# Create an A2A executor for your agent
+executor = A2AExecutor(agent=my_agent)
+
+# Set up the request handler and server application
+request_handler = DefaultRequestHandler(
+    agent_executor=executor,
+    task_store=InMemoryTaskStore(),
+)
+
+app = A2AStarletteApplication(
+    agent_card=my_agent_card,
+    http_handler=request_handler,
+).build()
 ```
 
 ## Import Path
 
 ```python
-from agent_framework.a2a import A2AAgent
+from agent_framework.a2a import A2AAgent, A2AExecutor
 # or directly:
-from agent_framework_a2a import A2AAgent
+from agent_framework_a2a import A2AAgent, A2AExecutor
 ```

python/packages/a2a/README.md

@@ -10,11 +10,49 @@ pip install agent-framework-a2a --pre
 
 The A2A agent integration enables communication with remote A2A-compliant agents using the standardized A2A protocol. This allows your Agent Framework applications to connect to agents running on different platforms, languages, or services.
 
+### A2AAgent (Client)
+
+The `A2AAgent` class is a client that wraps an A2A Client to connect the Agent Framework with external A2A-compliant agents.
+
+```python
+from agent_framework.a2a import A2AAgent
+
+# Connect to a remote A2A agent
+a2a_agent = A2AAgent(url="http://remote-agent/a2a")
+response = await a2a_agent.run("Hello!")
+```
+
+### A2AExecutor (Hosting)
+
+The `A2AExecutor` class bridges local AI agents built with the `agent_framework` library to the A2A protocol, allowing them to be hosted and accessed by other A2A-compliant clients.
+
+```python
+from agent_framework.a2a import A2AExecutor
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+
+# Create an A2A executor for your agent
+executor = A2AExecutor(agent=my_agent)
+
+# Set up the request handler and server application
+request_handler = DefaultRequestHandler(
+    agent_executor=executor,
+    task_store=InMemoryTaskStore(),
+)
+
+app = A2AStarletteApplication(
+    agent_card=my_agent_card,
+    http_handler=request_handler,
+).build()
+```
+
 ### Basic Usage Example
 
 See the [A2A agent examples](../../samples/04-hosting/a2a/) which demonstrate:
 
 - Connecting to remote A2A agents
+- Hosting local agents via A2A protocol
 - Sending messages and receiving responses
 - Handling different content types (text, files, data)
 - Streaming responses and real-time interaction

python/packages/a2a/agent_framework_a2a/__init__.py

@@ -2,6 +2,7 @@
 
 import importlib.metadata
 
+from ._a2a_executor import A2AExecutor
 from ._agent import A2AAgent, A2AContinuationToken
 
 try:
@@ -12,5 +13,6 @@ except importlib.metadata.PackageNotFoundError:
 __all__ = [
     "A2AAgent",
     "A2AContinuationToken",
+    "A2AExecutor",
     "__version__",
 ]

python/packages/a2a/agent_framework_a2a/_a2a_executor.py

@@ -0,0 +1,275 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import logging
+from asyncio import CancelledError
+from collections.abc import Mapping
+from functools import partial
+from typing import Any
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.server.tasks import TaskUpdater
+from a2a.types import FilePart, FileWithBytes, FileWithUri, Part, TaskState, TextPart
+from a2a.utils import new_task
+from agent_framework import (
+    AgentResponseUpdate,
+    AgentSession,
+    Message,
+    SupportsAgentRun,
+)
+from typing_extensions import override
+
+from agent_framework_a2a._utils import get_uri_data
+
+logger = logging.getLogger("agent_framework.a2a")
+
+
+class A2AExecutor(AgentExecutor):
+    """Execute AI agents using the A2A (Agent-to-Agent) protocol.
+
+    The A2AExecutor bridges AI agents built with the agent_framework library and the A2A protocol,
+    enabling structured agent execution with event-driven communication. It handles execution
+    contexts, delegates history management to the agent's session, and converts agent
+    responses into A2A protocol events.
+
+    The executor supports executing an Agent or WorkflowAgent. It provides comprehensive
+    error handling with task status updates and supports various content types including text,
+    binary data, and URI-based content.
+
+    Example:
+        .. code-block:: python
+
+            from a2a.server.apps import A2AStarletteApplication
+            from a2a.server.request_handlers import DefaultRequestHandler
+            from a2a.server.tasks import InMemoryTaskStore
+            from a2a.types import AgentCapabilities, AgentCard
+            from agent_framework.a2a import A2AExecutor
+            from agent_framework.openai import OpenAIResponsesClient
+
+            public_agent_card = AgentCard(
+                name="Food Agent",
+                description="A simple agent that provides food-related information.",
+                url="http://localhost:9999/",
+                version="1.0.0",
+                defaultInputModes=["text"],
+                defaultOutputModes=["text"],
+                capabilities=AgentCapabilities(streaming=True),
+                skills=[],
+            )
+
+            # Create an agent
+            agent = OpenAIResponsesClient().as_agent(
+                name="Food Agent",
+                instructions="A simple agent that provides food-related information.",
+            )
+
+            # Set up the A2A server with the A2AExecutor enabled for streaming
+            # and passing custom keyword arguments to the agent's run method.
+            request_handler = DefaultRequestHandler(
+                agent_executor=A2AExecutor(agent, stream=True, run_kwargs={"client_kwargs": {"max_tokens": 500}}),
+                task_store=InMemoryTaskStore(),
+            )
+
+            server = A2AStarletteApplication(
+                agent_card=public_agent_card,
+                http_handler=request_handler,
+            ).build()
+
+    Args:
+        agent: The AI agent to execute.
+        stream: Whether to stream the agent response. Defaults to False.
+        run_kwargs: Additional keyword arguments to pass to the agent's run method.
+    """
+
+    def __init__(self, agent: SupportsAgentRun, stream: bool = False, run_kwargs: Mapping[str, Any] | None = None):
+        """Initialize the A2AExecutor with the specified agent.
+
+        Args:
+            agent: The AI agent or workflow to execute.
+            stream: Whether to stream the agent response. Defaults to False.
+            run_kwargs: Additional keyword arguments to pass to the agent's run method.
+                Cannot contain 'session' or 'stream' as these are managed by the executor.
+
+        Raises:
+            ValueError: If run_kwargs contains 'session' or 'stream'.
+        """
+        super().__init__()
+        self._agent: SupportsAgentRun = agent
+        self._stream: bool = stream
+        if run_kwargs:
+            if "session" in run_kwargs:
+                raise ValueError("run_kwargs cannot contain 'session' as it is managed by the executor.")
+            if "stream" in run_kwargs:
+                raise ValueError("run_kwargs cannot contain 'stream' as it is managed by the executor.")
+        self._run_kwargs: Mapping[str, Any] = run_kwargs or {}
+
+    @override
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        """Cancel agent execution for the given request context.
+
+        Uses a TaskUpdater to send a cancellation event through the provided event queue.
+
+        Args:
+            context: The request context identifying the task to cancel.
+            event_queue: The event queue to publish the cancellation event to.
+
+        Raises:
+            ValueError: If context_id is not provided in the RequestContext.
+        """
+        if context.context_id is None:
+            raise ValueError("Context ID must be provided in the RequestContext")
+
+        updater = TaskUpdater(
+            event_queue=event_queue,
+            task_id=context.task_id or "",
+            context_id=context.context_id,
+        )
+
+        await updater.cancel()
+
+    @override
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        """Execute the agent with the given context and event queue.
+
+        Orchestrates the agent execution process: sets up the agent session,
+        executes the agent, processes response messages, and handles errors with appropriate task status updates.
+        """
+        if context.context_id is None:
+            raise ValueError("Context ID must be provided in the RequestContext")
+        if context.message is None:
+            raise ValueError("Message must be provided in the RequestContext")
+
+        query = context.get_user_input()
+        task = context.current_task
+
+        if not task:
+            task = new_task(context.message)
+            await event_queue.enqueue_event(task)
+
+        updater = TaskUpdater(event_queue, task.id, context.context_id)
+        await updater.submit()
+
+        try:
+            await updater.start_work()
+
+            session = self._agent.create_session(session_id=task.context_id)
+
+            if self._stream:
+                await self._run_stream(query, session, updater)
+            else:
+                await self._run(query, session, updater)
+
+            # Mark as complete
+            await updater.complete()
+        except CancelledError:
+            await updater.update_status(state=TaskState.canceled, final=True)
+        except Exception as e:
+            logger.exception("A2AExecutor encountered an error during execution.", exc_info=e)
+            await updater.update_status(
+                state=TaskState.failed,
+                final=True,
+                message=updater.new_agent_message([Part(root=TextPart(text=str(e)))]),
+            )
+
+    async def _run_stream(self, query: Any, session: AgentSession, updater: TaskUpdater) -> None:
+        """Run the agent in streaming mode and publish updates to the task updater."""
+        response_stream = self._agent.run(query, session=session, stream=True, **self._run_kwargs)
+        streamed_artifact_ids: set[str] = set()
+        await (
+            response_stream.with_transform_hook(
+                partial(self.handle_events, updater=updater, streamed_artifact_ids=streamed_artifact_ids)
+            )
+        ).get_final_response()
+
+    async def _run(self, query: Any, session: AgentSession, updater: TaskUpdater) -> None:
+        """Run the agent in non-streaming mode and publish messages to the task updater."""
+        response = await self._agent.run(query, session=session, stream=False, **self._run_kwargs)
+        response_messages = response.messages
+
+        if not isinstance(response_messages, list):
+            response_messages = [response_messages]
+
+        for message in response_messages:
+            await self.handle_events(message, updater)
+
+    async def handle_events(
+        self, item: Message | AgentResponseUpdate, updater: TaskUpdater, streamed_artifact_ids: set[str] | None = None
+    ) -> None:
+        """Convert agent response items (Messages or Updates) to A2A protocol events.
+
+        Processes Message or AgentResponseUpdate objects and converts them into A2A protocol format.
+        Handles text, data, and URI content. USER role messages are skipped.
+
+        Users can override this method in a subclass to implement custom transformations
+        from their agent's output format to A2A protocol events.
+
+        Args:
+            item: The agent response item (Message or AgentResponseUpdate) to process.
+            updater: The task updater to publish events to.
+            streamed_artifact_ids: A set of artifact IDs that have already been streamed.
+                Used to prevent duplicate updates for the same artifact.
+
+        Example:
+            .. code-block:: python
+
+                class CustomA2AExecutor(A2AExecutor):
+                    async def handle_events(
+                        self,
+                        item: Message | AgentResponseUpdate,
+                        updater: TaskUpdater,
+                        streamed_artifact_ids: set[str] | None = None,
+                    ) -> None:
+                        # Custom logic to transform item contents
+                        if item.role == "assistant" and item.contents:
+                            parts = [Part(root=TextPart(text=f"Custom: {item.contents[0].text}"))]
+                            await updater.update_status(
+                                state=TaskState.working,
+                                message=updater.new_agent_message(parts=parts),
+                            )
+                        else:
+                            await super().handle_events(item, updater)
+        """
+        role = getattr(item, "role", None)
+        if role == "user":
+            # This is a user message, we can ignore it in the context of task updates
+            return
+
+        parts: list[Part] = []
+        metadata = getattr(item, "additional_properties", None)
+
+        # AgentResponseUpdate uses 'contents', Message uses 'contents'
+        contents = getattr(item, "contents", [])
+
+        for content in contents:
+            if content.type == "text" and content.text:
+                parts.append(Part(root=TextPart(text=content.text)))
+            elif content.type == "data" and content.uri:
+                base64_str = get_uri_data(content.uri)
+                parts.append(Part(root=FilePart(file=FileWithBytes(bytes=base64_str, mime_type=content.media_type))))
+            elif content.type == "uri" and content.uri:
+                parts.append(Part(root=FilePart(file=FileWithUri(uri=content.uri, mime_type=content.media_type))))
+            else:
+                # Silently skip unsupported content types
+                logger.warning("A2AExecutor does not yet support content type: %s. Omitted.", content.type)
+
+        if parts:
+            if isinstance(item, AgentResponseUpdate):
+                # For streaming updates, we send TaskArtifactUpdateEvent via add_artifact
+                await updater.add_artifact(
+                    parts=parts,
+                    artifact_id=item.message_id,
+                    metadata=metadata,
+                    append=(
+                        True
+                        if streamed_artifact_ids is not None and item.message_id in (streamed_artifact_ids or set())
+                        else None
+                    ),
+                )
+                if item.message_id and streamed_artifact_ids is not None:
+                    streamed_artifact_ids.add(item.message_id)
+            else:
+                # For final messages, we send TaskStatusUpdateEvent with 'working' state
+                await updater.update_status(
+                    state=TaskState.working,
+                    message=updater.new_agent_message(parts=parts, metadata=metadata),
+                )

python/packages/a2a/agent_framework_a2a/_agent.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import base64
 import json
-import re
 import uuid
 from collections.abc import AsyncIterable, Awaitable, Mapping, Sequence
 from typing import Any, Final, Literal, TypeAlias, overload
@@ -49,7 +48,7 @@ from agent_framework.observability import AgentTelemetryLayer
 
 __all__ = ["A2AAgent", "A2AContinuationToken"]
 
-URI_PATTERN = re.compile(r"^data:(?P<media_type>[^;]+);base64,(?P<base64_data>[A-Za-z0-9+/=]+)$")
+from agent_framework_a2a._utils import get_uri_data
 
 
 class A2AContinuationToken(ContinuationToken):
@@ -78,14 +77,6 @@ A2AClientEvent: TypeAlias = tuple[Task, TaskStatusUpdateEvent | TaskArtifactUpda
 A2AStreamItem: TypeAlias = A2AMessage | A2AClientEvent
 
 
-def _get_uri_data(uri: str) -> str:
-    match = URI_PATTERN.match(uri)
-    if not match:
-        raise ValueError(f"Invalid data URI format: {uri}")
-
-    return match.group("base64_data")
-
-
 class A2AAgent(AgentTelemetryLayer, BaseAgent):
     """Agent2Agent (A2A) protocol implementation.
 
@@ -652,7 +643,7 @@ class A2AAgent(AgentTelemetryLayer, BaseAgent):
                         A2APart(
                             root=FilePart(
                                 file=FileWithBytes(
-                                    bytes=_get_uri_data(content.uri),
+                                    bytes=get_uri_data(content.uri),
                                     mime_type=content.media_type,
                                 ),
                                 metadata=content.additional_properties,

python/packages/a2a/agent_framework_a2a/_utils.py

@@ -0,0 +1,24 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import re
+
+URI_PATTERN = re.compile(r"^data:(?P<media_type>[^;]+);base64,(?P<base64_data>[A-Za-z0-9+/=]+)$")
+
+
+def get_uri_data(uri: str) -> str:
+    """Extracts the base64-encoded data from a data URI.
+
+    Args:
+        uri: The data URI to parse.
+
+    Returns:
+        The base64-encoded data part of the URI.
+
+    Raises:
+        ValueError: If the URI format is invalid.
+    """
+    match = URI_PATTERN.match(uri)
+    if not match:
+        raise ValueError(f"Invalid data URI format: {uri}")
+
+    return match.group("base64_data")

python/packages/a2a/pyproject.toml

@@ -4,7 +4,7 @@ description = "A2A integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "a2a-sdk>=0.3.5,<0.3.24",
 ]
 

python/packages/a2a/tests/test_a2a_agent.py

@@ -35,7 +35,7 @@ from agent_framework.a2a import A2AAgent
 from pytest import fixture, mark, raises
 
 from agent_framework_a2a import A2AContinuationToken
-from agent_framework_a2a._agent import _get_uri_data  # type: ignore
+from agent_framework_a2a._utils import get_uri_data
 
 
 class MockA2AClient:
@@ -353,18 +353,18 @@ def test_parse_message_from_artifact(a2a_agent: A2AAgent) -> None:
 
 
 def test_get_uri_data_valid_uri() -> None:
-    """Test _get_uri_data with valid data URI."""
+    """Test get_uri_data with valid data URI."""
 
     uri = "data:application/json;base64,eyJ0ZXN0IjoidmFsdWUifQ=="
-    result = _get_uri_data(uri)
+    result = get_uri_data(uri)
     assert result == "eyJ0ZXN0IjoidmFsdWUifQ=="
 
 
 def test_get_uri_data_invalid_uri() -> None:
-    """Test _get_uri_data with invalid URI format."""
+    """Test get_uri_data with invalid URI format."""
 
     with raises(ValueError, match="Invalid data URI format"):
-        _get_uri_data("not-a-valid-data-uri")
+        get_uri_data("not-a-valid-data-uri")
 
 
 def test_parse_contents_from_a2a_conversion(a2a_agent: A2AAgent) -> None:

python/packages/a2a/tests/test_a2a_executor.py

@@ -0,0 +1,910 @@
+# Copyright (c) Microsoft. All rights reserved.
+from asyncio import CancelledError
+from unittest.mock import AsyncMock, MagicMock, patch
+from uuid import uuid4
+
+from a2a.types import Task, TaskState, TextPart
+from agent_framework import (
+    AgentResponseUpdate,
+    Content,
+    Message,
+    SupportsAgentRun,
+)
+from agent_framework._types import AgentResponse
+from agent_framework.a2a import A2AExecutor
+from pytest import fixture, raises
+
+
+@fixture
+def mock_agent() -> MagicMock:
+    """Fixture that provides a mock SupportsAgentRun."""
+    agent = MagicMock(spec=SupportsAgentRun)
+    agent.run = AsyncMock()
+    return agent
+
+
+@fixture
+def mock_request_context() -> MagicMock:
+    """Fixture that provides a mock RequestContext."""
+    request_context = MagicMock()
+    request_context.context_id = str(uuid4())
+    request_context.get_user_input = MagicMock(return_value="Test query")
+    request_context.current_task = None
+    request_context.message = None
+    return request_context
+
+
+@fixture
+def mock_event_queue() -> MagicMock:
+    """Fixture that provides a mock EventQueue."""
+    queue = AsyncMock()
+    queue.enqueue_event = AsyncMock()
+    return queue
+
+
+@fixture
+def mock_task() -> Task:
+    """Fixture that provides a mock Task."""
+    task = MagicMock(spec=Task)
+    task.id = str(uuid4())
+    task.context_id = str(uuid4())
+    task.state = TaskState.completed
+    return task
+
+
+@fixture
+def mock_task_updater() -> MagicMock:
+    """Fixture that provides a mock TaskUpdater."""
+    updater = MagicMock()
+    updater.submit = AsyncMock()
+    updater.start_work = AsyncMock()
+    updater.complete = AsyncMock()
+    updater.update_status = AsyncMock()
+    updater.new_agent_message = MagicMock()
+    return updater
+
+
+@fixture
+def executor(mock_agent: MagicMock) -> A2AExecutor:
+    """Fixture that provides an A2AExecutor."""
+    return A2AExecutor(agent=mock_agent)
+
+
+class TestA2AExecutorInitialization:
+    """Tests for A2AExecutor initialization."""
+
+    def test_initialization_with_agent_only(self, mock_agent: MagicMock) -> None:
+        """Arrange: Create mock agent
+        Act: Initialize A2AExecutor with only agent
+        Assert: Executor is created with default values
+        """
+        # Act
+        executor = A2AExecutor(agent=mock_agent)
+
+        # Assert
+        assert executor._agent is mock_agent
+        assert executor._stream is False
+        assert executor._run_kwargs == {}
+
+    def test_initialization_with_stream_and_kwargs(self, mock_agent: MagicMock) -> None:
+        """Arrange: Create mock agent
+        Act: Initialize A2AExecutor with stream and run_kwargs
+        Assert: Executor is created with specified values
+        """
+        # Arrange
+        run_kwargs = {"temperature": 0.5}
+
+        # Act
+        executor = A2AExecutor(agent=mock_agent, stream=True, run_kwargs=run_kwargs)
+
+        # Assert
+        assert executor._agent is mock_agent
+        assert executor._stream is True
+        assert executor._run_kwargs == run_kwargs
+
+    def test_initialization_with_invalid_run_kwargs(self, mock_agent: MagicMock) -> None:
+        """Arrange: Create mock agent
+        Act: Initialize A2AExecutor with reserved keys in run_kwargs
+        Assert: ValueError is raised
+        """
+        # Act & Assert
+        with raises(ValueError, match="run_kwargs cannot contain 'session'"):
+            A2AExecutor(agent=mock_agent, run_kwargs={"session": "something"})
+
+        with raises(ValueError, match="run_kwargs cannot contain 'stream'"):
+            A2AExecutor(agent=mock_agent, run_kwargs={"stream": True})
+
+
+class TestA2AExecutorCancel:
+    """Tests for the cancel method."""
+
+    async def test_cancel_method_completes(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+    ) -> None:
+        """Arrange: Create executor with dependencies
+        Act: Call cancel method
+        Assert: Method completes without raising error
+        """
+        # Arrange
+        mock_request_context.task_id = "task-123"
+
+        # Act & Assert (should not raise)
+        await executor.cancel(mock_request_context, mock_event_queue)  # type: ignore
+
+    async def test_cancel_handles_different_contexts(
+        self,
+        executor: A2AExecutor,
+        mock_event_queue: MagicMock,
+    ) -> None:
+        """Arrange: Create executor with multiple request contexts
+        Act: Call cancel with different contexts
+        Assert: Each cancel completes successfully
+        """
+        # Arrange
+        context1 = MagicMock()
+        context1.context_id = "ctx-1"
+        context1.task_id = "task-1"
+        context2 = MagicMock()
+        context2.context_id = "ctx-2"
+        context2.task_id = "task-2"
+
+        # Act & Assert
+        await executor.cancel(context1, mock_event_queue)  # type: ignore
+        await executor.cancel(context2, mock_event_queue)  # type: ignore
+
+    async def test_cancel_raises_error_when_context_id_missing(
+        self,
+        executor: A2AExecutor,
+        mock_event_queue: MagicMock,
+    ) -> None:
+        """Arrange: Create context without context_id
+        Act: Call cancel method
+        Assert: ValueError is raised
+        """
+        # Arrange
+        mock_context = MagicMock()
+        mock_context.context_id = None
+
+        # Act & Assert
+        with raises(ValueError) as excinfo:
+            await executor.cancel(mock_context, mock_event_queue)  # type: ignore
+
+        # Assert
+        assert "Context ID" in str(excinfo.value)
+
+
+class TestA2AExecutorExecute:
+    """Tests for the execute method."""
+
+    async def test_execute_with_existing_task_succeeds(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+        mock_task: Task,
+    ) -> None:
+        """Arrange: Create executor with mocked dependencies and existing task
+        Act: Call execute method
+        Assert: Execution completes successfully
+        """
+        # Arrange
+        mock_request_context.get_user_input = MagicMock(return_value="Hello")
+        mock_request_context.current_task = mock_task
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = MagicMock()
+
+        response_message = Message(role="assistant", contents=[Content.from_text(text="Hello back")])
+        response = MagicMock(spec=AgentResponse)
+        response.messages = [response_message]
+        executor._agent.run = AsyncMock(return_value=response)
+        executor._agent.create_session = MagicMock()
+
+        with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+            mock_updater = MagicMock()
+            mock_updater.submit = AsyncMock()
+            mock_updater.start_work = AsyncMock()
+            mock_updater.complete = AsyncMock()
+            mock_updater.update_status = AsyncMock()
+            mock_updater.new_agent_message = MagicMock(return_value="message_obj")
+            mock_updater_class.return_value = mock_updater
+
+            # Act
+            await executor.execute(mock_request_context, mock_event_queue)
+
+            # Assert
+            mock_updater.submit.assert_called_once()
+            mock_updater.start_work.assert_called_once()
+            mock_updater.complete.assert_called_once()
+            executor._agent.create_session.assert_called_once()
+            executor._agent.run.assert_called_once()
+
+    async def test_execute_creates_task_when_not_exists(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+    ) -> None:
+        """Arrange: Create executor with request context without task
+        Act: Call execute method
+        Assert: New task is created and enqueued
+        """
+        # Arrange
+        mock_message = MagicMock()
+        mock_request_context.get_user_input = MagicMock(return_value="Hello")
+        mock_request_context.current_task = None
+        mock_request_context.message = mock_message
+        mock_request_context.context_id = "ctx-123"
+
+        response_message = Message(role="assistant", contents=[Content.from_text(text="Response")])
+        response = MagicMock(spec=AgentResponse)
+        response.messages = [response_message]
+        executor._agent.run = AsyncMock(return_value=response)
+        executor._agent.create_session = MagicMock()
+
+        with patch("agent_framework_a2a._a2a_executor.new_task") as mock_new_task:
+            mock_task = MagicMock(spec=Task)
+            mock_task.id = "task-new"
+            mock_task.context_id = "ctx-123"
+            mock_new_task.return_value = mock_task
+
+            with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+                mock_updater = MagicMock()
+                mock_updater.submit = AsyncMock()
+                mock_updater.start_work = AsyncMock()
+                mock_updater.complete = AsyncMock()
+                mock_updater.update_status = AsyncMock()
+                mock_updater.new_agent_message = MagicMock(return_value="message_obj")
+                mock_updater_class.return_value = mock_updater
+
+                # Act
+                await executor.execute(mock_request_context, mock_event_queue)
+
+                # Assert
+                mock_new_task.assert_called_once()
+                mock_event_queue.enqueue_event.assert_called_once()
+
+    async def test_execute_raises_error_when_context_id_missing(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+    ) -> None:
+        """Arrange: Create context without context_id
+        Act: Call execute method
+        Assert: ValueError is raised
+        """
+        # Arrange
+        mock_request_context.context_id = None
+        mock_request_context.message = MagicMock()
+
+        # Act & Assert
+        with raises(ValueError) as excinfo:
+            await executor.execute(mock_request_context, mock_event_queue)
+
+        # Assert
+        assert "Context ID" in str(excinfo.value)
+
+    async def test_execute_raises_error_when_message_missing(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+    ) -> None:
+        """Arrange: Create context without message
+        Act: Call execute method
+        Assert: ValueError is raised
+        """
+        # Arrange
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = None
+
+        # Act & Assert
+        with raises(ValueError) as excinfo:
+            await executor.execute(mock_request_context, mock_event_queue)
+
+        # Assert
+        assert "Message" in str(excinfo.value)
+
+    async def test_execute_handles_cancelled_error(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+        mock_task: Task,
+    ) -> None:
+        """Arrange: Create executor that raises CancelledError
+        Act: Call execute method
+        Assert: Error is caught and task is marked as canceled
+        """
+        # Arrange
+        mock_request_context.get_user_input = MagicMock(return_value="Hello")
+        mock_request_context.current_task = mock_task
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = MagicMock()
+
+        executor._agent.run = AsyncMock(side_effect=CancelledError())
+        executor._agent.create_session = MagicMock()
+
+        with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+            mock_updater = MagicMock()
+            mock_updater.submit = AsyncMock()
+            mock_updater.start_work = AsyncMock()
+            mock_updater.update_status = AsyncMock()
+            mock_updater_class.return_value = mock_updater
+
+            # Act
+            await executor.execute(mock_request_context, mock_event_queue)  # type: ignore
+
+            # Assert
+            mock_updater.update_status.assert_called()
+            call_args_list = mock_updater.update_status.call_args_list
+            assert any(
+                call[1].get("state") == TaskState.canceled and call[1].get("final") is True for call in call_args_list
+            )
+
+    async def test_execute_handles_generic_exception(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+        mock_task: Task,
+    ) -> None:
+        """Arrange: Create executor that raises generic exception
+        Act: Call execute method
+        Assert: Error is caught and task is marked as failed
+        """
+        # Arrange
+        mock_request_context.get_user_input = MagicMock(return_value="Hello")
+        mock_request_context.current_task = mock_task
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = MagicMock()
+
+        error_message = "Test error"
+        executor._agent.run = AsyncMock(side_effect=ValueError(error_message))
+        executor._agent.create_session = MagicMock()
+
+        with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+            mock_updater = MagicMock()
+            mock_updater.submit = AsyncMock()
+            mock_updater.start_work = AsyncMock()
+            mock_updater.update_status = AsyncMock()
+            mock_updater.new_agent_message = MagicMock(return_value="error_message_obj")
+            mock_updater_class.return_value = mock_updater
+
+            # Act
+            await executor.execute(mock_request_context, mock_event_queue)
+
+            # Assert
+            mock_updater.new_agent_message.assert_called_once()
+            args, _ = mock_updater.new_agent_message.call_args
+            parts = args[0]
+            assert len(parts) == 1
+            assert isinstance(parts[0].root, TextPart)
+            assert parts[0].root.text == error_message
+
+            call_args_list = mock_updater.update_status.call_args_list
+            assert any(
+                call[1].get("state") == TaskState.failed
+                and call[1].get("final") is True
+                and call[1].get("message") == "error_message_obj"
+                for call in call_args_list
+            )
+
+    async def test_execute_processes_multiple_response_messages(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+        mock_task: Task,
+    ) -> None:
+        """Arrange: Create executor that returns multiple response messages
+        Act: Call execute method
+        Assert: All messages are processed through handle_events
+        """
+        # Arrange
+        mock_request_context.get_user_input = MagicMock(return_value="Hello")
+        mock_request_context.current_task = mock_task
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = MagicMock()
+
+        response_message1 = Message(role="assistant", contents=[Content.from_text(text="First")])
+        response_message2 = Message(role="assistant", contents=[Content.from_text(text="Second")])
+        response = MagicMock(spec=AgentResponse)
+        response.messages = [response_message1, response_message2]
+        executor._agent.run = AsyncMock(return_value=response)
+        executor._agent.create_session = MagicMock()
+
+        # Mock handle_events
+        executor.handle_events = AsyncMock()
+
+        with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+            mock_updater = MagicMock()
+            mock_updater.submit = AsyncMock()
+            mock_updater.start_work = AsyncMock()
+            mock_updater.complete = AsyncMock()
+            mock_updater.update_status = AsyncMock()
+            mock_updater_class.return_value = mock_updater
+
+            # Act
+            await executor.execute(mock_request_context, mock_event_queue)
+
+            # Assert
+            assert executor.handle_events.call_count == 2
+
+    async def test_execute_passes_query_to_run(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+        mock_task: Task,
+    ) -> None:
+        """Arrange: Create executor with request
+        Act: Call execute method
+        Assert: Query text is passed to run method with default stream and kwargs
+        """
+        # Arrange
+        query_text = "Hello agent"
+        mock_request_context.get_user_input = MagicMock(return_value=query_text)
+        mock_request_context.current_task = mock_task
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = MagicMock()
+
+        response_message = Message(role="assistant", contents=[Content.from_text(text="Response")])
+        response = MagicMock(spec=AgentResponse)
+        response.messages = [response_message]
+        executor._agent.run = AsyncMock(return_value=response)
+        executor._agent.create_session = MagicMock()
+
+        with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+            mock_updater = MagicMock()
+            mock_updater.submit = AsyncMock()
+            mock_updater.start_work = AsyncMock()
+            mock_updater.complete = AsyncMock()
+            mock_updater.update_status = AsyncMock()
+            mock_updater.new_agent_message = MagicMock(return_value="message_obj")
+            mock_updater_class.return_value = mock_updater
+
+            # Act
+            await executor.execute(mock_request_context, mock_event_queue)
+
+            # Assert
+            executor._agent.run.assert_called_once_with(
+                query_text, session=executor._agent.create_session(), stream=False
+            )
+
+    async def test_execute_with_stream_enabled(
+        self,
+        mock_agent: MagicMock,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+        mock_task: Task,
+    ) -> None:
+        """Arrange: Create executor with stream=True
+        Act: Call execute method
+        Assert: _run_stream is called and passes stream=True to run
+        """
+        # Arrange
+        executor = A2AExecutor(agent=mock_agent, stream=True)
+        query_text = "Hello agent"
+        mock_request_context.get_user_input = MagicMock(return_value=query_text)
+        mock_request_context.current_task = mock_task
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = MagicMock()
+
+        mock_response_stream = MagicMock()
+        mock_response_stream.with_transform_hook = MagicMock(return_value=mock_response_stream)
+        mock_response_stream.get_final_response = AsyncMock()
+        mock_agent.run = MagicMock(return_value=mock_response_stream)
+        mock_agent.create_session = MagicMock()
+
+        with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+            mock_updater = MagicMock()
+            mock_updater.submit = AsyncMock()
+            mock_updater.start_work = AsyncMock()
+            mock_updater.complete = AsyncMock()
+            mock_updater.update_status = AsyncMock()
+            mock_updater_class.return_value = mock_updater
+
+            # Act
+            await executor.execute(mock_request_context, mock_event_queue)
+
+            # Assert
+            mock_agent.run.assert_called_once_with(query_text, session=mock_agent.create_session(), stream=True)
+            mock_response_stream.with_transform_hook.assert_called_once()
+            mock_response_stream.get_final_response.assert_called_once()
+
+    async def test_execute_with_run_kwargs(
+        self,
+        mock_agent: MagicMock,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+        mock_task: Task,
+    ) -> None:
+        """Arrange: Create executor with run_kwargs
+        Act: Call execute method
+        Assert: run_kwargs are passed to run method
+        """
+        # Arrange
+        run_kwargs = {"temperature": 0.5, "max_tokens": 100}
+        executor = A2AExecutor(agent=mock_agent, run_kwargs=run_kwargs)
+        query_text = "Hello agent"
+        mock_request_context.get_user_input = MagicMock(return_value=query_text)
+        mock_request_context.current_task = mock_task
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = MagicMock()
+
+        response_message = Message(role="assistant", contents=[Content.from_text(text="Response")])
+        response = MagicMock(spec=AgentResponse)
+        response.messages = [response_message]
+        mock_agent.run = AsyncMock(return_value=response)
+        mock_agent.create_session = MagicMock()
+
+        with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+            mock_updater = MagicMock()
+            mock_updater.submit = AsyncMock()
+            mock_updater.start_work = AsyncMock()
+            mock_updater.complete = AsyncMock()
+            mock_updater.update_status = AsyncMock()
+            mock_updater_class.return_value = mock_updater
+
+            # Act
+            await executor.execute(mock_request_context, mock_event_queue)
+
+            # Assert
+            mock_agent.run.assert_called_once_with(
+                query_text, session=mock_agent.create_session(), stream=False, **run_kwargs
+            )
+
+
+class TestA2AExecutorHandleEvents:
+    """Tests for A2AExecutor.handle_events method."""
+
+    async def test_run_method_with_single_message(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test the private _run method with a single message (not a list)."""
+        # Arrange
+        query = "test query"
+        session = MagicMock()
+        response_message = Message(role="assistant", contents=[Content.from_text(text="Response")])
+        response = MagicMock(spec=AgentResponse)
+        response.messages = response_message  # Not a list
+        executor._agent.run = AsyncMock(return_value=response)
+        executor.handle_events = AsyncMock()
+
+        # Act
+        await executor._run(query, session, mock_updater)
+
+        # Assert
+        executor.handle_events.assert_called_once_with(response_message, mock_updater)
+
+    @fixture
+    def mock_updater(self) -> MagicMock:
+        """Create a mock execution context."""
+        updater = MagicMock()
+        updater.update_status = AsyncMock()
+        updater.new_agent_message = MagicMock(return_value="mock_message")
+        return updater
+
+    async def test_ignore_user_messages(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test that messages from USER role are ignored."""
+        # Arrange
+        message = Message(
+            contents=[Content.from_text(text="User input")],
+            role="user",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_not_called()
+
+    async def test_ignore_messages_with_no_contents(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test that messages with no contents are ignored."""
+        # Arrange
+        message = Message(
+            contents=[],
+            role="assistant",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_not_called()
+
+    async def test_handle_text_content(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test handling messages with text content."""
+        # Arrange
+        text = "Hello, this is a test message"
+        message = Message(
+            contents=[Content.from_text(text=text)],
+            role="assistant",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_called_once()
+        call_args = mock_updater.update_status.call_args
+        assert call_args.kwargs["state"] == TaskState.working
+        assert mock_updater.new_agent_message.called
+
+    async def test_handle_multiple_text_contents(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test handling messages with multiple text contents."""
+        # Arrange
+        message = Message(
+            contents=[
+                Content.from_text(text="First message"),
+                Content.from_text(text="Second message"),
+            ],
+            role="assistant",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_called_once()
+        assert mock_updater.new_agent_message.called
+
+    async def test_handle_data_content(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test handling messages with data content."""
+        # Arrange
+        data = b"test file data"
+        message = Message(
+            contents=[Content.from_data(data=data, media_type="application/octet-stream")],
+            role="assistant",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_called_once()
+        call_args = mock_updater.update_status.call_args
+        assert call_args.kwargs["state"] == TaskState.working
+
+    async def test_handle_uri_content(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test handling messages with URI content."""
+        # Arrange
+        uri = "https://example.com/file.pdf"
+        message = Message(
+            contents=[Content.from_uri(uri=uri, media_type="application/pdf")],
+            role="assistant",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_called_once()
+        call_args = mock_updater.update_status.call_args
+        assert call_args.kwargs["state"] == TaskState.working
+
+    async def test_handle_mixed_content_types(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test handling messages with mixed content types."""
+        # Arrange
+        data = b"file data"
+
+        message = Message(
+            contents=[
+                Content.from_text(text="Processing file..."),
+                Content.from_data(data=data, media_type="application/octet-stream"),
+                Content.from_uri(uri="https://example.com/reference.pdf", media_type="application/pdf"),
+            ],
+            role="assistant",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_called_once()
+        call_args = mock_updater.update_status.call_args
+        assert call_args.kwargs["state"] == TaskState.working
+
+    async def test_handle_with_additional_properties(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test handling messages with additional properties metadata."""
+        # Arrange
+        additional_props = {"custom_field": "custom_value", "priority": "high"}
+        message = Message(
+            contents=[Content.from_text(text="Test message")],
+            role="assistant",
+            additional_properties=additional_props,
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_called_once()
+        mock_updater.new_agent_message.assert_called_once()
+        call_args = mock_updater.new_agent_message.call_args
+        assert call_args.kwargs["metadata"] == additional_props
+
+    async def test_handle_with_no_additional_properties(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test handling messages without additional properties."""
+        # Arrange
+        message = Message(
+            contents=[Content.from_text(text="Test message")],
+            role="assistant",
+            additional_properties=None,
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.update_status.assert_called_once()
+        mock_updater.new_agent_message.assert_called_once()
+        call_args = mock_updater.new_agent_message.call_args
+        assert call_args.kwargs["metadata"] == {}
+
+    async def test_parts_list_passed_to_new_agent_message(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test that parts list is correctly passed to new_agent_message."""
+        # Arrange
+        message = Message(
+            contents=[
+                Content.from_text(text="Message 1"),
+                Content.from_text(text="Message 2"),
+            ],
+            role="assistant",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_updater.new_agent_message.assert_called_once()
+        call_kwargs = mock_updater.new_agent_message.call_args.kwargs
+        assert "parts" in call_kwargs
+        parts_list = call_kwargs["parts"]
+        assert len(parts_list) == 2
+
+    async def test_task_state_always_working(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test that task state is always set to working."""
+        # Arrange
+        message = Message(
+            contents=[Content.from_text(text="Any message")],
+            role="assistant",
+        )
+
+        # Act
+        await executor.handle_events(message, mock_updater)
+
+        # Assert
+        call_kwargs = mock_updater.update_status.call_args.kwargs
+        assert call_kwargs["state"] == TaskState.working
+
+    async def test_handle_agent_response_update_no_streamed_set(
+        self, executor: A2AExecutor, mock_updater: MagicMock
+    ) -> None:
+        """Test handling AgentResponseUpdate (streaming) without a tracking set."""
+        # Arrange
+        update = AgentResponseUpdate(
+            contents=[Content.from_text(text="Streaming chunk")],
+            role="assistant",
+            message_id="msg-1",
+        )
+        mock_updater.add_artifact = AsyncMock()
+
+        # Act
+        await executor.handle_events(update, mock_updater)
+
+        # Assert
+        mock_updater.add_artifact.assert_called_once()
+        call_kwargs = mock_updater.add_artifact.call_args.kwargs
+        assert call_kwargs["artifact_id"] == "msg-1"
+        assert call_kwargs["append"] is None
+
+    async def test_handle_agent_response_update_first_time(
+        self, executor: A2AExecutor, mock_updater: MagicMock
+    ) -> None:
+        """Test handling AgentResponseUpdate (streaming) for the first time with a tracking set."""
+        # Arrange
+        update = AgentResponseUpdate(
+            contents=[Content.from_text(text="Streaming chunk")],
+            role="assistant",
+            message_id="msg-1",
+        )
+        mock_updater.add_artifact = AsyncMock()
+        streamed_artifact_ids = set()
+
+        # Act
+        await executor.handle_events(update, mock_updater, streamed_artifact_ids=streamed_artifact_ids)
+
+        # Assert
+        mock_updater.add_artifact.assert_called_once()
+        call_kwargs = mock_updater.add_artifact.call_args.kwargs
+        assert call_kwargs["append"] is None
+        assert "msg-1" in streamed_artifact_ids
+
+    async def test_handle_agent_response_update_subsequent_time(
+        self, executor: A2AExecutor, mock_updater: MagicMock
+    ) -> None:
+        """Test handling AgentResponseUpdate (streaming) for subsequent times with a tracking set."""
+        # Arrange
+        update = AgentResponseUpdate(
+            contents=[Content.from_text(text="Next chunk")],
+            role="assistant",
+            message_id="msg-1",
+        )
+        mock_updater.add_artifact = AsyncMock()
+        streamed_artifact_ids = {"msg-1"}
+
+        # Act
+        await executor.handle_events(update, mock_updater, streamed_artifact_ids=streamed_artifact_ids)
+
+        # Assert
+        mock_updater.add_artifact.assert_called_once()
+        call_kwargs = mock_updater.add_artifact.call_args.kwargs
+        assert call_kwargs["append"] is True
+
+    async def test_handle_unsupported_content_type(self, executor: A2AExecutor, mock_updater: MagicMock) -> None:
+        """Test handling messages with unsupported content types."""
+        # Arrange
+        message = Message(
+            contents=[Content(type="unknown", text="Some text")],
+            role="assistant",
+        )
+
+        # Act
+        with patch("agent_framework_a2a._a2a_executor.logger") as mock_logger:
+            await executor.handle_events(message, mock_updater)
+
+        # Assert
+        mock_logger.warning.assert_called_once()
+        mock_updater.update_status.assert_not_called()
+
+
+class TestA2AExecutorIntegration:
+    """Integration tests for A2AExecutor."""
+
+    async def test_full_execution_flow_with_responses(
+        self,
+        executor: A2AExecutor,
+        mock_request_context: MagicMock,
+        mock_event_queue: MagicMock,
+        mock_task: Task,
+    ) -> None:
+        """Arrange: Create executor with all mocked dependencies
+        Act: Execute full flow from request to completion
+        Assert: All components interact correctly
+        """
+        # Arrange
+        mock_request_context.get_user_input = MagicMock(return_value="Hello agent")
+        mock_request_context.current_task = mock_task
+        mock_request_context.context_id = "ctx-123"
+        mock_request_context.message = MagicMock()
+
+        response = MagicMock(spec=AgentResponse)
+        response_message = MagicMock(spec=Message)
+        response.messages = [response_message]
+        response_message.contents = [Content.from_text(text="Hello user")]
+        response_message.role = "assistant"
+        response_message.additional_properties = None
+
+        executor._agent.run = AsyncMock(return_value=response)
+        executor._agent.create_session = MagicMock()
+        executor.handle_events = AsyncMock()
+
+        with patch("agent_framework_a2a._a2a_executor.TaskUpdater") as mock_updater_class:
+            mock_updater = MagicMock()
+            mock_updater.submit = AsyncMock()
+            mock_updater.start_work = AsyncMock()
+            mock_updater.complete = AsyncMock()
+            mock_updater.update_status = AsyncMock()
+            mock_updater_class.return_value = mock_updater
+
+            # Act
+            await executor.execute(mock_request_context, mock_event_queue)
+
+            # Assert
+            mock_updater.submit.assert_called_once()
+            mock_updater.start_work.assert_called_once()
+            executor.handle_events.assert_called_once()
+            mock_updater.complete.assert_called_once()

python/packages/a2a/tests/test_utils.py

@@ -0,0 +1,41 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import pytest
+
+from agent_framework_a2a._utils import get_uri_data
+
+
+def test_get_uri_data_valid() -> None:
+    """Test get_uri_data with valid data URIs."""
+    # Simple text/plain
+    uri = "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ=="
+    assert get_uri_data(uri) == "SGVsbG8sIFdvcmxkIQ=="
+
+    # Image png
+    uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
+    assert get_uri_data(uri) == "iVBORw0KGgoAAAANSUhEUgfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="
+
+    # Application octet-stream
+    uri = "data:application/octet-stream;base64,AQIDBA=="
+    assert get_uri_data(uri) == "AQIDBA=="
+
+
+def test_get_uri_data_invalid_format() -> None:
+    """Test get_uri_data with invalid URI formats."""
+    invalid_uris = [
+        "not-a-uri",
+        "http://example.com",
+        "data:text/plain;SGVsbG8sIFdvcmxkIQ==",  # Missing base64 marker
+        "data:base64,SGVsbG8sIFdvcmxkIQ==",  # Missing media type
+        "data:text/plain;charset=utf-8;base64,SGVsbG8sIFdvcmxkIQ==",  # Extra parameters (current regex doesn't support)
+        "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ== extra",
+    ]
+    for uri in invalid_uris:
+        with pytest.raises(ValueError, match="Invalid data URI format"):
+            get_uri_data(uri)
+
+
+def test_get_uri_data_empty() -> None:
+    """Test get_uri_data with empty string."""
+    with pytest.raises(ValueError, match="Invalid data URI format"):
+        get_uri_data("")

python/packages/ag-ui/agent_framework_ag_ui/_message_adapters.py

@@ -263,27 +263,21 @@ def _deduplicate_messages(messages: list[Message]) -> list[Message]:
     return unique_messages
 
 
-def _parse_multimodal_media_part(part: dict[str, Any]) -> Content | None:
-    """Convert a multimodal media part into Agent Framework content."""
-    part_type = str(part.get("type", "")).lower()
-    source = part.get("source")
+def _extract_multimodal_source_fields(
+    part: dict[str, Any],
+) -> tuple[str | None, str | None, str | None, str | None]:
+    """Extract ``(url, data, binary_id, mime_type)`` from an AG-UI multimodal part.
 
-    mime_type = cast(
-        str | None,
-        part.get("mimeType")
-        or part.get("mime_type")
-        or {
-            "image": "image/*",
-            "audio": "audio/*",
-            "video": "video/*",
-            "document": "application/octet-stream",
-            "binary": "application/octet-stream",
-        }.get(part_type, "application/octet-stream"),
-    )
+    Handles both the current AG-UI spec (``source.value`` for base64 payloads) and the
+    legacy ``source.data`` field for backward compatibility. Returned values are the
+    raw extracted strings (or ``None`` when absent); callers apply their own defaults.
+    """
+    mime_type = cast(str | None, part.get("mimeType") or part.get("mime_type"))
     url = cast(str | None, part.get("url") or part.get("uri"))
     data = cast(str | None, part.get("data"))
     binary_id = cast(str | None, part.get("id"))
 
+    source = part.get("source")
     if isinstance(source, dict):
         source_dict = cast(dict[str, Any], source)
         source_type = str(source_dict.get("type", "")).lower()
@@ -294,14 +288,31 @@ def _parse_multimodal_media_part(part: dict[str, Any]) -> Content | None:
         if source_type in {"url", "uri"}:
             url = cast(str | None, source_dict.get("url") or source_dict.get("uri"))
         elif source_type in {"base64", "data", "binary"}:
-            data = cast(str | None, source_dict.get("data"))
+            data = cast(str | None, source_dict.get("value") or source_dict.get("data"))
         elif source_type in {"id", "file"}:
             binary_id = cast(str | None, source_dict.get("id"))
         else:
             url = cast(str | None, source_dict.get("url") or source_dict.get("uri") or url)
-            data = cast(str | None, source_dict.get("data") or data)
+            data = cast(str | None, source_dict.get("value") or source_dict.get("data") or data)
             binary_id = cast(str | None, source_dict.get("id") or binary_id)
 
+    return url, data, binary_id, mime_type
+
+
+def _parse_multimodal_media_part(part: dict[str, Any]) -> Content | None:
+    """Convert a multimodal media part into Agent Framework content."""
+    part_type = str(part.get("type", "")).lower()
+    url, data, binary_id, mime_type = _extract_multimodal_source_fields(part)
+
+    if not mime_type:
+        mime_type = {
+            "image": "image/*",
+            "audio": "audio/*",
+            "video": "video/*",
+            "document": "application/octet-stream",
+            "binary": "application/octet-stream",
+        }.get(part_type, "application/octet-stream")
+
     if isinstance(url, str) and url:
         return Content.from_uri(uri=url, media_type=mime_type)
 
@@ -389,30 +400,7 @@ def _normalize_snapshot_content(content: Any) -> Any:
         def _legacy_binary_part(part: dict[str, Any]) -> dict[str, Any]:
             """Convert draft/legacy multimodal parts to AG-UI snapshot binary shape."""
             normalized: dict[str, Any] = {"type": "binary"}
-
-            mime_type = cast(str | None, part.get("mimeType") or part.get("mime_type"))
-            url = cast(str | None, part.get("url") or part.get("uri"))
-            data = cast(str | None, part.get("data"))
-            binary_id = cast(str | None, part.get("id"))
-
-            source = part.get("source")
-            if isinstance(source, dict):
-                source_part = cast(dict[str, Any], source)
-                source_mime = source_part.get("mimeType") or source_part.get("mime_type")
-                if isinstance(source_mime, str) and source_mime:
-                    mime_type = source_mime
-
-                source_type = str(source_part.get("type", "")).lower()
-                if source_type in {"url", "uri"}:
-                    url = cast(str | None, source_part.get("url") or source_part.get("uri"))
-                elif source_type in {"base64", "data", "binary"}:
-                    data = cast(str | None, source_part.get("data"))
-                elif source_type in {"id", "file"}:
-                    binary_id = cast(str | None, source_part.get("id"))
-                else:
-                    url = cast(str | None, source_part.get("url") or source_part.get("uri") or url)
-                    data = cast(str | None, source_part.get("data") or data)
-                    binary_id = cast(str | None, source_part.get("id") or binary_id)
+            url, data, binary_id, mime_type = _extract_multimodal_source_fields(part)
 
             if isinstance(mime_type, str) and mime_type:
                 normalized["mimeType"] = mime_type

python/packages/ag-ui/agent_framework_ag_ui/_run_common.py

@@ -596,7 +596,7 @@ def _emit_text_reasoning(content: Content, flow: FlowState | None = None) -> lis
             events.extend(_close_reasoning_block(flow))
             # Open new reasoning block.
             events.append(ReasoningStartEvent(message_id=message_id))
-            events.append(ReasoningMessageStartEvent(message_id=message_id, role="assistant"))
+            events.append(ReasoningMessageStartEvent(message_id=message_id, role="reasoning"))
             flow.reasoning_message_id = message_id
 
         if text:
@@ -613,7 +613,7 @@ def _emit_text_reasoning(content: Content, flow: FlowState | None = None) -> lis
     else:
         # No flow -- backward-compatible full sequence per call.
         events.append(ReasoningStartEvent(message_id=message_id))
-        events.append(ReasoningMessageStartEvent(message_id=message_id, role="assistant"))
+        events.append(ReasoningMessageStartEvent(message_id=message_id, role="reasoning"))
 
         if text:
             events.append(ReasoningMessageContentEvent(message_id=message_id, delta=text))

python/packages/ag-ui/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -22,8 +22,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
-    "ag-ui-protocol==0.1.13",
+    "agent-framework-core>=1.2.0,<2",
+    "ag-ui-protocol>=0.1.16,<0.2",
     "fastapi>=0.115.0,<0.133.1",
     "uvicorn[standard]>=0.30.0,<0.42.0"
 ]

python/packages/ag-ui/tests/ag_ui/test_message_adapters.py

@@ -536,6 +536,77 @@ def test_agui_snapshot_format_preserves_multimodal_content():
     assert content_parts[1]["url"] == "https://example.com/image.png"
 
 
+def test_agui_snapshot_format_reads_base64_value_field():
+    """Snapshot normalization reads the spec 'value' field for base64 sources."""
+    payload = base64.b64encode(b"abc").decode("utf-8")
+    normalized = agui_messages_to_snapshot_format(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {"type": "base64", "value": payload, "mimeType": "image/png"},
+                    },
+                ],
+            }
+        ]
+    )
+
+    binary_part = normalized[0]["content"][0]
+    assert binary_part["type"] == "binary"
+    assert binary_part["mimeType"] == "image/png"
+    assert binary_part["data"] == payload
+
+
+def test_agui_snapshot_format_base64_value_preferred_over_data():
+    """Snapshot normalization prefers 'value' when both 'value' and 'data' are set."""
+    value_payload = base64.b64encode(b"new-spec").decode("utf-8")
+    data_payload = base64.b64encode(b"legacy").decode("utf-8")
+    normalized = agui_messages_to_snapshot_format(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "value": value_payload,
+                            "data": data_payload,
+                            "mimeType": "image/png",
+                        },
+                    },
+                ],
+            }
+        ]
+    )
+
+    binary_part = normalized[0]["content"][0]
+    assert binary_part["data"] == value_payload
+
+
+def test_agui_snapshot_format_base64_data_field_backward_compat():
+    """Snapshot normalization still reads the legacy 'data' field when 'value' is absent."""
+    payload = base64.b64encode(b"legacy").decode("utf-8")
+    normalized = agui_messages_to_snapshot_format(
+        [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image",
+                        "source": {"type": "base64", "data": payload, "mimeType": "image/png"},
+                    },
+                ],
+            }
+        ]
+    )
+
+    binary_part = normalized[0]["content"][0]
+    assert binary_part["data"] == payload
+
+
 def test_agui_with_tool_calls_to_agent_framework():
     """Assistant message with tool_calls is converted to FunctionCallContent."""
     agui_msg = {
@@ -1760,3 +1831,67 @@ class TestReasoningRoundTrip:
         assert "First answer" in texts
         assert "Follow-up question" in texts
         assert "Prior reasoning" not in texts
+
+
+def test_parse_multimodal_media_part_base64_value_field():
+    """Source with type='base64' reads data from the 'value' field per AG-UI spec."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "base64", "value": "aGVsbG8=", "mimeType": "image/png"}}
+    )
+    assert result is not None
+    assert "aGVsbG8=" in result.uri
+
+
+def test_parse_multimodal_media_part_data_source_value_field():
+    """Source with type='data' reads data from the 'value' field per AG-UI spec."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "data", "value": "aGVsbG8=", "mimeType": "image/png"}}
+    )
+    assert result is not None
+    assert "aGVsbG8=" in result.uri
+
+
+def test_parse_multimodal_media_part_base64_data_field_backward_compat():
+    """Source with type='base64' still supports deprecated 'data' field."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "base64", "data": "aGVsbG8=", "mimeType": "image/png"}}
+    )
+    assert result is not None
+    assert "aGVsbG8=" in result.uri
+
+
+def test_parse_multimodal_media_part_value_preferred_over_data():
+    """When both 'value' and 'data' are present, 'value' takes precedence."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "value": "dmFsdWU=",
+                "data": "ZGF0YQ==",
+                "mimeType": "image/png",
+            },
+        }
+    )
+    assert result is not None
+    # 'value' field content should be used (base64 of "value")
+    assert "dmFsdWU=" in result.uri
+
+
+def test_parse_multimodal_media_part_unknown_source_value_fallback():
+    """Unknown source type falls back to 'value' field before 'data' field."""
+    from agent_framework_ag_ui._message_adapters import _parse_multimodal_media_part
+
+    result = _parse_multimodal_media_part(
+        {"type": "image", "source": {"type": "custom", "value": "aGVsbG8=", "mimeType": "image/png"}}
+    )
+    assert result is not None
+    assert "aGVsbG8=" in result.uri

python/packages/ag-ui/tests/ag_ui/test_run.py

@@ -1244,7 +1244,7 @@ class TestEmitTextReasoning:
         assert events[0].message_id == "reason_1"
         assert isinstance(events[1], ReasoningMessageStartEvent)
         assert events[1].message_id == "reason_1"
-        assert events[1].role == "assistant"
+        assert events[1].role == "reasoning"
         assert isinstance(events[2], ReasoningMessageContentEvent)
         assert events[2].message_id == "reason_1"
         assert events[2].delta == "The user is asking about weather, so I should call the weather tool."
@@ -1642,6 +1642,37 @@ class TestReasoningInSnapshot:
         assert close[0].message_id == "block2"
 
 
+class TestReasoningEventRole:
+    """Tests that reasoning events use role='reasoning' per AG-UI spec."""
+
+    def test_reasoning_role_without_flow(self):
+        """ReasoningMessageStartEvent uses role='reasoning' in non-flow mode."""
+        content = Content.from_text_reasoning(
+            id="reason_role_1",
+            text="Thinking about the question.",
+        )
+
+        events = _emit_text_reasoning(content)
+
+        msg_starts = [e for e in events if isinstance(e, ReasoningMessageStartEvent)]
+        assert len(msg_starts) == 1
+        assert msg_starts[0].role == "reasoning"
+
+    def test_reasoning_role_with_flow(self):
+        """ReasoningMessageStartEvent uses role='reasoning' in streaming flow mode."""
+        flow = FlowState()
+        content = Content.from_text_reasoning(
+            id="reason_role_2",
+            text="Reasoning in streaming mode.",
+        )
+
+        events = _emit_text_reasoning(content, flow)
+
+        msg_starts = [e for e in events if isinstance(e, ReasoningMessageStartEvent)]
+        assert len(msg_starts) == 1
+        assert msg_starts[0].role == "reasoning"
+
+
 async def test_session_id_matches_thread_id():
     """Session created by run_agent_stream uses the client thread_id as session_id."""
     from conftest import StubAgent

python/packages/anthropic/agent_framework_anthropic/_bedrock_client.py

@@ -6,13 +6,13 @@ from collections.abc import Sequence
 from typing import Any, ClassVar, Generic, TypedDict
 
 from agent_framework import (
-    AGENT_FRAMEWORK_USER_AGENT,
     ChatAndFunctionMiddlewareTypes,
     ChatMiddlewareLayer,
     FunctionInvocationConfiguration,
     FunctionInvocationLayer,
 )
 from agent_framework._settings import SecretString, load_settings
+from agent_framework._telemetry import get_user_agent
 from agent_framework.observability import ChatTelemetryLayer
 from anthropic import AsyncAnthropicBedrock
 
@@ -94,7 +94,7 @@ class RawAnthropicBedrockClient(RawAnthropicClient[AnthropicOptionsT], Generic[A
                 aws_profile=settings.get("aws_profile"),
                 aws_session_token=session_token_secret.get_secret_value() if session_token_secret is not None else None,
                 base_url=settings.get("anthropic_bedrock_base_url"),
-                default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+                default_headers={"User-Agent": get_user_agent()},
             )
 
         super().__init__(

python/packages/anthropic/agent_framework_anthropic/_chat_client.py

@@ -8,7 +8,6 @@ from collections.abc import AsyncIterable, Awaitable, Callable, Mapping, Sequenc
 from typing import Any, ClassVar, Final, Generic, Literal, TypedDict
 
 from agent_framework import (
-    AGENT_FRAMEWORK_USER_AGENT,
     Annotation,
     BaseChatClient,
     ChatAndFunctionMiddlewareTypes,
@@ -28,6 +27,7 @@ from agent_framework import (
     tool,
 )
 from agent_framework._settings import SecretString, load_settings
+from agent_framework._telemetry import get_user_agent
 from agent_framework._tools import SHELL_TOOL_KIND_VALUE
 from agent_framework._types import _get_data_bytes_as_str  # type: ignore
 from agent_framework.observability import ChatTelemetryLayer
@@ -332,7 +332,7 @@ class RawAnthropicClient(
 
             anthropic_client = AsyncAnthropic(
                 api_key=api_key_secret.get_secret_value(),
-                default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+                default_headers={"User-Agent": get_user_agent()},
             )
 
         # Initialize parent
@@ -604,7 +604,7 @@ class RawAnthropicClient(
         run_options["betas"] = self._prepare_betas(options)
 
         # extra headers
-        run_options["extra_headers"] = {"User-Agent": AGENT_FRAMEWORK_USER_AGENT}
+        run_options["extra_headers"] = {"User-Agent": get_user_agent()}
 
         # Handle user option -> metadata.user_id (Anthropic uses metadata.user_id instead of user)
         if user := run_options.pop("user", None):

python/packages/anthropic/agent_framework_anthropic/_foundry_client.py

@@ -6,13 +6,13 @@ from collections.abc import Awaitable, Callable, Sequence
 from typing import Any, ClassVar, Generic, TypedDict
 
 from agent_framework import (
-    AGENT_FRAMEWORK_USER_AGENT,
     ChatAndFunctionMiddlewareTypes,
     ChatMiddlewareLayer,
     FunctionInvocationConfiguration,
     FunctionInvocationLayer,
 )
 from agent_framework._settings import SecretString, load_settings
+from agent_framework._telemetry import get_user_agent
 from agent_framework.observability import ChatTelemetryLayer
 from anthropic import AsyncAnthropicFoundry
 
@@ -91,14 +91,14 @@ class RawAnthropicFoundryClient(RawAnthropicClient[AnthropicOptionsT], Generic[A
                     base_url=base_url_setting,
                     api_key=api_key_value,
                     azure_ad_token_provider=azure_ad_token_provider,
-                    default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+                    default_headers={"User-Agent": get_user_agent()},
                 )
             else:
                 anthropic_client = AsyncAnthropicFoundry(
                     resource=resource_setting,
                     api_key=api_key_value,
                     azure_ad_token_provider=azure_ad_token_provider,
-                    default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+                    default_headers={"User-Agent": get_user_agent()},
                 )
 
         super().__init__(

python/packages/anthropic/agent_framework_anthropic/_vertex_client.py

@@ -6,13 +6,13 @@ from collections.abc import Sequence
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypedDict
 
 from agent_framework import (
-    AGENT_FRAMEWORK_USER_AGENT,
     ChatAndFunctionMiddlewareTypes,
     ChatMiddlewareLayer,
     FunctionInvocationConfiguration,
     FunctionInvocationLayer,
 )
 from agent_framework._settings import load_settings
+from agent_framework._telemetry import get_user_agent
 from agent_framework.observability import ChatTelemetryLayer
 from anthropic import NOT_GIVEN, AsyncAnthropicVertex
 
@@ -89,7 +89,7 @@ class RawAnthropicVertexClient(RawAnthropicClient[AnthropicOptionsT], Generic[An
                 access_token=access_token,
                 credentials=credentials,
                 base_url=settings.get("anthropic_vertex_base_url"),
-                default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+                default_headers={"User-Agent": get_user_agent()},
             )
 
         super().__init__(

python/packages/anthropic/pyproject.toml

@@ -4,7 +4,7 @@ description = "Anthropic integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "anthropic>=0.80.0,<0.80.1",
 ]
 

python/packages/anthropic/tests/test_anthropic_provider_clients.py

@@ -3,7 +3,8 @@
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
-from agent_framework import AGENT_FRAMEWORK_USER_AGENT, ChatMiddlewareLayer, FunctionInvocationLayer
+from agent_framework import ChatMiddlewareLayer, FunctionInvocationLayer
+from agent_framework._telemetry import get_user_agent
 from agent_framework.observability import ChatTelemetryLayer
 
 from agent_framework_anthropic import (
@@ -61,7 +62,7 @@ def test_raw_anthropic_foundry_client_creates_sdk_client_from_settings(tmp_path)
         resource="test-resource",
         api_key="test-key",
         azure_ad_token_provider=None,
-        default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+        default_headers={"User-Agent": get_user_agent()},
     )
 
 
@@ -85,7 +86,7 @@ def test_raw_anthropic_foundry_client_creates_sdk_client_from_base_url_settings(
         base_url="https://test-resource.services.ai.azure.com/anthropic/",
         api_key="test-key",
         azure_ad_token_provider=None,
-        default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+        default_headers={"User-Agent": get_user_agent()},
     )
 
 
@@ -130,7 +131,7 @@ def test_raw_anthropic_bedrock_client_creates_sdk_client_from_arguments() -> Non
         aws_profile=None,
         aws_session_token=None,
         base_url=None,
-        default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+        default_headers={"User-Agent": get_user_agent()},
     )
 
 
@@ -152,5 +153,5 @@ def test_raw_anthropic_vertex_client_creates_sdk_client_from_arguments() -> None
         access_token=None,
         credentials=None,
         base_url=None,
-        default_headers={"User-Agent": AGENT_FRAMEWORK_USER_AGENT},
+        default_headers={"User-Agent": get_user_agent()},
     )

python/packages/azure-ai-search/agent_framework_azure_ai_search/_context_provider.py

@@ -14,7 +14,6 @@ from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypedDict, overload
 
 from agent_framework import (
-    AGENT_FRAMEWORK_USER_AGENT,
     AgentSession,
     Annotation,
     Content,
@@ -25,6 +24,7 @@ from agent_framework import (
     SupportsGetEmbeddings,
     load_settings,
 )
+from agent_framework._telemetry import get_user_agent
 from agent_framework.exceptions import SettingNotFoundError
 from azure.core.credentials import AzureKeyCredential, TokenCredential
 from azure.core.credentials_async import AsyncTokenCredential
@@ -535,7 +535,7 @@ class AzureAISearchContextProvider(ContextProvider):
                 endpoint=self.endpoint,
                 index_name=self.index_name,
                 credential=self.credential,
-                user_agent=AGENT_FRAMEWORK_USER_AGENT,
+                user_agent=get_user_agent(),
             )
 
         self._index_client: SearchIndexClient | None = None
@@ -544,7 +544,7 @@ class AzureAISearchContextProvider(ContextProvider):
             self._index_client = SearchIndexClient(
                 endpoint=self.endpoint,
                 credential=self.credential,
-                user_agent=AGENT_FRAMEWORK_USER_AGENT,
+                user_agent=get_user_agent(),
             )
 
         self._knowledge_base_initialized = False
@@ -640,7 +640,7 @@ class AzureAISearchContextProvider(ContextProvider):
                 self._index_client = SearchIndexClient(
                     endpoint=self.endpoint,
                     credential=self.credential,
-                    user_agent=AGENT_FRAMEWORK_USER_AGENT,
+                    user_agent=get_user_agent(),
                 )
             if not self.index_name:
                 logger.warning("Cannot auto-discover vector field: index_name is not set.")
@@ -740,7 +740,7 @@ class AzureAISearchContextProvider(ContextProvider):
                     endpoint=self.endpoint,
                     knowledge_base_name=knowledge_base_name,
                     credential=self.credential,
-                    user_agent=AGENT_FRAMEWORK_USER_AGENT,
+                    user_agent=get_user_agent(),
                 )
             self._knowledge_base_initialized = True
             return
@@ -802,7 +802,7 @@ class AzureAISearchContextProvider(ContextProvider):
                 endpoint=self.endpoint,
                 knowledge_base_name=knowledge_base_name,
                 credential=self.credential,
-                user_agent=AGENT_FRAMEWORK_USER_AGENT,
+                user_agent=get_user_agent(),
             )
 
     async def _agentic_search(self, messages: list[Message]) -> list[Message]:

python/packages/azure-ai-search/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure AI Search integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "azure-search-documents>=11.7.0b2,<11.7.0b3",
 ]
 

python/packages/azure-cosmos/agent_framework_azure_cosmos/_checkpoint_storage.py

@@ -7,8 +7,8 @@ from __future__ import annotations
 import logging
 from typing import Any, TypedDict
 
-from agent_framework import AGENT_FRAMEWORK_USER_AGENT
 from agent_framework._settings import SecretString, load_settings
+from agent_framework._telemetry import get_user_agent
 from agent_framework._workflows._checkpoint import CheckpointID, WorkflowCheckpoint
 from agent_framework._workflows._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_value
 from agent_framework.exceptions import WorkflowCheckpointException
@@ -194,7 +194,7 @@ class CosmosCheckpointStorage:
             self._cosmos_client = CosmosClient(
                 url=settings["endpoint"],  # type: ignore[arg-type]
                 credential=credential or settings["key"].get_secret_value(),  # type: ignore[arg-type,union-attr]
-                user_agent_suffix=AGENT_FRAMEWORK_USER_AGENT,
+                user_agent_suffix=get_user_agent(),
             )
             self._owns_client = True
 

python/packages/azure-cosmos/agent_framework_azure_cosmos/_history_provider.py

@@ -10,9 +10,10 @@ import uuid
 from collections.abc import Sequence
 from typing import Any, ClassVar, TypedDict
 
-from agent_framework import AGENT_FRAMEWORK_USER_AGENT, Message
+from agent_framework import Message
 from agent_framework._sessions import HistoryProvider
 from agent_framework._settings import SecretString, load_settings
+from agent_framework._telemetry import get_user_agent
 from azure.core.credentials import TokenCredential
 from azure.core.credentials_async import AsyncTokenCredential
 from azure.cosmos import PartitionKey
@@ -121,7 +122,7 @@ class CosmosHistoryProvider(HistoryProvider):
             self._cosmos_client = CosmosClient(
                 url=settings["endpoint"],  # type: ignore[arg-type]
                 credential=credential or settings["key"].get_secret_value(),  # type: ignore[arg-type,union-attr]
-                user_agent_suffix=AGENT_FRAMEWORK_USER_AGENT,
+                user_agent_suffix=get_user_agent(),
             )
             self._owns_client = True
 

python/packages/azure-cosmos/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Cosmos DB history provider integration for Microsoft Agent
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "azure-cosmos>=4.3.0,<5",
 ]
 

python/packages/azurefunctions/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Functions integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "agent-framework-durabletask",
     "azure-functions>=1.24.0,<2",
     "azure-functions-durable>=1.3.1,<2",

python/packages/bedrock/agent_framework_bedrock/_chat_client.py

@@ -13,7 +13,6 @@ from typing import Any, ClassVar, Generic, Literal, TypedDict
 from uuid import uuid4
 
 from agent_framework import (
-    AGENT_FRAMEWORK_USER_AGENT,
     BaseChatClient,
     ChatAndFunctionMiddlewareTypes,
     ChatMiddlewareLayer,
@@ -31,6 +30,7 @@ from agent_framework import (
     validate_tool_mode,
 )
 from agent_framework._settings import SecretString, load_settings
+from agent_framework._telemetry import get_user_agent
 from agent_framework.exceptions import ChatClientInvalidResponseException
 from agent_framework.observability import ChatTelemetryLayer
 from boto3.session import Session as Boto3Session
@@ -299,7 +299,7 @@ class BedrockChatClient(
             self._bedrock_client = session.client(
                 "bedrock-runtime",
                 region_name=region,
-                config=BotoConfig(user_agent_extra=AGENT_FRAMEWORK_USER_AGENT),
+                config=BotoConfig(user_agent_extra=get_user_agent()),
             )
 
         super().__init__(

python/packages/bedrock/agent_framework_bedrock/_embedding_client.py

@@ -11,7 +11,6 @@ from collections.abc import Sequence
 from typing import Any, ClassVar, Generic, TypedDict
 
 from agent_framework import (
-    AGENT_FRAMEWORK_USER_AGENT,
     BaseEmbeddingClient,
     Embedding,
     EmbeddingGenerationOptions,
@@ -20,6 +19,7 @@ from agent_framework import (
     UsageDetails,
     load_settings,
 )
+from agent_framework._telemetry import get_user_agent
 from agent_framework.observability import EmbeddingTelemetryLayer
 from boto3.session import Session as Boto3Session
 from botocore.client import BaseClient
@@ -140,7 +140,7 @@ class RawBedrockEmbeddingClient(
             self._bedrock_client = boto3_session.client(
                 "bedrock-runtime",
                 region_name=region_name or resolved_region,
-                config=BotoConfig(user_agent_extra=AGENT_FRAMEWORK_USER_AGENT),
+                config=BotoConfig(user_agent_extra=get_user_agent()),
             )
 
         self.model: str = settings["embedding_model"]  # type: ignore[assignment]  # pyright: ignore[reportTypedDictNotRequiredAccess]

python/packages/bedrock/pyproject.toml

@@ -4,7 +4,7 @@ description = "Amazon Bedrock integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "boto3>=1.35.0,<2.0.0",
     "botocore>=1.35.0,<2.0.0",
 ]

python/packages/chatkit/pyproject.toml

@@ -4,7 +4,7 @@ description = "OpenAI ChatKit integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "openai-chatkit>=1.4.1,<2.0.0",
 ]
 

python/packages/claude/pyproject.toml

@@ -4,7 +4,7 @@ description = "Claude Agent SDK integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "claude-agent-sdk>=0.1.36,<0.1.49",
 ]
 

python/packages/copilotstudio/pyproject.toml

@@ -4,7 +4,7 @@ description = "Copilot Studio integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260423"
+version = "1.0.0b260424"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.1.1,<2",
+    "agent-framework-core>=1.2.0,<2",
     "microsoft-agents-copilotstudio-client>=0.3.1,<0.3.2",
 ]
 

python/packages/core/agent_framework/__init__.py

@@ -213,6 +213,15 @@ from ._workflows._executor import (
     handler,
 )
 from ._workflows._function_executor import FunctionExecutor, executor
+from ._workflows._functional import (
+    FunctionalWorkflow,
+    FunctionalWorkflowAgent,
+    RunContext,
+    StepWrapper,
+    get_run_context,
+    step,
+    workflow,
+)
 from ._workflows._request_info_mixin import response_handler
 from ._workflows._runner import Runner
 from ._workflows._runner_context import (
@@ -238,6 +247,7 @@ from ._workflows._workflow_executor import (
     WorkflowExecutor,
 )
 from .exceptions import (
+    AgentFrameworkException,
     MiddlewareException,
     UserInputRequiredException,
     WorkflowCheckpointException,
@@ -271,6 +281,7 @@ __all__ = [
     "AgentExecutor",
     "AgentExecutorRequest",
     "AgentExecutorResponse",
+    "AgentFrameworkException",
     "AgentMiddleware",
     "AgentMiddlewareLayer",
     "AgentMiddlewareTypes",
@@ -332,6 +343,8 @@ __all__ = [
     "FunctionMiddleware",
     "FunctionMiddlewareTypes",
     "FunctionTool",
+    "FunctionalWorkflow",
+    "FunctionalWorkflowAgent",
     "GeneratedEmbeddings",
     "GraphConnectivityError",
     "HistoryProvider",
@@ -354,6 +367,7 @@ __all__ = [
     "ResponseStream",
     "Role",
     "RoleLiteral",
+    "RunContext",
     "Runner",
     "RunnerContext",
     "SecretString",
@@ -366,6 +380,7 @@ __all__ = [
     "SkillScriptRunner",
     "SkillsProvider",
     "SlidingWindowStrategy",
+    "StepWrapper",
     "SubWorkflowRequestMessage",
     "SubWorkflowResponseMessage",
     "SummarizationStrategy",
@@ -424,6 +439,7 @@ __all__ = [
     "evaluator",
     "executor",
     "function_middleware",
+    "get_run_context",
     "handler",
     "included_messages",
     "included_token_count",
@@ -439,6 +455,7 @@ __all__ = [
     "register_state_type",
     "resolve_agent_id",
     "response_handler",
+    "step",
     "tool",
     "tool_call_args_match",
     "tool_called_check",
@@ -447,4 +464,5 @@ __all__ = [
     "validate_tool_mode",
     "validate_tools",
     "validate_workflow_graph",
+    "workflow",
 ]

python/packages/core/agent_framework/_feature_stage.py

@@ -48,6 +48,7 @@ class ExperimentalFeature(str, Enum):
 
     EVALS = "EVALS"
     FILE_HISTORY = "FILE_HISTORY"
+    FUNCTIONAL_WORKFLOWS = "FUNCTIONAL_WORKFLOWS"
     SKILLS = "SKILLS"
     TOOLBOXES = "TOOLBOXES"
 

python/packages/core/agent_framework/_telemetry.py

@@ -2,11 +2,9 @@
 
 from __future__ import annotations
 
+import contextlib
 import logging
 import os
-from collections.abc import Generator
-from contextlib import contextmanager
-from contextvars import ContextVar
 from typing import Any, Final
 
 from . import __version__ as version_info
@@ -29,34 +27,71 @@ USER_AGENT_KEY: Final[str] = "User-Agent"
 HTTP_USER_AGENT: Final[str] = "agent-framework-python"
 AGENT_FRAMEWORK_USER_AGENT = f"{HTTP_USER_AGENT}/{version_info}"  # type: ignore[has-type]
 
-_user_agent_prefixes: ContextVar[tuple[str, ...]] = ContextVar("_user_agent_prefixes", default=())
+# This environment variable is reserved by the Foundry hosting environment to
+# indicate that the agent is running in a hosted environment.
+_FOUNDRY_HOSTING_ENV_VAR = "FOUNDRY_HOSTING_ENVIRONMENT"
+# This prefix is added to the user agent string when the agent is running in a hosted environment.
+_HOSTED_USER_AGENT_PREFIX = "foundry-hosting"
+
+_user_agent_prefixes: set[str] = set()
+_hosted_env_detected: bool = False
 
 
-@contextmanager
-def user_agent_prefix(prefix: str) -> Generator[None]:
-    """Context manager that adds a prefix to the user agent string for the current scope.
+def _add_user_agent_prefix(prefix: str) -> None:
+    """Permanently add a prefix to the user agent string.
 
-    This is useful for upstream layers that want to identify themselves in telemetry
-    for the duration of a request without permanently mutating global state.
+    This is used by hosting layers to identify themselves in telemetry.
+    Once added, the prefix applies to all subsequent user agent strings.
 
     Args:
         prefix: The prefix to add (e.g. "foundry-hosting").
     """
-    current = _user_agent_prefixes.get()
-    token = _user_agent_prefixes.set((*current, prefix)) if prefix and prefix not in current else None
+    if prefix:
+        _user_agent_prefixes.add(prefix)
+
+
+def _detect_hosted_environment() -> None:
+    """Detect if running in a hosted environment and add the user agent prefix.
+
+    Checks the ``FOUNDRY_HOSTING_ENVIRONMENT`` env var first, then falls back
+    to checking whether the agent server SDK is installed (via
+    ``importlib.util.find_spec``) before importing it, to avoid unnecessary
+    import overhead for non-hosted scenarios.
+    """
+    global _hosted_env_detected
+    if _hosted_env_detected:
+        return
+
+    if (env_value := os.environ.get(_FOUNDRY_HOSTING_ENV_VAR)) is not None:
+        # Env var exists — trust its value and skip the fallback.
+        if env_value:
+            _add_user_agent_prefix(_HOSTED_USER_AGENT_PREFIX)
+            _hosted_env_detected = True
+        return
+
+    # Env var not set — fall back to AgentConfig as a second layer of defense.
+    # Use find_spec to avoid the cost of a full import when the SDK is not installed.
+    import importlib.util
+
     try:
-        yield
-    finally:
-        if token is not None:
-            _user_agent_prefixes.reset(token)
+        if importlib.util.find_spec("azure.ai.agentserver.core") is None:
+            return
+    except (ModuleNotFoundError, ValueError):
+        return
+    with contextlib.suppress(ImportError, AttributeError):
+        from azure.ai.agentserver.core import AgentConfig  # pyright: ignore[reportMissingImports]
+
+        if AgentConfig.from_env().is_hosted:
+            _add_user_agent_prefix(_HOSTED_USER_AGENT_PREFIX)
+            _hosted_env_detected = True
 
 
-def _get_user_agent() -> str:
-    """Return the full user agent string including any context-scoped prefixes."""
-    prefixes = _user_agent_prefixes.get()
-    if not prefixes:
+def get_user_agent() -> str:
+    """Return the full user agent string including any registered prefixes."""
+    _detect_hosted_environment()
+    if not _user_agent_prefixes:
         return AGENT_FRAMEWORK_USER_AGENT
-    return f"{'/'.join(prefixes)}/{AGENT_FRAMEWORK_USER_AGENT}"
+    return f"{'/'.join(sorted(_user_agent_prefixes))}/{AGENT_FRAMEWORK_USER_AGENT}"
 
 
 def prepend_agent_framework_to_user_agent(headers: dict[str, Any] | None = None) -> dict[str, Any]:
@@ -89,7 +124,7 @@ def prepend_agent_framework_to_user_agent(headers: dict[str, Any] | None = None)
     """
     if not IS_TELEMETRY_ENABLED:
         return headers or {}
-    user_agent = _get_user_agent()
+    user_agent = get_user_agent()
     if not headers:
         return {USER_AGENT_KEY: user_agent}
     headers[USER_AGENT_KEY] = f"{user_agent} {headers[USER_AGENT_KEY]}" if USER_AGENT_KEY in headers else user_agent

python/packages/core/agent_framework/_workflows/_events.py

@@ -120,6 +120,7 @@ WorkflowEventType = Literal[
     "executor_invoked",  # Executor handler was called (use .executor_id, .data)
     "executor_completed",  # Executor handler completed (use .executor_id, .data)
     "executor_failed",  # Executor handler raised error (use .executor_id, .details)
+    "executor_bypassed",  # Executor skipped via cache hit during replay (use .executor_id, .data)
     # Orchestration event types (use .data for typed payload)
     "group_chat",  # Group chat orchestrator events (use .data as GroupChatRequestSentEvent | GroupChatResponseReceivedEvent) # noqa: E501
     "handoff_sent",  # Handoff routing events (use .data as HandoffSentEvent)
@@ -148,6 +149,7 @@ class WorkflowEvent(Generic[DataT]):
     - `WorkflowEvent.executor_invoked(executor_id)` - executor handler called
     - `WorkflowEvent.executor_completed(executor_id)` - executor handler completed
     - `WorkflowEvent.executor_failed(executor_id, details)` - executor handler failed
+    - `WorkflowEvent.executor_bypassed(executor_id)` - executor skipped via cache hit
 
     The generic parameter DataT represents the type of the event's data payload:
     - Lifecycle events: `WorkflowEvent[None]` (data is None)
@@ -318,6 +320,11 @@ class WorkflowEvent(Generic[DataT]):
         """Create an 'executor_failed' event when an executor handler raises an error."""
         return WorkflowEvent("executor_failed", executor_id=executor_id, data=details, details=details)
 
+    @classmethod
+    def executor_bypassed(cls, executor_id: str, data: DataT | None = None) -> WorkflowEvent[DataT]:
+        """Create an 'executor_bypassed' event when a step is skipped via cache hit during replay."""
+        return cls("executor_bypassed", executor_id=executor_id, data=data)
+
     # ==========================================================================
     # Property for type-safe access
     # ==========================================================================

python/packages/core/agent_framework/_workflows/_workflow.py

@@ -340,10 +340,10 @@ class Workflow(DictConvertible):
                 # Emit explicit start/status events to the stream
                 with _framework_event_origin():
                     started = WorkflowEvent.started()
-                yield started
+                yield started  # noqa: RUF070
                 with _framework_event_origin():
                     in_progress = WorkflowEvent.status(WorkflowRunState.IN_PROGRESS)
-                yield in_progress
+                yield in_progress  # noqa: RUF070
 
                 # Reset context for a new run if supported
                 if reset_context:
@@ -388,7 +388,7 @@ class Workflow(DictConvertible):
                         emitted_in_progress_pending = True
                         with _framework_event_origin():
                             pending_status = WorkflowEvent.status(WorkflowRunState.IN_PROGRESS_PENDING_REQUESTS)
-                        yield pending_status
+                        yield pending_status  # noqa: RUF070
                 # Workflow runs until idle - emit final status based on whether requests are pending
                 if saw_request:
                     with _framework_event_origin():
@@ -409,10 +409,10 @@ class Workflow(DictConvertible):
                 details = WorkflowErrorDetails.from_exception(exc)
                 with _framework_event_origin():
                     failed_event = WorkflowEvent.failed(details)
-                yield failed_event
+                yield failed_event  # noqa: RUF070
                 with _framework_event_origin():
                     failed_status = WorkflowEvent.status(WorkflowRunState.FAILED)
-                yield failed_status
+                yield failed_status  # noqa: RUF070
                 span.add_event(
                     name=OtelAttr.WORKFLOW_ERROR,
                     attributes={