Add error handling to additional workflow samples with agents

Co-authored-by: lokitoth <6936551+lokitoth@users.noreply.github.com>

.devcontainer/dotnet/devcontainer.json

@@ -1,9 +1,12 @@
 {
   "name": "C# (.NET)",
-  "image": "mcr.microsoft.com/devcontainers/dotnet",
+  //"image": "mcr.microsoft.com/devcontainers/dotnet",
+  // Workaround for https://github.com/devcontainers/images/issues/1752
+  "build": {
+    "dockerfile": "dotnet.Dockerfile"
+  },
   "features": {
     "ghcr.io/devcontainers/features/azure-cli:1.2.9": {},
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
     "ghcr.io/devcontainers/features/github-cli:1": {
       "version": "2"
     },

.devcontainer/dotnet/dotnet.Dockerfile

@@ -0,0 +1,5 @@
+FROM mcr.microsoft.com/devcontainers/universal:latest
+
+# Remove Yarn repository with expired GPG key to prevent apt-get update failures
+# Tracking issue: https://github.com/devcontainers/images/issues/1752
+RUN rm -f /etc/apt/sources.list.d/yarn.list

.github/.linkspector.yml

@@ -20,7 +20,6 @@ ignorePatterns:
   - pattern: "https://your-resource.openai.azure.com/"
   - pattern: "http://host.docker.internal"
   - pattern: "https://openai.github.io/openai-agents-js/openai/agents/classes/"
-  - pattern: "https:\/\/dotnet.microsoft.com\/download"
 # excludedDirs:
   # Folders which include links to localhost, since it's not ignored with regular expressions
 baseUrl: https://github.com/microsoft/agent-framework/

.github/actions/python-setup/action.yml

@@ -8,10 +8,6 @@ inputs:
     os:
       description: The operating system to set up
       required: true
-    exclude-packages:
-      description: Space-separated list of packages to exclude from uv sync
-      required: false
-      default: ''
 
 runs:
     using: "composite"
@@ -23,20 +19,6 @@ runs:
             enable-cache: true
             cache-suffix: ${{ inputs.os }}-${{ inputs.python-version }}
             cache-dependency-glob: "**/uv.lock"
-      - name: Exclude incompatible workspace packages
-        if: ${{ inputs.exclude-packages != '' }}
-        shell: bash
-        run: |
-          for pkg in ${{ inputs.exclude-packages }}; do
-            for f in python/packages/*/pyproject.toml; do
-              if grep -q "name = \"$pkg\"" "$f"; then
-                pkg_dir=$(dirname "$f" | sed 's|python/||')
-                echo "Excluding workspace package: $pkg ($pkg_dir)"
-                sed -i.bak '/\[tool\.uv\.workspace\]/a\exclude = ["'"$pkg_dir"'"]' python/pyproject.toml
-                sed -i.bak '/'"$pkg"' = { workspace = true }/d' python/pyproject.toml
-              fi
-            done
-          done
       - name: Install the project
         shell: bash
         run: |

.github/actions/sample-validation-setup/action.yml

@@ -1,50 +0,0 @@
-name: Sample Validation Setup
-description: Sets up the environment for sample validation (checkout, Node.js, Copilot CLI, Azure login, Python)
-
-inputs:
-  azure-client-id:
-    description: Azure Client ID for OIDC login
-    required: true
-  azure-tenant-id:
-    description: Azure Tenant ID for OIDC login
-    required: true
-  azure-subscription-id:
-    description: Azure Subscription ID for OIDC login
-    required: true
-  python-version:
-    description: The Python version to set up
-    required: false
-    default: "3.12"
-  os:
-    description: The operating system to set up
-    required: false
-    default: "Linux"
-
-runs:
-  using: "composite"
-  steps:
-    - name: Set up Node.js environment
-      uses: actions/setup-node@v6
-      with:
-        node-version: 22
-
-    - name: Install Copilot CLI
-      shell: bash
-      run: npm install -g @github/copilot
-
-    - name: Test Copilot CLI
-      shell: bash
-      run: copilot --version && copilot -p "What can you do in one sentence?"
-
-    - name: Azure CLI Login
-      uses: azure/login@v2
-      with:
-        client-id: ${{ inputs.azure-client-id }}
-        tenant-id: ${{ inputs.azure-tenant-id }}
-        subscription-id: ${{ inputs.azure-subscription-id }}
-
-    - name: Set up python and install the project
-      uses: ./.github/actions/python-setup
-      with:
-        python-version: ${{ inputs.python-version }}
-        os: ${{ inputs.os }}

.github/actions/setup-local-mcp-server/action.yml

@@ -1,166 +0,0 @@
-name: Setup Local MCP Server
-description: Start and validate a local streamable HTTP MCP server for integration tests
-
-inputs:
-  fallback_url:
-    description: Existing LOCAL_MCP_URL value to keep as a fallback if local startup fails
-    required: false
-    default: ''
-  host:
-    description: Host interface to bind the local MCP server
-    required: false
-    default: '127.0.0.1'
-  port:
-    description: Port to bind the local MCP server
-    required: false
-    default: '8011'
-  mount_path:
-    description: Mount path for the local streamable HTTP MCP endpoint
-    required: false
-    default: '/mcp'
-
-outputs:
-  effective_url:
-    description: Local MCP URL when startup succeeds, otherwise the provided fallback URL
-    value: ${{ steps.start.outputs.effective_url }}
-  local_url:
-    description: URL of the local MCP server
-    value: ${{ steps.start.outputs.local_url }}
-  started:
-    description: Whether the local MCP server started and passed validation
-    value: ${{ steps.start.outputs.started }}
-  pid:
-    description: PID of the local MCP server process when startup succeeded
-    value: ${{ steps.start.outputs.pid }}
-
-runs:
-  using: composite
-  steps:
-    - name: Start and validate local MCP server
-      id: start
-      shell: bash
-      run: |
-        set -euo pipefail
-
-        host="${{ inputs.host }}"
-        port="${{ inputs.port }}"
-        mount_path="${{ inputs.mount_path }}"
-        fallback_url="${{ inputs.fallback_url }}"
-
-        if [[ ! "$mount_path" =~ ^/ ]]; then
-          mount_path="/$mount_path"
-        fi
-
-        local_url="http://${host}:${port}${mount_path}"
-        health_url="http://${host}:${port}/healthz"
-        log_file="$RUNNER_TEMP/local-mcp-server.log"
-        pid_file="$RUNNER_TEMP/local-mcp-server.pid"
-        rm -f "$log_file" "$pid_file"
-
-        server_pid="$(
-          python3 - "$GITHUB_WORKSPACE/python" "$log_file" "$host" "$port" "$mount_path" <<'PY'
-        from __future__ import annotations
-
-        import subprocess
-        import sys
-
-        workspace, log_file, host, port, mount_path = sys.argv[1:]
-
-        with open(log_file, "w", encoding="utf-8") as log:
-            process = subprocess.Popen(
-                [
-                    "uv",
-                    "run",
-                    "python",
-                    "scripts/local_mcp_streamable_http_server.py",
-                    "--host",
-                    host,
-                    "--port",
-                    port,
-                    "--mount-path",
-                    mount_path,
-                ],
-                cwd=workspace,
-                stdout=log,
-                stderr=subprocess.STDOUT,
-                start_new_session=True,
-            )
-
-        print(process.pid)
-        PY
-        )"
-        echo "$server_pid" > "$pid_file"
-
-        started=false
-        for _ in $(seq 1 30); do
-          if curl --silent --fail "$health_url" >/dev/null; then
-            started=true
-            break
-          fi
-          if ! kill -0 "$server_pid" 2>/dev/null; then
-            break
-          fi
-          sleep 1
-        done
-
-        if [[ "$started" == "true" ]]; then
-          if ! (
-            cd "$GITHUB_WORKSPACE/python"
-            LOCAL_MCP_URL="$local_url" uv run python - <<'PY'
-        from __future__ import annotations
-
-        import asyncio
-        import os
-
-        from agent_framework import Content, MCPStreamableHTTPTool
-
-
-        def result_to_text(result: str | list[Content]) -> str:
-            if isinstance(result, str):
-                return result
-            return "\n".join(content.text for content in result if content.type == "text" and content.text)
-
-
-        async def main() -> None:
-            tool = MCPStreamableHTTPTool(
-                name="local_ci_mcp",
-                url=os.environ["LOCAL_MCP_URL"],
-                approval_mode="never_require",
-            )
-
-            async with tool:
-                assert tool.functions, "Local MCP server did not expose any tools."
-                result = result_to_text(await tool.functions[0].invoke(query="What is Agent Framework?"))
-                assert result, "Local MCP server returned an empty response."
-
-
-        asyncio.run(main())
-        PY
-          ); then
-            started=false
-          fi
-        fi
-
-        effective_url="$local_url"
-        pid="$server_pid"
-
-        if [[ "$started" != "true" ]]; then
-          effective_url="$fallback_url"
-          pid=""
-          if kill -0 "$server_pid" 2>/dev/null; then
-            kill -TERM -- "-$server_pid" 2>/dev/null || kill -TERM "$server_pid" || true
-            sleep 1
-            kill -KILL -- "-$server_pid" 2>/dev/null || kill -KILL "$server_pid" || true
-          fi
-          echo "Local MCP server was unavailable; continuing with fallback LOCAL_MCP_URL."
-          if [[ -f "$log_file" ]]; then
-            tail -n 100 "$log_file" || true
-          fi
-        else
-          echo "Using local MCP server at $local_url"
-        fi
-
-        echo "started=$started" >> "$GITHUB_OUTPUT"
-        echo "local_url=$local_url" >> "$GITHUB_OUTPUT"
-        echo "effective_url=$effective_url" >> "$GITHUB_OUTPUT"
-        echo "pid=$pid" >> "$GITHUB_OUTPUT"

.github/labeler.yml

@@ -23,7 +23,7 @@ workflows:
   - any-glob-to-any-file:
     - dotnet/src/Microsoft.Agents.AI.Workflows/**
     - dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/**
-    - dotnet/samples/03-workflows/**
+    - dotnet/samples/GettingStarted/Workflow/**
     - python/packages/main/agent_framework/_workflow/**
     - python/samples/getting_started/workflow/**
 

.github/scripts/stale_issue_pr_ping.py

@@ -1,216 +0,0 @@
-# Copyright (c) Microsoft. All rights reserved.
-
-"""Scan open issues and PRs labeled 'waiting-for-author' for stale follow-ups.
-
-Team members manually add the 'waiting-for-author' label when they need a
-response from the external author.  If the author hasn't replied within
-DAYS_THRESHOLD days of the last team comment, post a reminder and add the
-'requested-info' label to prevent duplicate pings.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-import time
-from datetime import datetime, timezone
-
-from github import Auth, Github, GithubException
-from github.Issue import Issue
-from github.IssueComment import IssueComment
-
-
-PING_COMMENT = (
-    "@{author}, friendly reminder — this issue is waiting on your response. "
-    "Please share any updates when you get a chance. (This is an automated message.)"
-)
-TRIGGER_LABEL = "waiting-for-author"
-PINGED_LABEL = "requested-info"
-
-
-def get_team_members(g: Github, org: str, team_slug: str) -> set[str]:
-    """Fetch active team member usernames."""
-    try:
-        org_obj = g.get_organization(org)
-        team = org_obj.get_team_by_slug(team_slug)
-        return {m.login for m in team.get_members()}
-    except GithubException as exc:
-        if exc.status in (403, 404):
-            print(
-                f"ERROR: Failed to fetch team members for {org}/{team_slug} "
-                f"(HTTP {exc.status}). Check that the token has the 'read:org' "
-                f"scope and that the team slug '{team_slug}' is correct."
-            )
-        else:
-            print(f"ERROR: Failed to fetch team members for {org}/{team_slug}: {exc}")
-        sys.exit(1)
-    except Exception as exc:
-        print(f"ERROR: Failed to fetch team members for {org}/{team_slug}: {exc}")
-        sys.exit(1)
-
-
-def find_last_team_comment(
-    comments: list[IssueComment], team_members: set[str]
-) -> IssueComment | None:
-    """Return the most recent comment from a team member, or None."""
-    for comment in reversed(comments):
-        if comment.user and comment.user.login in team_members:
-            return comment
-    return None
-
-
-def author_replied_after(
-    comments: list[IssueComment], author: str, after: datetime
-) -> bool:
-    """Check if the issue author commented after the given timestamp."""
-    for comment in comments:
-        if (
-            comment.user
-            and comment.user.login == author
-            and comment.created_at > after
-        ):
-            return True
-    return False
-
-
-def should_ping(
-    issue: Issue,
-    team_members: set[str],
-    days_threshold: int,
-    now: datetime,
-) -> bool:
-    """Determine whether this issue/PR should be pinged.
-
-    Only issues/PRs carrying the 'waiting-for-author' label are candidates.
-    """
-    author = issue.user.login
-
-    # Skip if the trigger label is not present
-    if not any(label.name == TRIGGER_LABEL for label in issue.labels):
-        return False
-    # Skip if author is a team member
-    if author in team_members:
-        return False
-
-    # Skip if already pinged
-    if any(label.name == PINGED_LABEL for label in issue.labels):
-        return False
-
-    # Skip if no comments at all
-    if issue.comments == 0:
-        return False
-
-    # Fetch comments once for both lookups
-    comments = list(issue.get_comments())
-
-    # Find last team member comment
-    last_team_comment = find_last_team_comment(comments, team_members)
-    if last_team_comment is None:
-        return False
-
-    # Skip if author replied after the last team comment
-    if author_replied_after(comments, author, last_team_comment.created_at):
-        return False
-
-    # Check if enough days have passed
-    days_since = (now - last_team_comment.created_at.astimezone(timezone.utc)).days
-    if days_since < days_threshold:
-        return False
-
-    return True
-
-
-def ping(issue: Issue, dry_run: bool) -> bool:
-    """Post a reminder comment and add the 'requested-info' label. Returns True on success."""
-    author = issue.user.login
-    kind = "PR" if issue.pull_request else "Issue"
-
-    if dry_run:
-        print(f"  [DRY RUN] Would ping {kind} #{issue.number} (@{author})")
-        return True
-
-    max_retries = 3
-    commented = False
-    labeled = False
-    for attempt in range(1, max_retries + 1):
-        try:
-            if not commented:
-                issue.create_comment(PING_COMMENT.format(author=author))
-                commented = True
-            if not labeled:
-                issue.add_to_labels(PINGED_LABEL)
-                labeled = True
-            print(f"  Pinged {kind} #{issue.number} (@{author})")
-            return True
-        except Exception as exc:
-            if attempt < max_retries:
-                wait = 2 ** attempt  # 2s, 4s
-                print(f"  WARN: Attempt {attempt}/{max_retries} failed for {kind} #{issue.number}: {exc}. Retrying in {wait}s...")
-                time.sleep(wait)
-            else:
-                print(f"  ERROR: Failed to ping {kind} #{issue.number} after {max_retries} attempts: {exc}")
-                return False
-
-
-def main() -> None:
-    token = os.environ.get("GITHUB_TOKEN")
-    if not token:
-        print("ERROR: GITHUB_TOKEN environment variable is required")
-        sys.exit(1)
-
-    repository = os.environ.get("GITHUB_REPOSITORY")
-    if not repository:
-        print("ERROR: GITHUB_REPOSITORY environment variable is required")
-        sys.exit(1)
-
-    team_slug = os.environ.get("TEAM_SLUG")
-    if not team_slug:
-        print("ERROR: TEAM_SLUG environment variable is required")
-        sys.exit(1)
-
-    days_threshold_raw = os.environ.get("DAYS_THRESHOLD", "4")
-    try:
-        days_threshold = int(days_threshold_raw)
-    except ValueError:
-        print(f"ERROR: DAYS_THRESHOLD must be a numeric value, got '{days_threshold_raw}'")
-        sys.exit(1)
-    dry_run = os.environ.get("DRY_RUN", "false").lower() == "true"
-
-    org = repository.split("/")[0]
-
-    if dry_run:
-        print("Running in DRY RUN mode — no comments or labels will be applied.\n")
-
-    g = Github(auth=Auth.Token(token))
-    repo = g.get_repo(repository)
-
-    print(f"Fetching team members for {org}/{team_slug}...")
-    team_members = get_team_members(g, org, team_slug)
-    print(f"Found {len(team_members)} team members.\n")
-
-    now = datetime.now(timezone.utc)
-    pinged = []
-    failed = []
-    scanned = 0
-
-    print(f"Scanning open issues and PRs labeled '{TRIGGER_LABEL}' (threshold: {days_threshold} days)...\n")
-
-    for issue in repo.get_issues(state="open", labels=[TRIGGER_LABEL]):
-        scanned += 1
-
-        if should_ping(issue, team_members, days_threshold, now):
-            if ping(issue, dry_run):
-                pinged.append(issue.number)
-            else:
-                failed.append(issue.number)
-
-    print(f"\nDone. Scanned {scanned} items, pinged {len(pinged)}, failed {len(failed)}.")
-    if pinged:
-        print(f"Pinged: {', '.join(f'#{n}' for n in pinged)}")
-    if failed:
-        print(f"Failed: {', '.join(f'#{n}' for n in failed)}")
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

.github/tests/test_stale_issue_pr_ping.py

@@ -1,297 +0,0 @@
-# Copyright (c) Microsoft. All rights reserved.
-
-"""Tests for stale_issue_pr_ping.py."""
-
-from __future__ import annotations
-
-import os
-import sys
-from datetime import datetime, timezone, timedelta
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-# Ensure the script directory is importable
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "scripts"))
-
-from stale_issue_pr_ping import (
-    PINGED_LABEL,
-    PING_COMMENT,
-    TRIGGER_LABEL,
-    author_replied_after,
-    find_last_team_comment,
-    get_team_members,
-    main,
-    ping,
-    should_ping,
-)
-
-TEAM = {"alice", "bob"}
-NOW = datetime(2026, 3, 15, 12, 0, 0, tzinfo=timezone.utc)
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-def _make_comment(login: str | None, created_at: datetime) -> MagicMock:
-    """Create a mock IssueComment."""
-    c = MagicMock()
-    if login is None:
-        c.user = None
-    else:
-        c.user = MagicMock()
-        c.user.login = login
-    c.created_at = created_at
-    return c
-
-
-def _make_label(name: str) -> MagicMock:
-    lbl = MagicMock()
-    lbl.name = name
-    return lbl
-
-
-def _make_issue(
-    author: str = "external",
-    labels: list[str] | None = None,
-    comment_count: int = 1,
-    comments: list[MagicMock] | None = None,
-    pull_request: bool = False,
-    number: int = 42,
-) -> MagicMock:
-    issue = MagicMock()
-    issue.user = MagicMock()
-    issue.user.login = author
-    issue.number = number
-    # Default to having the trigger label, since the API query pre-filters.
-    if labels is None:
-        labels = [TRIGGER_LABEL]
-    issue.labels = [_make_label(n) for n in labels]
-    issue.comments = comment_count
-    issue.pull_request = MagicMock() if pull_request else None
-    if comments is not None:
-        issue.get_comments.return_value = comments
-    return issue
-
-
-# ---------------------------------------------------------------------------
-# find_last_team_comment
-# ---------------------------------------------------------------------------
-
-class TestFindLastTeamComment:
-    def test_returns_last_team_comment(self):
-        c1 = _make_comment("alice", datetime(2026, 3, 1, tzinfo=timezone.utc))
-        c2 = _make_comment("external", datetime(2026, 3, 2, tzinfo=timezone.utc))
-        c3 = _make_comment("bob", datetime(2026, 3, 3, tzinfo=timezone.utc))
-        assert find_last_team_comment([c1, c2, c3], TEAM) is c3
-
-    def test_returns_none_when_no_team_comments(self):
-        c1 = _make_comment("external", datetime(2026, 3, 1, tzinfo=timezone.utc))
-        assert find_last_team_comment([c1], TEAM) is None
-
-    def test_returns_none_for_empty_list(self):
-        assert find_last_team_comment([], TEAM) is None
-
-    def test_skips_deleted_user(self):
-        c1 = _make_comment(None, datetime(2026, 3, 1, tzinfo=timezone.utc))
-        c2 = _make_comment("alice", datetime(2026, 3, 2, tzinfo=timezone.utc))
-        assert find_last_team_comment([c1, c2], TEAM) is c2
-
-    def test_only_deleted_users(self):
-        c1 = _make_comment(None, datetime(2026, 3, 1, tzinfo=timezone.utc))
-        assert find_last_team_comment([c1], TEAM) is None
-
-
-# ---------------------------------------------------------------------------
-# author_replied_after
-# ---------------------------------------------------------------------------
-
-class TestAuthorRepliedAfter:
-    def test_author_replied(self):
-        after = datetime(2026, 3, 1, tzinfo=timezone.utc)
-        c1 = _make_comment("external", datetime(2026, 3, 2, tzinfo=timezone.utc))
-        assert author_replied_after([c1], "external", after) is True
-
-    def test_author_not_replied(self):
-        after = datetime(2026, 3, 5, tzinfo=timezone.utc)
-        c1 = _make_comment("external", datetime(2026, 3, 2, tzinfo=timezone.utc))
-        assert author_replied_after([c1], "external", after) is False
-
-    def test_different_user_replied(self):
-        after = datetime(2026, 3, 1, tzinfo=timezone.utc)
-        c1 = _make_comment("someone_else", datetime(2026, 3, 2, tzinfo=timezone.utc))
-        assert author_replied_after([c1], "external", after) is False
-
-    def test_deleted_user_comment(self):
-        after = datetime(2026, 3, 1, tzinfo=timezone.utc)
-        c1 = _make_comment(None, datetime(2026, 3, 2, tzinfo=timezone.utc))
-        assert author_replied_after([c1], "external", after) is False
-
-
-# ---------------------------------------------------------------------------
-# should_ping
-# ---------------------------------------------------------------------------
-
-class TestShouldPing:
-    def test_should_ping_stale_issue(self):
-        team_comment = _make_comment("alice", NOW - timedelta(days=5))
-        issue = _make_issue(comments=[team_comment], comment_count=1)
-        assert should_ping(issue, TEAM, 4, NOW) is True
-
-    def test_skip_team_member_author(self):
-        issue = _make_issue(author="alice", labels=[TRIGGER_LABEL], comment_count=1)
-        assert should_ping(issue, TEAM, 4, NOW) is False
-
-    def test_skip_already_pinged(self):
-        issue = _make_issue(labels=[TRIGGER_LABEL, PINGED_LABEL], comment_count=1)
-        assert should_ping(issue, TEAM, 4, NOW) is False
-
-    def test_skip_no_comments(self):
-        issue = _make_issue(comment_count=0)
-        assert should_ping(issue, TEAM, 4, NOW) is False
-
-    def test_skip_no_team_comment(self):
-        c = _make_comment("external", NOW - timedelta(days=5))
-        issue = _make_issue(comments=[c], comment_count=1)
-        assert should_ping(issue, TEAM, 4, NOW) is False
-
-    def test_skip_author_replied(self):
-        team_c = _make_comment("alice", NOW - timedelta(days=5))
-        author_c = _make_comment("external", NOW - timedelta(days=3))
-        issue = _make_issue(comments=[team_c, author_c], comment_count=2)
-        assert should_ping(issue, TEAM, 4, NOW) is False
-
-    def test_skip_not_enough_days(self):
-        team_comment = _make_comment("alice", NOW - timedelta(days=2))
-        issue = _make_issue(comments=[team_comment], comment_count=1)
-        assert should_ping(issue, TEAM, 4, NOW) is False
-
-    def test_aware_datetime_handled(self):
-        """Timezone-aware datetimes should not be mangled by astimezone."""
-        aware_dt = (NOW - timedelta(days=5)).replace(tzinfo=timezone.utc)
-        team_comment = _make_comment("alice", aware_dt)
-        issue = _make_issue(comments=[team_comment], comment_count=1)
-        assert should_ping(issue, TEAM, 4, NOW) is True
-
-    def test_naive_datetime_handled(self):
-        """Naive datetimes (pre-PyGithub 2.x) should be handled by astimezone."""
-        naive_dt = (NOW - timedelta(days=5)).replace(tzinfo=None)
-        team_comment = _make_comment("alice", naive_dt)
-        issue = _make_issue(comments=[team_comment], comment_count=1)
-        # astimezone on naive datetime treats it as local time; just verify no crash
-        should_ping(issue, TEAM, 4, NOW)
-
-
-# ---------------------------------------------------------------------------
-# ping
-# ---------------------------------------------------------------------------
-
-class TestPing:
-    def test_dry_run(self, capsys):
-        issue = _make_issue()
-        assert ping(issue, dry_run=True) is True
-        issue.create_comment.assert_not_called()
-        assert "DRY RUN" in capsys.readouterr().out
-
-    def test_success(self, capsys):
-        issue = _make_issue()
-        assert ping(issue, dry_run=False) is True
-        issue.create_comment.assert_called_once()
-        issue.add_to_labels.assert_called_once_with(PINGED_LABEL)
-
-    @patch("stale_issue_pr_ping.time.sleep")
-    def test_retry_on_failure(self, mock_sleep):
-        issue = _make_issue()
-        issue.create_comment.side_effect = [Exception("net error"), None]
-        assert ping(issue, dry_run=False) is True
-        assert issue.create_comment.call_count == 2
-        mock_sleep.assert_called_once()
-
-    @patch("stale_issue_pr_ping.time.sleep")
-    def test_idempotent_retry_skips_comment_on_label_failure(self, mock_sleep):
-        """If create_comment succeeds but add_to_labels fails, retry should not re-comment."""
-        issue = _make_issue()
-        issue.add_to_labels.side_effect = [Exception("label error"), None]
-        assert ping(issue, dry_run=False) is True
-        # Comment should only be created once even though there were 2 attempts
-        assert issue.create_comment.call_count == 1
-        assert issue.add_to_labels.call_count == 2
-
-    @patch("stale_issue_pr_ping.time.sleep")
-    def test_all_retries_fail(self, mock_sleep):
-        issue = _make_issue()
-        issue.create_comment.side_effect = Exception("permanent error")
-        assert ping(issue, dry_run=False) is False
-        assert issue.create_comment.call_count == 3
-
-
-# ---------------------------------------------------------------------------
-# get_team_members
-# ---------------------------------------------------------------------------
-
-class TestGetTeamMembers:
-    def test_success(self):
-        g = MagicMock()
-        member = MagicMock()
-        member.login = "alice"
-        g.get_organization.return_value.get_team_by_slug.return_value.get_members.return_value = [member]
-        assert get_team_members(g, "org", "my-team") == {"alice"}
-
-    def test_403_error_message(self, capsys):
-        from github import GithubException
-
-        g = MagicMock()
-        g.get_organization.return_value.get_team_by_slug.side_effect = GithubException(
-            403, {"message": "Forbidden"}, None
-        )
-        with pytest.raises(SystemExit):
-            get_team_members(g, "org", "my-team")
-        out = capsys.readouterr().out
-        assert "read:org" in out
-        assert "403" in out
-
-    def test_404_error_message(self, capsys):
-        from github import GithubException
-
-        g = MagicMock()
-        g.get_organization.return_value.get_team_by_slug.side_effect = GithubException(
-            404, {"message": "Not Found"}, None
-        )
-        with pytest.raises(SystemExit):
-            get_team_members(g, "org", "bad-slug")
-        out = capsys.readouterr().out
-        assert "read:org" in out
-        assert "bad-slug" in out
-
-    def test_generic_error(self, capsys):
-        g = MagicMock()
-        g.get_organization.side_effect = RuntimeError("boom")
-        with pytest.raises(SystemExit):
-            get_team_members(g, "org", "team")
-
-
-# ---------------------------------------------------------------------------
-# main – env var validation
-# ---------------------------------------------------------------------------
-
-class TestMain:
-    @patch.dict(os.environ, {
-        "GITHUB_TOKEN": "tok",
-        "GITHUB_REPOSITORY": "org/repo",
-        "TEAM_SLUG": "my-team",
-        "DAYS_THRESHOLD": "abc",
-    }, clear=True)
-    def test_invalid_days_threshold(self, capsys):
-        with pytest.raises(SystemExit):
-            main()
-        assert "numeric" in capsys.readouterr().out
-
-    @patch.dict(os.environ, {
-        "GITHUB_TOKEN": "tok",
-        "GITHUB_REPOSITORY": "org/repo",
-    }, clear=True)
-    def test_missing_team_slug(self, capsys):
-        with pytest.raises(SystemExit):
-            main()
-        assert "TEAM_SLUG" in capsys.readouterr().out

.github/workflows/dotnet-build-and-test.yml

@@ -59,20 +59,20 @@ jobs:
         if: steps.filter.outputs.dotnet != 'true'
         run: echo "NOT dotnet file"
 
-  # Build the full solution (including samples) on all TFMs. No tests.
-  dotnet-build:
+  dotnet-build-and-test:
     needs: paths-filter
     if: needs.paths-filter.outputs.dotnetChanges == 'true'
     strategy:
       fail-fast: false
       matrix:
         include:
-          - { targetFramework: "net10.0", os: "ubuntu-latest", configuration: Release }
+          - { targetFramework: "net10.0", os: "ubuntu-latest", configuration: Release, integration-tests: true, environment: "integration" }
           - { targetFramework: "net9.0", os: "windows-latest", configuration: Debug }
           - { targetFramework: "net8.0", os: "ubuntu-latest", configuration: Release }
-          - { targetFramework: "net472", os: "windows-latest", configuration: Release }
+          - { targetFramework: "net472", os: "windows-latest", configuration: Release, integration-tests: true, environment: "integration" }
 
     runs-on: ${{ matrix.os }}
+    environment: ${{ matrix.environment }}
     steps:
       - uses: actions/checkout@v6
         with:
@@ -84,8 +84,18 @@ jobs:
               python
               workflow-samples
 
+      # Start Cosmos DB Emulator for all integration tests and only for unit tests when CosmosDB changes happened)
+      - name: Start Azure Cosmos DB Emulator
+        if: ${{ runner.os == 'Windows' && (needs.paths-filter.outputs.cosmosDbChanges == 'true' || (github.event_name != 'pull_request' && matrix.integration-tests)) }}
+        shell: pwsh
+        run: |
+          Write-Host "Launching Azure Cosmos DB Emulator"
+          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
+          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
+
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
+        uses: actions/setup-dotnet@v5.1.0
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
       - name: Build dotnet solutions
@@ -130,98 +140,25 @@ jobs:
           popd
           rm -rf "$TEMP_DIR"
 
-  # Build src+tests only (no samples) for a single TFM and run tests.
-  dotnet-test:
-    needs: paths-filter
-    if: needs.paths-filter.outputs.dotnetChanges == 'true'
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - { targetFramework: "net10.0", os: "ubuntu-latest", configuration: Release, integration-tests: true, environment: "integration" }
-          - { targetFramework: "net472", os: "windows-latest", configuration: Release, integration-tests: true, environment: "integration" }
-
-    runs-on: ${{ matrix.os }}
-    environment: ${{ matrix.environment }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-            persist-credentials: false
-            sparse-checkout: |
-              .
-              .github
-              dotnet
-              python
-              workflow-samples
-
-      # Start Cosmos DB Emulator for all integration tests and only for unit tests when CosmosDB changes happened)
-      - name: Start Azure Cosmos DB Emulator
-        if: ${{ runner.os == 'Windows' && (needs.paths-filter.outputs.cosmosDbChanges == 'true' || (github.event_name != 'pull_request' && matrix.integration-tests)) }}
-        shell: pwsh
-        run: |
-          Write-Host "Launching Azure Cosmos DB Emulator"
-          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
-          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-          echo "COSMOSDB_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
-
-      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
-        with:
-          global-json-file: ${{ github.workspace }}/dotnet/global.json
-
-      - name: Generate test solution (no samples)
-        shell: pwsh
-        run: |
-          ./dotnet/eng/scripts/New-FilteredSolution.ps1 `
-            -Solution dotnet/agent-framework-dotnet.slnx `
-            -TargetFramework ${{ matrix.targetFramework }} `
-            -Configuration ${{ matrix.configuration }} `
-            -ExcludeSamples `
-            -OutputPath dotnet/filtered.slnx `
-            -Verbose
-
-      - name: Build src and tests
-        shell: bash
-        run: dotnet build dotnet/filtered.slnx -c ${{ matrix.configuration }} -f ${{ matrix.targetFramework }} --warnaserror
-
-      - name: Generate test-type filtered solutions
-        shell: pwsh
-        run: |
-          $commonArgs = @{
-            Solution       = "dotnet/filtered.slnx"
-            TargetFramework = "${{ matrix.targetFramework }}"
-            Configuration   = "${{ matrix.configuration }}"
-            Verbose         = $true
-          }
-          ./dotnet/eng/scripts/New-FilteredSolution.ps1 @commonArgs `
-            -TestProjectNameFilter "*UnitTests*" `
-            -OutputPath dotnet/filtered-unit.slnx
-          ./dotnet/eng/scripts/New-FilteredSolution.ps1 @commonArgs `
-            -TestProjectNameFilter "*IntegrationTests*" `
-            -OutputPath dotnet/filtered-integration.slnx
-
       - name: Run Unit Tests
-        shell: pwsh
-        working-directory: dotnet
+        shell: bash
         run: |
-          $coverageSettings = Join-Path $PWD "tests/coverage.runsettings"
-          $coverageArgs = @()
-          if ("${{ matrix.targetFramework }}" -eq "${{ env.COVERAGE_FRAMEWORK }}") {
-            $coverageArgs = @(
-              "--coverage",
-              "--coverage-output-format", "cobertura",
-              "--coverage-settings", $coverageSettings,
-              "--results-directory", "../TestResults/Coverage/"
-            )
-          }
+          export UT_PROJECTS=$(find ./dotnet -type f -name "*.UnitTests.csproj" | tr '\n' ' ')
+          for project in $UT_PROJECTS; do
+            # Query the project's target frameworks using MSBuild with the current configuration
+            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
 
-          dotnet test --solution ./filtered-unit.slnx `
-            -f ${{ matrix.targetFramework }} `
-            -c ${{ matrix.configuration }} `
-            --no-build -v Normal `
-            --report-xunit-trx `
-            --ignore-exit-code 8 `
-            @coverageArgs
+            # Check if the project supports the target framework
+            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
+              if [[ "${{ matrix.targetFramework }}" == "${{ env.COVERAGE_FRAMEWORK }}" ]]; then
+                dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --collect:"XPlat Code Coverage" --results-directory:"TestResults/Coverage/" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.ExcludeByAttribute=GeneratedCodeAttribute,CompilerGeneratedAttribute,ExcludeFromCodeCoverageAttribute
+              else
+                dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx
+              fi
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
+          done
         env:
           # Cosmos DB Emulator connection settings
           COSMOSDB_ENDPOINT: https://localhost:8081
@@ -248,48 +185,53 @@ jobs:
         id: azure-functions-setup
 
       - name: Run Integration Tests
-        shell: pwsh
-        working-directory: dotnet
+        shell: bash
         if: github.event_name != 'pull_request' && matrix.integration-tests
         run: |
-          dotnet test --solution ./filtered-integration.slnx `
-            -f ${{ matrix.targetFramework }} `
-            -c ${{ matrix.configuration }} `
-            --no-build -v Normal `
-            --report-xunit-trx `
-            --ignore-exit-code 8 `
-            --filter-not-trait "Category=IntegrationDisabled" `
-            --parallel-algorithm aggressive `
-            --max-threads 2.0x
+          export INTEGRATION_TEST_PROJECTS=$(find ./dotnet -type f -name "*IntegrationTests.csproj" | tr '\n' ' ')
+          for project in $INTEGRATION_TEST_PROJECTS; do
+            # Query the project's target frameworks using MSBuild with the current configuration
+            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
+
+            # Check if the project supports the target framework
+            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
+              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --filter "Category!=IntegrationDisabled"
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
+          done
         env:
           # Cosmos DB Emulator connection settings
           COSMOSDB_ENDPOINT: https://localhost:8081
           COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
           # OpenAI Models
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          OPENAI_CHAT_MODEL_NAME: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
-          OPENAI_REASONING_MODEL_NAME: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
+          OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
+          OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
+          OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
           # Azure OpenAI Models
-          AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
-          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
-          AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
           # Azure AI Foundry
-          AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-          AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
-          AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
+          AzureAI__Endpoint: ${{ secrets.AZUREAI__ENDPOINT }}
+          AzureAI__DeploymentName: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
+          AzureAI__BingConnectionId: ${{ vars.AZUREAI__BINGCONECTIONID }}
+          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+          FOUNDRY_MEDIA_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MEDIA_DEPLOYMENT_NAME }}
+          FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MODEL_DEPLOYMENT_NAME }}
+          FOUNDRY_CONNECTION_GROUNDING_TOOL: ${{ vars.FOUNDRY_CONNECTION_GROUNDING_TOOL }}
 
       # Generate test reports and check coverage
       - name: Generate test reports
         if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
-        uses: danielpalme/ReportGenerator-GitHub-Action@5.5.3
+        uses: danielpalme/ReportGenerator-GitHub-Action@5.5.1
         with:
-          reports: "./TestResults/Coverage/**/*.cobertura.xml"
+          reports: "./TestResults/Coverage/**/coverage.cobertura.xml"
           targetdir: "./TestResults/Reports"
           reporttypes: "HtmlInline;JsonSummary"
 
       - name: Upload coverage report artifact
         if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v6
         with:
           name: CoverageReport-${{ matrix.os }}-${{ matrix.targetFramework }}-${{ matrix.configuration }} # Artifact name
           path: ./TestResults/Reports # Directory containing files to upload
@@ -297,13 +239,13 @@ jobs:
       - name: Check coverage
         if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
         shell: pwsh
-        run: ./dotnet/eng/scripts/dotnet-check-coverage.ps1 -JsonReportPath "TestResults/Reports/Summary.json" -CoverageThreshold $env:COVERAGE_THRESHOLD
+        run: .github/workflows/dotnet-check-coverage.ps1 -JsonReportPath "TestResults/Reports/Summary.json" -CoverageThreshold $env:COVERAGE_THRESHOLD
 
   # This final job is required to satisfy the merge queue. It must only run (or succeed) if no tests failed
   dotnet-build-and-test-check:
     if: always()
     runs-on: ubuntu-latest
-    needs: [dotnet-build, dotnet-test]
+    needs: [dotnet-build-and-test]
     steps:
       - name: Get Date
         shell: bash

.github/workflows/dotnet-format.yml

@@ -86,10 +86,11 @@ jobs:
         run: docker pull mcr.microsoft.com/dotnet/sdk:${{ matrix.dotnet }}
 
       # This step will run dotnet format on each of the unique csproj files and fail if any changes are made
+      # exclude-diagnostics should be removed after fixes for IL2026 and IL3050 are out: https://github.com/dotnet/sdk/issues/51136
       - name: Run dotnet format
         if: steps.find-csproj.outputs.csproj_files != ''
         run: |
           for csproj in ${{ steps.find-csproj.outputs.csproj_files }}; do
             echo "Running dotnet format on $csproj"
-            docker run --rm -v $(pwd):/app -w /app mcr.microsoft.com/dotnet/sdk:${{ matrix.dotnet }} /bin/sh -c "dotnet format $csproj --verify-no-changes --verbosity diagnostic"
+            docker run --rm -v $(pwd):/app -w /app mcr.microsoft.com/dotnet/sdk:${{ matrix.dotnet }} /bin/sh -c "dotnet format $csproj --verify-no-changes --verbosity diagnostic --exclude-diagnostics IL2026 IL3050"
           done

.github/workflows/dotnet-integration-tests.yml

@@ -1,102 +0,0 @@
-#
-# Dedicated .NET integration tests workflow, called from the manual integration test orchestrator.
-# Only runs integration test matrix entries (net10.0 and net472).
-#
-
-name: dotnet-integration-tests
-
-on:
-  workflow_call:
-    inputs:
-      checkout-ref:
-        description: "Git ref to checkout (e.g., refs/pull/123/head)"
-        required: true
-        type: string
-
-permissions:
-  contents: read
-  id-token: write
-
-jobs:
-  dotnet-integration-tests:
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - { targetFramework: "net10.0", os: "ubuntu-latest", configuration: Release }
-          - { targetFramework: "net472", os: "windows-latest", configuration: Release }
-    runs-on: ${{ matrix.os }}
-    environment: integration
-    timeout-minutes: 60
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-          sparse-checkout: |
-            .
-            .github
-            dotnet
-            python
-            workflow-samples
-
-      - name: Start Azure Cosmos DB Emulator
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          Write-Host "Launching Azure Cosmos DB Emulator"
-          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
-          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
-
-      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.2.0
-        with:
-          global-json-file: ${{ github.workspace }}/dotnet/global.json
-
-      - name: Build dotnet solutions
-        shell: bash
-        run: |
-          export SOLUTIONS=$(find ./dotnet/ -type f -name "*.slnx" | tr '\n' ' ')
-          for solution in $SOLUTIONS; do
-            dotnet build $solution -c ${{ matrix.configuration }} --warnaserror
-          done
-
-      - 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: Set up Durable Task and Azure Functions Integration Test Emulators
-        if: matrix.os == 'ubuntu-latest'
-        uses: ./.github/actions/azure-functions-integration-setup
-
-      - name: Run Integration Tests
-        shell: bash
-        run: |
-          export INTEGRATION_TEST_PROJECTS=$(find ./dotnet -type f -name "*IntegrationTests.csproj" | tr '\n' ' ')
-          for project in $INTEGRATION_TEST_PROJECTS; do
-            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
-            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
-              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --filter "Category!=IntegrationDisabled"
-            else
-              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
-            fi
-          done
-        env:
-          COSMOSDB_ENDPOINT: https://localhost:8081
-          COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
-          OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
-          OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
-          OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
-          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-          AzureAI__Endpoint: ${{ secrets.AZUREAI__ENDPOINT }}
-          AzureAI__DeploymentName: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-          AzureAI__BingConnectionId: ${{ vars.AZUREAI__BINGCONECTIONID }}
-          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-          FOUNDRY_MEDIA_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MEDIA_DEPLOYMENT_NAME }}
-          FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MODEL_DEPLOYMENT_NAME }}
-          FOUNDRY_CONNECTION_GROUNDING_TOOL: ${{ vars.FOUNDRY_CONNECTION_GROUNDING_TOOL }}

.github/workflows/integration-tests-manual.yml

@@ -1,134 +0,0 @@
-#
-# This workflow allows manually running integration tests against an open PR or a branch.
-# Go to Actions → "Integration Tests (Manual)" → Run workflow → enter a PR number or branch name.
-#
-# It calls dedicated integration-only workflows (dotnet-integration-tests and python-integration-tests),
-# passing a ref so they check out and test the correct code.
-# Changed paths are detected here so only the relevant test suites run.
-#
-
-name: Integration Tests (Manual)
-
-on:
-  workflow_dispatch:
-    inputs:
-      pr-number:
-        description: "PR number to run integration tests against (leave empty if using branch)"
-        required: false
-        type: string
-        default: ""
-      branch:
-        description: "Branch name to run integration tests against (leave empty if using PR number)"
-        required: false
-        type: string
-        default: ""
-
-permissions:
-  contents: read
-  pull-requests: read
-  id-token: write
-
-concurrency:
-  group: integration-tests-manual-${{ github.event.inputs.pr-number || github.event.inputs.branch }}
-  cancel-in-progress: true
-
-jobs:
-  resolve-ref:
-    name: Resolve ref
-    runs-on: ubuntu-latest
-    outputs:
-      checkout-ref: ${{ steps.resolve.outputs.checkout-ref }}
-      dotnet-changes: ${{ steps.detect-changes.outputs.dotnet }}
-      python-changes: ${{ steps.detect-changes.outputs.python }}
-    steps:
-      - name: Resolve checkout ref
-        id: resolve
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ github.event.inputs.pr-number }}
-          BRANCH: ${{ github.event.inputs.branch }}
-          REPO: ${{ github.repository }}
-        run: |
-          if [ -n "$PR_NUMBER" ] && [ -n "$BRANCH" ]; then
-            echo "::error::Please provide either a PR number or a branch name, not both."
-            exit 1
-          fi
-
-          if [ -z "$PR_NUMBER" ] && [ -z "$BRANCH" ]; then
-            echo "::error::Please provide either a PR number or a branch name."
-            exit 1
-          fi
-
-          if [ -n "$PR_NUMBER" ]; then
-            if ! echo "$PR_NUMBER" | grep -Eq '^[0-9]+$'; then
-              echo "::error::Invalid PR number. Only numeric values are allowed."
-              exit 1
-            fi
-
-            PR_DATA=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json state)
-            PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
-
-            if [ "$PR_STATE" != "OPEN" ]; then
-              echo "::error::PR #$PR_NUMBER is not open (state: $PR_STATE)"
-              exit 1
-            fi
-
-            echo "checkout-ref=refs/pull/$PR_NUMBER/head" >> "$GITHUB_OUTPUT"
-            echo "Running integration tests for PR #$PR_NUMBER"
-          else
-            if ! echo "$BRANCH" | grep -Eq '^[a-zA-Z0-9_./-]+$'; then
-              echo "::error::Invalid branch name. Only alphanumeric characters, hyphens, underscores, dots, and slashes are allowed."
-              exit 1
-            fi
-
-            echo "checkout-ref=$BRANCH" >> "$GITHUB_OUTPUT"
-            echo "Running integration tests for branch $BRANCH"
-          fi
-
-      - name: Detect changed paths
-        id: detect-changes
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ github.event.inputs.pr-number }}
-          BRANCH: ${{ github.event.inputs.branch }}
-          REPO: ${{ github.repository }}
-        run: |
-          if [ -n "$PR_NUMBER" ]; then
-            CHANGED_FILES=$(gh pr diff "$PR_NUMBER" --repo "$REPO" --name-only)
-          else
-            # For branches, compare against main using the GitHub API
-            CHANGED_FILES=$(gh api "repos/$REPO/compare/main...$BRANCH" --jq '.files[].filename')
-          fi
-
-          DOTNET_CHANGES=false
-          PYTHON_CHANGES=false
-
-          if echo "$CHANGED_FILES" | grep -q '^dotnet/'; then
-            DOTNET_CHANGES=true
-          fi
-
-          if echo "$CHANGED_FILES" | grep -q '^python/'; then
-            PYTHON_CHANGES=true
-          fi
-
-          echo "dotnet=$DOTNET_CHANGES" >> "$GITHUB_OUTPUT"
-          echo "python=$PYTHON_CHANGES" >> "$GITHUB_OUTPUT"
-          echo "Detected changes — dotnet: $DOTNET_CHANGES, python: $PYTHON_CHANGES"
-
-  dotnet-integration-tests:
-    name: .NET Integration Tests
-    needs: resolve-ref
-    if: needs.resolve-ref.outputs.dotnet-changes == 'true'
-    uses: ./.github/workflows/dotnet-integration-tests.yml
-    with:
-      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
-    secrets: inherit
-
-  python-integration-tests:
-    name: Python Integration Tests
-    needs: resolve-ref
-    if: needs.resolve-ref.outputs.python-changes == 'true'
-    uses: ./.github/workflows/python-integration-tests.yml
-    with:
-      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
-    secrets: inherit

.github/workflows/merge-gatekeeper.yml

@@ -29,7 +29,4 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           timeout: 3600
           interval: 30
-          # "Cleanup artifacts", "Agent", "Prepare", and "Upload results" are check runs
-          # created by an org-level GitHub App (MSDO), not by any workflow in this repo.
-          # They are outside our control and their transient failures should not block merges.
-          ignored: CodeQL,CodeQL analysis (csharp),Cleanup artifacts,Agent,Prepare,Upload results
+          ignored: CodeQL,CodeQL analysis (csharp)

.github/workflows/python-check-coverage.py

@@ -1,13 +1,10 @@
 #!/usr/bin/env python3
 # Copyright (c) Microsoft. All rights reserved.
-"""Check Python test coverage against threshold for enforced targets.
+"""Check Python test coverage against threshold for enforced modules.
 
 This script parses a Cobertura XML coverage report and enforces a minimum
-coverage threshold on specific targets. Targets can be package names
-(e.g., "packages.core.agent_framework") or individual Python file paths
-(e.g., "packages/core/agent_framework/observability.py").
-
-Non-enforced targets are reported for visibility but don't block the build.
+coverage threshold on specific modules. Non-enforced modules are reported
+for visibility but don't block the build.
 
 Usage:
     python python-check-coverage.py <coverage-xml-path> <threshold>
@@ -21,30 +18,24 @@ import xml.etree.ElementTree as ET
 from dataclasses import dataclass
 
 # =============================================================================
-# ENFORCED TARGETS CONFIGURATION
+# ENFORCED MODULES CONFIGURATION
 # =============================================================================
-# Add or remove entries from this set to control which targets must meet
-# the coverage threshold. Only these targets will fail the build if below
-# threshold. Other targets are reported for visibility only.
+# Add or remove modules from this set to control which packages must meet
+# the coverage threshold. Only these modules will fail the build if below
+# threshold. Other modules are reported for visibility only.
 #
-# Target values can be:
-# - Package paths as they appear in the coverage report
-#   (e.g., "packages.azure-ai.agent_framework_azure_ai")
-# - Python source file paths as they appear in the coverage report
-#   (e.g., "packages/core/agent_framework/observability.py")
+# Module paths should match the package paths as they appear in the coverage
+# report (e.g., "packages.azure-ai.agent_framework_azure_ai" for packages/azure-ai).
+# Sub-modules can be included by specifying their full path.
 # =============================================================================
-ENFORCED_TARGETS: set[str] = {
-    # Packages
+ENFORCED_MODULES: set[str] = {
     "packages.azure-ai.agent_framework_azure_ai",
     "packages.core.agent_framework",
     "packages.core.agent_framework._workflows",
     "packages.purview.agent_framework_purview",
-    "packages.anthropic.agent_framework_anthropic",
-    "packages.azure-ai-search.agent_framework_azure_ai_search",
-    "packages.openai.agent_framework_openai",
-    # Individual files (if you want to enforce specific files instead of whole packages)
-    "packages/core/agent_framework/observability.py",
-    # Add more targets here as coverage improves
+    # Add more modules here as coverage improves:
+    # "packages.azure-ai-search.agent_framework_azure_ai_search",
+    # "packages.anthropic.agent_framework_anthropic",
 }
 
 
@@ -71,21 +62,14 @@ class PackageCoverage:
         return self.branch_rate * 100
 
 
-def normalize_coverage_path(path: str) -> str:
-    """Normalize coverage paths for reliable matching."""
-    return path.replace("\\", "/").lstrip("./")
-
-
-def parse_coverage_xml(
-    xml_path: str,
-) -> tuple[dict[str, PackageCoverage], dict[str, PackageCoverage], float, float]:
+def parse_coverage_xml(xml_path: str) -> tuple[dict[str, PackageCoverage], float, float]:
     """Parse Cobertura XML and extract per-package coverage data.
 
     Args:
         xml_path: Path to the Cobertura XML coverage report.
 
     Returns:
-        A tuple of (packages_dict, files_dict, overall_line_rate, overall_branch_rate).
+        A tuple of (packages_dict, overall_line_rate, overall_branch_rate).
     """
     tree = ET.parse(xml_path)
     root = tree.getroot()
@@ -95,7 +79,6 @@ def parse_coverage_xml(
     overall_branch_rate = float(root.get("branch-rate", 0))
 
     packages: dict[str, PackageCoverage] = {}
-    file_stats: dict[str, dict[str, int]] = {}
 
     for package in root.findall(".//package"):
         package_path = package.get("name", "unknown")
@@ -110,43 +93,19 @@ def parse_coverage_xml(
         branches_covered = 0
 
         for class_elem in package.findall(".//class"):
-            file_path = normalize_coverage_path(class_elem.get("filename", ""))
-            if file_path and file_path not in file_stats:
-                file_stats[file_path] = {
-                    "lines_valid": 0,
-                    "lines_covered": 0,
-                    "branches_valid": 0,
-                    "branches_covered": 0,
-                }
-
             for line in class_elem.findall(".//line"):
                 lines_valid += 1
                 if int(line.get("hits", 0)) > 0:
                     lines_covered += 1
-
-                if file_path:
-                    file_stats[file_path]["lines_valid"] += 1
-                    if int(line.get("hits", 0)) > 0:
-                        file_stats[file_path]["lines_covered"] += 1
-
                 # Branch coverage from line elements
                 if line.get("branch") == "true":
                     condition_coverage = line.get("condition-coverage", "")
                     if condition_coverage:
                         # Parse "X% (covered/total)" format
                         try:
-                            coverage_parts = (
-                                condition_coverage.split("(")[1].rstrip(")").split("/")
-                            )
+                            coverage_parts = condition_coverage.split("(")[1].rstrip(")").split("/")
                             branches_covered += int(coverage_parts[0])
                             branches_valid += int(coverage_parts[1])
-                            if file_path:
-                                file_stats[file_path]["branches_covered"] += int(
-                                    coverage_parts[0]
-                                )
-                                file_stats[file_path]["branches_valid"] += int(
-                                    coverage_parts[1]
-                                )
                         except (IndexError, ValueError):
                             # Ignore malformed condition-coverage strings; treat this line as having no branch data.
                             pass
@@ -155,33 +114,14 @@ def parse_coverage_xml(
         packages[package_path] = PackageCoverage(
             name=package_path,
             line_rate=line_rate if lines_valid == 0 else lines_covered / lines_valid,
-            branch_rate=branch_rate
-            if branches_valid == 0
-            else branches_covered / branches_valid,
+            branch_rate=branch_rate if branches_valid == 0 else branches_covered / branches_valid,
             lines_valid=lines_valid,
             lines_covered=lines_covered,
             branches_valid=branches_valid,
             branches_covered=branches_covered,
         )
 
-    files: dict[str, PackageCoverage] = {}
-    for file_path, stats in file_stats.items():
-        lines_valid = stats["lines_valid"]
-        lines_covered = stats["lines_covered"]
-        branches_valid = stats["branches_valid"]
-        branches_covered = stats["branches_covered"]
-
-        files[file_path] = PackageCoverage(
-            name=file_path,
-            line_rate=0 if lines_valid == 0 else lines_covered / lines_valid,
-            branch_rate=0 if branches_valid == 0 else branches_covered / branches_valid,
-            lines_valid=lines_valid,
-            lines_covered=lines_covered,
-            branches_valid=branches_valid,
-            branches_covered=branches_covered,
-        )
-
-    return packages, files, overall_line_rate, overall_branch_rate
+    return packages, overall_line_rate, overall_branch_rate
 
 
 def format_coverage_value(coverage: float, threshold: float, is_enforced: bool) -> str:
@@ -190,7 +130,7 @@ def format_coverage_value(coverage: float, threshold: float, is_enforced: bool)
     Args:
         coverage: Coverage percentage (0-100).
         threshold: Minimum required coverage percentage.
-        is_enforced: Whether this target is enforced.
+        is_enforced: Whether this module is enforced.
 
     Returns:
         Formatted string like "85.5%" or "85.5% ✅" or "75.0% ❌".
@@ -204,7 +144,6 @@ def format_coverage_value(coverage: float, threshold: float, is_enforced: bool)
 
 def print_coverage_table(
     packages: dict[str, PackageCoverage],
-    files: dict[str, PackageCoverage],
     threshold: float,
     overall_line_rate: float,
     overall_branch_rate: float,
@@ -213,7 +152,6 @@ def print_coverage_table(
 
     Args:
         packages: Dictionary of package name to coverage data.
-        files: Dictionary of file path to coverage data, used for per-file enforcement.
         threshold: Minimum required coverage percentage.
         overall_line_rate: Overall line coverage rate (0-1).
         overall_branch_rate: Overall branch coverage rate (0-1).
@@ -227,25 +165,21 @@ def print_coverage_table(
     print(f"Overall Branch Coverage: {overall_branch_rate * 100:.1f}%")
     print(f"Threshold:               {threshold}%")
 
-    enforced_targets = {normalize_coverage_path(t) for t in ENFORCED_TARGETS}
-
     # Package table
     print("\n" + "-" * 110)
     print(f"{'Package':<80} {'Lines':<15} {'Line Cov':<15}")
     print("-" * 110)
 
-    # Sort: enforced package targets first, then alphabetically
+    # Sort: enforced modules first, then alphabetically
     sorted_packages = sorted(
         packages.values(),
-        key=lambda p: (p.name not in ENFORCED_TARGETS, p.name),
+        key=lambda p: (p.name not in ENFORCED_MODULES, p.name),
     )
 
     for pkg in sorted_packages:
-        is_enforced = normalize_coverage_path(pkg.name) in enforced_targets
+        is_enforced = pkg.name in ENFORCED_MODULES
         enforced_marker = "[ENFORCED] " if is_enforced else ""
-        line_cov = format_coverage_value(
-            pkg.line_coverage_percent, threshold, is_enforced
-        )
+        line_cov = format_coverage_value(pkg.line_coverage_percent, threshold, is_enforced)
         lines_info = f"{pkg.lines_covered}/{pkg.lines_valid}"
         package_label = f"{enforced_marker}{pkg.name}"
 
@@ -253,98 +187,50 @@ def print_coverage_table(
 
     print("-" * 110)
 
-    # Enforced file/model entries (if configured)
-    enforced_files = [
-        files[target]
-        for target in sorted(enforced_targets)
-        if target in files and target.endswith(".py")
-    ]
-
-    if enforced_files:
-        print("\nEnforced Files/Models")
-        print("-" * 110)
-        print(f"{'File':<80} {'Lines':<15} {'Line Cov':<15}")
-        print("-" * 110)
-
-        for file_cov in enforced_files:
-            line_cov = format_coverage_value(
-                file_cov.line_coverage_percent, threshold, True
-            )
-            lines_info = f"{file_cov.lines_covered}/{file_cov.lines_valid}"
-            print(f"[ENFORCED] {file_cov.name:<69} {lines_info:<15} {line_cov:<15}")
-
-        print("-" * 110)
-
 
 def check_coverage(xml_path: str, threshold: float) -> bool:
-    """Check if all enforced targets meet the coverage threshold.
+    """Check if all enforced modules meet the coverage threshold.
 
     Args:
         xml_path: Path to the Cobertura XML coverage report.
         threshold: Minimum required coverage percentage.
 
     Returns:
-        True if all enforced targets pass, False otherwise.
+        True if all enforced modules pass, False otherwise.
     """
-    packages, files, overall_line_rate, overall_branch_rate = parse_coverage_xml(
-        xml_path
-    )
+    packages, overall_line_rate, overall_branch_rate = parse_coverage_xml(xml_path)
 
-    print_coverage_table(
-        packages, files, threshold, overall_line_rate, overall_branch_rate
-    )
+    print_coverage_table(packages, threshold, overall_line_rate, overall_branch_rate)
 
-    # Check enforced targets
-    failed_targets: list[str] = []
-    missing_targets: list[str] = []
+    # Check enforced modules
+    failed_modules: list[str] = []
+    missing_modules: list[str] = []
 
-    for target_name in ENFORCED_TARGETS:
-        normalized_target = normalize_coverage_path(target_name)
-        package_alias = normalized_target.replace("/", ".")
-
-        target_coverage = None
-        if target_name in packages:
-            target_coverage = packages[target_name]
-        elif normalized_target in files:
-            target_coverage = files[normalized_target]
-        elif package_alias in packages:
-            target_coverage = packages[package_alias]
-
-        if target_coverage is None:
-            missing_targets.append(target_name)
+    for module_name in ENFORCED_MODULES:
+        if module_name not in packages:
+            missing_modules.append(module_name)
             continue
 
-        if target_coverage.line_coverage_percent < threshold:
-            failed_targets.append(
-                f"{target_name} ({target_coverage.line_coverage_percent:.1f}%)"
-            )
+        pkg = packages[module_name]
+        if pkg.line_coverage_percent < threshold:
+            failed_modules.append(f"{module_name} ({pkg.line_coverage_percent:.1f}%)")
 
     # Report results
-    if missing_targets:
-        print(
-            f"\n❌ FAILED: Enforced targets not found in coverage report: {', '.join(missing_targets)}"
-        )
+    if missing_modules:
+        print(f"\n❌ FAILED: Enforced modules not found in coverage report: {', '.join(missing_modules)}")
         return False
 
-    if failed_targets:
-        print(
-            f"\n❌ FAILED: The following enforced targets are below {threshold}% coverage threshold:"
-        )
-        for target in failed_targets:
-            print(f"   - {target}")
-        print("\nTo fix: Add more tests to improve coverage for the failing targets.")
+    if failed_modules:
+        print(f"\n❌ FAILED: The following enforced modules are below {threshold}% coverage threshold:")
+        for module in failed_modules:
+            print(f"   - {module}")
+        print("\nTo fix: Add more tests to improve coverage for the failing modules.")
         return False
 
-    if ENFORCED_TARGETS:
-        found_enforced = [
-            target
-            for target in ENFORCED_TARGETS
-            if target in packages or normalize_coverage_path(target) in files
-        ]
+    if ENFORCED_MODULES:
+        found_enforced = [m for m in ENFORCED_MODULES if m in packages]
         if found_enforced:
-            print(
-                f"\n✅ PASSED: All enforced targets meet the {threshold}% coverage threshold."
-            )
+            print(f"\n✅ PASSED: All enforced modules meet the {threshold}% coverage threshold.")
 
     return True
 

.github/workflows/python-code-quality.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11"]
+        python-version: ["3.10"]
     runs-on: ubuntu-latest
     continue-on-error: true
     defaults:
@@ -55,7 +55,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11"]
+        python-version: ["3.10"]
     runs-on: ubuntu-latest
     continue-on-error: true
     defaults:
@@ -75,7 +75,7 @@ jobs:
           os: ${{ runner.os }}
         env:
           UV_CACHE_DIR: /tmp/.uv-cache
-      - name: Run syntax and pyright across packages
+      - name: Run fmt, lint, pyright in parallel across packages
         run: uv run poe check-packages
 
   samples-markdown:
@@ -84,7 +84,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11"]
+        python-version: ["3.10"]
     runs-on: ubuntu-latest
     continue-on-error: true
     defaults:
@@ -104,8 +104,10 @@ jobs:
           os: ${{ runner.os }}
         env:
           UV_CACHE_DIR: /tmp/.uv-cache
-      - name: Run samples checks
-        run: uv run poe check -S
+      - name: Run samples lint
+        run: uv run poe samples-lint
+      - name: Run samples syntax check
+        run: uv run poe samples-syntax
       - name: Run markdown code lint
         run: uv run poe markdown-code-lint
 
@@ -115,7 +117,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11"]
+        python-version: ["3.10"]
     runs-on: ubuntu-latest
     continue-on-error: true
     defaults:
@@ -138,4 +140,4 @@ jobs:
       - name: Run Mypy
         env:
           GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref || github.base_ref || 'main' }}
-        run: uv run python scripts/workspace_poe_tasks.py ci-mypy
+        run: uv run poe ci-mypy

.github/workflows/python-dependency-range-validation.yml

@@ -1,216 +0,0 @@
-# Probe the highest allowed dependency versions, then open issues/PRs from the passing updates.
-name: Python - Dependency Range Validation
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  issues: write
-  pull-requests: write
-
-env:
-  UV_CACHE_DIR: /tmp/.uv-cache
-
-jobs:
-  dependency-range-validation:
-    name: Dependency Range Validation
-    runs-on: ubuntu-latest
-    env:
-      # For now only run 3.13, if we do encounter situations where there are mismatches between packages and python versions (other then 3.10 and 3.14 which are known to not be able to install everything)
-      # then we will have to reevaluate.
-      UV_PYTHON: "3.13"
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Set up python and install the project
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-        env:
-          UV_CACHE_DIR: /tmp/.uv-cache
-
-      - name: Run dependency range validation
-        id: validate_ranges
-        # Keep workflow running so we can still publish diagnostics from this run.
-        continue-on-error: true
-        run: uv run poe validate-dependency-bounds-project --mode upper --package "*"
-        working-directory: ./python
-
-      - name: Upload dependency range report
-        # Always publish the report so failures are inspectable even when validation fails.
-        if: always()
-        uses: actions/upload-artifact@v7
-        with:
-          name: dependency-range-results
-          path: python/scripts/dependencies/dependency-range-results.json
-          if-no-files-found: warn
-
-      - name: Create issues for failed dependency candidates
-        # Always process the report so failed candidates create actionable tracking issues.
-        if: always()
-        uses: actions/github-script@v8
-        with:
-          script: |
-            const fs = require("fs")
-            const reportPath = "python/scripts/dependencies/dependency-range-results.json"
-
-            if (!fs.existsSync(reportPath)) {
-              core.warning(`No dependency range report found at ${reportPath}`)
-              return
-            }
-
-            const report = JSON.parse(fs.readFileSync(reportPath, "utf8"))
-            const dependencyFailures = []
-
-            for (const packageResult of report.packages ?? []) {
-              for (const dependency of packageResult.dependencies ?? []) {
-                const candidateVersions = new Set(dependency.candidate_versions ?? [])
-                const failedAttempts = (dependency.attempts ?? []).filter(
-                  (attempt) => attempt.status === "failed" && candidateVersions.has(attempt.trial_upper)
-                )
-                if (!failedAttempts.length) {
-                  continue
-                }
-
-                const failuresByVersion = new Map()
-                for (const attempt of failedAttempts) {
-                  const version = attempt.trial_upper || "unknown"
-                  if (!failuresByVersion.has(version)) {
-                    failuresByVersion.set(version, attempt.error || "No error output captured.")
-                  }
-                }
-
-                dependencyFailures.push({
-                  packageName: packageResult.package_name,
-                  projectPath: packageResult.project_path,
-                  dependencyName: dependency.name,
-                  originalRequirements: dependency.original_requirements ?? [],
-                  finalRequirements: dependency.final_requirements ?? [],
-                  failedVersions: [...failuresByVersion.entries()].map(([version, error]) => ({ version, error })),
-                })
-              }
-            }
-
-            if (!dependencyFailures.length) {
-              core.info("No failing dependency candidates found.")
-              return
-            }
-
-            const owner = context.repo.owner
-            const repo = context.repo.repo
-            const openIssues = await github.paginate(github.rest.issues.listForRepo, {
-              owner,
-              repo,
-              state: "open",
-              per_page: 100,
-            })
-            const openIssueTitles = new Set(
-              openIssues.filter((issue) => !issue.pull_request).map((issue) => issue.title)
-            )
-
-            const formatError = (message) => String(message || "No error output captured.").replace(/```/g, "'''")
-
-            for (const failure of dependencyFailures) {
-              const title = `Dependency validation failed: ${failure.dependencyName} (${failure.packageName})`
-              if (openIssueTitles.has(title)) {
-                core.info(`Issue already exists: ${title}`)
-                continue
-              }
-
-              const visibleFailures = failure.failedVersions.slice(0, 5)
-              const omittedCount = failure.failedVersions.length - visibleFailures.length
-              const failureDetails = visibleFailures
-                .map(
-                  (entry) =>
-                    `- \`${entry.version}\`\n\n\`\`\`\n${formatError(entry.error).slice(0, 3500)}\n\`\`\``
-                )
-                .join("\n\n")
-
-              const body = [
-                "Automated dependency range validation found candidate versions that failed checks.",
-                "",
-                `- Package: \`${failure.packageName}\``,
-                `- Project path: \`${failure.projectPath}\``,
-                `- Dependency: \`${failure.dependencyName}\``,
-                `- Original requirements: ${
-                  failure.originalRequirements.length
-                    ? failure.originalRequirements.map((value) => `\`${value}\``).join(", ")
-                    : "_none_"
-                }`,
-                `- Final requirements after run: ${
-                  failure.finalRequirements.length
-                    ? failure.finalRequirements.map((value) => `\`${value}\``).join(", ")
-                    : "_none_"
-                }`,
-                "",
-                "### Failed versions and errors",
-                failureDetails,
-                omittedCount > 0 ? `\n_Additional failed versions omitted: ${omittedCount}_` : "",
-                "",
-                `Workflow run: ${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`,
-              ].join("\n")
-
-              await github.rest.issues.create({
-                owner,
-                repo,
-                title,
-                body,
-              })
-              openIssueTitles.add(title)
-              core.info(`Created issue: ${title}`)
-            }
-
-      - name: Refresh lockfile
-        # Only refresh lockfile after a clean validation to avoid committing known-bad ranges.
-        if: steps.validate_ranges.outcome == 'success'
-        run: uv lock --upgrade
-        working-directory: ./python
-
-      - name: Commit and push dependency updates
-        id: commit_updates
-        if: steps.validate_ranges.outcome == 'success'
-        run: |
-          BRANCH="automation/python-dependency-range-updates"
-
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git checkout -B "${BRANCH}"
-
-          git add python/packages/*/pyproject.toml python/uv.lock
-          if git diff --cached --quiet; then
-            echo "has_changes=false" >> "$GITHUB_OUTPUT"
-            echo "No dependency updates to commit."
-            exit 0
-          fi
-
-          git commit -m "chore: update dependency ranges"
-          git push --force-with-lease --set-upstream origin "${BRANCH}"
-          echo "has_changes=true" >> "$GITHUB_OUTPUT"
-
-      - name: Create or update pull request with GitHub CLI
-        # Only open/update PRs for validated updates to keep automation branches trustworthy.
-        if: steps.validate_ranges.outcome == 'success' && steps.commit_updates.outputs.has_changes == 'true'
-        run: |
-          BRANCH="automation/python-dependency-range-updates"
-          PR_TITLE="Python: chore: update dependency ranges"
-          PR_BODY_FILE="$(mktemp)"
-
-          cat > "${PR_BODY_FILE}" <<'EOF'
-          This PR was generated by the dependency range validation workflow.
-
-          - Ran `uv run poe validate-dependency-bounds-project --mode upper --package "*"`
-          - Updated package dependency bounds
-          - Refreshed `python/uv.lock` with `uv lock --upgrade`
-          EOF
-
-          PR_NUMBER="$(gh pr list --head "${BRANCH}" --base main --state open --json number --jq '.[0].number')"
-          if [ -n "${PR_NUMBER}" ]; then
-            gh pr edit "${PR_NUMBER}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
-          else
-            gh pr create --base main --head "${BRANCH}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
-          fi

.github/workflows/python-dev-dependency-upgrade.yml

@@ -1,91 +0,0 @@
-name: Python - Dev Dependency Upgrade
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  pull-requests: write
-
-env:
-  UV_CACHE_DIR: /tmp/.uv-cache
-
-jobs:
-  upgrade-dev-dependencies:
-    name: Upgrade Dev Dependencies
-    runs-on: ubuntu-latest
-    env:
-      UV_PYTHON: "3.13"
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Set up python and install the project
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-        env:
-          UV_CACHE_DIR: /tmp/.uv-cache
-
-      - name: Upgrade dev dependencies and validate workspace
-        run: uv run poe upgrade-dev-dependencies
-        working-directory: ./python
-
-      - name: Commit and push dev dependency updates
-        id: commit_updates
-        run: |
-          BRANCH="automation/python-dev-dependency-updates"
-
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git checkout -B "${BRANCH}"
-
-          git add python/pyproject.toml python/packages/*/pyproject.toml python/uv.lock
-          if git diff --cached --quiet; then
-            echo "has_changes=false" >> "$GITHUB_OUTPUT"
-            echo "No dev dependency updates to commit."
-            exit 0
-          fi
-
-          git commit -F- <<'EOF'
-          Python: chore: upgrade dev dependencies
-          EOF
-          git push --force-with-lease --set-upstream origin "${BRANCH}"
-          echo "has_changes=true" >> "$GITHUB_OUTPUT"
-
-      - name: Create or update pull request with GitHub CLI
-        if: steps.commit_updates.outputs.has_changes == 'true'
-        run: |
-          BRANCH="automation/python-dev-dependency-updates"
-          PR_TITLE="Python: chore: upgrade dev dependencies"
-          PR_BODY_FILE="$(mktemp)"
-
-          cat > "${PR_BODY_FILE}" <<'EOF'
-          ### Motivation and Context
-
-          This automated update refreshes Python dev dependency pins across the workspace and reruns the repo validation gates before opening a pull request.
-
-          ### Description
-
-          - Ran `uv run poe upgrade-dev-dependencies`
-          - Refreshed dev dependency pins in workspace `pyproject.toml` files
-          - Refreshed `python/uv.lock` with `uv lock --upgrade`
-          - Reinstalled from the frozen lockfile and reran `check`, `typing`, and `test`
-
-          ### Contribution Checklist
-
-          - [x] The code builds clean without any errors or warnings
-          - [x] The PR follows the [Contribution Guidelines](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md)
-          - [x] All unit tests pass, and I have added new tests where possible
-          - [ ] **Is this a breaking change?** If yes, add "[BREAKING]" prefix to the title of the PR.
-          EOF
-
-          PR_NUMBER="$(gh pr list --head "${BRANCH}" --base main --state open --json number --jq '.[0].number')"
-          if [ -n "${PR_NUMBER}" ]; then
-            gh pr edit "${PR_NUMBER}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
-          else
-            gh pr create --base main --head "${BRANCH}" --title "${PR_TITLE}" --body-file "${PR_BODY_FILE}"
-          fi

.github/workflows/python-integration-tests.yml

@@ -1,367 +0,0 @@
-#
-# Dedicated Python integration tests workflow, called from the manual integration test orchestrator.
-# Runs all tests (unit + integration) split into parallel jobs by provider.
-#
-# NOTE: This workflow and python-merge-tests.yml share the same set of parallel
-# test jobs. Keep them in sync — when adding, removing, or modifying a job here,
-# apply the same change to python-merge-tests.yml.
-#
-
-name: python-integration-tests
-
-on:
-  workflow_call:
-    inputs:
-      checkout-ref:
-        description: "Git ref to checkout (e.g., refs/pull/123/head)"
-        required: true
-        type: string
-
-permissions:
-  contents: read
-  id-token: write
-
-env:
-  UV_CACHE_DIR: /tmp/.uv-cache
-  UV_PYTHON: "3.13"
-
-jobs:
-  # Unit tests: all non-integration tests across all packages
-  python-tests-unit:
-    name: Python Integration Tests - Unit
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (unit tests only)
-        run: >
-          uv run poe test -A
-          -m "not integration"
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # OpenAI integration tests
-  python-tests-openai:
-    name: Python Integration Tests - OpenAI
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (OpenAI integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/openai/tests
-          -m "integration and not azure"
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # Azure OpenAI integration tests
-  python-tests-azure-openai:
-    name: Python Integration Tests - Azure OpenAI
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - 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: Test with pytest (Azure OpenAI integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/openai/tests/openai/test_openai_chat_completion_client_azure.py
-          packages/openai/tests/openai/test_openai_chat_client_azure.py
-          packages/openai/tests/openai/test_openai_embedding_client_azure.py
-          packages/azure-ai/tests/azure_openai
-          --ignore=packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # Misc integration tests (Anthropic, Ollama, MCP)
-  python-tests-misc-integration:
-    name: Python Integration Tests - Misc
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Start local MCP server
-        id: local-mcp
-        uses: ./.github/actions/setup-local-mcp-server
-        with:
-          fallback_url: ${{ env.LOCAL_MCP_URL }}
-      - name: Prefer local MCP URL when available
-        run: echo "LOCAL_MCP_URL=${{ steps.local-mcp.outputs.effective_url }}" >> "$GITHUB_ENV"
-      - name: Test with pytest (Anthropic, Ollama, MCP integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/anthropic/tests
-          packages/ollama/tests
-          packages/core/tests/core/test_mcp.py
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-      - name: Stop local MCP server
-        if: always()
-        shell: bash
-        run: |
-          set -euo pipefail
-          server_pid="${{ steps.local-mcp.outputs.pid }}"
-          if [[ -z "$server_pid" ]]; then
-            exit 0
-          fi
-          if ! kill -0 "$server_pid" 2>/dev/null; then
-            exit 0
-          fi
-          kill -TERM -- "-$server_pid" 2>/dev/null || kill -TERM "$server_pid" 2>/dev/null || true
-          for _ in $(seq 1 10); do
-            if ! kill -0 "$server_pid" 2>/dev/null; then
-              exit 0
-            fi
-            sleep 1
-          done
-          kill -KILL -- "-$server_pid" 2>/dev/null || kill -KILL "$server_pid" 2>/dev/null || true
-
-  # Azure Functions + Durable Task integration tests
-  python-tests-functions:
-    name: Python Integration Tests - Functions
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      UV_PYTHON: "3.11"
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
-      FUNCTIONS_WORKER_RUNTIME: "python"
-      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
-      AzureWebJobsStorage: "UseDevelopmentStorage=true"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - 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: Set up Azure Functions Integration Test Emulators
-        uses: ./.github/actions/azure-functions-integration-setup
-        id: azure-functions-setup
-      - name: Test with pytest (Functions + Durable Task integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/azurefunctions/tests/integration_tests
-          packages/durabletask/tests/integration_tests
-          -m integration
-          -n logical --dist worksteal
-          -x
-          --timeout=360 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # Foundry integration tests
-  python-tests-foundry:
-    name: Python Integration Tests - Foundry
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-      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 }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - 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: Test with pytest
-        timeout-minutes: 15
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
-          packages/foundry/tests
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # Azure Cosmos integration tests
-  python-tests-cosmos:
-    name: Python Integration Tests - Cosmos
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    services:
-      cosmosdb:
-        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
-        ports:
-          - 8081:8081
-    env:
-      AZURE_COSMOS_ENDPOINT: "http://localhost:8081/"
-      # Static Azure Cosmos DB emulator key (documented): https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
-      AZURE_COSMOS_KEY: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-      AZURE_COSMOS_DATABASE_NAME: "agent-framework-cosmos-it-db"
-      AZURE_COSMOS_CONTAINER_NAME: "agent-framework-cosmos-it-container"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Wait for Cosmos DB emulator
-        run: |
-          for i in {1..60}; do
-            if curl --silent --show-error http://localhost:8081/ > /dev/null; then
-              echo "Cosmos DB emulator is ready."
-              exit 0
-            fi
-            sleep 2
-          done
-          echo "Cosmos DB emulator did not become ready in time." >&2
-          exit 1
-      - name: Test with pytest (Cosmos integration)
-        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
-
-  python-integration-tests-check:
-    if: always()
-    runs-on: ubuntu-latest
-    needs:
-      [
-        python-tests-unit,
-        python-tests-openai,
-        python-tests-azure-openai,
-        python-tests-misc-integration,
-        python-tests-functions,
-        python-tests-foundry,
-        python-tests-cosmos
-      ]
-    steps:
-      - name: Fail workflow if tests failed
-        if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v8
-        with:
-          script: core.setFailed('Integration Tests Failed!')
-
-      - name: Fail workflow if tests cancelled
-        if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v8
-        with:
-          script: core.setFailed('Integration Tests Cancelled!')

.github/workflows/python-lab-tests.yml

@@ -67,7 +67,6 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
-          exclude-packages: ${{ matrix.python-version == '3.10' && 'agent-framework-github-copilot' || '' }}
         env:
           # Configure a constant location for the uv cache
           UV_CACHE_DIR: /tmp/.uv-cache
@@ -76,9 +75,6 @@ jobs:
       - name: Run lab tests
         run: cd packages/lab && uv run poe test
 
-      - name: Run resource-intensive lab tests
-        run: cd packages/lab && uv run pytest -m "resource_intensive and not integration" --junitxml=test-results-resource-intensive.xml
-
       - name: Run lab lint
         run: cd packages/lab && uv run poe lint
 

.github/workflows/python-merge-tests.yml

@@ -1,9 +1,4 @@
 name: Python - Merge - Tests
-#
-# NOTE: This workflow and python-integration-tests.yml share the same set of
-# parallel test jobs. Keep them in sync — when adding, removing, or modifying a
-# job here, apply the same change to python-integration-tests.yml.
-#
 
 on:
   workflow_dispatch:
@@ -15,13 +10,13 @@ on:
     - cron: "0 0 * * *" # Run at midnight UTC daily
 
 permissions:
-  contents: read
+  contents: write
   id-token: write
 
 env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
-  UV_PYTHON: "3.13"
+  RUN_INTEGRATION_TESTS: "true"
   RUN_SAMPLES_TESTS: ${{ vars.RUN_SAMPLES_TESTS }}
 
 jobs:
@@ -31,14 +26,7 @@ jobs:
       contents: read
       pull-requests: read
     outputs:
-      pythonChanges: ${{ steps.filter.outputs.python }}
-      coreChanged: ${{ steps.filter.outputs.core }}
-      openaiChanged: ${{ steps.filter.outputs.openai }}
-      azureChanged: ${{ steps.filter.outputs.azure }}
-      miscChanged: ${{ steps.filter.outputs.misc }}
-      functionsChanged: ${{ steps.filter.outputs.functions }}
-      azureAiChanged: ${{ steps.filter.outputs.azure-ai }}
-      cosmosChanged: ${{ steps.filter.outputs.cosmos }}
+      pythonChanges: ${{ steps.filter.outputs.python}}
     steps:
       - uses: actions/checkout@v6
       - uses: dorny/paths-filter@v3
@@ -47,42 +35,6 @@ jobs:
           filters: |
             python:
               - 'python/**'
-              - '.github/actions/setup-local-mcp-server/**'
-              - '.github/workflows/python-merge-tests.yml'
-              - '.github/workflows/python-integration-tests.yml'
-            core:
-              - 'python/packages/core/agent_framework/_*.py'
-              - 'python/packages/core/agent_framework/_workflows/**'
-              - 'python/packages/core/agent_framework/exceptions.py'
-              - 'python/packages/core/agent_framework/observability.py'
-            openai:
-              - 'python/packages/core/agent_framework/openai/**'
-              - 'python/packages/openai/**'
-              - 'python/samples/**/providers/openai/**'
-            azure:
-              - 'python/packages/openai/**'
-              - 'python/packages/core/agent_framework/azure/**'
-              - 'python/packages/azure-ai/agent_framework_azure_ai/_deprecated_azure_openai.py'
-              - 'python/packages/azure-ai/tests/azure_openai/**'
-              - 'python/samples/**/providers/azure/openai_chat_completion_client_azure*.py'
-            misc:
-              - 'python/packages/anthropic/**'
-              - 'python/packages/ollama/**'
-              - 'python/packages/core/agent_framework/_mcp.py'
-              - 'python/packages/core/tests/core/test_mcp.py'
-              - 'python/scripts/local_mcp_streamable_http_server.py'
-              - '.github/actions/setup-local-mcp-server/**'
-              - '.github/workflows/python-merge-tests.yml'
-              - '.github/workflows/python-integration-tests.yml'
-            functions:
-              - 'python/packages/azurefunctions/**'
-              - 'python/packages/durabletask/**'
-            azure-ai:
-              - 'python/packages/azure-ai/**'
-              - 'python/packages/foundry/**'
-              - 'python/samples/**/providers/foundry/**'
-            cosmos:
-              - 'python/packages/azure-cosmos/**'
       # run only if 'python' files were changed
       - name: python tests
         if: steps.filter.outputs.python == 'true'
@@ -91,262 +43,34 @@ jobs:
       - name: not python tests
         if: steps.filter.outputs.python != 'true'
         run: echo "NOT python file"
-  # Unit tests: always run all non-integration tests across all packages
-  python-tests-unit:
-    name: Python Tests - Unit
+  python-tests-core:
+    name: Python Tests - Core
     needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true'
-    runs-on: ubuntu-latest
-    environment: integration
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (unit tests only)
-        run: >
-          uv run poe test -A
-          -m "not integration"
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: Unit test results
-
-  # OpenAI integration tests
-  python-tests-openai:
-    name: Python Tests - OpenAI Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.openaiChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
+    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
+    runs-on: ${{ matrix.os }}
+    environment: ${{ matrix.environment }}
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.10"]
+        os: [ubuntu-latest]
+        environment: ["integration"]
     env:
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      UV_PYTHON: ${{ matrix.python-version }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (OpenAI integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/openai/tests
-          -m "integration and not azure"
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Test OpenAI samples
-        timeout-minutes: 10
-        if: env.RUN_SAMPLES_TESTS == 'true'
-        run: uv run pytest tests/samples/ -m "openai"
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: OpenAI integration test results
-
-  # Azure OpenAI integration tests
-  python-tests-azure-openai:
-    name: Python Tests - Azure OpenAI Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.azureChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Azure CLI Login
-        if: github.event_name != 'pull_request'
-        uses: azure/login@v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-      - name: Test with pytest (Azure OpenAI integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/openai/tests/openai/test_openai_chat_completion_client_azure.py
-          packages/openai/tests/openai/test_openai_chat_client_azure.py
-          packages/openai/tests/openai/test_openai_embedding_client_azure.py
-          packages/azure-ai/tests/azure_openai
-          --ignore=packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Test Azure samples
-        timeout-minutes: 10
-        if: env.RUN_SAMPLES_TESTS == 'true'
-        run: uv run pytest tests/samples/ -m "azure"
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: Azure OpenAI integration test results
-
-  # Misc integration tests (Anthropic, Ollama, MCP)
-  python-tests-misc-integration:
-    name: Python Tests - Misc Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.miscChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
       ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
       ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Start local MCP server
-        id: local-mcp
-        uses: ./.github/actions/setup-local-mcp-server
-        with:
-          fallback_url: ${{ env.LOCAL_MCP_URL }}
-      - name: Prefer local MCP URL when available
-        run: echo "LOCAL_MCP_URL=${{ steps.local-mcp.outputs.effective_url }}" >> "$GITHUB_ENV"
-      - name: Test with pytest (Anthropic, Ollama, MCP integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/anthropic/tests
-          packages/ollama/tests
-          packages/core/tests/core/test_mcp.py
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Stop local MCP server
-        if: always()
-        shell: bash
-        run: |
-          set -euo pipefail
-          server_pid="${{ steps.local-mcp.outputs.pid }}"
-          if [[ -z "$server_pid" ]]; then
-            exit 0
-          fi
-          if ! kill -0 "$server_pid" 2>/dev/null; then
-            exit 0
-          fi
-          kill -TERM -- "-$server_pid" 2>/dev/null || kill -TERM "$server_pid" 2>/dev/null || true
-          for _ in $(seq 1 10); do
-            if ! kill -0 "$server_pid" 2>/dev/null; then
-              exit 0
-            fi
-            sleep 1
-          done
-          kill -KILL -- "-$server_pid" 2>/dev/null || kill -KILL "$server_pid" 2>/dev/null || true
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: Misc integration test results
-
-  # Azure Functions + Durable Task integration tests
-  python-tests-functions:
-    name: Python Tests - Functions Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.functionsChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      UV_PYTHON: "3.11"
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
       AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+      # For Azure Functions integration tests
       FUNCTIONS_WORKER_RUNTIME: "python"
       DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
       AzureWebJobsStorage: "UseDevelopmentStorage=true"
+
     defaults:
       run:
         working-directory: python
@@ -356,8 +80,11 @@ jobs:
         id: python-setup
         uses: ./.github/actions/python-setup
         with:
-          python-version: ${{ env.UV_PYTHON }}
+          python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
         uses: azure/login@v2
@@ -368,16 +95,13 @@ jobs:
       - name: Set up Azure Functions Integration Test Emulators
         uses: ./.github/actions/azure-functions-integration-setup
         id: azure-functions-setup
-      - name: Test with pytest (Functions + Durable Task integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/azurefunctions/tests/integration_tests
-          packages/durabletask/tests/integration_tests
-          -m integration
-          -n logical --dist worksteal
-          -x
-          --timeout=360 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
+      - name: Test with pytest
+        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        working-directory: ./python
+      - name: Test core samples
+        timeout-minutes: 10
+        if: env.RUN_SAMPLES_TESTS == 'true'
+        run: uv run pytest tests/samples/ -m "openai" -m "azure"
         working-directory: ./python
       - name: Surface failing tests
         if: always()
@@ -387,26 +111,24 @@ jobs:
           summary: true
           display-options: fEX
           fail-on-empty: false
-          title: Functions integration test results
+          title: Test results
 
-  python-tests-foundry:
-    name: Python Integration Tests - Foundry
+  python-tests-azure-ai:
+    name: Python Tests - Azure AI
     needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.azureAiChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
+    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
+    runs-on: ${{ matrix.os }}
+    environment: ${{ matrix.environment }}
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.10"]
+        os: [ubuntu-latest]
+        environment: ["integration"]
     env:
+      UV_PYTHON: ${{ matrix.python-version }}
       AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
       AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-      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 }}
       LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
     defaults:
       run:
@@ -417,8 +139,11 @@ jobs:
         id: python-setup
         uses: ./.github/actions/python-setup
         with:
-          python-version: ${{ env.UV_PYTHON }}
+          python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
         uses: azure/login@v2
@@ -428,14 +153,7 @@ jobs:
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       - name: Test with pytest
         timeout-minutes: 15
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
-          packages/foundry/tests
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
         working-directory: ./python
       - name: Test Azure AI samples
         timeout-minutes: 10
@@ -454,78 +172,16 @@ jobs:
 
   # TODO: Add python-tests-lab
 
-  # Azure Cosmos integration tests
-  python-tests-cosmos:
-    name: Python Tests - Cosmos Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.cosmosChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
-    services:
-      cosmosdb:
-        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
-        ports:
-          - 8081:8081
-    env:
-      AZURE_COSMOS_ENDPOINT: "http://localhost:8081/"
-      # Static Azure Cosmos DB emulator key (documented): https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
-      AZURE_COSMOS_KEY: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-      AZURE_COSMOS_DATABASE_NAME: "agent-framework-cosmos-it-db"
-      AZURE_COSMOS_CONTAINER_NAME: "agent-framework-cosmos-it-container"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Wait for Cosmos DB emulator
-        run: |
-          for i in {1..60}; do
-            if curl --silent --show-error http://localhost:8081/ > /dev/null; then
-              echo "Cosmos DB emulator is ready."
-              exit 0
-            fi
-            sleep 2
-          done
-          echo "Cosmos DB emulator did not become ready in time." >&2
-          exit 1
-      - name: Test with pytest (Cosmos integration)
-        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: Cosmos integration test results
-
   python-integration-tests-check:
     if: always()
     runs-on: ubuntu-latest
     needs:
       [
-        python-tests-unit,
-        python-tests-openai,
-        python-tests-azure-openai,
-        python-tests-misc-integration,
-        python-tests-functions,
-        python-tests-foundry,
-        python-tests-cosmos,
+        python-tests-core,
+        python-tests-azure-ai
       ]
     steps:
+
       - name: Fail workflow if tests failed
         id: check_tests_failed
         if: contains(join(needs.*.result, ','), 'failure')

.github/workflows/python-sample-validation.yml

@@ -1,752 +0,0 @@
-name: Python - Sample Validation
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: "0 0 * * *" # Run at midnight UTC daily
-
-env:
-  # Configure a constant location for the uv cache
-  UV_CACHE_DIR: /tmp/.uv-cache
-  # GitHub Copilot configuration
-  GITHUB_COPILOT_MODEL: claude-opus-4.6
-  COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
-
-permissions:
-  contents: read
-  id-token: write
-
-jobs:
-  validate-01-get-started:
-    name: Validate 01-get-started
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Required configuration for get-started samples
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 01-get-started --save-report --report-name 01-get-started
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-01-get-started
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents:
-    name: Validate 02-agents
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
-      # OpenAI configuration
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      # GitHub MCP
-      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      # Observability
-      ENABLE_INSTRUMENTATION: "true"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
-          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME=$AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME" >> .env
-          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
-          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
-          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
-          echo "GITHUB_PAT=$GITHUB_PAT" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents --exclude providers --save-report --report-name 02-agents
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-openai:
-    name: Validate 02-agents/providers/openai
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
-          echo "OPENAI_MODEL=$OPENAI_MODEL" >> .env
-          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
-          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/openai --save-report --report-name 02-agents-openai
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-openai
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-azure:
-    name: Validate 02-agents/providers/azure
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/azure --save-report --report-name 02-agents-azure
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-azure
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-anthropic:
-    name: Validate 02-agents/providers/anthropic
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" >> .env
-          echo "ANTHROPIC_CHAT_MODEL_ID=$ANTHROPIC_CHAT_MODEL_ID" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/anthropic --save-report --report-name 02-agents-anthropic
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-anthropic
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-github-copilot:
-    name: Validate 02-agents/providers/github_copilot
-    runs-on: ubuntu-latest
-    environment: integration
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/github_copilot --save-report --report-name 02-agents-github-copilot
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-github-copilot
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-amazon:
-    name: Validate 02-agents/providers/amazon
-    if: false # Temporarily disabled - requires AWS credentials
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      BEDROCK_CHAT_MODEL_ID: ${{ vars.BEDROCK__CHATMODELID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/amazon --save-report --report-name 02-agents-amazon
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-amazon
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-ollama:
-    name: Validate 02-agents/providers/ollama
-    if: false # Temporarily disabled - requires local Ollama server
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      OLLAMA_MODEL: ${{ vars.OLLAMA__MODEL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/ollama --save-report --report-name 02-agents-ollama
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-ollama
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-foundry:
-    name: Validate 02-agents/providers/foundry
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
-          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/foundry --save-report --report-name 02-agents-foundry
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-foundry
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-copilotstudio:
-    name: Validate 02-agents/providers/copilotstudio
-    if: false # Temporarily disabled - requires Copilot Studio setup
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      COPILOTSTUDIOAGENT__ENVIRONMENTID: ${{ secrets.COPILOTSTUDIOAGENT__ENVIRONMENTID }}
-      COPILOTSTUDIOAGENT__SCHEMANAME: ${{ secrets.COPILOTSTUDIOAGENT__SCHEMANAME }}
-      COPILOTSTUDIOAGENT__TENANTID: ${{ secrets.COPILOTSTUDIOAGENT__TENANTID }}
-      COPILOTSTUDIOAGENT__AGENTAPPID: ${{ secrets.COPILOTSTUDIOAGENT__AGENTAPPID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "COPILOTSTUDIOAGENT__ENVIRONMENTID=$COPILOTSTUDIOAGENT__ENVIRONMENTID" >> .env
-          echo "COPILOTSTUDIOAGENT__SCHEMANAME=$COPILOTSTUDIOAGENT__SCHEMANAME" >> .env
-          echo "COPILOTSTUDIOAGENT__TENANTID=$COPILOTSTUDIOAGENT__TENANTID" >> .env
-          echo "COPILOTSTUDIOAGENT__AGENTAPPID=$COPILOTSTUDIOAGENT__AGENTAPPID" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/copilotstudio --save-report --report-name 02-agents-copilotstudio
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-copilotstudio
-          path: python/samples/sample_validation/reports/
-
-  validate-02-agents-custom:
-    name: Validate 02-agents/providers/custom
-    runs-on: ubuntu-latest
-    environment: integration
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents/providers/custom --save-report --report-name 02-agents-custom
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-02-agents-custom
-          path: python/samples/sample_validation/reports/
-
-  validate-03-workflows:
-    name: Validate 03-workflows
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
-          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 03-workflows --save-report --report-name 03-workflows
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-03-workflows
-          path: python/samples/sample_validation/reports/
-
-  validate-04-hosting:
-    name: Validate 04-hosting
-    if: false # Temporarily disabled because of sample complexity
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # A2A configuration
-      A2A_AGENT_HOST: http://localhost:5001/
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 04-hosting --save-report --report-name 04-hosting
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-04-hosting
-          path: python/samples/sample_validation/reports/
-
-  validate-05-end-to-end:
-    name: Validate 05-end-to-end
-    if: false # Temporarily disabled because of sample complexity
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure AI Search (for evaluation samples)
-      AZURE_SEARCH_ENDPOINT: ${{ secrets.AZURE_SEARCH_ENDPOINT }}
-      AZURE_SEARCH_API_KEY: ${{ secrets.AZURE_SEARCH_API_KEY }}
-      AZURE_SEARCH_INDEX_NAME: ${{ secrets.AZURE_SEARCH_INDEX_NAME }}
-      # Evaluation sample
-      AZURE_AI_MODEL_DEPLOYMENT_NAME_WORKFLOW: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 05-end-to-end --save-report --report-name 05-end-to-end
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-05-end-to-end
-          path: python/samples/sample_validation/reports/
-
-  validate-autogen-migration:
-    name: Validate autogen-migration
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      # OpenAI configuration
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
-          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
-          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir autogen-migration --save-report --report-name autogen-migration
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-autogen-migration
-          path: python/samples/sample_validation/reports/
-
-  validate-semantic-kernel-migration:
-    name: Validate semantic-kernel-migration
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # OpenAI configuration
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
-      # Copilot Studio
-      COPILOTSTUDIOAGENT__ENVIRONMENTID: ${{ secrets.COPILOTSTUDIOAGENT__ENVIRONMENTID }}
-      COPILOTSTUDIOAGENT__SCHEMANAME: ${{ secrets.COPILOTSTUDIOAGENT__SCHEMANAME }}
-      COPILOTSTUDIOAGENT__TENANTID: ${{ secrets.COPILOTSTUDIOAGENT__TENANTID }}
-      COPILOTSTUDIOAGENT__AGENTAPPID: ${{ secrets.COPILOTSTUDIOAGENT__AGENTAPPID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Create .env for samples
-        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
-          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
-          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
-          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
-          echo "COPILOTSTUDIOAGENT__ENVIRONMENTID=$COPILOTSTUDIOAGENT__ENVIRONMENTID" >> .env
-          echo "COPILOTSTUDIOAGENT__SCHEMANAME=$COPILOTSTUDIOAGENT__SCHEMANAME" >> .env
-          echo "COPILOTSTUDIOAGENT__TENANTID=$COPILOTSTUDIOAGENT__TENANTID" >> .env
-          echo "COPILOTSTUDIOAGENT__AGENTAPPID=$COPILOTSTUDIOAGENT__AGENTAPPID" >> .env
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir semantic-kernel-migration --save-report --report-name semantic-kernel-migration
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-report-semantic-kernel-migration
-          path: python/samples/sample_validation/reports/
-
-  aggregate-results:
-    name: Aggregate Results
-    runs-on: ubuntu-latest
-    if: always()
-    needs:
-      - validate-01-get-started
-      - validate-02-agents
-      - validate-02-agents-openai
-      - validate-02-agents-azure
-      - validate-02-agents-anthropic
-      - validate-02-agents-github-copilot
-      - validate-02-agents-amazon
-      - validate-02-agents-ollama
-      - validate-02-agents-foundry
-      - validate-02-agents-copilotstudio
-      - validate-02-agents-custom
-      - validate-03-workflows
-      - validate-04-hosting
-      - validate-05-end-to-end
-      - validate-autogen-migration
-      - validate-semantic-kernel-migration
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Download all validation reports
-        uses: actions/download-artifact@v7
-        with:
-          pattern: validation-report-*
-          path: reports/
-          merge-multiple: true
-
-      - name: Restore validation history
-        id: cache-restore
-        uses: actions/cache/restore@v4
-        with:
-          path: validation-history/
-          key: validation-history-${{ github.run_id }}
-          restore-keys: |
-            validation-history-
-
-      - name: Aggregate results and generate trend report
-        run: |
-          python3 python/scripts/sample_validation/aggregate.py \
-            reports/ \
-            validation-history/history.json \
-            trend-report.md
-
-      - name: Write trend report to job summary
-        run: cat trend-report.md >> "$GITHUB_STEP_SUMMARY"
-
-      - name: Save validation history
-        uses: actions/cache/save@v4
-        with:
-          path: validation-history/
-          key: validation-history-${{ github.run_id }}
-
-      - name: Upload trend report
-        uses: actions/upload-artifact@v7
-        if: always()
-        with:
-          name: validation-trend-report
-          path: trend-report.md

.github/workflows/python-test-coverage-report.yml

@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
       - name: Download coverage report
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@v7
         with:
           github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
           run-id: ${{ github.event.workflow_run.id }}
@@ -46,7 +46,7 @@ jobs:
           echo "PR_NUMBER=$PR_NUMBER" >> "$GITHUB_ENV"
       - name: Pytest coverage comment
         id: coverageComment
-        uses: MishaKav/pytest-coverage-comment@v1.6.0
+        uses: MishaKav/pytest-coverage-comment@v1.2.0
         with:
           github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
           issue-number: ${{ env.PR_NUMBER }}

.github/workflows/python-test-coverage.yml

@@ -20,7 +20,7 @@ jobs:
       run:
         working-directory: python
     env:
-      UV_PYTHON: "3.11"
+      UV_PYTHON: "3.10"
     steps:
       - uses: actions/checkout@v6
       # Save the PR number to a file since the workflow_run event
@@ -32,17 +32,17 @@ jobs:
         id: python-setup
         uses: ./.github/actions/python-setup
         with:
-          python-version: ${{ env.UV_PYTHON }}
+          python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
         env:
           # Configure a constant location for the uv cache
           UV_CACHE_DIR: /tmp/.uv-cache
       - name: Run all tests with coverage report
-        run: uv run poe test -A -C --cov-report=xml:python-coverage.xml -q --junitxml=pytest.xml
+        run: uv run poe all-tests-cov --cov-report=xml:python-coverage.xml -q --junitxml=pytest.xml
       - name: Check coverage threshold
         run: python ${{ github.workspace }}/.github/workflows/python-check-coverage.py python-coverage.xml ${{ env.COVERAGE_THRESHOLD }}
       - name: Upload coverage report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@v6
         with:
           path: |
             python/python-coverage.xml

.github/workflows/python-tests.yml

@@ -34,13 +34,12 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
-          exclude-packages: ${{ matrix.python-version == '3.10' && 'agent-framework-github-copilot' || '' }}
         env:
           # Configure a constant location for the uv cache
           UV_CACHE_DIR: /tmp/.uv-cache
       # Unit tests
       - name: Run all tests
-        run: uv run poe test -A
+        run: uv run poe all-tests
         working-directory: ./python
 
       # Surface failing tests

.github/workflows/stale-issue-pr-ping.yml

@@ -1,49 +0,0 @@
-name: Stale issue and PR ping
-
-on:
-  schedule:
-    - cron: '0 0 * * *'  # Midnight UTC daily
-  workflow_dispatch:
-    inputs:
-      days_threshold:
-        description: 'Days of silence before pinging the author'
-        required: false
-        default: '4'
-      dry_run:
-        description: 'Log what would be pinged without taking action'
-        required: false
-        default: 'false'
-        type: choice
-        options:
-          - 'false'
-          - 'true'
-
-concurrency:
-  group: stale-issue-pr-ping
-  cancel-in-progress: true
-
-jobs:
-  ping_stale:
-    name: "Ping stale issues and PRs"
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      issues: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: '3.13'
-
-      - name: Install dependencies
-        run: pip install PyGithub==2.6.0
-
-      - name: Run stale issue/PR ping
-        run: python .github/scripts/stale_issue_pr_ping.py
-        env:
-          GITHUB_TOKEN: ${{ secrets.GH_ACTIONS_PR_WRITE }}
-          TEAM_SLUG: ${{ secrets.DEVELOPER_TEAM }}
-          DAYS_THRESHOLD: ${{ github.event.inputs.days_threshold || '4' }}
-          DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}

.gitignore

@@ -205,9 +205,6 @@ WARP.md
 **/memory-bank/
 **/projectBrief.md
 **/tmpclaude*
-# Dependency-bound validation reports
-python/scripts/dependency-*-results.json
-python/scripts/dependencies/dependency-*-results.json
 
 # Azurite storage emulator files
 */__azurite_db_blob__.json*

README.md

@@ -53,7 +53,7 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 ### ✨ **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/)
+  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/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
@@ -73,11 +73,11 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 - **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/)
+  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/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/)
+  - [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/GettingStarted/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/)
+  - [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/)
 
 ### 💬 **We want your feedback!**
 
@@ -125,13 +125,12 @@ Create a simple Agent, using OpenAI Responses, that writes a haiku about the Mic
 
 ```c#
 // dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
-using Microsoft.Agents.AI;
+using System;
 using OpenAI;
-using OpenAI.Responses;
 
 // Replace the <apikey> with your OpenAI API key.
 var agent = new OpenAIClient("<apikey>")
-    .GetResponsesClient("gpt-4o-mini")
+    .GetOpenAIResponseClient("gpt-4o-mini")
     .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
@@ -143,17 +142,14 @@ Create a simple Agent, using Azure OpenAI Responses with token based auth, that
 // dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 // dotnet add package Azure.Identity
 // Use `az login` to authenticate with Azure CLI
-using System.ClientModel.Primitives;
-using Azure.Identity;
-using Microsoft.Agents.AI;
+using System;
 using OpenAI;
-using OpenAI.Responses;
 
 // Replace <resource> and gpt-4o-mini with your Azure OpenAI resource name and deployment name.
 var agent = new OpenAIClient(
     new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"),
     new OpenAIClientOptions() { Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1") })
-    .GetResponsesClient("gpt-4o-mini")
+    .GetOpenAIResponseClient("gpt-4o-mini")
     .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
@@ -169,9 +165,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 
 ### .NET
 
-- [Getting Started with Agents](./dotnet/samples/02-agents/Agents): basic agent creation and tool usage
-- [Agent Provider Samples](./dotnet/samples/02-agents/AgentProviders): samples showing different agent providers
-- [Workflow Samples](./dotnet/samples/03-workflows): advanced multi-agent patterns and workflow orchestration
+- [Getting Started with Agents](./dotnet/samples/GettingStarted/Agents): basic agent creation and tool usage
+- [Agent Provider Samples](./dotnet/samples/GettingStarted/AgentProviders): samples showing different agent providers
+- [Workflow Samples](./dotnet/samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
 
 ## Contributor Resources
 

agent-samples/openai/OpenAIResponses.yaml

@@ -11,7 +11,7 @@ model:
         topP: 0.95
     connection:
         kind: key
-        apiKey: =Env.OPENAI_API_KEY
+        apiKey: =Env.OPENAI_APIKEY
 outputSchema:
     properties:
         language:

docs/decisions/0001-agent-run-response.md

@@ -4,8 +4,8 @@ status: accepted
 contact: westey-m
 date: 2025-07-10 {YYYY-MM-DD when the decision was last updated}
 deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
-consulted:
-informed:
+consulted: 
+informed: 
 ---
 
 # Agent Run Responses Design
@@ -64,7 +64,7 @@ Approaches observed from the compared SDKs:
 | AutoGen | **Approach 1** Separates messages into Agent-Agent (maps to Primary) and Internal (maps to Secondary) and these are returned as separate properties on the agent response object.  See [types of messages](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tutorial/messages.html#types-of-messages) and [Response](https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.base.html#autogen_agentchat.base.Response) | **Approach 2** Returns a stream of internal events and the last item is a Response object. See [ChatAgent.on_messages_stream](https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.base.html#autogen_agentchat.base.ChatAgent.on_messages_stream) |
 | OpenAI Agent SDK | **Approach 1** Separates new_items (Primary+Secondary) from final output (Primary) as separate properties on the [RunResult](https://github.com/openai/openai-agents-python/blob/main/src/agents/result.py#L39) | **Approach 1** Similar to non-streaming, has a way of streaming updates via a method on the response object which includes all data, and then a separate final output property on the response object which is populated only when the run is complete. See [RunResultStreaming](https://github.com/openai/openai-agents-python/blob/main/src/agents/result.py#L136) |
 | Google ADK | **Approach 2** [Emits events](https://google.github.io/adk-docs/runtime/#step-by-step-breakdown) with [FinalResponse](https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/events/Event.java#L232) true (Primary) / false (Secondary) and callers have to filter out those with false to get just the final response message | **Approach 2** Similar to non-streaming except [events](https://google.github.io/adk-docs/runtime/#streaming-vs-non-streaming-output-partialtrue) are emitted with [Partial](https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/events/Event.java#L133) true to indicate that they are streaming messages. A final non partial event is also emitted. |
-| AWS (Strands) | **Approach 3** Returns an [AgentResult](https://strandsagents.com/docs/api/python/strands.agent.agent_result/) (Primary) with messages and a reason for the run's completion. | **Approach 2** [Streams events](https://strandsagents.com/docs/api/python/strands.agent.agent/) (Primary+Secondary) including, response text, current_tool_use, even data from "callbacks" (strands plugins) |
+| AWS (Strands) | **Approach 3** Returns an [AgentResult](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent_result/) (Primary) with messages and a reason for the run's completion. | **Approach 2** [Streams events](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent/#strands.agent.agent.Agent.stream_async) (Primary+Secondary) including, response text, current_tool_use, even data from "callbacks" (strands plugins) |
 | LangGraph | **Approach 2** A mixed list of all [messages](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) | **Approach 2** A mixed list of all [messages](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) |
 | Agno | **Combination of various approaches** Returns a [RunResponse](https://docs.agno.com/reference/agents/run-response) object with text content, messages (essentially chat history including inputs and instructions), reasoning and thinking text properties. Secondary events could potentially be extracted from messages. | **Approach 2** Returns [RunResponseEvent](https://docs.agno.com/reference/agents/run-response#runresponseevent-types-and-attributes) objects including tool call, memory update, etc, information, where the [RunResponseCompletedEvent](https://docs.agno.com/reference/agents/run-response#runresponsecompletedevent) has similar properties to RunResponse|
 | A2A | **Approach 3** Returns a [Task or Message](https://a2aproject.github.io/A2A/latest/specification/#71-messagesend) where the message is the final result (Primary) and task is a reference to a long running process. | **Approach 2** Returns a [stream](https://a2aproject.github.io/A2A/latest/specification/#72-messagestream) that contains task updates (Secondary) and a final message (Primary) |
@@ -496,9 +496,9 @@ We need to decide what AIContent types, each agent response type will be mapped
 |-|-|
 | AutoGen | **Approach 1** Supports [configuring an agent](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tutorial/agents.html#structured-output) at agent creation. |
 | Google ADK | **Approach 1** Both [input and output schemas can be specified for LLM Agents](https://google.github.io/adk-docs/agents/llm-agents/#structuring-data-input_schema-output_schema-output_key) at construction time. This option is specific to this agent type and other agent types do not necessarily support |
-| AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/docs/api/python/strands.agent.agent/) |
+| AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent/#strands.agent.agent.Agent.structured_output) |
 | LangGraph | **Approach 1** Supports [configuring an agent](https://langchain-ai.github.io/langgraph/agents/agents/?h=structured#6-configure-structured-output) at agent construction time, and a [structured response](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) can be retrieved as a special property on the agent response |
-| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/input-output/structured-output/agent) at agent construction time |
+| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/examples/getting-started/structured-output) at agent construction time |
 | A2A | **Informal Approach 2** Doesn't formally support schema negotiation, but [hints can be provided via metadata](https://a2a-protocol.org/latest/specification/#97-structured-data-exchange-requesting-and-providing-json) at invocation time |
 | Protocol Activity | Supports returning [Complex types](https://github.com/microsoft/Agents/blob/main/specs/activity/protocol-activity.md#complex-types) but no support for requesting a type |
 
@@ -508,7 +508,7 @@ We need to decide what AIContent types, each agent response type will be mapped
 |-|-|
 | AutoGen | Supports a [stop reason](https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.base.html#autogen_agentchat.base.TaskResult.stop_reason) which is a freeform text string |
 | Google ADK | [No equivalent present](https://github.com/google/adk-python/blob/main/src/google/adk/events/event.py) |
-| AWS (Strands) | Exposes a [stop_reason](https://strandsagents.com/docs/api/python/strands.types.event_loop/) property on the [AgentResult](https://strandsagents.com/docs/api/python/strands.agent.agent_result/) class with options that are tied closely to LLM operations. |
+| AWS (Strands) | Exposes a [stop_reason](https://strandsagents.com/latest/documentation/docs/api-reference/python/types/event_loop/#strands.types.event_loop.StopReason) property on the [AgentResult](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent_result/) class with options that are tied closely to LLM operations. |
 | LangGraph | No equivalent present, output contains only [messages](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) |
 | Agno | [No equivalent present](https://docs.agno.com/reference/agents/run-response) |
 | A2A | No equivalent present, response only contains a [message](https://a2a-protocol.org/latest/specification/#64-message-object) or [task](https://a2a-protocol.org/latest/specification/#61-task-object). |

docs/decisions/0016-python-context-middleware.md

@@ -1072,51 +1072,6 @@ Rationale for B1 over B2: Simpler is better. The whole state dict is passed to e
 > **Note on trust:** Since all `ContextProvider` instances reason over conversation messages (which may contain sensitive user data), they should be **trusted by default**. This is also why we allow all plugins to see all state - if a plugin is untrusted, it shouldn't be in the pipeline at all. The whole state dict is passed rather than isolated slices because plugins that handle messages already have access to the full conversation context.
 
 
-### Addendum (2026-02-17): Provider-scoped hook state and default source IDs
-
-This addendum introduces a **breaking change** that supersedes earlier references in this ADR where hooks received the
-entire `session.state` object as their `state` parameter.
-
-#### Hook state contract
-
-- `before_run` and `after_run` now receive a **provider-scoped** mutable state dict.
-- The framework passes `session.state.setdefault(provider.source_id, {})` to hook `state`.
-- Cross-provider/global inspection remains available through `session.state` on `AgentSession`.
-
-#### Session requirement and fallback behavior
-
-- Provider hooks must use session-backed scoped state; there is no ad-hoc `{}` fallback state.
-- If providers run without a caller-supplied session, the framework creates an internal run-scoped `AgentSession` and
-  passes provider-scoped state from that session.
-
-#### Migration guidance
-
-Migrate provider implementations and samples from nested access to scoped access:
-
-- `state[self.source_id]["key"]` → `state["key"]`
-- `state.setdefault(self.source_id, {})["key"]` → `state["key"]`
-
-#### DEFAULT_SOURCE_ID standardization
-
-Aligned with and extending [PR #3944](https://github.com/microsoft/agent-framework/pull/3944), all built-in/connector
-providers in this surface now define a `DEFAULT_SOURCE_ID` and allow constructor override via `source_id`.
-
-Naming convention:
-
-- snake_case
-- close to the provider class name
-- history providers may use `*_memory` where differentiation is useful
-
-Defaults introduced by this change:
-
-- `InMemoryHistoryProvider.DEFAULT_SOURCE_ID = "in_memory"`
-- `Mem0ContextProvider.DEFAULT_SOURCE_ID = "mem0"`
-- `RedisContextProvider.DEFAULT_SOURCE_ID = "redis"`
-- `RedisHistoryProvider.DEFAULT_SOURCE_ID = "redis_memory"`
-- `AzureAISearchContextProvider.DEFAULT_SOURCE_ID = "azure_ai_search"`
-- `FoundryMemoryProvider.DEFAULT_SOURCE_ID = "foundry_memory"`
-
-
 ## Comparison to .NET Implementation
 
 The .NET Agent Framework provides equivalent functionality through a different structure. Both implementations achieve the same goals using idioms natural to their respective languages.

docs/decisions/0017-agent-additional-properties.md

@@ -1,211 +0,0 @@
----
-status: accepted
-contact: westey-m
-date: 2026-02-24
-deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, lokitoth, alliscode, taochenosu, moonbox3
-consulted:
-informed:
----
-
-# AdditionalProperties for AIAgent and AgentSession
-
-## Context and Problem Statement
-
-The `AIAgent` base class currently exposes `Id`, `Name`, and `Description` as its core metadata properties, and `AgentSession` exposes only a `StateBag` property.
-Neither type has a mechanism for attaching arbitrary metadata, such as protocol-specific descriptors (e.g., A2A agent cards), hosting attributes, session-level tags, or custom user-defined metadata for discovery and routing.
-
-Other types in the framework already carry `AdditionalProperties` — notably `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate` — all using `AdditionalPropertiesDictionary` from `Microsoft.Extensions.AI`.
-Adding a similar property to `AIAgent` and `AgentSession` would give both types a consistent, extensible metadata surface.
-
-Related: [Work Item #2133](https://github.com/microsoft/agent-framework/issues/2133)
-
-## Decision Drivers
-
-- **Consistency**: Other core types (`AgentRunOptions`, `AgentResponse`, `AgentResponseUpdate`) already expose `AdditionalProperties`. `AIAgent` and `AgentSession` are the major abstractions that lack this.
-- **Extensibility**: Hosting libraries, protocol adapters (A2A, AG-UI), and discovery mechanisms need a place to attach agent-level and session-level metadata without subclassing.
-- **Simplicity**: The solution should be easy to understand and use; avoid over-engineering.
-- **Minimal breaking change**: The addition should not require changes to existing agent implementations.
-- **Clear semantics**: Users should understand what `AdditionalProperties` on an agent or session means and how it differs from `AdditionalProperties` on `AgentRunOptions`.
-
-## Considered Options
-
-### Surface Area
-
-- **Option A**: Public get-only property, auto-initialized (`AdditionalPropertiesDictionary AdditionalProperties { get; } = new()`) on both `AIAgent` and `AgentSession`
-- **Option B**: Public get/set nullable property (`AdditionalPropertiesDictionary? AdditionalProperties { get; set; }`) on both `AIAgent` and `AgentSession`
-- **Option C**: Constructor-injected dictionary with public get-only accessor on both `AIAgent` and `AgentSession`
-- **Option D**: External container/wrapper object — metadata lives outside `AIAgent` and `AgentSession`; no changes to the base classes
-
-### Semantics
-
-- **Option 1**: Metadata only — describes the agent or session; not propagated when calling `IChatClient`
-- **Option 2**: Passed down the stack — merged into `ChatOptions.AdditionalProperties` during `ChatClientAgent` runs
-
-## Decision Outcome
-
-The chosen option is **Option D + Option 1**: an external container/wrapper object, used purely as metadata.
-
-### Consequences
-
-- Good, because `AIAgent` and `AgentSession` remain unchanged, avoiding any increase to the core framework surface area while still enabling extensible metadata.
-- Good, because an external wrapper (owned by hosting/protocol libraries or user code, not the `AIAgent` / `AgentSession` base classes) can internally use `AdditionalPropertiesDictionary` to stay consistent with existing patterns on `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate`.
-- Good, because metadata-only semantics keep a clean separation from per-run extensibility (`AgentRunOptions.AdditionalProperties`) and avoid unexpected side effects during agent execution.
-- Good, because no additional allocation occurs on `AIAgent` or `AgentSession` when no metadata is needed; external wrappers can be created only when metadata is required.
-- Bad, because callers and libraries must manage and pass around both the agent/session instance and its associated metadata wrapper, keeping them correctly associated.
-- Bad, because different hosting or protocol layers may define their own wrapper types, which can fragment the ecosystem unless conventions are agreed upon.
-
-## Pros and Cons of the Options
-
-### Option A — Public get-only property, auto-initialized
-
-The property is always non-null and ready to use. Users add metadata after construction.
-
-```csharp
-public abstract partial class AIAgent
-{
-    public AdditionalPropertiesDictionary AdditionalProperties { get; } = new();
-}
-
-public abstract partial class AgentSession
-{
-    public AdditionalPropertiesDictionary AdditionalProperties { get; } = new();
-}
-
-// Usage
-agent.AdditionalProperties["protocol"] = "A2A";
-agent.AdditionalProperties.Add<MyAgentCardInfo>(cardInfo);
-session.AdditionalProperties["tenant"] = tenantId;
-```
-
-- Good, because users never encounter `null` — no defensive null checks needed.
-- Good, because the dictionary reference cannot be replaced, preventing accidental data loss.
-- Good, because it is the simplest API surface to use.
-- Neutral, because it always allocates, even when no metadata is needed. The allocation cost is negligible.
-- Bad, because it cannot be set at construction time as a single object (users must populate it post-construction).
-
-### Option B — Public get/set nullable property
-
-Matches the existing pattern on `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate`.
-
-```csharp
-public abstract partial class AIAgent
-{
-    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
-}
-
-public abstract partial class AgentSession
-{
-    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
-}
-
-// Usage
-agent.AdditionalProperties ??= new();
-agent.AdditionalProperties["protocol"] = "A2A";
-session.AdditionalProperties ??= new();
-session.AdditionalProperties["tenant"] = tenantId;
-```
-
-- Good, because it is consistent with the existing `AdditionalProperties` pattern on `AgentRunOptions` and `AgentResponse`.
-- Good, because it avoids allocation when no metadata is needed.
-- Bad, because every consumer must null-check before reading or writing.
-- Bad, because the entire dictionary can be replaced, risking accidental loss of metadata set by other components (e.g., a hosting library sets metadata, then user code replaces the dictionary).
-
-### Option C — Constructor-injected with public get
-
-The dictionary is provided at construction time and exposed as get-only.
-
-```csharp
-public abstract partial class AIAgent
-{
-    public AdditionalPropertiesDictionary AdditionalProperties { get; }
-
-    protected AIAgent(AdditionalPropertiesDictionary? additionalProperties = null)
-    {
-        this.AdditionalProperties = additionalProperties ?? new();
-    }
-}
-
-public abstract partial class AgentSession
-{
-    public AdditionalPropertiesDictionary AdditionalProperties { get; }
-
-    protected AgentSession(AdditionalPropertiesDictionary? additionalProperties = null)
-    {
-        this.AdditionalProperties = additionalProperties ?? new();
-    }
-}
-```
-
-- Good, because an agent's metadata can be established before any code runs against it.
-- Bad, because `AdditionalPropertiesDictionary` has no read-only variant, so the constructor-injection pattern gives a false sense of immutability — callers can still mutate the dictionary contents after construction.
-- Bad, because it requires adding a constructor parameter to the abstract base classes, which is a source-breaking change for all existing `AIAgent` and `AgentSession` subclasses (even with a default value, it changes the constructor signature that derived classes chain to).
-- Bad, because it is more complex with little practical benefit over Option A, since post-construction mutation is equally possible.
-
-### Option D — External container/wrapper object
-
-Rather than adding `AdditionalProperties` to `AIAgent` or `AgentSession`, users wrap the agent or session in a container object that carries both the instance and any associated metadata. No changes to the base classes are required.
-
-```csharp
-public class AgentWithMetadata
-{
-    public required AIAgent Agent { get; init; }
-    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
-}
-
-public class SessionWithMetadata
-{
-    public required AgentSession Session { get; init; }
-    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
-}
-
-// Usage
-var wrapper = new AgentWithMetadata
-{
-    Agent = myAgent,
-    AdditionalProperties = new() { ["protocol"] = "A2A" }
-};
-```
-
-- Good, because it requires no changes to `AIAgent` or `AgentSession`, avoiding any risk of breaking existing implementations.
-- Good, because metadata is clearly external to the agent and session, eliminating any ambiguity about whether it might be passed down the execution stack.
-- Good, because the container pattern gives the user full control over the metadata lifecycle and serialization.
-- Bad, because it is not discoverable — users must know about the container convention; there is no built-in API surface guiding them.
-
-### Option 1 — Metadata only
-
-`AdditionalProperties` on `AIAgent` and `AgentSession` is descriptive metadata. It is **not** automatically propagated when the agent calls downstream services such as `IChatClient`.
-
-- Good, because it keeps a clean separation of concerns: agent/session-level metadata vs. per-run options.
-- Good, because it avoids unintended side effects — metadata added for discovery or hosting won't leak into LLM requests.
-- Good, because per-run extensibility is already served by `AgentRunOptions.AdditionalProperties` (see [ADR 0014](0014-feature-collections.md)), so there is no gap.
-- Neutral, because users who want to pass agent metadata to the chat client can still do so manually via `AgentRunOptions`.
-
-### Option 2 — Passed down the stack
-
-`AdditionalProperties` on `AIAgent` and `AgentSession` are automatically merged into `ChatOptions.AdditionalProperties` (or similar) when `ChatClientAgent` invokes the underlying `IChatClient`.
-
-- Good, because it provides an automatic way to send agent-level configuration to the LLM provider.
-- Bad, because it conflates metadata (describing the agent) with operational parameters (controlling LLM behavior), leading to potential confusion.
-- Bad, because it risks leaking unrelated metadata into LLM calls (e.g., hosting tags, discovery URLs).
-- Bad, because it would be `ChatClientAgent`-specific behavior on a base-class property, creating inconsistency for non-`ChatClientAgent` implementations.
-- Bad, because it duplicates the purpose of `AgentRunOptions.AdditionalProperties`, which already serves as the per-run extensibility point for passing data down the stack.
-
-## Serialization Considerations
-
-`AIAgent` instances are not typically serialized, so `AdditionalProperties` on `AIAgent` does not raise serialization concerns.
-
-`AgentSession` instances, however, are routinely serialized and deserialized — for example, to persist conversation state across application restarts. Adding `AdditionalProperties` to `AgentSession` introduces a serialization challenge: `AdditionalPropertiesDictionary` is a `Dictionary<string, object?>`, and `object?` values do not carry enough type information for the JSON deserializer to reconstruct the original CLR types.
-
-### Default behavior — JsonElement round-tripping
-
-By default, when an `AgentSession` with `AdditionalProperties` is serialized and later deserialized, any complex objects stored as values in the dictionary will be deserialized as `JsonElement` rather than their original types. This is the same behavior exhibited by `ChatMessage.AdditionalProperties` and other `AdditionalPropertiesDictionary` usages in `Microsoft.Extensions.AI`, and is the approach we will follow.
-
-### Custom serialization via JsonSerializerOptions
-
-`AIAgent.SerializeSessionAsync` and `AIAgent.DeserializeSessionAsync` already accept an optional `JsonSerializerOptions` parameter. Users who need strongly-typed round-tripping of `AdditionalProperties` values can supply custom options with appropriate converters or type info resolvers. This is non-trivial to implement but provides full control over deserialization behavior when needed.
-
-## More Information
-
-- [ADR 0014 — Feature Collections](0014-feature-collections.md) established that `AdditionalProperties` on `AgentRunOptions` serves as the per-run extensibility mechanism. The proposed agent-level and session-level properties serve a complementary, distinct purpose: static metadata describing the agent or session itself.
-- `AdditionalPropertiesDictionary` is defined in `Microsoft.Extensions.AI` and is already a dependency of `Microsoft.Agents.AI.Abstractions`. No new package references are needed.
-- Type-safe access is available via the existing `AdditionalPropertiesExtensions` helper methods (`Add<T>`, `TryGetValue<T>`, `Contains<T>`, `Remove<T>`), which use `typeof(T).FullName` as the dictionary key.

docs/decisions/0018-agentthread-serialization.md

@@ -1,163 +0,0 @@
----
-# These are optional elements. Feel free to remove any of them.
-status: accepted
-contact: westey-m
-date: 2026-02-25
-deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
-consulted: 
-informed:
----
-
-# AgentSession serialization
-
-## Context and Problem Statement
-
-Serializing AgentSessions is done today by calling SerializeSession on the AIAgent instance and deserialization
-is done via the DeserializeSession method on the AIAgent instance.
-
-This approach has some drawbacks:
-
-1. It requires each AgentSession implementation to implement its own serialization logic. This can lead to inconsistencies and errors if not done correctly.
-1. It means that only one serialization format can be supported at a time. If we want to support multiple formats (e.g., JSON, XML, binary), we would need to implement separate serialization logic for each format.
-1. It is not possible to serialize and deserialize lists of AgentSessions, since each need to be handled individually.
-1. Users may not realise that they need to call these specific methods to serialize/deserialize AgentSessions.
-
-The reason why this approach was chosen initially is that AgentSessions may have behaviors that are attached to them and only the agent knows what behaviors to attach.
-These behaviors also have their own state that are attached to the AgentSession.
-The behaviors may have references to SDKs or other resources that cannot be created via standard deserialization mechanisms.
-E.g. an AgentSession may have a custom ChatMessageStore that knows how to store chat history in a specific storage backend and has a reference to the SDK client for that backend.
-When deserializing the AgentSession, we need to make sure that the ChatMessageStore is created with the correct SDK client.
-
-## Decision Drivers
-
-- A. Ability to continue to support custom behaviors (AIContextProviders / ChatHistoryProviders).
-- B. Ability to serialize and deserialize AgentSessions via standard serialization mechanisms, e.g. JsonSerializer.Serialize and JsonSerializer.Deserialize.
-- C. Ability for the caller to access custom providers.
-
-## Considered Options
-
-- Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
-- Option 2: Separate state from behavior, and only have state on AgentSession
-- Option 3: Keep the current approach of custom Serialize/Deserialize methods
-
-### Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
-
-Decision Drivers satisfied: A, B and C (C only partially)
-
-Have separate properties on the AgentSession for state and behavior and mark the behavior property with [JsonIgnore].
-After deserializing the AgentSession, the behavior is null and when the AgentSession is first used by the Agent, the behavior is created and attached to the AgentSession.
-
-This requires polymorphic deserialization to be supported, so that the correct AgentSession subclass and the correct behavior state is created during deserialization.
-Since the implementations for AgentSessions and their behaviors are not all known at compile time, we need a way to register custom AgentSession types and their corresponding behavior types for serialization with System.Text.Json on our JsonUtilities helpers.
-
-A drawback of this approach is that the AgentSession is in an incomplete state after deserialization until it is first used,
-so if a user was to call `GetService<MyBehavior>()` on the AgentSession before it is used by the Agent, it would return null.
-
-Behaviors like ChatMessageStore and AIContextProviders would need to change to support taking state as input and exposing state publicly.
-
-```csharp
-public class ChatClientAgentSession
-{
-    ...
-    public ChatMessageStoreState ChatMessageStoreState { get; }
-    public ChatMessageStore? ChatMessageStore { get; }
-    ...
-}
-
-[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
-[JsonDerivedType(typeof(InMemoryChatMessageStoreState), nameof(InMemoryChatMessageStoreState))]
-public abstract class ChatMessageStoreState
-{
-}
-public class InMemoryChatMessageStoreState : ChatMessageStoreState
-{
-    public IList<ChatMessage> Messages { get; set; } = [];
-}
-
-public abstract class ChatMessageStore<TState>
-    where TState : ChatMessageStoreState
-{
-    ...
-    public abstract TState State { get; }
-    ...
-}
-
-public sealed class InMemoryChatMessageStore : ChatMessageStore<InMemoryChatMessageStoreState>, IList<ChatMessage>
-{
-    private readonly InMemoryChatMessageStoreState _state;
-
-    public InMemoryChatMessageStore(InMemoryChatMessageStoreState? state)
-    {
-        this._state = state ?? new InMemoryChatMessageStoreState();
-    }
-
-    public override InMemoryChatMessageStoreState State => this._state;
-
-    ...
-}
-```
-
-ChatClientAgent factories would need to change to support creating behaviors based on state:
-
-```csharp
-    public Func<ChatMessageStoreFactoryContext, ChatMessageStore>? ChatMessageStoreFactory { get; set; }
-
-    public class ChatMessageStoreFactoryContext
-    {
-        public ChatMessageStoreState? State { get; set; }
-    }
-```
-
-The run behavior of the ChatClientAgent would be as follows:
-
-1. If an AgentSession is provided, check if the ChatMessageStore property is null.
-1. If it is, check if the ChatMessageStoreState property is null.
-    1. If ChatMessageStoreState is null, check if there is a provided ChatMessageStoreFactory.
-        1. If there is, call it with a ChatMessageStoreFactoryContext containing null State to create a default ChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
-        2. If there is not, create a default InMemoryChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
-    1. If ChatMessageStoreState is not null, check if there is a provided ChatMessageStoreFactory.
-        1. If there is, call it with a ChatMessageStoreFactoryContext containing the State to create a ChatMessageStore behavior based on the state.
-        2. If there is not, create an InMemoryChatMessageStore behavior based on the State.
-
-### Option 2: Separate state from behavior, and only have state on AgentSession
-
-Decision Drivers satisfied: A, B and C.
-
-This is similar to Option 1 but instead of having a behavior property on the AgentSession, we only have a StateBag property on the AgentSession.
-Behaviors really make more sense to live with the agent rather than the Session, but state should live on the session.
-When the AgentSession is used by the Agent, the Agent runs the behaviors against the Session, and the behavior stores it's state on the Session StateBag.
-
-This means that users are unable to access the behavior from the AgentSession, e.g. via `AgentSession.GetService<TBehavior>()`.
-
-However, the behaviors can be public properties on the Agent or can be retrieved from the agent via `AIAgent.GetService<MyAIContextProvider>()`.
-
-```csharp
-public class AgentSession
-{
-    ...
-    public AgentSessionStateBag StateBag { get; protected set; } = new();
-    ...
-}
-```
-
-### Option 3: Keep the current approach of custom Serialize/Deserialize methods
-
-Decision Drivers satisfied: A and C
-
-This option keeps the current approach of having custom Serialize/Deserialize methods on the AgentSession and AIAgent.
-
-## Decision Outcome
-
-Chosen option:
-
-**Option 2** — separate state from behavior, with only state on the AgentSession — because it satisfies all decision drivers and provides the cleanest separation of concerns. Since not all AgentSession implementations have yet been cleanly separated from their behaviors, AIAgent.SerializeSession and AIAgent.DeserializeSession is kept for the time being, but most session types can be serialized and deserialized directly using JsonSerializer.
-
-### Consequences
-
-- Good, because providers are fully stateless — the same provider instance works correctly across any number of concurrent sessions without risk of state leakage.
-- Good, because `AgentSession` can be serialized and deserialized with standard `System.Text.Json` mechanisms, satisfying decision driver B.
-- Good, because the generic `StateBag` is extensible — new providers can store arbitrary state without requiring changes to the session class.
-- Good, because users can access providers via the agent (e.g. `agent.GetService<InMemoryChatHistoryProvider>()`) satisfying decision driver C.
-- Good, because sessions are always in a complete and valid state after deserialization — there is no "incomplete until first use" problem as in Option 1.
-- Neutral, because providers cannot be accessed directly from the session; callers must go through the agent. This is a minor usability trade-off but keeps the session focused on state only.
-- Bad, because each provider must be disciplined about using `ProviderSessionState<T>` and not storing session-specific data in instance fields. This is a correctness concern for custom provider implementers.

docs/decisions/0020-foundry-agent-type-naming.md

@@ -1,125 +0,0 @@
----
-status: accepted
-contact: rogerbarreto
-date: 2026-03-06
-deciders: rogerbarreto, alliscode
-consulted: ""
-informed: ""
----
-
-# Foundry agent surface stays centered on `ChatClientAgent`
-
-## Context
-
-The Microsoft Foundry integration exposes two distinct usage patterns:
-
-1. Direct Responses usage, where callers provide model, instructions, and tools at runtime.
-2. Server-side versioned agents, where callers create and manage `AgentVersion` resources through `AIProjectClient.Agents`.
-
-We briefly explored adding public wrapper types such as `FoundryAgent`, `FoundryVersionedAgent`, and `FoundryResponsesChatClient` to make those paths feel more specialized. That direction created extra public types, duplicated existing `ChatClientAgent` behavior, and pushed samples toward compatibility helpers instead of the native Azure SDK flow.
-
-## Decision
-
-Keep the public surface centered on `ChatClientAgent`.
-
-- Direct Responses scenarios use `AIProjectClient.AsAIAgent(...)`.
-- Server-side versioned scenarios use native `AIProjectClient.Agents` APIs to create or retrieve agent resources, then wrap `AgentRecord` or `AgentVersion` with `AIProjectClient.AsAIAgent(...)`.
-- Compatibility helpers such as `AIProjectClient.CreateAIAgentAsync(...)` and `AIProjectClient.GetAIAgentAsync(...)` remain only as obsolete migration shims.
-- Public wrapper types `FoundryAgent`, `FoundryVersionedAgent`, `FoundryResponsesChatClient`, and `FoundryResponsesChatClientAgent` are not part of the chosen direction.
-
-## Why
-
-- `ChatClientAgent` is already the framework abstraction used everywhere else.
-- `AIProjectClient` is the native Azure SDK entry point for versioned agent lifecycle operations.
-- A single agent abstraction avoids parallel type hierarchies for the same backend.
-- Samples become clearer when they show either:
-  - direct Responses construction via `AIProjectClient.AsAIAgent(...)`, or
-  - native Foundry resource management via `AIProjectClient.Agents`.
-
-## Consequences
-
-### Direct Responses path
-
-Use the convenience overloads on `AIProjectClient`:
-
-```csharp
-AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
-
-ChatClientAgent agent = aiProjectClient.AsAIAgent(
-    model: deploymentName,
-    instructions: "You are good at telling jokes.",
-    name: "JokerAgent");
-```
-
-Or use composed `ChatClientAgent`
-
-```csharp
-ProjectResponsesClient projectResponsesClient = new(new Uri(endpoint), new DefaultAzureCredential(), new AgentReference($"model:{deploymentName}"));
-
-ChatClientAgent agent = new(
-    chatClient: projectResponsesClient.AsIChatClient(),
-    instructions: "You are good at telling jokes.",
-    name: "JokerAgent");
-```
-
-This path is code-first and does not create a persistent server-side agent.
-
-### Versioned agent path
-
-Use the convenience overloads on `AIProjectClient`:
-
-```csharp
-AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
-
-AgentVersion version = await aiProjectClient.Agents.CreateAgentVersionAsync(
-    "JokerAgent",
-    new AgentVersionCreationOptions(
-        new PromptAgentDefinition(deploymentName)
-        {
-            Instructions = "You are good at telling jokes."
-        }));
-
-ChatClientAgent agent = aiProjectClient.AsAIAgent(version);
-```
-
-Or use composed `ChatClientAgent`
-
-```csharp
-AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
-
-AgentVersion version = await aiProjectClient.Agents.CreateAgentVersionAsync(
-    "JokerAgent",
-    new AgentVersionCreationOptions(
-        new PromptAgentDefinition(deploymentName)
-        {
-            Instructions = "You are good at telling jokes."
-        }));
-
-ProjectResponsesClient projectResponsesClient = aiProjectClient
-    .GetProjectOpenAIClient()
-    .GetProjectResponsesClientForAgent(new AgentReference(version.Name, version.Version));
-
-ChatClientAgent agent = new(
-    chatClient: projectResponsesClient.AsIChatClient(),
-    name: "JokerAgent");
-```
-
-### Samples
-
-- `FoundryAgents/` samples show the direct Responses path with `AIProjectClient.AsAIAgent(...)`.
-- `FoundryVersionedAgents/` samples should show native `AIProjectClient.Agents` create/get/delete flows plus `AsAIAgent(...)`.
-
-### Compatibility APIs
-
-Obsolete helper extensions remain only to ease migration of existing code. New samples and new guidance should not be written against them.
-
-## Rejected direction
-
-Do not introduce or preserve separate public wrapper types whose main purpose is to forward to `ChatClientAgent` while carrying Foundry-specific naming.
-
-That approach:
-
-- duplicates lifecycle concepts already present on `AIProjectClient`,
-- fragments the public API,
-- complicates samples and docs,
-- and makes migration harder by encouraging wrapper-specific affordances.

docs/decisions/0020-foundry-evals-integration.md

@@ -1,815 +0,0 @@
----
-status: accepted
-contact: bentho
-date: 2026-02-27
-deciders: bentho, markwallace-microsoft, westey-m
-consulted: Pratyush Mishra, Shivam Shrivastava, Manni Arora (Centrica eval scenario)
-informed: Agent Framework team, Foundry Evals team
----
-
-# Agent Evaluation Architecture with Azure AI Foundry Integration
-
-## Context and Problem Statement
-
-Azure AI Foundry provides a rich evaluation service for AI agents — built-in evaluators for agent behavior (task adherence, intent resolution), tool usage (tool call accuracy, tool selection), quality (coherence, fluency, relevance), and safety (violence, self-harm, prohibited actions). Results are viewable in the Foundry portal with dashboards and comparison views.
-
-However, using Foundry Evals with an agent-framework agent today requires significant manual effort. Developers must:
-
-1. Transform agent-framework's `Message`/`Content` types into the OpenAI-style agent message schema that Foundry evaluators expect
-2. Map tool definitions from agent-framework's `FunctionTool` format to evaluator-compatible schemas
-3. Manually wire up the correct Foundry data source type (`azure_ai_traces`, `jsonl`, `azure_ai_target_completions`, etc.) depending on their scenario
-4. Handle App Insights trace ID queries, response ID collection, and eval polling
-
-Additionally, evaluation is a concern that extends beyond any single provider. Developers may want to use local evaluators (LLM-as-judge, regex, keyword matching), third-party evaluation libraries, or multiple providers in combination. The architecture must support this without creating a Foundry-specific lock-in at the API level.
-
-### Functional Requirements for Agent Evaluation
-
-- **Single agents and workflows.** Evaluate both individual agent responses and multi-agent workflow results, with per-agent breakdown to pinpoint underperformance.
-- **One-shot and multi-turn conversations.** Capture full conversation trajectories — including tool calls and results — not just final query/response pairs.
-- **Conversation factoring.** Support splitting conversations into query/response in multiple ways (last turn, full trajectory, per-turn) because different factorings measure different things.
-- **Multiple providers, mix and match.** Run Foundry LLM-as-judge evaluators alongside fast local checks and custom evaluators on the same data, without restructuring code.
-- **Third-party extensibility.** Any evaluation library can participate by implementing the `Evaluator` protocol (Python) or `IAgentEvaluator` interface (.NET). No predetermined list of supported libraries — the protocol is intentionally simple (`evaluate(items) → results`) so that wrappers for libraries like DeepEval, RAGAS, or Promptfoo are straightforward to write.
-- **Bring your own evaluator.** Creating a custom evaluator should be as simple as writing a function.
-- **Evaluate without re-running.** Evaluate existing responses from logs or previous runs without invoking the agent again.
-
-## Decision Drivers
-
-- **Zero-friction evaluation**: Developers should go from "I have an agent" to "I have eval results" with minimal code.
-- **Provider-agnostic API**: Core evaluation capabilities must not be tied to any specific provider. Provider configuration should be separate from the evaluation call.
-- **Lowest concept count**: Introduce the fewest possible new types, abstractions, and APIs for developers to learn.
-- **Leverage existing knowledge**: The framework already knows which agents exist, what tools they have, and what conversations occurred. Evals should use this automatically rather than requiring the developer to re-specify it.
-- **Foundry-native results**: When using Foundry, results should be viewable in the Foundry portal with dashboards and comparison views.
-- **Progressive disclosure**: Simple scenarios should be near-zero code. Advanced scenarios should build on the same primitives.
-- **Cross-language parity**: Design must be implementable in both Python and .NET.
-
-## Considered Options
-
-1. **Provider-specific functions** — Build Foundry-specific helper functions (`evaluate_agent()`, etc.) directly in the Azure package. All eval functions take Foundry connection parameters.
-2. **Evaluator protocol with shared orchestration** — Define a provider-agnostic `Evaluator` protocol in the base agent library (`agent_framework` in Python, `Microsoft.Agents.AI` in .NET). Orchestration functions live alongside it. Providers implement the protocol.
-3. **Full eval framework** — Build comprehensive eval infrastructure including custom evaluator definitions, scoring profiles, and reporting inside agent-framework.
-
-## Decision Outcome
-
-Proposed option: "Evaluator protocol with shared orchestration", because it delivers the low-friction developer experience, supports multiple providers without API changes, and keeps the concept count low.
-
-### Usage Examples
-
-#### Evaluate an agent
-
-The agent is invoked once per query by default. For statistically meaningful evaluation, provide multiple diverse queries. For measuring **consistency** (does the same query produce reliable results?), use `num_repetitions` to run each query N times independently:
-
-**Python:**
-
-```python
-evals = FoundryEvals(
-    project_client=client,
-    model_deployment="gpt-4o",
-    evaluators=[FoundryEvals.RELEVANCE, FoundryEvals.COHERENCE],
-)
-
-results = await evaluate_agent(
-    agent=my_agent,
-    queries=[
-        "What's the weather in Seattle?",
-        "Plan a weekend trip to Portland",
-        "What restaurants are near Pike Place?",
-    ],
-    evaluators=evals,
-)
-for r in results:
-    r.assert_passed()
-```
-
-**C#:**
-
-```csharp
-var evals = new FoundryEvals(chatConfiguration, FoundryEvals.Relevance, FoundryEvals.Coherence);
-
-AgentEvaluationResults results = await agent.EvaluateAsync(
-    new[] {
-        "What's the weather in Seattle?",
-        "Plan a weekend trip to Portland",
-        "What restaurants are near Pike Place?",
-    },
-    evals);
-
-results.AssertAllPassed();
-```
-
-`evaluate_agent` returns one `EvalResults` per evaluator. Each result contains per-item scores with the evaluated response for auditing:
-
-```
-# results[0] (FoundryEvals)
-EvalResults(status="completed", passed=3, failed=0, total=3)
-  items[0]: EvalItemResult(
-    query="What's the weather in Seattle?",
-    response="It's currently 72°F and sunny in Seattle.",
-    scores={"relevance": 5, "coherence": 5})
-  items[1]: EvalItemResult(
-    query="Plan a weekend trip to Portland",
-    response="Here's a 2-day Portland itinerary...",
-    scores={"relevance": 4, "coherence": 5})
-  items[2]: EvalItemResult(
-    query="What restaurants are near Pike Place?",
-    response="Top restaurants near Pike Place Market: ...",
-    scores={"relevance": 5, "coherence": 4})
-```
-
-#### Measure consistency with repetitions
-
-Run each query multiple times to detect non-deterministic behavior:
-
-**Python:**
-
-```python
-results = await evaluate_agent(
-    agent=my_agent,
-    queries=["What's the weather in Seattle?"],
-    evaluators=evals,
-    num_repetitions=3,  # each query runs 3 times independently
-)
-# results contain 3 items (1 query × 3 repetitions)
-```
-
-**C#:**
-
-```csharp
-AgentEvaluationResults results = await agent.EvaluateAsync(
-    new[] { "What's the weather in Seattle?" },
-    evals,
-    numRepetitions: 3);  // each query runs 3 times independently
-// results contain 3 items (1 query × 3 repetitions)
-```
-
-#### Evaluate a response you already have
-
-When you already have agent responses, pass them directly to skip re-running the agent. Each query is paired with its corresponding response:
-
-**Python:**
-
-```python
-queries = ["What's the weather?", "What's the capital of France?"]
-responses = [await agent.run([Message("user", [q])]) for q in queries]
-
-results = await evaluate_agent(
-    responses=responses,
-    evaluators=evals,
-)
-```
-
-**C#:**
-
-```csharp
-var queries = new[] { "What's the weather?" };
-var responses = new List<AgentResponse>();
-foreach (var q in queries)
-    responses.Add(await agent.RunAsync(new[] { new ChatMessage(ChatRole.User, q) }));
-
-AgentEvaluationResults results = await agent.EvaluateAsync(
-    responses: responses,
-    evals);
-```
-
-Each `AgentResponse` already contains the conversation (query + response), so the evaluator extracts query/response from the conversation. When you pass `responses` without `queries`, the conversation is the source of truth.
-
-#### Evaluate with conversation split strategies
-
-By default, evaluators see only the last turn (final user message → final assistant response). For multi-turn conversations, you can control how the conversation is factored for evaluation:
-
-**Python:**
-
-```python
-results = await evaluate_agent(
-    agent=agent,
-    queries=["Plan a 3-day trip to Paris"],
-    evaluators=evals,
-    conversation_split=ConversationSplit.FULL,      # evaluate entire trajectory
-)
-
-# Or per-turn: each user→assistant exchange scored independently
-results = await evaluate_agent(
-    agent=agent,
-    queries=["Plan a 3-day trip to Paris"],
-    evaluators=evals,
-    conversation_split=ConversationSplit.PER_TURN,
-)
-```
-
-**C#:**
-
-```csharp
-// Full conversation as context
-AgentEvaluationResults results = await agent.EvaluateAsync(
-    new[] { "Plan a 3-day trip to Paris" },
-    evals,
-    splitter: ConversationSplitters.Full);
-
-// Per-turn splitting
-var items = EvalItem.PerTurnItems(conversation);  // one EvalItem per user turn
-var results = await evals.EvaluateAsync(items);
-```
-
-With `PER_TURN`, a 3-turn conversation produces 3 scored items:
-
-```
-EvalResults(status="completed", passed=3, failed=0, total=3)
-  items[0]: query="Plan a 3-day trip to Paris"    scores={"relevance": 5}
-  items[1]: query="What about restaurants?"        scores={"relevance": 4}
-  items[2]: query="Make it budget-friendly"        scores={"relevance": 5}
-```
-
-#### Evaluate a multi-agent workflow
-
-**Python:**
-
-```python
-result = await workflow.run("Plan a trip to Paris")
-eval_results = await evaluate_workflow(
-    workflow=workflow,
-    workflow_result=result,
-    evaluators=evals,
-)
-
-for r in eval_results:
-    print(f"  overall: {r.passed}/{r.total}")
-    for name, sub in r.sub_results.items():
-        print(f"    {name}: {sub.passed}/{sub.total}")
-```
-
-**C#:**
-
-```csharp
-WorkflowRunResult result = await workflow.RunAsync("Plan a trip to Paris");
-
-IReadOnlyList<AgentEvaluationResults> evalResults = await result.EvaluateAsync(evals);
-
-foreach (var r in evalResults)
-{
-    Console.WriteLine($"  overall: {r.Passed}/{r.Total}");
-    foreach (var (name, sub) in r.SubResults)
-        Console.WriteLine($"    {name}: {sub.Passed}/{sub.Total}");
-}
-```
-
-Workflows return one result per evaluator, with sub-results per agent in the workflow:
-
-```
-EvalResults(status="completed", passed=2, failed=0, total=2)
-  sub_results:
-    "planner":  EvalResults(passed=1, total=1)
-    "researcher": EvalResults(passed=1, total=1)
-```
-
-#### Mix multiple providers
-
-**Python:**
-
-```python
-@evaluator
-def is_helpful(response: str) -> bool:
-    return len(response.split()) > 10
-
-foundry = FoundryEvals(
-    project_client=client,
-    model_deployment="gpt-4o",
-    evaluators=[FoundryEvals.RELEVANCE, FoundryEvals.COHERENCE],
-)
-
-results = await evaluate_agent(
-    agent=agent,
-    queries=queries,
-    evaluators=[is_helpful, keyword_check("weather"), foundry],
-)
-```
-
-**C#:**
-
-```csharp
-IReadOnlyList<AgentEvaluationResults> results = await agent.EvaluateAsync(
-    queries,
-    evaluators: new IAgentEvaluator[]
-    {
-        new LocalEvaluator(
-            EvalChecks.KeywordCheck("weather"),
-            FunctionEvaluator.Create("is_helpful", (string r) => r.Split(' ').Length > 10)),
-        new FoundryEvals(chatConfiguration, FoundryEvals.Relevance, FoundryEvals.Coherence),
-    });
-```
-
-Multiple evaluators return one result each — `results[0]` is the local evaluator, `results[1]` is Foundry.
-
-#### Custom function evaluators
-
-**Python:**
-
-```python
-@evaluator
-def mentions_city(response: str, expected_output: str) -> bool:
-    return expected_output.lower() in response.lower()
-
-@evaluator
-def used_tools(conversation: list, tools: list) -> float:
-    # ... scoring logic
-    return score
-
-local = LocalEvaluator(mentions_city, used_tools)
-```
-
-`@evaluator` uses **parameter name injection** — the function's parameter names determine what data it receives from the `EvalItem`. Supported names: `query`, `response`, `expected`, `expected_tool_calls`, `conversation`, `tools`, `context`. Any combination is valid.
-
-**C#:**
-
-```csharp
-var local = new LocalEvaluator(
-    FunctionEvaluator.Create("mentions_city",
-        (EvalItem item) => item.ExpectedOutput != null
-            && item.Response.Contains(item.ExpectedOutput, StringComparison.OrdinalIgnoreCase)),
-    FunctionEvaluator.Create("is_concise",
-        (string response) => response.Split(' ').Length < 500));
-```
-
-## What To Build
-
-### Core: Evaluator Protocol
-
-A runtime-checkable protocol that any evaluation provider implements:
-
-```python
-@runtime_checkable
-class Evaluator(Protocol):
-    name: str
-
-    async def evaluate(
-        self, items: Sequence[EvalItem], *, eval_name: str = "Agent Framework Eval"
-    ) -> EvalResults: ...
-```
-
-The protocol is minimal — just `name` and `evaluate()`.
-
-### Core: EvalItem
-
-Provider-agnostic data format for items to evaluate:
-
-```python
-@dataclass
-class ExpectedToolCall:
-    name: str                                    # Tool/function name
-    arguments: dict[str, Any] | None = None      # None = don't check args
-
-@dataclass
-class EvalItem:
-    conversation: list[Message]               # Single source of truth
-    tools: list[FunctionTool] | None = None   # Agent's available tools
-    context: str | None = None
-    expected_output: str | None = None          # Ground-truth for comparison
-    expected_tool_calls: list[ExpectedToolCall] | None = None
-    split_strategy: ConversationSplitter | None = None
-
-    query: str       # property — derived from conversation split
-    response: str    # property — derived from conversation split
-```
-
-`conversation` is the single source of truth. `query` and `response` are derived properties — splitting the conversation at the last user message (default) and extracting text from each side. Changing the `split_strategy` consistently changes all derived values.
-
-`tools` provides typed `FunctionTool` objects — including MCP tools, which are automatically extracted after agent runs.
-
-### Internal: AgentEvalConverter
-
-Internal class that converts agent-framework types to `EvalItem`. Used by `evaluate_agent()` and `evaluate_workflow()` — not part of the public API:
-
-| Agent Framework | Eval Format |
-|---|---|
-| `Content.function_call` | `tool_call` in OpenAI chat format |
-| `Content.function_result` | `tool_result` in OpenAI chat format |
-| `FunctionTool` | `{name, description, parameters}` schema |
-| `Message` history | `conversation` list + `query`/`response` extraction |
-
-### Core: EvalResults
-
-Rich result type with convenience properties for CI integration:
-
-```python
-results.all_passed          # bool: no failures or errors (recursive for workflow)
-results.passed              # int: passing count
-results.failed              # int: failure count
-results.total               # int: total = passed + failed + errored
-results.items               # list[EvalItemResult]: per-item detail with query, response, and scores
-results.error               # str | None: error details on failure
-results.sub_results         # dict: per-agent breakdown (workflow evals)
-results.report_url          # str | None: portal link (Foundry)
-results.assert_passed()     # raises AssertionError with details
-```
-
-### Core: Orchestration Functions
-
-Provider-agnostic functions that extract data and delegate to evaluators:
-
-| Function | What it does |
-|---|---|
-| `evaluate_agent()` | Runs agent against test queries (or evaluates pre-existing `responses=`), converts to `EvalItem`s, passes to evaluator. Accepts optional `expected_output=` for ground-truth comparison, `expected_tool_calls=` for tool-correctness evaluation, and `num_repetitions=` for consistency measurement |
-| `evaluate_workflow()` | Extracts per-agent data from `WorkflowRunResult`, evaluates each agent and overall output. Per-agent breakdown in `sub_results`. Also accepts `num_repetitions=` |
-
-### Core: Conversation Split Strategies
-
-Multi-turn conversations must be split into query (input) and response (output) halves for evaluation. How you split determines *what you're evaluating*:
-
-**Last-turn split** — split at the last user message. Everything up to and including it is the query context; the agent's subsequent actions are the response:
-
-```
-conversation: user1 → assistant1 → user2 → assistant2(tool) → tool_result → assistant3
-query_messages:    [user1, assistant1, user2]
-response_messages: [assistant2(tool), tool_result, assistant3]
-```
-
-This evaluates: "Given all the context so far, did the agent answer the latest question well?" Best for response quality at a specific point in the conversation.
-
-**Full-conversation split** — the first user message is the query; everything after is the response:
-
-```
-query_messages:    [user1]
-response_messages: [assistant1, user2, assistant2(tool), tool_result, assistant3]
-```
-
-This evaluates: "Given the original request, did the entire conversation trajectory serve the user?" Best for task completion and overall conversation quality.
-
-**Per-turn split** — produces N eval items from an N-turn conversation. Each turn is evaluated with its cumulative context:
-
-```
-item 1: query = [user1],                        response = [assistant1]
-item 2: query = [user1, assistant1, user2],      response = [assistant2(tool), tool_result, assistant3]
-```
-
-This evaluates each response independently. Best for fine-grained analysis and pinpointing where a conversation goes wrong.
-
-These factorings produce different scores for the same conversation. The framework ships all three as built-in strategies, defaulting to last-turn. Developers can also provide a custom splitter — a function (Python) or `IConversationSplitter` implementation (.NET) — and override the strategy at the call site or per evaluator.
-
-### Azure AI: FoundryEvals
-
-`Evaluator` implementation backed by Azure AI Foundry:
-
-```python
-class FoundryEvals:
-    def __init__(self, *, project_client=None, openai_client=None,
-                 model_deployment: str, evaluators=None, ...)
-    async def evaluate(self, items, *, eval_name) -> EvalResults
-```
-
-**Smart auto-detection in `evaluate()`:**
-- Default evaluators: relevance, coherence, task_adherence
-- Auto-adds `tool_call_accuracy` when items have tools/`tool_definitions`
-- Filters out tool evaluators for items without tools
-
-### Azure AI: FoundryEvals Constants
-
-```python
-from agent_framework_azure_ai import FoundryEvals
-
-evaluators = [FoundryEvals.RELEVANCE, FoundryEvals.TOOL_CALL_ACCURACY]
-```
-
-Categories: Agent behavior, Tool usage, Quality, Safety.
-
-### Azure AI: Foundry-Specific Functions
-
-| Function | What it does |
-|---|---|
-| `evaluate_traces()` | Evaluate from stored response IDs or OTel traces |
-| `evaluate_foundry_target()` | Evaluate a Foundry-registered agent or deployment |
-
-### Core: LocalEvaluator and Function Evaluators
-
-`LocalEvaluator` implements the `Evaluator` protocol for fast, API-free evaluation. It runs check functions locally — useful for inner-loop development, CI smoke tests, and combining with cloud-based evaluators.
-
-Built-in checks:
-- `keyword_check(*keywords)` — response must contain specified keywords
-- `tool_called_check(*tool_names)` — agent must have called specified tools
-- `tool_calls_present` — all `expected_tool_calls` names appear in conversation (unordered, extras OK)
-- `tool_call_args_match` — expected tool calls match on name + arguments (subset match on args)
-
-Custom function evaluators use `@evaluator` to wrap plain Python functions. The function's **parameter names** determine what data it receives from the `EvalItem`:
-
-```python
-from agent_framework import evaluator, LocalEvaluator
-
-# Tier 1: Simple check — just query + response
-@evaluator
-def is_concise(response: str) -> bool:
-    return len(response.split()) < 500
-
-# Tier 2: Ground truth — compare against expected output
-@evaluator
-def mentions_city(response: str, expected_output: str) -> bool:
-    return expected_output.lower() in response.lower()
-
-# Tier 3: Full context — inspect conversation and tools
-@evaluator
-def used_tools(conversation: list, tools: list) -> float:
-    # ... scoring logic
-    return score
-
-local = LocalEvaluator(is_concise, mentions_city, used_tools)
-```
-
-Supported parameters: `query`, `response`, `expected`, `expected_tool_calls`, `conversation`, `tools`, `context`.
-Return types: `bool`, `float` (≥0.5 = pass), `dict` with `score` or `passed` key, or `CheckResult`.
-
-Async functions are handled automatically — `@evaluator` detects `async def` and produces the right wrapper.
-
-### Example: GAIA Benchmark
-
-[GAIA](https://huggingface.co/gaia-benchmark) tests real-world multi-step tasks with known expected answers. Each task has a question and a ground-truth answer, with optional file attachments. The framework accommodates GAIA's knobs (difficulty levels, file inputs, multi-step tool use) through the existing `EvalItem` fields:
-
-```python
-from datasets import load_dataset
-from agent_framework import evaluate_agent, evaluator, LocalEvaluator
-
-gaia = load_dataset("gaia-benchmark/GAIA", "2023_level1", split="test")
-
-@evaluator
-def exact_match(response: str, expected_output: str) -> bool:
-    return expected_output.strip().lower() in response.strip().lower()
-
-# Simple path — evaluate_agent handles running + expected_output stamping
-results = await evaluate_agent(
-    agent=agent,
-    queries=[task["Question"] for task in gaia],
-    expected_output=[task["Final answer"] for task in gaia],
-    evaluators=LocalEvaluator(exact_match),
-)
-```
-
-### Package Location
-
-- Core types and orchestration: `agent_framework._eval`, `agent_framework._local_eval` (Python), `Microsoft.Agents.AI` (.NET)
-- Foundry provider: `agent_framework_azure_ai._foundry_evals` (Python), `Microsoft.Agents.AI.AzureAI` (.NET)
-- Azure-AI re-exports core types for convenience (Python)
-
-## Known Limitations
-
-1. **Tool evaluators require query + agent**: Tool evaluators need tool definition schemas. When using these evaluators with `evaluate_agent(responses=...)`, provide `queries=` and pass an agent with tool definitions.
-2. **`model_deployment` always required**: Could potentially be inferred from the Foundry project configuration.
-
-## Open Questions
-
-1. **Red teaming non-registered agents**: Requires Foundry API support for callback-based flows.
-2. **Datasets with expected outputs**: A dataset abstraction for pre-populating `expected_output` values across eval runs is a natural next step but not yet designed.
-3. **Multi-modal evaluation**: The `conversation` field on `EvalItem` already stores full `Message`/`Content` (Python) and `ChatMessage` (.NET) objects, which can represent multi-modal content (images, audio, structured data). Evaluators that accept the full `EvalItem` or `conversation` parameter can access this content today. However, the convenience shortcuts — `query`/`response` string projections and the `FunctionEvaluator` string overloads — are text-only. Multi-modal-aware evaluators should use the full-item path (`Func<EvalItem, CheckResult>` in .NET, `conversation: list` parameter in Python).
-
-## .NET Implementation Design
-
-### Key Difference: MEAI Ecosystem
-
-Unlike Python, the .NET ecosystem already has `Microsoft.Extensions.AI.Evaluation` (v10.3.0) providing:
-
-- `IEvaluator` — per-item evaluation of `(messages, chatResponse) → EvaluationResult`
-- `CompositeEvaluator` — combines multiple evaluators
-- Quality evaluators — `RelevanceEvaluator`, `CoherenceEvaluator`, `GroundednessEvaluator`
-- Safety evaluators — `ContentHarmEvaluator`, `ProtectedMaterialEvaluator`
-- Metric types — `NumericMetric`, `BooleanMetric`, `StringMetric`
-
-The .NET integration uses MEAI's `IEvaluator` directly — no new evaluator interface. Our contribution is the **orchestration layer**: extension methods that run agents, extract data, call `IEvaluator` per item, and aggregate results.
-
-### Architecture
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│  Developer Code                                              │
-│  agent.EvaluateAsync(queries, evaluator)                     │
-│  run.EvaluateAsync(evaluator)                                │
-└────────────────┬─────────────────────────────────────────────┘
-                 │
-┌────────────────▼─────────────────────────────────────────────┐
-│  Orchestration Layer (Microsoft.Agents.AI)                   │
-│  AgentEvaluationExtensions — runs agents, extracts data,     │
-│  calls IEvaluator per item, aggregates into                  │
-│  AgentEvaluationResults                                      │
-└────────────────┬─────────────────────────────────────────────┘
-                 │ IEvaluator (MEAI)
-                 │
-     ┌───────────┼────────────┐
-     │           │            │
- ┌───▼───-┐  ┌───▼────┐  ┌────▼──────────┐
- │ MEAI   │  │ Local  │  │ Foundry       │
- │ Quality│  │ Checks │  │ (cloud batch) │
- │ Safety │  │ Lambdas│  │               │
- └────────┘  └────────┘  └───────────────┘
-```
-
-All evaluators implement MEAI's `IEvaluator`. The orchestration layer doesn't need to know which kind — it calls `EvaluateAsync(messages, chatResponse)` per item on all of them. `FoundryEvals` handles batching internally (buffers items, submits once, returns per-item results).
-
-### .NET Core Types
-
-**No new evaluator interface.** Use MEAI's `IEvaluator` directly.
-
-**`AgentEvaluationResults`** — The only new type. Aggregates per-item MEAI `EvaluationResult`s across a batch of queries:
-
-```csharp
-public class AgentEvaluationResults
-{
-    public string Provider { get; init; }
-    public string? ReportUrl { get; init; }
-
-    // Per-item — standard MEAI EvaluationResult, unchanged
-    public IReadOnlyList<EvaluationResult> Items { get; init; }
-
-    // Aggregate pass/fail derived from metric interpretations
-    public int Passed { get; }
-    public int Failed { get; }
-    public int Total { get; }
-    public bool AllPassed { get; }
-
-    // Workflow: per-agent breakdown
-    public IReadOnlyDictionary<string, AgentEvaluationResults>? SubResults { get; init; }
-
-    public void AssertAllPassed(string? message = null);
-}
-```
-
-### .NET Evaluator Implementations
-
-All implement MEAI's `IEvaluator`:
-
-**`LocalEvaluator`** — Runs lambda checks locally, returns `BooleanMetric` per check:
-
-```csharp
-var local = new LocalEvaluator(
-    FunctionEvaluator.Create("is_concise",
-        (string response) => response.Split().Length < 500),
-    EvalChecks.KeywordCheck("weather"),
-    EvalChecks.ToolCalledCheck("get_weather"));
-```
-
-**MEAI evaluators** — Used directly, no adapter needed:
-
-```csharp
-var quality = new CompositeEvaluator(
-    new RelevanceEvaluator(),
-    new CoherenceEvaluator());
-```
-
-**`FoundryEvals`** — Implements `IEvaluator` but batches internally. On first call, buffers the item. On the last item (or when explicitly flushed), submits the batch to Foundry and distributes per-item results:
-
-```csharp
-var foundry = new FoundryEvals(projectClient, "gpt-4o");
-```
-
-### .NET Orchestration: Extension Methods
-
-```csharp
-public static class AgentEvaluationExtensions
-{
-    // Evaluate an agent against test queries
-    public static Task<AgentEvaluationResults> EvaluateAsync(
-        this AIAgent agent,
-        IEnumerable<string> queries,
-        IEvaluator evaluator,
-        ChatConfiguration? chatConfiguration = null,
-        IEnumerable<string>? expectedOutput = null,
-        CancellationToken cancellationToken = default);
-
-    // Evaluate pre-existing responses (without re-running the agent)
-    public static Task<AgentEvaluationResults> EvaluateAsync(
-        this AIAgent agent,
-        AgentResponse responses,
-        IEvaluator evaluator,
-        IEnumerable<string>? queries = null,
-        ChatConfiguration? chatConfiguration = null,
-        IEnumerable<string>? expectedOutput = null,
-        CancellationToken cancellationToken = default);
-
-    // Evaluate with multiple evaluators (one result per evaluator)
-    public static Task<IReadOnlyList<AgentEvaluationResults>> EvaluateAsync(
-        this AIAgent agent,
-        IEnumerable<string> queries,
-        IEnumerable<IEvaluator> evaluators,
-        ChatConfiguration? chatConfiguration = null,
-        IEnumerable<string>? expectedOutput = null,
-        CancellationToken cancellationToken = default);
-
-    // Evaluate a workflow run with per-agent breakdown
-    public static Task<AgentEvaluationResults> EvaluateAsync(
-        this Run run,
-        IEvaluator evaluator,
-        ChatConfiguration? chatConfiguration = null,
-        bool includeOverall = true,
-        bool includePerAgent = true,
-        CancellationToken cancellationToken = default);
-}
-```
-
-**Usage:**
-
-```csharp
-// MEAI evaluators — just works
-var results = await agent.EvaluateAsync(
-    queries: ["What's the weather?"],
-    evaluator: new RelevanceEvaluator(),
-    chatConfiguration: new ChatConfiguration(evalClient));
-
-// Local checks
-var results = await agent.EvaluateAsync(
-    queries: ["What's the weather?"],
-    evaluator: new LocalEvaluator(
-        EvalChecks.KeywordCheck("weather")));
-
-// Foundry cloud
-var results = await agent.EvaluateAsync(
-    queries: ["What's the weather?"],
-    evaluator: new FoundryEvals(projectClient, "gpt-4o"));
-
-// Evaluate existing response (without re-running the agent)
-var response = await agent.RunAsync("What's the weather?");
-var results = await agent.EvaluateAsync(
-    responses: response,
-    queries: ["What's the weather?"],
-    evaluator: new FoundryEvals(projectClient, "gpt-4o"));
-
-// Mixed — one result per evaluator
-var results = await agent.EvaluateAsync(
-    queries: ["What's the weather?"],
-    evaluators: [
-        new LocalEvaluator(EvalChecks.KeywordCheck("weather")),
-        new RelevanceEvaluator(),
-        new FoundryEvals(projectClient, "gpt-4o")
-    ],
-    chatConfiguration: new ChatConfiguration(evalClient));
-
-// Workflow with per-agent breakdown
-Run run = await workflowRunner.RunAsync(workflow, "Plan a trip");
-var results = await run.EvaluateAsync(
-    evaluator: new FoundryEvals(projectClient, "gpt-4o"));
-```
-
-### .NET Function Evaluators
-
-Typed factory overloads (C# equivalent of Python's `@evaluator`):
-
-```csharp
-public static class FunctionEvaluator
-{
-    public static EvalCheck Create(string name, Func<string, bool> check);           // response only
-    public static EvalCheck Create(string name, Func<string, string?, bool> check);  // expectedOutput
-    public static EvalCheck Create(string name, Func<EvalItem, bool> check);         // full item
-    public static EvalCheck Create(string name, Func<EvalItem, CheckResult> check);  // full control
-    public static EvalCheck Create(string name, Func<string, Task<bool>> check);     // async
-}
-```
-
-`EvalItem` is a lightweight record used only by `FunctionEvaluator` and `LocalEvaluator` to pass context to check functions. It is not part of the `IEvaluator` interface:
-
-```csharp
-public record ExpectedToolCall(string Name, IReadOnlyDictionary<string, object>? Arguments = null);
-
-public sealed class EvalItem
-{
-    public EvalItem(string query, string response, IReadOnlyList<ChatMessage> conversation);
-
-    public string Query { get; }
-    public string Response { get; }
-    public IReadOnlyList<ChatMessage> Conversation { get; }
-    public IReadOnlyList<AITool>? Tools { get; set; }
-    public string? ExpectedOutput { get; set; }
-    public IReadOnlyList<ExpectedToolCall>? ExpectedToolCalls { get; set; }
-    public string? Context { get; set; }
-    public IConversationSplitter? Splitter { get; set; }
-}
-```
-
-### Workflow Data Extraction (.NET)
-
-`run.EvaluateAsync()` walks `Run.OutgoingEvents` via LINQ:
-
-1. Pair `ExecutorInvokedEvent` / `ExecutorCompletedEvent` by `ExecutorId`
-2. Extract `AgentResponseEvent` for per-agent `ChatResponse`
-3. Call `evaluator.EvaluateAsync()` per invocation
-4. Group by `ExecutorId` for per-agent `SubResults`
-5. Use final workflow output for overall eval
-
-### .NET Package Structure
-
-| Package | Contents |
-|---------|----------|
-| `Microsoft.Agents.AI` | `IAgentEvaluator`, `AgentEvaluationResults`, `LocalEvaluator`, `FunctionEvaluator`, `EvalChecks`, `EvalItem`, `ExpectedToolCall`, `AgentEvaluationExtensions` |
-| `Microsoft.Agents.AI.AzureAI` | `FoundryEvals` (provider + constants) |
-
-### Python ↔ .NET Mapping
-
-| Python | .NET |
-|--------|------|
-| `Evaluator` protocol | `IAgentEvaluator` (our interface; MEAI provides `IEvaluator` for per-item scoring) |
-| `EvalItem` dataclass | `EvalItem` class |
-| `EvalResults` | `AgentEvaluationResults` |
-| `EvalItemResult` / `EvalScoreResult` | MEAI `EvaluationResult` / `EvaluationMetric` (reused) |
-| `LocalEvaluator` | `LocalEvaluator` (implements `IAgentEvaluator`) |
-| `@evaluator` | `FunctionEvaluator.Create()` overloads |
-| `keyword_check()` / `tool_called_check()` | `EvalChecks.KeywordCheck()` / `EvalChecks.ToolCalledCheck()` |
-| `tool_calls_present` / `tool_call_args_match` | (custom `FunctionEvaluator` — same pattern) |
-| `ExpectedToolCall` dataclass | `ExpectedToolCall` record |
-| `FoundryEvals` | `FoundryEvals` (implements `IAgentEvaluator`, includes evaluator name constants) |
-| `evaluate_agent()` | `agent.EvaluateAsync(queries, evaluator)` extension method |
-| `evaluate_agent(responses=)` | `agent.EvaluateAsync(responses, evaluator)` extension method |
-| `evaluate_workflow()` | `run.EvaluateAsync()` extension method |
-
-## More Information
-
-- [Foundry Evals documentation](https://learn.microsoft.com/azure/ai-foundry/concepts/evaluation-approach-gen-ai) — Azure AI Foundry evaluation overview

docs/decisions/0021-agent-skills-design.md

@@ -1,960 +0,0 @@
-status: proposed
-date: 2026-03-23
-contact: sergeymenshykh
-deciders: rbarreto, westey-m, eavanvalkenburg
----
-
-# Agent Skills: Multi-Source Architecture
-
-## Context and Problem Statement
-
-The Agent Framework needs a skills system that lets agents discover and use domain-specific knowledge, reference documents, and executable scripts. Skills can originate from different sources — filesystem directories (SKILL.md files), inline C# code, or reusable class libraries — and the framework must support all three uniformly while allowing extensibility, composition, and filtering.
-
-## Decision Drivers
-
-- Skills must be definable from multiple sources: filesystem, inline code, reusable classes, etc
-- Common abstractions are needed so the provider and builder work uniformly regardless of skill origin
-- File-based scripts must support user-defined executors, enabling custom runtimes and languages; code/class-based scripts execute in-process as C# delegates
-- Skills must be filterable so consumers can include or exclude specific skills based on defined criteria
-- Multiple skill sources must be composable into a single provider
-- It must be possible to add custom skill sources (e.g., databases, REST APIs, package registries) by implementing a common abstraction
-
-## Architecture
-
-### Model-Facing Tools
-
-Skills are presented to the model as up to three tools that progressively disclose skill content. The system prompt lists available skill names and descriptions; the model then calls these tools on demand:
-
-- **`load_skill(skillName)`** — returns the full skill body (instructions, listed resources, listed scripts)
-- **`read_skill_resource(skillName, resourceName)`** — reads a supplementary resource (file-based or code-defined) associated with a skill
-- **`run_skill_script(skillName, scriptName, arguments?)`** — executes a script associated with a skill; only registered when at least one skill contains scripts
-
-Each tool delegates to the corresponding method on the resolved `AgentSkill` — calling `Resource.ReadAsync()` or `Script.RunAsync()` respectively.
-
-If skills have no scripts defined, the `run_skill_script` tool is **not advertised** to the model and instructions related to script execution are **not included** in the default skills instructions.
-
-### Abstract Base Types
-
-The architecture defines four abstract base types that all skill variants implement:
-
-```csharp
-public abstract class AgentSkill
-{
-    public abstract AgentSkillFrontmatter Frontmatter { get; }
-    public abstract string Content { get; }
-    public abstract IReadOnlyList<AgentSkillResource>? Resources { get; }
-    public abstract IReadOnlyList<AgentSkillScript>? Scripts { get; }
-}
-
-public abstract class AgentSkillResource
-{
-    public string Name { get; }
-    public string? Description { get; }
-    public abstract Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default);
-}
-
-public abstract class AgentSkillScript
-{
-    public string Name { get; }
-    public string? Description { get; }
-    public abstract Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, CancellationToken cancellationToken = default);
-}
-
-public abstract class AgentSkillsSource
-{
-    public abstract Task<IList<AgentSkill>> GetSkillsAsync(CancellationToken cancellationToken = default);
-}
-```
-
-Skill metadata is captured via `AgentSkillFrontmatter`:
-
-```csharp
-public sealed class AgentSkillFrontmatter
-{
-    public AgentSkillFrontmatter(string name, string description) { ... }
-
-    public string Name { get; }
-    public string Description { get; }
-    public string? License { get; set; }
-    public string? Compatibility { get; set; }
-    public string? AllowedTools { get; set; }
-    public AdditionalPropertiesDictionary? Metadata { get; set; }
-}
-```
-
-The type hierarchy at a glance:
-
-```
-AgentSkill (abstract)                   AgentSkillsSource (abstract)
-├── AgentFileSkill                      ├── AgentFileSkillsSource          (public)
-└── [Programmatic]                      ├── AgentInMemorySkillsSource      (public)
-    ├── AgentInlineSkill                ├── AggregatingAgentSkillsSource     (public)
-    └── AgentClassSkill (abstract)      └── DelegatingAgentSkillsSource    (abstract, public)
-                                            ├── FilteringAgentSkillsSource  (public)
-AgentSkillResource (abstract)               ├── CachingAgentSkillsSource    (public)
-├── AgentFileSkillResource                  └── DeduplicatingAgentSkillsSource (public)
-└── AgentInlineSkillResource
-                                        AgentSkillScript (abstract)
-                                        ├── AgentFileSkillScript
-                                        └── AgentInlineSkillScript
-```
-
-There are two top-level categories of skills:
-
-1. **File-Based Skills** — discovered from `SKILL.md` files on the filesystem. Resources and scripts are files in subdirectories.
-2. **Programmatic Skills** — defined in C# code. These are further divided into:
-   - **Inline Skills** — built at runtime via the `AgentInlineSkill` class and its fluent API. Ideal for quick, agent-specific skill definitions.
-   - **Class-Based Skills** — defined as reusable C# classes that subclass `AgentClassSkill`. Ideal for packaging skills as shared libraries or NuGet packages.
-
-Both programmatic skill types use `AgentInlineSkillResource` and `AgentInlineSkillScript` for their resources and scripts. They are typically served by `AgentInMemorySkillsSource`, which accepts any `AgentSkill` and is not limited to programmatic skills.
-
-### File-Based Skills
-
-File-based skills are authored as `SKILL.md` files on disk. Resources and scripts are discovered from corresponding subfolders within the skill directory.
-
-**`AgentFileSkill`** — A filesystem-based skill discovered from a directory containing a `SKILL.md` file. Parsed from YAML frontmatter; content is the raw markdown body. Resources and scripts are discovered from files in corresponding subfolders:
-
-```csharp
-public sealed class AgentFileSkill : AgentSkill
-{
-    internal AgentFileSkill(
-        AgentSkillFrontmatter frontmatter, string content, string path,
-        IReadOnlyList<AgentSkillResource>? resources = null,
-        IReadOnlyList<AgentSkillScript>? scripts = null) { ... }
-}
-```
-
-**`AgentFileSkillResource`** — A file-based skill resource. Reads content from a file on disk relative to the skill directory:
-
-```csharp
-internal sealed class AgentFileSkillResource : AgentSkillResource
-{
-    public AgentFileSkillResource(string name, string fullPath) { ... }
-
-    public string FullPath { get; }
-
-    public override Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default)
-    {
-        return File.ReadAllTextAsync(FullPath, Encoding.UTF8, cancellationToken);
-    }
-}
-```
-
-**`AgentFileSkillScript`** — A file-based skill script that represents a script file on disk. Delegates execution to an external `AgentFileSkillScriptRunner` callback (e.g., runs Python/shell via `Process.Start`). Throws `NotSupportedException` if no executor is configured:
-
-```csharp
-public delegate Task<object?> AgentFileSkillScriptRunner(
-    AgentFileSkill skill, AgentFileSkillScript script,
-    AIFunctionArguments arguments, CancellationToken cancellationToken);
-
-public sealed class AgentFileSkillScript : AgentSkillScript
-{
-    private readonly AgentFileSkillScriptRunner _executor;
-
-    internal AgentFileSkillScript(string name, string fullPath, AgentFileSkillScriptRunner executor)
-        : base(name) { ... }
-
-    public override async Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, ...)
-    {
-
-        return await _executor(fileSkill, this, arguments, cancellationToken);
-    }
-}
-```
-
-The executor can be provided at the **provider level** via `AgentSkillsProviderBuilder.UseFileScriptRunner(executor)` and optionally overridden for a **particular file skill** or for a **set of skills** at the file skill source level, giving fine-grained control over how different scripts are executed.
-
-**`AgentFileSkillsSource`** — A skill source that discovers skills from filesystem directories containing `SKILL.md` files. Recursively scans directories (max 2 levels), validates frontmatter, and enforces path traversal and symlink security checks:
-
-```csharp
-public sealed partial class AgentFileSkillsSource : AgentSkillsSource
-{
-    public AgentFileSkillsSource(
-        IEnumerable<string> skillPaths,
-        AgentFileSkillScriptRunner scriptRunner,
-        AgentFileSkillsSourceOptions? options = null,
-        ILoggerFactory? loggerFactory = null) { ... }
-}
-```
-
-**`AgentFileSkillsSourceOptions`** — Configuration options for `AgentFileSkillsSource`. Allows customizing the allowed file extensions for resources and scripts without adding constructor parameters:
-
-```csharp
-public sealed class AgentFileSkillsSourceOptions
-{
-    public IEnumerable<string>? AllowedResourceExtensions { get; set; }
-    public IEnumerable<string>? AllowedScriptExtensions { get; set; }
-}
-```
-
-**Example** — A file-based skill on disk and how it is added to a source:
-
-```
-skills/
-└── unit-converter/
-    ├── SKILL.md               # frontmatter + instructions
-    ├── resources/
-    │   └── conversion-table.csv   # discovered as a resource
-    └── scripts/
-        └── convert.py             # discovered as a script
-```
-
-```csharp
-var source = new AgentFileSkillsSource(skillPaths: ["./skills"], scriptRunner: SubprocessScriptRunner.RunAsync);
-
-var provider = new AgentSkillsProvider(source);
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-### Programmatic Skills
-
-Programmatic skills are defined in C# code rather than discovered from the filesystem. There are two kinds: **inline** and **class-based**. Both use `AgentInlineSkillResource` and `AgentInlineSkillScript` for resources and scripts, and are held by a single `AgentInMemorySkillsSource`.
-
-**`AgentInMemorySkillsSource`** — A general-purpose skill source that holds any `AgentSkill` instances in memory. Although commonly used for programmatic skills (`AgentInlineSkill` and `AgentClassSkill`), it accepts any `AgentSkill` subclass and is not restricted to code-defined skills:
-
-```csharp
-public sealed class AgentInMemorySkillsSource : AgentSkillsSource
-{
-    public AgentInMemorySkillsSource(
-        IEnumerable<AgentSkill> skills,
-        ILoggerFactory? loggerFactory = null) { ... }
-}
-```
-
-#### Inline Skills
-
-Inline skills are built at runtime via the `AgentInlineSkill` class and its fluent API. They are ideal for quick, agent-specific skill definitions where a full class hierarchy would be overkill.
-
-**`AgentInlineSkill`** — A skill defined entirely in code. Resources can be static values or functions; scripts are always functions. Constructed with name, description, and instructions, then extended with resources and scripts:
-
-```csharp
-public sealed class AgentInlineSkill : AgentSkill
-{
-    public AgentInlineSkill(string name, string description, string instructions, string? license = null, string? compatibility = null, ...) { ... }
-    public AgentInlineSkill(AgentSkillFrontmatter frontmatter, string instructions) { ... }
-
-    public AgentInlineSkill AddResource(object value, string name, string? description = null);
-    public AgentInlineSkill AddResource(Delegate handler, string name, string? description = null);
-    public AgentInlineSkill AddScript(Delegate handler, string name, string? description = null);
-}
-```
-
-**`AgentInlineSkillResource`** — A skill resource that wraps a static value:
-
-```csharp
-public sealed class AgentInlineSkillResource : AgentSkillResource
-{
-    public AgentInlineSkillResource(object value, string name, string? description = null)
-        : base(name, description)
-    {
-        _value = value;
-    }
-
-    public override Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default)
-    {
-        return Task.FromResult<object?>(_value);
-    }
-}
-```
-
-**`AgentInlineSkillResource`** — A skill resource backed by a delegate. The delegate is invoked via an `AIFunction` each time `ReadAsync` is called, producing a dynamic (computed) value:
-
-```csharp
-public sealed class AgentInlineSkillResource : AgentSkillResource
-{
-    public AgentInlineSkillResource(Delegate handler, string name, string? description = null)
-        : base(name, description)
-    {
-        _function = AIFunctionFactory.Create(handler, name: name);
-    }
-
-    public override async Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default)
-    {
-        return await _function.InvokeAsync(new AIFunctionArguments() { Services = serviceProvider }, cancellationToken);
-    }
-}
-```
-
-**`AgentInlineSkillScript`** — A skill script backed by a delegate via an `AIFunction`:
-
-```csharp
-public sealed class AgentInlineSkillScript : AgentSkillScript
-{
-    private readonly AIFunction _function;
-
-    public AgentInlineSkillScript(Delegate handler, string name, string? description = null)
-        : base(name, description)
-    {
-        _function = AIFunctionFactory.Create(handler, name: name);
-    }
-
-    public JsonElement? ParametersSchema => _function.JsonSchema;
-
-    public override async Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, ...)
-    {
-        return await _function.InvokeAsync(arguments, cancellationToken);
-    }
-}
-```
-
-**Example** — Creating an inline skill with a resource and script, then adding it to a source:
-
-```csharp
-var skill = new AgentInlineSkill(
-        name: "unit-converter",
-        description: "Converts between measurement units.",
-        instructions: """
-            Use this skill to convert values between metric and imperial units.
-            Refer to the conversion-table resource for supported unit pairs.
-            Run the convert script to perform conversions.
-            """
-    )
-    .AddResource("kg=2.205lb, m=3.281ft, L=0.264gal", "conversion-table", "Supported unit pairs")
-    .AddScript(Convert, "convert", "Converts a value between units");
-
-var source = new AgentInMemorySkillsSource([skill]);
-
-var provider = new AgentSkillsProvider(source);
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-
-static string Convert(double value, double factor)
-    => JsonSerializer.Serialize(new { result = Math.Round(value * factor, 4) });
-```
-
-#### Class-Based Skills
-
-Class-based skills are designed for packaging skills as reusable libraries. Users subclass `AgentClassSkill` and override properties. Unlike inline skills, class-based skills are self-contained, can live in shared libraries or NuGet packages, and are well-suited for dependency injection.
-
-**`AgentClassSkill`** — An abstract base class for defining skills as reusable C# classes that bundle all skill components (frontmatter, instructions, resources, scripts) together. Designed for packaging skills as distributable libraries:
-
-```csharp
-public abstract class AgentClassSkill : AgentSkill
-{
-    public abstract string Instructions { get; }
-
-    // Content is auto-synthesized from Frontmatter + Instructions + Resources + Scripts
-    public override string Content =>
-        SkillContentBuilder.BuildContent(Frontmatter.Name, Frontmatter.Description,
-            SkillContentBuilder.BuildBody(Instructions, Resources, Scripts));
-}
-```
-
-**Example** — Defining a class-based skill and adding it to a source:
-
-```csharp
-public class UnitConverterSkill : AgentClassSkill
-{
-    public override AgentSkillFrontmatter Frontmatter { get; } =
-        new("unit-converter", "Converts between measurement units.");
-
-    public override string Instructions => """
-        Use this skill to convert values between metric and imperial units.
-        Refer to the conversion-table resource for supported unit pairs.
-        Run the convert script to perform conversions.
-        """;
-
-    public override IReadOnlyList<AgentSkillResource>? Resources { get; } =
-    [
-        new AgentInlineSkillResource("kg=2.205lb, m=3.281ft", "conversion-table"),
-    ];
-
-    public override IReadOnlyList<AgentSkillScript>? Scripts { get; } =
-    [
-        new AgentInlineSkillScript(Convert, "convert"),
-    ];
-
-    private static string Convert(double value, double factor)
-        => JsonSerializer.Serialize(new { result = Math.Round(value * factor, 4) });
-}
-
-var source = new AgentInMemorySkillsSource([new UnitConverterSkill()]);
-
-var provider = new AgentSkillsProvider(source);
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-## Filtering, Caching, and Deduplication
-
-The following subsections present alternative approaches for handling filtering, caching, and deduplication of skills across multiple sources.
-
-### Via Composition
-
-In this approach, the `AgentSkillsProvider` accepts a **single** `AgentSkillsSource`. Multiple sources are composed externally via an aggregate source, and cross-cutting concerns like filtering, caching, and deduplication are implemented as **source decorators** — subclasses of `DelegatingAgentSkillsSource` that intercept `GetSkillsAsync()`.
-
-**`FilteringAgentSkillsSource`** — A decorator that applies filter logic before returning results. The decorator pattern keeps filtering orthogonal to source implementations and allows composing multiple filters:
-
-```csharp
-public sealed class FilteringAgentSkillsSource : DelegatingAgentSkillsSource
-{
-    private readonly Func<AgentSkill, bool> _predicate;
-
-    public FilteringAgentSkillsSource(AgentSkillsSource innerSource, Func<AgentSkill, bool> predicate)
-        : base(innerSource)
-    {
-        _predicate = predicate;
-    }
-
-    public override async Task<IList<AgentSkill>> GetSkillsAsync(CancellationToken cancellationToken = default)
-    {
-        var skills = await this.InnerSource.GetSkillsAsync(cancellationToken);
-        return skills.Where(_predicate).ToList();
-    }
-}
-```
-
-**`CachingAgentSkillsSource`** — A decorator that caches skills after the first load, keeping the provider stateless and giving consumers control over caching granularity per source. For example, file-based skills (expensive to discover) can be cached while code-defined skills remain uncached:
-
-```csharp
-public sealed class CachingAgentSkillsSource : DelegatingAgentSkillsSource
-{
-    private IList<AgentSkill>? _cached;
-
-    public CachingAgentSkillsSource(AgentSkillsSource innerSource)
-        : base(innerSource)
-    {
-    }
-
-    public override async Task<IList<AgentSkill>> GetSkillsAsync(CancellationToken cancellationToken = default)
-    {
-        return _cached ??= await this.InnerSource.GetSkillsAsync(cancellationToken);
-    }
-}
-```
-
-**Deduplication** is similarly implemented as a decorator (`DeduplicatingAgentSkillsSource`) that deduplicates by name (case-insensitive, first-one-wins) and logs a warning for skipped duplicates.
-
-**Example** — Combining file-based and code-defined sources with filtering and caching:
-
-```csharp
-var fileSource = new CachingAgentSkillsSource(new AgentFileSkillsSource(["./skills"]));
-var codeSource = new AgentInMemorySkillsSource([myCodeSkill]);
-
-var compositeSource = new FilteringAgentSkillsSource(
-    new AggregatingAgentSkillsSource([fileSource, codeSource]),
-    filter: s => s.Frontmatter.Name != "internal");
-
-var provider = new AgentSkillsProvider(compositeSource);
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-**Pros:**
-- Clean single-responsibility: the provider serves skills, sources provide them.
-- Caching, filtering, and deduplication are composable as source decorators — each concern is a separate, testable wrapper.
-
-**Cons:**
-- DI is less flexible: multiple `AgentSkillsSource` implementations registered in the container cannot be auto-injected into the provider. The consumer must manually compose them via an aggregate source.
-- Increased public API surface: requires additional public classes (aggregate source, caching decorators, filtering decorators) that consumers need to learn and use.
-
-### Via AgentSkillsProvider
-
-In this approach, the `AgentSkillsProvider` accepts **`IEnumerable<AgentSkillsSource>`** and handles aggregation, filtering, caching, and deduplication internally.
-
-The provider aggregates skills from all registered sources, deduplicates by name (case-insensitive, first-one-wins), caches the result after the first load, and optionally applies filtering via a predicate on `AgentSkillsProviderOptions`. Duplicate skill names are logged as warnings.
-
-**Example** — Registering multiple sources directly with the provider:
-
-```csharp
-// Conceptual example — in practice, use AgentSkillsProviderBuilder
-var fileSource = new AgentFileSkillsSource(["./skills"]);
-var codeSource = new AgentInMemorySkillsSource([myCodeSkill]);
-
-var provider = new AgentSkillsProvider(
-    sources: [fileSource, codeSource],
-    options: new AgentSkillsProviderOptions
-    {
-        Filter = s => s.Frontmatter.Name != "internal",
-    });
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-**Pros:**
-- DI-friendly: register multiple `AgentSkillsSource` implementations in the container, and they are all auto-injected into `AgentSkillsProvider` via `IEnumerable<AgentSkillsSource>`.
-- Smaller public API surface: no need for aggregate source, caching decorators, or filtering decorator classes — these concerns are handled internally by the provider.
-
-**Cons:**
-- The provider takes on multiple responsibilities — aggregation, caching, deduplication, and filtering.
-- Less granular caching control: caching is all-or-nothing across sources rather than per-source as with decorators.
-- Less extensible: new behaviors (e.g., ordering, TTL expiration) require modifying the provider rather than adding a decorator.
-
-### Builder Pattern
-
-**`AgentSkillsProviderBuilder`** provides a fluent API for composing skills from multiple sources. The builder centralizes configuration — script executors, approval callbacks, prompt templates, and filtering — so consumers don't need to know the underlying source types.
-
-The builder internally decides how to wire up the object graph: it creates the appropriate source instances, applies caching and filtering, and returns a fully configured `AgentSkillsProvider`. This keeps the setup code concise while still allowing fine-grained control when needed.
-
-**Example** — Using the builder to combine multiple source types with configuration:
-
-```csharp
-var provider = new AgentSkillsProviderBuilder()
-    .UseFileSkill("./skills")                           // file-based source
-    .UseInlineSkills(codeSkill)                            // code-defined source
-    .UseClassSkills(new ClassSkill())                    // class-based source
-    .UseFileScriptRunner(SubprocessScriptRunner.RunAsync) // script runner
-    .UseScriptApproval()                                // optional human-in-the-loop
-    .UsePromptTemplate(customTemplate)                  // optional prompt customization
-    .UseFilter(s => s.Frontmatter.Name != "internal")   // optional skill filtering
-    .Build();
-
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
-{
-    AIContextProviders = [provider],
-});
-```
-
-## Adding a Custom Skill Type
-
-The skills framework is designed for extensibility. While file-based and inline skills cover common
-scenarios, you can introduce entirely new skill types by subclassing the four base classes:
-
-| Base class            | Purpose                                             |
-|-----------------------|-----------------------------------------------------|
-| `AgentSkillsSource`   | Discovers and loads skills from a particular origin  |
-| `AgentSkill`          | Holds metadata, content, resources, and scripts      |
-| `AgentSkillResource`  | Provides supplementary content to a skill            |
-| `AgentSkillScript`    | Represents an executable action within a skill       |
-
-The example below implements a **cloud-based skill type** where skills, resources, and scripts are
-all stored in and executed through a remote cloud service (e.g., Azure Blob Storage + Azure Functions).
-
-### Step 1 — Define a custom resource
-
-A `CloudSkillResource` reads resource content from a cloud storage endpoint instead of the local
-filesystem:
-
-```csharp
-/// <summary>
-/// A skill resource backed by a cloud storage endpoint.
-/// </summary>
-public sealed class CloudSkillResource : AgentSkillResource
-{
-    private readonly HttpClient _httpClient;
-
-    public CloudSkillResource(string name, Uri blobUri, HttpClient httpClient, string? description = null)
-        : base(name, description)
-    {
-        BlobUri = blobUri ?? throw new ArgumentNullException(nameof(blobUri));
-        _httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
-    }
-
-    /// <summary>
-    /// Gets the URI of the cloud blob that holds this resource's content.
-    /// </summary>
-    public Uri BlobUri { get; }
-
-    /// <inheritdoc/>
-    public override async Task<object?> ReadAsync(
-        IServiceProvider? serviceProvider = null,
-        CancellationToken cancellationToken = default)
-    {
-        return await _httpClient.GetStringAsync(BlobUri, cancellationToken).ConfigureAwait(false);
-    }
-}
-```
-
-### Step 2 — Define a custom script
-
-A `CloudSkillScript` executes a script by calling a cloud function endpoint, passing arguments as
-the request body:
-
-```csharp
-/// <summary>
-/// A skill script executed via a cloud function endpoint.
-/// </summary>
-public sealed class CloudSkillScript : AgentSkillScript
-{
-    private readonly HttpClient _httpClient;
-
-    public CloudSkillScript(string name, Uri functionUri, HttpClient httpClient, string? description = null)
-        : base(name, description)
-    {
-        FunctionUri = functionUri ?? throw new ArgumentNullException(nameof(functionUri));
-        _httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
-    }
-
-    /// <summary>
-    /// Gets the URI of the cloud function that runs this script.
-    /// </summary>
-    public Uri FunctionUri { get; }
-
-    /// <inheritdoc/>
-    public override async Task<object?> RunAsync(
-        AgentSkill skill,
-        AIFunctionArguments arguments,
-        CancellationToken cancellationToken = default)
-    {
-        var json = JsonSerializer.Serialize(arguments);
-        using var content = new StringContent(json, Encoding.UTF8, "application/json");
-        var response = await _httpClient.PostAsync(FunctionUri, content, cancellationToken)
-            .ConfigureAwait(false);
-        response.EnsureSuccessStatusCode();
-        return await response.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
-    }
-}
-```
-
-### Step 3 — Define a custom skill
-
-A `CloudSkill` bundles cloud-specific metadata (e.g., the base endpoint) with the standard skill
-shape:
-
-```csharp
-/// <summary>
-/// An <see cref="AgentSkill"/> whose content, resources, and scripts are stored in a cloud service.
-/// </summary>
-public sealed class CloudSkill : AgentSkill
-{
-    public CloudSkill(
-        AgentSkillFrontmatter frontmatter,
-        string content,
-        Uri endpoint,
-        IReadOnlyList<AgentSkillResource>? resources = null,
-        IReadOnlyList<AgentSkillScript>? scripts = null)
-    {
-        Frontmatter = frontmatter ?? throw new ArgumentNullException(nameof(frontmatter));
-        Content = content ?? throw new ArgumentNullException(nameof(content));
-        Endpoint = endpoint ?? throw new ArgumentNullException(nameof(endpoint));
-        Resources = resources;
-        Scripts = scripts;
-    }
-
-    /// <inheritdoc/>
-    public override AgentSkillFrontmatter Frontmatter { get; }
-
-    /// <inheritdoc/>
-    public override string Content { get; }
-
-    /// <summary>
-    /// Gets the base cloud endpoint for this skill.
-    /// </summary>
-    public Uri Endpoint { get; }
-
-    /// <inheritdoc/>
-    public override IReadOnlyList<AgentSkillResource>? Resources { get; }
-
-    /// <inheritdoc/>
-    public override IReadOnlyList<AgentSkillScript>? Scripts { get; }
-}
-```
-
-### Step 4 — Define a custom source
-
-A `CloudSkillsSource` discovers skills from a cloud catalog API and constructs `CloudSkill`
-instances with their associated resources and scripts:
-
-```csharp
-/// <summary>
-/// A skill source that discovers and loads skills from a cloud catalog API.
-/// </summary>
-public sealed class CloudSkillsSource : AgentSkillsSource
-{
-    private readonly Uri _catalogUri;
-    private readonly HttpClient _httpClient;
-
-    public CloudSkillsSource(Uri catalogUri, HttpClient httpClient)
-    {
-        _catalogUri = catalogUri ?? throw new ArgumentNullException(nameof(catalogUri));
-        _httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
-    }
-
-    /// <inheritdoc/>
-    public override async Task<IList<AgentSkill>> GetSkillsAsync(
-        CancellationToken cancellationToken = default)
-    {
-        // Fetch the skill catalog from the cloud service.
-        var json = await _httpClient.GetStringAsync(_catalogUri, cancellationToken)
-            .ConfigureAwait(false);
-        var catalog = JsonSerializer.Deserialize<CloudSkillCatalog>(json)!;
-
-        var skills = new List<AgentSkill>();
-
-        foreach (var entry in catalog.Skills)
-        {
-            var frontmatter = new AgentSkillFrontmatter(entry.Name, entry.Description);
-
-            // Build cloud-backed resources.
-            var resources = entry.Resources
-                .Select(r => new CloudSkillResource(r.Name, r.BlobUri, _httpClient, r.Description))
-                .ToList<AgentSkillResource>();
-
-            // Build cloud-backed scripts.
-            var scripts = entry.Scripts
-                .Select(s => new CloudSkillScript(s.Name, s.FunctionUri, _httpClient, s.Description))
-                .ToList<AgentSkillScript>();
-
-            skills.Add(new CloudSkill(frontmatter, entry.Content, entry.Endpoint, resources, scripts));
-        }
-
-        return skills;
-    }
-}
-```
-
-### Step 5 — Register with the builder
-
-Use `UseSource` to wire the custom source into the provider:
-
-```csharp
-var httpClient = new HttpClient();
-
-var provider = new AgentSkillsProviderBuilder()
-    .UseSource(new CloudSkillsSource(
-        new Uri("https://my-service.example.com/skills/catalog"),
-        httpClient))
-    // Mix with other source types if needed:
-    .UseFileSkill("/local/skills", scriptRunner)
-    .UseInlineSkills(someInlineSkill)
-    .Build();
-```
-
-The `AgentSkillsProvider` handles all skill types uniformly — any combination of file-based, inline,
-class-based, and custom skills can coexist in the same provider. Custom skills automatically
-participate in the model-facing tools (`load_skill`, `read_skill_resource`, `run_skill_script`),
-filtering, deduplication, and caching — no additional integration work is required.
-
-## Script Representation: `AgentSkillScript` vs `AIFunction`
-
-Two approaches were considered for representing executable scripts within skills:
-
-### Option A — Custom `AgentSkillScript` abstract base class (original design)
-
-Scripts are modeled as a custom `AgentSkillScript` abstract class with `Name`, `Description`, and
-`RunAsync(AgentSkill, AIFunctionArguments, CancellationToken)`. Concrete implementations:
-`AgentInlineSkillScript` (wraps a delegate/`AIFunction`) and `AgentFileSkillScript` (wraps a file path + executor delegate).
-
-```csharp
-// Base type
-public abstract class AgentSkillScript
-{
-    public string Name { get; }
-    public string? Description { get; }
-    public abstract Task<object?> RunAsync(AgentSkill skill, AIFunctionArguments arguments, CancellationToken cancellationToken = default);
-}
-
-// AgentSkill exposes scripts as:
-public abstract IReadOnlyList<AgentSkillScript>? Scripts { get; }
-
-// Inline script wraps an AIFunction internally
-var script = new AgentInlineSkillScript(ConvertUnits, "convert");
-
-// Pre-built AIFunction must be wrapped
-var script = new AgentInlineSkillScript(myAIFunction);
-
-// Class-based skill declares scripts as:
-public override IReadOnlyList<AgentSkillScript>? Scripts { get; } =
-[
-    new AgentInlineSkillScript(ConvertUnits, "convert"),
-];
-
-// Provider executes scripts by passing the owning skill:
-await script.RunAsync(skill, arguments, cancellationToken);
-```
-
-**Pros:**
-
-- **Explicit skill context at execution time.** `RunAsync` receives the owning `AgentSkill`, so any script can access skill metadata or resources during execution without requiring construction-time wiring.
-- **Self-contained abstraction.** A dedicated type communicates clearly that scripts are a skills-framework concept, separate from general-purpose AI functions.
-- **Easier extensibility for custom script types.** Third-party implementations can subclass `AgentSkillScript` and access the owning skill in `RunAsync` without special setup.
-
-**Cons:**
-
-- **Wrapper overhead.** `AgentInlineSkillScript` is a thin pass-through around `AIFunction` — it adds a class, a constructor, and an indirection layer for no behavioral difference.
-- **Parallel abstraction.** `AgentSkillScript` and `AIFunction` serve overlapping purposes (named callable with arguments), creating two parallel hierarchies for the same concept.
-- **Friction for consumers.** Users who already have `AIFunction` instances must wrap them in `AgentInlineSkillScript` to use them as scripts, adding ceremony.
-
-### Option B — Reuse `AIFunction` directly
-
-Scripts are represented as `AIFunction` (from `Microsoft.Extensions.AI`). `AgentSkill.Scripts` returns
-`IReadOnlyList<AIFunction>?`. `AgentInlineSkillScript` is eliminated entirely — callers use
-`AIFunctionFactory.Create(delegate, name: ...)` or pass `AIFunction` instances directly.
-`AgentFileSkillScript` becomes an `AIFunction` subclass that captures its owning `AgentFileSkill` via
-an internal back-reference set during construction.
-
-```csharp
-// AgentSkill exposes scripts as AIFunction directly:
-public abstract IReadOnlyList<AIFunction>? Scripts { get; }
-
-// Inline scripts use AIFunctionFactory — no wrapper class needed
-var skill = new AgentInlineSkill("my-skill", "desc", "instructions");
-skill.AddScript(ConvertUnits, "convert");           // delegate
-skill.AddScript(myAIFunction);                       // pre-built AIFunction — no wrapping
-
-// Class-based skill declares scripts as:
-public override IReadOnlyList<AIFunction>? Scripts { get; } =
-[
-    AIFunctionFactory.Create(ConvertUnits, name: "convert"),
-];
-
-// Provider executes scripts via standard AIFunction invocation:
-await script.InvokeAsync(arguments, cancellationToken);
-
-// File-based scripts extend AIFunction and capture the owning skill internally:
-public sealed class AgentFileSkillScript : AIFunction
-{
-    internal AgentFileSkill? Skill { get; set; }   // set by AgentFileSkill constructor
-
-    protected override async ValueTask<object?> InvokeCoreAsync(
-        AIFunctionArguments arguments, CancellationToken cancellationToken)
-    {
-        return await _executor(Skill!, this, arguments, cancellationToken);
-    }
-}
-```
-
-**Pros:**
-
-- **Fewer types.** Eliminates `AgentSkillScript` and `AgentInlineSkillScript`, reducing the public API surface by two classes.
-- **Seamless interop.** Any `AIFunction` — whether from `AIFunctionFactory`, a custom subclass, or an external library — can be used as a skill script with zero wrapping.
-- **Consistent with `Microsoft.Extensions.AI` ecosystem.** Scripts share the same type as tool functions used by `IChatClient` and `FunctionInvokingChatClient`, reducing conceptual overhead for developers already familiar with the ecosystem.
-
-**Cons:**
-
-- **No owning-skill context in invocation signature.** `AIFunction.InvokeAsync` does not accept an `AgentSkill` parameter, so `AgentFileSkillScript` must capture its owning skill via an internal setter during construction. This adds a construction-order dependency: the skill must set the back-reference on its scripts.
-- **Custom script types lose automatic skill access.** Third-party `AIFunction` subclasses that need the owning skill must implement their own mechanism (e.g., constructor injection, closure capture) instead of receiving it as a method parameter.
-- **Semantic overloading.** `AIFunction` now means both "a tool the model can call" and "a script within a skill", which could blur the distinction for framework users.
-
-## Resource Representation: `AgentSkillResource` vs `AIFunction`
-
-Two approaches were considered for representing skill resources (supplementary content such as references, assets, or dynamic data):
-
-### Option A — Custom `AgentSkillResource` abstract base class (original design)
-
-Resources are modeled as a custom `AgentSkillResource` abstract class with `Name`, `Description`, and
-`ReadAsync(IServiceProvider?, CancellationToken)`. Concrete implementations:
-`AgentInlineSkillResource` (static value, delegate, or `AIFunction` wrapper) and `AgentFileSkillResource` (reads file content from disk).
-
-```csharp
-// Base type
-public abstract class AgentSkillResource
-{
-    public string Name { get; }
-    public string? Description { get; }
-    public abstract Task<object?> ReadAsync(IServiceProvider? serviceProvider = null, CancellationToken cancellationToken = default);
-}
-
-// AgentSkill exposes resources as:
-public abstract IReadOnlyList<AgentSkillResource>? Resources { get; }
-
-// Static resource
-var resource = new AgentInlineSkillResource("static content", "my-resource");
-
-// Dynamic resource (delegate)
-var resource = new AgentInlineSkillResource((IServiceProvider sp) => GetData(sp), "my-resource");
-
-// Pre-built AIFunction must be wrapped
-var resource = new AgentInlineSkillResource(myAIFunction);
-
-// Class-based skill declares resources as:
-public override IReadOnlyList<AgentSkillResource>? Resources { get; } =
-[
-    new AgentInlineSkillResource("# Conversion Tables\n...", "conversion-table"),
-];
-
-// Provider reads resources via:
-await resource.ReadAsync(serviceProvider, cancellationToken);
-```
-
-**Pros:**
-
-- **Clear semantic distinction.** A dedicated `AgentSkillResource` type distinguishes resources (data providers) from scripts (executable actions), making the API self-documenting.
-- **Purpose-built API.** `ReadAsync` communicates intent better than `InvokeAsync` for a data-access operation.
-
-**Cons:**
-
-- **Wrapper overhead.** `AgentInlineSkillResource` wraps `AIFunction` internally for delegate/function cases — adding a class and indirection for no behavioral difference.
-- **Parallel abstraction.** `AgentSkillResource` and `AIFunction` serve overlapping purposes (named callable that returns data), creating two parallel hierarchies.
-- **Friction for consumers.** Users who already have `AIFunction` instances must wrap them in `AgentInlineSkillResource`, adding ceremony.
-
-### Option B — Reuse `AIFunction` directly
-
-Resources are represented as `AIFunction`. `AgentSkill.Resources` returns `IReadOnlyList<AIFunction>?`.
-`AgentInlineSkillResource` becomes an `AIFunction` subclass (retained as a convenience for the static-value
-pattern: `new AgentInlineSkillResource("data", "name")`). `AgentFileSkillResource` becomes an `AIFunction`
-subclass that reads file content.
-
-```csharp
-// AgentSkill exposes resources as AIFunction directly:
-public abstract IReadOnlyList<AIFunction>? Resources { get; }
-
-// Static resource — AgentInlineSkillResource is retained as a convenience AIFunction subclass
-var resource = new AgentInlineSkillResource("static content", "my-resource");
-
-// Dynamic resource — AgentInlineSkillResource wraps delegate as AIFunction
-var resource = new AgentInlineSkillResource((IServiceProvider sp) => GetData(sp), "my-resource");
-
-// Pre-built AIFunction can be used directly — no wrapping needed
-skill.AddResource(myAIFunction);
-
-// Class-based skill declares resources as:
-public override IReadOnlyList<AIFunction>? Resources { get; } =
-[
-    new AgentInlineSkillResource("# Conversion Tables\n...", "conversion-table"),
-];
-
-// Provider reads resources via standard AIFunction invocation:
-await resource.InvokeAsync(arguments, cancellationToken);
-
-// File-based resources extend AIFunction directly:
-internal sealed class AgentFileSkillResource : AIFunction
-{
-    public string FullPath { get; }
-
-    protected override async ValueTask<object?> InvokeCoreAsync(
-        AIFunctionArguments arguments, CancellationToken cancellationToken)
-    {
-        return await File.ReadAllTextAsync(FullPath, Encoding.UTF8, cancellationToken);
-    }
-}
-```
-
-**Pros:**
-
-- **Fewer base types.** Eliminates the `AgentSkillResource` abstract class, reducing the public API surface.
-- **Seamless interop.** Any `AIFunction` can be used as a skill resource with zero wrapping.
-
-**Cons:**
-
-- **Loss of semantic distinction.** Resources and scripts are now both `AIFunction`, which could make it less obvious which list a function belongs to when reading code.
-- **Static values require a wrapper.** Unlike the original `ReadAsync` which could return a stored value directly, `AIFunction.InvokeAsync` implies invocation. `AgentInlineSkillResource` is retained as a convenience subclass to handle the static-value case, so this is not eliminated — just moved to a different class.
-
-## Decision Outcome
-
-### 1. Keep `AgentSkillResource` and `AgentSkillScript` (Option A for both sections)
-
-We are staying with the custom `AgentSkillResource` and `AgentSkillScript` model classes instead of reusing `AIFunction`:
-
-- **Resources have no parameters.** If a consumer provides an `AIFunction` with parameters, those parameters will never be advertised to the LLM, and the resulting call will fail.
-- **Approval breaks for `AIFunction`-based representations.** When a resource or script represented by an `AIFunction` is configured with approval, the second approval invocation will not work correctly.
-- **Injecting the owning skill into an `AIFunction`-based script is problematic.** Constructor injection would introduce a circular reference between the skill and the script. An internal property setter is possible but adds coupling.
-
-### 2. Make all agent skill classes internal
-
-All agent-skill-related classes are made `internal` to minimize the public API surface while the feature matures. We can reconsider and promote types to `public` later based on community signal.
-
-This leaves two public entry points:
-
-- **`AgentSkillsProvider`** — use directly when all skills come from a single source and filtering is not needed.
-- **`AgentSkillsProviderBuilder`** — use when mixing skill types or when filtering support is required.
-
-### 3. Caching at provider level
-
-Caching of tools and instructions is implemented inside `AgentSkillsProvider` rather than as an external decorator. Recreating tools and instructions on every provider call is wasteful, and a caching decorator sitting outside the provider would not have the information needed to cache them effectively.

docs/decisions/0021-provider-leading-clients.md

@@ -1,72 +0,0 @@
----
-status: accepted
-contact: eavanvalkenburg
-date: 2026-03-20
-deciders: eavanvalkenburg, sphenry, chetantoshnival
-consulted: taochenosu, moonbox3, dmytrostruk, giles17, alliscode
----
-
-# Provider-Leading Client Design & OpenAI Package Extraction
-
-## Context and Problem Statement
-
-The `agent-framework-core` package currently bundles OpenAI and Azure OpenAI client implementations along with their dependencies (`openai`, `azure-identity`, `azure-ai-projects`, `packaging`). This makes core heavier than necessary for users who don't use OpenAI, and it conflates the core abstractions with a specific provider implementation. Additionally, the current class naming (`OpenAIResponsesClient`, `OpenAIChatClient`) is based on the underlying OpenAI API names rather than what users actually want to do, making discoverability harder for newcomers.
-
-## Decision Drivers
-
-- **Lightweight core**: Core should only contain abstractions, middleware infrastructure, and telemetry — no provider-specific code or dependencies.
-- **Discoverability-first**: Import namespaces should guide users to the right client. `from agent_framework.openai import ...` should surface all OpenAI-related clients; `from agent_framework.azure import ...` should surface Foundry, Azure AI, and other Azure-specific classes.
-- **Provider-leading naming**: The primary client name should reflect the provider, not the underlying API. The Responses API is now the recommended default for OpenAI, so its client should be called `OpenAIChatClient` (not `OpenAIResponsesClient`).
-- **Clean separation of concerns**: Azure-specific deprecated wrappers belong in the azure-ai package, not in the OpenAI package.
-
-## Considered Options
-
-- **Keep OpenAI in core**: Simpler but keeps core heavy; doesn't help discoverability.
-- **Extract OpenAI with Azure wrappers in the OpenAI package**: Keeps Azure OpenAI wrappers alongside OpenAI code, but pollutes the OpenAI package with Azure concerns.
-- **Extract OpenAI, place Azure wrappers in azure-ai**: Clean separation; the OpenAI package has zero Azure dependencies; deprecated Azure wrappers live in a single file in azure-ai for easy future deletion.
-
-## Decision Outcome
-
-Chosen option: "Extract OpenAI, place Azure wrappers in azure-ai", because it achieves the lightest core, cleanest OpenAI package, and the most maintainable deprecation path.
-
-Key changes:
-
-1. **New `agent-framework-openai` package** with dependencies on `agent-framework-core`, `openai`, and `packaging` only.
-2. **Class renames**: `OpenAIResponsesClient` → `OpenAIChatClient` (Responses API), `OpenAIChatClient` → `OpenAIChatCompletionClient` (Chat Completions API). Old names remain as deprecated aliases.
-3. **Deprecated classes**: `OpenAIAssistantsClient`, all `AzureOpenAI*Client` classes, `AzureAIClient`, `AzureAIAgentClient`, and `AzureAIProjectAgentProvider` are marked deprecated.
-4. **New `FoundryChatClient`** in azure-ai for Azure AI Foundry Responses API access, built on `RawFoundryChatClient(RawOpenAIChatClient)`.
-5. **All deprecated `AzureOpenAI*` classes** consolidated into a single file (`_deprecated_azure_openai.py`) in the azure-ai package for clean future deletion.
-6. **Core's `agent_framework.openai` and `agent_framework.azure` namespaces** become lazy-loading gateways, preserving backward-compatible import paths while removing hard dependencies.
-7. **Unified `model` parameter** replaces `model_id` (OpenAI), `deployment_name` (Azure OpenAI), and `model_deployment_name` (Azure AI) across all client constructors. The term `model` is intentionally generic: it naturally maps to an OpenAI model name *and* to an Azure OpenAI deployment name, making it straightforward to use `OpenAIChatClient` with either OpenAI or Azure OpenAI backends (via `AsyncAzureOpenAI`). Environment variables are similarly unified (e.g., `OPENAI_MODEL` instead of separate `OPENAI_RESPONSES_MODEL_ID` / `OPENAI_CHAT_MODEL_ID`).
-8. **`FoundryAgent`** replaces the pattern of `Agent(client=AzureAIClient(...))` for connecting to pre-configured agents in Azure AI Foundry (PromptAgents and HostedAgents). The underlying `RawFoundryAgentChatClient` is an implementation detail — most users interact only with `FoundryAgent`. `AzureAIAgentClient` is separately deprecated as it refers to the V1 Agents Service API. See below for design rationale.
-
-### Foundry Agent Design: `FoundryAgentClient` vs `FoundryAgent`
-
-The existing `AzureAIClient` combines two concerns: CRUD lifecycle management (creating/deleting agents on the service) and runtime communication (sending messages via the Responses API). The new design removes CRUD entirely — users connect to agents that already exist in Foundry.
-
-**Two approaches were considered:**
-
-**Option A — `FoundryAgentClient` only (public ChatClient):**
-Users compose `Agent(client=FoundryAgentClient(...), tools=[...])`. This follows the universal `Agent(client=X)` pattern used by every other provider. However, a "client" that wraps a named remote agent (with `agent_name` as a constructor param) is semantically odd — clients typically wrap a model endpoint, not a specific agent.
-
-**Option B — `FoundryAgent` (Agent subclass) + private `_FoundryAgentChatClient` and public `RawFoundryAgentChatClient`:**
-Users write `FoundryAgent(agent_name="my-agent", ...)` for the common case. Internally, `FoundryAgent` creates a `_FoundryAgentChatClient` and passes it to the standard `Agent` base class. For advanced customization, users pass `client_type=RawFoundryAgentChatClient` (or a custom subclass) to control the client middleware layers. The `Agent(client=RawFoundryAgentChatClient(...))` composition pattern still works for users who prefer it.
-
-**Chosen option: Option B**, because:
-- The common case (`FoundryAgent(...)`) is a single object with no boilerplate.
-- `client_type=` gives full control over client middleware without parameter duplication — the agent forwards connection params to the client internally.
-- `RawFoundryAgent(RawAgent)` and `FoundryAgent(Agent)` mirror the established `RawAgent`/`Agent` pattern.
-- Runtime validation (only `FunctionTool` allowed) lives in `RawFoundryAgentChatClient._prepare_options`, ensuring it applies regardless of how the client is used — through `FoundryAgent`, `Agent(client=...)`, or any custom composition.
-
-**Public classes:**
-- `RawFoundryAgentChatClient(RawOpenAIChatClient)` — Responses API client that injects agent reference and validates tools. Extension point for custom client middleware.
-- `RawFoundryAgent(RawAgent)` — Agent without agent-level middleware/telemetry.
-- `FoundryAgent(AgentTelemetryLayer, AgentMiddlewareLayer, RawFoundryAgent)` — Recommended production agent.
-
-**Internal (private):**
-- `_FoundryAgentChatClient` — Full client with function invocation, chat middleware, and telemetry layers. Created automatically by `FoundryAgent`; users customize via `client_type=RawFoundryAgentChatClient` or a custom subclass.
-
-**Deprecated:**
-- `AzureAIClient` — replaced by `FoundryAgent` (which uses `FoundryAgentClient` internally).
-- `AzureAIAgentClient` — refers to V1 Agents Service API, no direct replacement.
-- `AzureAIProjectAgentProvider` — replaced by `FoundryAgent`.

docs/decisions/0022-chat-history-persistence-consistency.md

@@ -1,116 +0,0 @@
----
-status: accepted
-contact: westey-m
-date: 2026-03-23
-deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
-consulted:
-informed:
----
-
-# Chat History Persistence Consistency
-
-## Context and Problem Statement
-
-When using `ChatClientAgent` with tools, the `FunctionInvokingChatClient` (FIC) loops multiple times — service call → tool execution → service call → … — before producing a final response. There are two points of discrepancy between how chat history is stored by the framework's `ChatHistoryProvider` and how the underlying AI service stores chat history (e.g., OpenAI Responses with `store=true`):
-
-1. **Persistence timing**: The AI service persists messages after *each* service call within the FIC loop. The `ChatHistoryProvider` currently persists messages only once, at the *end* of the full agent run (after all FIC loop iterations complete).
-
-2. **Trailing `FunctionResultContent` storage**: When tool calling is terminated mid-loop (e.g., via `FunctionInvokingChatClient` termination filters), the final response from the agent may contain `FunctionResultContent` that was never sent to a subsequent service call. The AI service never stores this trailing `FunctionResultContent`, but the `ChatHistoryProvider` currently stores all response content, including the trailing `FunctionResultContent`.
-
-These discrepancies mean that a `ChatHistoryProvider`-managed conversation and a service-managed conversation can diverge in content and structure, even when processing the same interactions.
-
-### Practical Impact: Resuming After Tool-Call Termination
-
-Today, users of `AIAgent` get different behaviors depending on whether chat history is stored service-side or in a `ChatHistoryProvider`. This creates concrete challenges — for example, when the function call loop is terminated and the user wants to resume the conversation in a subsequent run. With service-stored history, the trailing `FunctionResultContent` is never persisted, so the last stored message is the `FunctionCallContent` from the service. With `ChatHistoryProvider`-stored history, the trailing `FunctionResultContent` *is* persisted. The user cannot know whether the last `FunctionResultContent` is in the chat history or not without inspecting the storage mechanism, making it difficult to write resumption logic that works correctly regardless of the storage backend.
-
-### Relationship Between the Two Discrepancies
-
-The persistence timing and `FunctionResultContent` trimming behaviors are interrelated:
-
-- **Per-service-call persistence**: When messages are persisted after each individual service call, trailing `FunctionResultContent` trimming is unnecessary. If tool calling is terminated, the `FunctionResultContent` from the terminated call was never sent to a subsequent service call, so it is never persisted. The per-service-call approach naturally matches the service's behavior.
-
-- **Per-run persistence**: When messages are batched and persisted at the end of the full run, trailing `FunctionResultContent` trimming becomes necessary to match the service's behavior. Without trimming, the stored history contains `FunctionResultContent` that the service would never have stored.
-
-This means the trimming feature (introduced in [PR #4792](https://github.com/microsoft/agent-framework/pull/4792)) is primarily needed as a complement to per-run persistence. The `PersistChatHistoryAtEndOfRun` setting (introduced in [PR #4762](https://github.com/microsoft/agent-framework/pull/4762)) inverts the default so that per-service-call persistence is the standard behavior, and per-run persistence is opt-in.
-
-## Decision Drivers
-
-- **A. Consistency**: The default behavior of `ChatHistoryProvider` should produce stored history that closely matches what the underlying AI service would store, minimizing surprise when switching between framework-managed and service-managed chat history.
-- **B. Atomicity**: A run that fails mid-way through a multi-step tool-calling loop should not leave chat history in a partially-updated state, unless the user explicitly opts into that behavior.
-- **C. Recoverability**: For long-running tool-calling loops, it should be possible to recover intermediate progress if the process is interrupted, rather than losing all work from the current run.
-- **D. Simplicity**: The default behavior should be easy to understand and predict for most users, without requiring knowledge of the FIC loop internals.
-- **E. Flexibility**: Regardless of the chosen default, users should be able to opt into the alternative behavior.
-
-## Considered Options
-
-- Option 1: Default to per-run persistence with `FunctionResultContent` trimming (opt-in to per-service-call)
-- Option 2: Default to per-service-call persistence (opt-in to per-run)
-
-## Pros and Cons of the Options
-
-### Option 1: Default to per-run persistence with `FunctionResultContent` trimming
-
-Keep the current default behavior of persisting chat history only at the end of the full agent run. Add `FunctionResultContent` trimming as the default to improve consistency with service storage. Provide an opt-in setting for users who want per-service-call persistence.
-
-Settings:
-- `PersistChatHistoryAtEndOfRun` = `true`
-
-- Good, because runs are atomic — chat history is only updated when the full run succeeds, satisfying driver B.
-- Good, because the mental model is simple: one run = one history update, satisfying driver D.
-- Good, because trimming trailing `FunctionResultContent` improves consistency with service storage, partially satisfying driver A.
-- Good, because users can opt in to per-service-call persistence for checkpointing/recovery scenarios, satisfying drivers C and E.
-- Bad, because the default persistence timing still differs from the service's behavior (per-run vs. per-service-call), only partially satisfying driver A.
-- Bad, because if the process crashes mid-loop, all intermediate progress from the current run is lost, not satisfying driver C by default.
-
-### Option 2: Default to per-service-call persistence
-
-Change the default to persist chat history after each individual service call within the FIC loop, matching the AI service's behavior. Trailing `FunctionResultContent` trimming is unnecessary with this approach (it is naturally handled). Provide an opt-in setting for users who want per-run atomicity with trimming.
-
-Settings:
-- `PersistChatHistoryAtEndOfRun` = `false` (default)
-
-- Good, because the stored history matches the service's behavior by default for both timing and content, fully satisfying driver A.
-- Good, because intermediate progress is preserved if the process is interrupted, satisfying driver C.
-- Good, because no separate `FunctionResultContent` trimming logic is needed, reducing complexity.
-- Bad, because chat history may be left in an incomplete state if the run fails mid-loop (e.g., `FunctionCallContent` stored without corresponding `FunctionResultContent`), not satisfying driver B. A subsequent run cannot proceed without manually providing the missing `FunctionResultContent`.
-- Bad, because the mental model is more complex: a single run may produce multiple history updates, partially failing driver D.
-- Neutral, because users can opt out to per-run persistence if they prefer atomicity, satisfying driver E.
-
-## Decision Outcome
-
-Chosen option: **Option 2 — Default to per-service-call persistence**, because it fully satisfies the consistency driver (A), naturally handles `FunctionResultContent` trimming without additional logic, and provides better recoverability for long-running tool-calling loops. Per-run persistence remains available via the `PersistChatHistoryAtEndOfRun` setting for users who prefer atomic run semantics.
-
-### Configuration Matrix
-
-The behavior depends on the combination of `UseProvidedChatClientAsIs` and `PersistChatHistoryAtEndOfRun`:
-
-| `UseProvidedChatClientAsIs` | `PersistChatHistoryAtEndOfRun` | Behavior |
-|---|---|---|
-| `false` (default) | `false` (default) | **Per-service-call persistence.** A `ChatHistoryPersistingChatClient` middleware is automatically injected into the chat client pipeline between `FunctionInvokingChatClient` and the leaf `IChatClient`. Messages are persisted after each service call. |
-| `true` | `false` | **User responsibility.** No middleware is injected because the user has provided a custom chat client stack. The user is responsible for ensuring correct persistence behavior (e.g., by including their own persisting middleware). |
-| `false` | `true` | **Per-run persistence with marking.** A `ChatHistoryPersistingChatClient` middleware is injected, but configured to *mark* messages with metadata rather than store them immediately. At the end of the run, marked messages are stored. Trailing `FunctionResultContent` is trimmed. |
-| `true` | `true` | **Per-run persistence with warning.** The system checks whether the custom chat client stack includes a `ChatHistoryPersistingChatClient`. If not, a warning is emitted (particularly relevant for workflow handoff scenarios where trimming cannot be guaranteed). If no `ChatHistoryPersistingChatClient` is preset, all messages are stored at the end of the run, otherwise marked messages are stored. |
-
-### Consequences
-
-- Good, because the stored history matches the service's behavior by default for both timing and content, fully satisfying consistency (driver A).
-- Good, because intermediate progress is preserved if the process is interrupted, satisfying recoverability (driver C).
-- Good, because no separate `FunctionResultContent` trimming logic is needed in the default path, reducing complexity.
-- Good, because marking persisted messages with metadata enables deduplication and aids debugging.
-- Good, because warnings for custom chat client configurations without the persisting middleware help prevent silent failures in workflow handoff scenarios.
-- Bad, because chat history may be left in an incomplete state if the run fails mid-loop (e.g., `FunctionCallContent` stored without corresponding `FunctionResultContent`), requiring manual recovery in rare cases.
-- Bad, because the mental model is more complex for the default path: a single run may produce multiple history updates.
-- Neutral, because users who prefer atomic run semantics can opt in to per-run persistence via `PersistChatHistoryAtEndOfRun = true`.
-- Neutral, because increased write frequency from per-service-call persistence may impact performance for some storage backends; this can be mitigated with a caching decorator.
-
-### Implementation Notes
-
-#### Conversation ID Consistency
-
-The `ChatHistoryPersistingChatClient` middleware must also update the session's `ConversationId` consistently for both response-based and conversation-based service interactions, ensuring the session always reflects the latest service-provided identifier.
-
-## More Information
-
-- [PR #4762: Persist messages during function call loop](https://github.com/microsoft/agent-framework/pull/4762) — introduces `PersistChatHistoryAfterEachServiceCall` option and `ChatHistoryPersistingChatClient` decorator
-- [PR #4792: Trim final FRC to match service storage](https://github.com/microsoft/agent-framework/pull/4792) — introduces `StoreFinalFunctionResultContent` option and `FilterFinalFunctionResultContent` logic
-- [Issue #2889](https://github.com/microsoft/agent-framework/issues/2889) — original issue tracking chat history persistence during function call loops

docs/features/durable-agents/AGENTS.md

@@ -1,48 +0,0 @@
-# AGENTS.md
-
-Instructions for AI coding agents working on durable agents documentation.
-
-## Scope
-
-This directory contains feature documentation for the durable agents integration. The source code and samples live elsewhere:
-
-- .NET implementation: `dotnet/src/Microsoft.Agents.AI.DurableTask/` and `dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/`
-- Python implementation: `python/packages/durabletask/` and `python/packages/azurefunctions/` (package `agent-framework-azurefunctions`)
-- .NET samples: `dotnet/samples/04-hosting/DurableAgents/`
-- Python samples: `python/samples/04-hosting/durabletask/`
-- Official docs (Microsoft Learn): <https://learn.microsoft.com/agent-framework/integrations/azure-functions>
-
-## Document structure
-
-| File | Purpose |
-| --- | --- |
-| `README.md` | Main technical overview: architecture, hosting models, orchestration patterns, and links to samples. |
-| `durable-agents-ttl.md` | Deep-dive on session Time-To-Live (TTL) configuration and behavior. |
-
-Add new sibling documents when a topic is too detailed for the README (e.g., a new feature like reliable streaming or MCP tool exposure). Keep the README focused on orientation and link out to siblings for depth.
-
-## Writing guidelines
-
-- **Audience**: Developers already familiar with the Microsoft Agent Framework who want to understand what durability adds and how to use it.
-- **Host-agnostic first**: Durable agents work in console apps, Azure Functions, and any Durable Task–compatible host. Show host-agnostic patterns (plain orchestration functions, `IServiceCollection` registration) before Azure Functions–specific patterns. Avoid giving the impression that Azure Functions is the only hosting option.
-- **Both languages**: Always include C# and Python examples side by side. Keep them equivalent in functionality.
-- **Callout syntax**: Use GitHub-flavored callouts (`> [!NOTE]`, `> [!IMPORTANT]`, `> [!WARNING]`) rather than bold-text callouts (`> **Note:** ...`).
-- **Line length**: Do not wrap long lines. Rely on text viewers / renderers for line wrapping.
-- **Tables**: Use spaces around pipes in separator rows (`| --- |` not `|---|`).
-- **Code snippets**: Keep them minimal and self-contained. Omit boilerplate (using statements, environment variable reads) unless the snippet is specifically about setup.
-- **Cross-references**: Link to Microsoft Learn for conceptual background (Durable Entities, Durable Task Scheduler, Azure Functions). Link to sibling docs within this directory for feature deep-dives.
-
-## Linting
-
-Run markdownlint on all documents before committing, with line-length checks disabled:
-
-```bash
-markdownlint docs/features/durable-agents/ --disable MD013
-```
-
-## When to update these docs
-
-- A new durable agent feature is added (e.g., a new orchestration pattern, hosting model, or configuration option).
-- The public API surface changes in a way that affects how developers use durable agents.
-- New sample directories are added — update the sample links in README.md.
-- The official Microsoft Learn documentation is restructured — update external links.

docs/features/durable-agents/README.md

@@ -1,239 +0,0 @@
-# Durable agents
-
-## Overview
-
-Durable agents extend the standard Microsoft Agent Framework with **durable state management** powered by the Durable Task framework. An ordinary Agent Framework agent runs in-process: its conversation history lives in memory and is lost when the process ends. A durable agent persists conversation history and execution state in external storage so that sessions survive process restarts, failures, and scale-out events.
-
-| Capability | Ordinary agent | Durable agent |
-| --- | --- | --- |
-| Conversation history | In-memory only | Durably persisted |
-| Failure recovery | State lost on crash | Automatically resumed |
-| Multi-instance scale-out | Not supported | Any worker can resume a session |
-| Multi-agent orchestrations | Manual coordination | Deterministic, checkpointed workflows |
-| Human-in-the-loop | Must keep process alive | Can wait days/weeks with zero compute |
-| Hosting | Any process | Console app, Azure Functions, or any Durable Task–compatible host |
-
-> [!NOTE]
-> For a step-by-step tutorial and deployment guidance, see [Azure Functions (Durable)](https://learn.microsoft.com/agent-framework/integrations/azure-functions) on Microsoft Learn.
-
-## How durable agents work
-
-Durable agents are implemented on top of [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities) (also called "virtual actors"). Each **agent session** maps to one entity instance whose state contains the full conversation history. When you send a message to a durable agent, the following happens:
-
-1. The message is dispatched to the entity identified by an `AgentSessionId` (a composite of the agent name and a unique session key).
-2. The entity loads its persisted `DurableAgentState`, which includes the complete conversation history.
-3. The entity invokes the underlying `AIAgent` with the full conversation history, collects the response, and appends both the request and the response to the state.
-4. The updated state is persisted back to durable storage automatically.
-
-Because the entity framework serializes access to each entity instance, concurrent messages to the same session are processed one at a time, eliminating race conditions.
-
-### Agent session identity
-
-Every durable agent session is identified by an `AgentSessionId`, which has two components:
-
-- **Name** – the registered name of the agent (case-insensitive).
-- **Key** – a unique session key (case-sensitive), typically a GUID.
-
-The session ID is mapped to an underlying Durable Task entity ID with a `dafx-` prefix (e.g., `dafx-joker`). This naming convention is consistent across both .NET and Python implementations.
-
-## Architecture
-
-### .NET
-
-The .NET implementation consists of two NuGet packages:
-
-| Package | Purpose |
-| --- | --- |
-| `Microsoft.Agents.AI.DurableTask` | Core durable agent types: `DurableAIAgent`, `AgentEntity`, `DurableAgentSession`, `AgentSessionId`, `DurableAgentsOptions`, and the state model. |
-| `Microsoft.Agents.AI.Hosting.AzureFunctions` | Azure Functions hosting integration: auto-generated HTTP endpoints, MCP tool triggers, entity function triggers, and the `ConfigureDurableAgents` extension method on `FunctionsApplicationBuilder`. |
-
-Key types:
-
-- **`DurableAIAgent`** – A subclass of `AIAgent` used *inside orchestrations*. Obtained via `context.GetAgent("agentName")`, it routes `RunAsync` calls through the orchestration's entity APIs so that each call is checkpointed.
-- **`DurableAIAgentProxy`** – A subclass of `AIAgent` used *outside orchestrations* (e.g., from HTTP triggers or console apps). It signals the entity via `DurableTaskClient` and polls for the response.
-- **`AgentEntity`** – The `TaskEntity<DurableAgentState>` that hosts the real agent. It loads the registered `AIAgent` by name, wraps it in an `EntityAgentWrapper`, feeds it the full conversation history, and persists the result.
-- **`DurableAgentSession`** – An `AgentSession` subclass that carries the `AgentSessionId`.
-- **`DurableAgentsOptions`** – Builder for registering agents and configuring TTL.
-
-### Python
-
-The core Python implementation is in the `agent-framework-durabletask` package (`python/packages/durabletask`). Azure Functions hosting (including `AgentFunctionApp`) is in the separate `agent-framework-azurefunctions` package (`python/packages/azurefunctions`).
-
-Key types:
-
-- **`DurableAIAgent`** – A generic proxy (`DurableAIAgent[TaskT]`) implementing `SupportsAgentRun`. Returns a `TaskT` from `run()` — either an `AgentResponse` (client context) or a `DurableAgentTask` (orchestration context, must be `yield`ed).
-- **`DurableAIAgentWorker`** – Wraps a `TaskHubGrpcWorker` and registers agents as durable entities via `add_agent()`.
-- **`DurableAIAgentClient`** – Wraps a `TaskHubGrpcClient` for external callers. `get_agent()` returns a `DurableAIAgent[AgentResponse]`.
-- **`DurableAIAgentOrchestrationContext`** – Wraps an `OrchestrationContext` for use inside orchestrations. `get_agent()` returns a `DurableAIAgent[DurableAgentTask]`.
-- **`AgentEntity`** – Platform-agnostic agent execution logic that manages state, invokes the agent, handles streaming, and calls response callbacks.
-
-## Hosting models
-
-### Azure Functions
-
-The recommended production hosting model. A single call to `ConfigureDurableAgents` (C#) or `AgentFunctionApp` (Python) automatically:
-
-- Registers agent entities with the Durable Task worker.
-- Generates HTTP endpoints at `/api/agents/{agentName}/run` for each registered agent.
-- Supports `thread_id` query parameter / JSON field and the `x-ms-thread-id` response header for session continuity.
-- Supports fire-and-forget via the `x-ms-wait-for-response: false` header (returns HTTP 202).
-- Optionally exposes agents as MCP tools.
-
-**C# example:**
-
-```csharp
-using IHost app = FunctionsApplication
-    .CreateBuilder(args)
-    .ConfigureFunctionsWebApplication()
-    .ConfigureDurableAgents(options => options.AddAIAgent(agent))
-    .Build();
-app.Run();
-```
-
-**Python example:**
-
-```python
-app = AgentFunctionApp(agents=[agent])
-```
-
-### Console apps / generic hosts
-
-For self-hosted or non-serverless scenarios, register durable agents via `IServiceCollection.ConfigureDurableAgents` (.NET) or `DurableAIAgentWorker` (Python) with explicit Durable Task worker and client configuration.
-
-**C# example:**
-
-```csharp
-IHost host = Host.CreateDefaultBuilder(args)
-    .ConfigureServices(services =>
-    {
-        services.ConfigureDurableAgents(
-            options => options.AddAIAgent(agent),
-            workerBuilder: b => b.UseDurableTaskScheduler(connectionString),
-            clientBuilder: b => b.UseDurableTaskScheduler(connectionString));
-    })
-    .Build();
-```
-
-**Python example:**
-
-```python
-worker = DurableAIAgentWorker(TaskHubGrpcWorker(host_address="localhost:4001"))
-worker.add_agent(agent)
-worker.start()
-```
-
-## Deterministic multi-agent orchestrations
-
-Durable agents can be composed into deterministic, checkpointed workflows using Durable Task orchestrations. The orchestration framework replays orchestrator code on failure, so completed agent calls are not re-executed.
-
-### Patterns
-
-| Pattern | Description |
-| --- | --- |
-| **Sequential (chaining)** | Call agents one after another, passing outputs forward. |
-| **Parallel (fan-out/fan-in)** | Run multiple agents concurrently and aggregate results. |
-| **Conditional** | Branch orchestration logic based on structured agent output. |
-| **Human-in-the-loop** | Pause for external events (approvals, feedback) with optional timeouts. |
-
-### Using agents in orchestrations
-
-Inside an orchestration function, obtain a `DurableAIAgent` via the orchestration context. Each agent gets its own session (created with `CreateSessionAsync` / `create_session`), and you can call the same agent multiple times on the same session to maintain conversation context across sequential invocations.
-
-**C#:**
-
-```csharp
-static async Task<string> WritingOrchestration(TaskOrchestrationContext context)
-{
-    // Get a durable agent reference — works in any host (console app, Azure Functions, etc.)
-    DurableAIAgent writer = context.GetAgent("WriterAgent");
-
-    // Create a session to maintain conversation context across multiple calls
-    AgentSession session = await writer.CreateSessionAsync();
-
-    // First call: generate an initial draft
-    AgentResponse<TextResponse> draft = await writer.RunAsync<TextResponse>(
-        message: "Write a concise inspirational sentence about learning.",
-        session: session);
-
-    // Second call: refine the draft — the agent sees the full conversation history
-    AgentResponse<TextResponse> refined = await writer.RunAsync<TextResponse>(
-        message: $"Improve this further while keeping it under 25 words: {draft.Result.Text}",
-        session: session);
-
-    return refined.Result.Text;
-}
-```
-
-**Python:**
-
-```python
-def writing_orchestration(context, _):
-    agent_ctx = DurableAIAgentOrchestrationContext(context)
-
-    # Get a durable agent reference — works in any host (standalone worker, Azure Functions, etc.)
-    writer = agent_ctx.get_agent("WriterAgent")
-
-    # Create a session to maintain conversation context across multiple calls
-    session = writer.create_session()
-
-    # First call: generate an initial draft
-    draft = yield writer.run(
-        messages="Write a concise inspirational sentence about learning.",
-        session=session,
-    )
-
-    # Second call: refine the draft — the agent sees the full conversation history
-    refined = yield writer.run(
-        messages=f"Improve this further while keeping it under 25 words: {draft.text}",
-        session=session,
-    )
-
-    return refined.text
-```
-
-> [!IMPORTANT]
-> In .NET, `DurableAIAgent.RunAsync<T>` deliberately avoids `ConfigureAwait(false)` because the Durable Task Framework uses a custom synchronization context — all continuations must run on the orchestration thread.
-
-## Streaming and response callbacks
-
-Durable agents do not support true end-to-end streaming because entity operations are request/response. However, **reliable streaming** is supported via response callbacks:
-
-- **`IAgentResponseHandler`** (.NET) or **`AgentResponseCallbackProtocol`** (Python) – Implement this interface to receive streaming updates as the underlying agent generates them (e.g., push tokens to a Redis Stream for client consumption).
-- The entity still returns the complete `AgentResponse` after the stream is fully consumed.
-- Clients can reconnect and resume reading from a cursor-based stream (e.g., Redis Streams) without losing messages.
-
-See the **Reliable Streaming** samples for a complete implementation using Redis Streams.
-
-## Session TTL (Time-To-Live)
-
-Durable agent sessions support automatic cleanup via configurable TTL. See [Session TTL](durable-agents-ttl.md) for details on configuration, behavior, and best practices.
-
-## Observability
-
-When using the [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler) as the durable backend, you get built-in observability through its dashboard:
-
-- **Conversation history** – View complete chat history for each agent session.
-- **Orchestration visualization** – See multi-agent execution flows, including parallel branches and conditional logic.
-- **Performance metrics** – Monitor agent response times, token usage, and orchestration duration.
-- **Debugging** – Trace tool invocations and external event handling.
-
-## Samples
-
-- **.NET** – [Console app samples](../../../dotnet/samples/04-hosting/DurableAgents/ConsoleApps/) and [Azure Functions samples](../../../dotnet/samples/04-hosting/DurableAgents/AzureFunctions/) covering single-agent, chaining, concurrency, conditionals, human-in-the-loop, long-running tools, MCP tool exposure, and reliable streaming.
-- **Python** – [Durable Task samples](../../../python/samples/04-hosting/durabletask/) covering single-agent, multi-agent, streaming, chaining, concurrency, conditionals, and human-in-the-loop.
-
-## Packages
-
-| Language | Package | Source |
-| --- | --- | --- |
-| .NET | `Microsoft.Agents.AI.DurableTask` | [`dotnet/src/Microsoft.Agents.AI.DurableTask`](../../../dotnet/src/Microsoft.Agents.AI.DurableTask) |
-| .NET | `Microsoft.Agents.AI.Hosting.AzureFunctions` | [`dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions`](../../../dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions) |
-| Python | `agent-framework-durabletask` | [`python/packages/durabletask`](../../../python/packages/durabletask) |
-| Python | `agent-framework-azurefunctions` | [`python/packages/azurefunctions`](../../../python/packages/azurefunctions) |
-
-## Further reading
-
-- [Azure Functions (Durable) — Microsoft Learn](https://learn.microsoft.com/agent-framework/integrations/azure-functions)
-- [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler)
-- [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities)
-- [Session TTL](durable-agents-ttl.md)

docs/features/vector-stores-and-embeddings/README.md

@@ -1,390 +0,0 @@
-# Vector Stores and Embeddings
-
-## Overview
-
-This feature ports the vector store abstractions, embedding generator abstractions, and their implementations from Semantic Kernel into Agent Framework. The ported code follows AF's coding standards, feels native to AF, and is structured to allow data models/schemas to be reusable across both frameworks. The embedding abstraction combines the best of SK's `EmbeddingGeneratorBase` and MEAI's `IEmbeddingGenerator<TInput, TEmbedding>`.
-
-| Capability | Description |
-| --- | --- |
-| Embedding generation | Generic embedding client abstraction supporting text, image, and audio inputs |
-| Vector store collections | CRUD operations on vector store collections (upsert, get, delete) |
-| Vector search | Unified search interface with `search_type` parameter (`"vector"`, `"keyword_hybrid"`) |
-| Data model decorator | `@vectorstoremodel` decorator for defining vector store data models (supports Pydantic, dataclasses, plain classes, dicts) |
-| Agent tools | `create_search_tool`, `create_upsert_tool`, `create_get_tool`, `create_delete_tool` for agent-usable vector store operations |
-| In-memory store | Zero-dependency vector store for testing and development |
-| 13+ connectors | Azure AI Search, Qdrant, Redis, PostgreSQL, MongoDB, Cosmos DB, Pinecone, Chroma, Weaviate, Oracle, SQL Server, FAISS |
-
-## Key Design Decisions
-
-### Embedding Abstractions (combining SK + MEAI)
-- **Both Protocol and Base class** (matching AF's `SupportsChatGetResponse` + `BaseChatClient` pattern):
-  - `SupportsGetEmbeddings` — Protocol for duck-typing
-  - `BaseEmbeddingClient` — ABC base class for implementations (similar to `BaseChatClient`)
-- **Generic input type** (`EmbeddingInputT`, default `str`) from MEAI — allows image/audio embeddings in the future
-- **Generic output type** (`EmbeddingT`, default `list[float]`) from MEAI — supports `list[float]`, `list[int]`, `bytes`, etc.
-- **Generic order**: `[EmbeddingInputT, EmbeddingT, EmbeddingOptionsT]` — options last, matching MEAI's `IEmbeddingGenerator<TInput, TEmbedding>` with options appended
-- **TypeVar naming convention**: Use `SuffixT` per AF standard (e.g., `EmbeddingInputT`, `EmbeddingT`, `ModelT`, `KeyT`)
-- `EmbeddingGenerationOptions` TypedDict (inspired by MEAI, matching AF's `ChatOptions` pattern) — `total=False`, includes `dimensions`, `model_id`. No `additional_properties` since each implementation extends with its own fields.
-- Protocol and base class are generic over input, output, and options: `SupportsGetEmbeddings[EmbeddingInputT, EmbeddingT, OptionsContraT]`, `BaseEmbeddingClient[EmbeddingInputT, EmbeddingT, OptionsCoT]`
-- **`Embedding[EmbeddingT]` type** in `_types.py` — a lightweight generic class (not Pydantic) with `vector: EmbeddingT`, `model_id: str | None`, `dimensions: int | None` (explicit or computed from vector), `created_at: datetime | None`, `additional_properties: dict[str, Any]`
-- **`GeneratedEmbeddings[EmbeddingT, EmbeddingOptionsT]` type** — a list-like container of `Embedding[EmbeddingT]` objects with `options: EmbeddingOptionsT | None` (stores the options used to generate), `usage: dict[str, Any] | None`, `additional_properties: dict[str, Any]`
-- **No numpy dependency** — return `list[float]` by default; users cast as needed
-
-### Vector Store Abstractions
-- **Port core abstractions without Pydantic for internal classes** — use plain classes
-- **Both Protocol and Base class** for vector store operations (matching AF pattern):
-  - `SupportsVectorUpsert` / `SupportsVectorSearch` — Protocols for duck-typing (follows `Supports<Capability>` naming convention)
-  - `BaseVectorCollection` / `BaseVectorSearch` — ABC base classes for implementations
-  - `BaseVectorStore` — ABC base class for store operations (factory for collections, no protocol needed)
-- **TypeVar naming convention**: `ModelT`, `KeyT`, `FilterT` (suffix T, per AF standard)
-- **Support Pydantic for user-facing data models** — the `@vectorstoremodel` decorator and `VectorStoreCollectionDefinition` should work with Pydantic models, dataclasses, plain classes, and dicts
-- **Remove SK-specific dependencies** — no `KernelBaseModel`, `KernelFunction`, `KernelParameterMetadata`, `kernel_function`, `PromptExecutionSettings`
-- **Embedding types in `_types.py`**, embedding protocol/base class in `_clients.py`
-- **All vector store specific types, enums, protocols, base classes** in `_vectors.py`
-- **Error handling** uses AF's exception hierarchy (e.g., `IntegrationException` variants)
-
-### Package Structure
-- **Embedding types** (`Embedding`, `GeneratedEmbeddings`, `EmbeddingGenerationOptions`) in `agent_framework/_types.py`
-- **Embedding protocol + base class** (`SupportsGetEmbeddings`, `BaseEmbeddingClient`) in `agent_framework/_clients.py`
-- **All vector store specific code** in a new `agent_framework/_vectors.py` module — this includes:
-  - Enums: `FieldTypes`, `IndexKind`, `DistanceFunction`
-  - `VectorStoreField`, `VectorStoreCollectionDefinition`
-  - `SearchOptions`, `SearchResponse`, `RecordFilterOptions`
-  - `@vectorstoremodel` decorator
-  - Serialization/deserialization protocols
-  - `VectorStoreRecordHandler`, `BaseVectorCollection`, `BaseVectorStore`, `BaseVectorSearch`
-  - `SupportsVectorUpsert`, `SupportsVectorSearch` protocols
-- **OpenAI embeddings** in `agent_framework/openai/` (built into core, like OpenAI chat)
-- **Azure OpenAI embeddings** in `agent_framework/azure/` (built into core, follows `AzureOpenAIChatClient` pattern)
-- **Each vector store connector** in its own AF package under `packages/`
-- **In-memory store** in core (no external deps)
-- **TextSearch and its implementations** (Brave, Google) — last phase, separate work
-
-## Naming: SK → AF
-
-### Names that change
-
-| SK Name | AF Name | Rationale |
-|---------|---------|-----------|
-| `VectorStoreCollection` | `BaseVectorCollection` | Drop redundant `Store`, add `Base` prefix per AF pattern |
-| `VectorStore` | `BaseVectorStore` | Add `Base` prefix per AF pattern |
-| `VectorSearch` | `BaseVectorSearch` | Add `Base` prefix per AF pattern |
-| `VectorSearchOptions` | `SearchOptions` | Shorter — context is already vector search |
-| `VectorSearchResult` | `SearchResponse` | Align with `ChatResponse`/`AgentResponse` |
-| `GetFilteredRecordOptions` | `RecordFilterOptions` | Shorter, more natural |
-| `EmbeddingGeneratorBase` | `BaseEmbeddingClient` | Matches AF `BaseChatClient` pattern |
-| `VectorStoreCollectionProtocol` | `SupportsVectorUpsert` | AF `Supports*` naming convention |
-| `VectorSearchProtocol` | `SupportsVectorSearch` | AF `Supports*` naming convention |
-| `__kernel_vectorstoremodel__` | `__vectorstoremodel__` | Drop SK `kernel` prefix |
-| `__kernel_vectorstoremodel_definition__` | `__vectorstoremodel_definition__` | Drop SK `kernel` prefix |
-| `search()` + `hybrid_search()` | `search(search_type=...)` | Single method with `Literal` parameter |
-| `SearchType` enum | `Literal["vector", "keyword_hybrid"]` | No enum, just a literal |
-| `KernelSearchResults` | `SearchResults` | Drop SK `Kernel` prefix (plural — container of `SearchResponse` items) |
-
-### Names that stay the same
-
-| Name | Location |
-|------|----------|
-| `@vectorstoremodel` | `_vectors.py` |
-| `VectorStoreField` | `_vectors.py` |
-| `VectorStoreCollectionDefinition` | `_vectors.py` |
-| `VectorStoreRecordHandler` | `_vectors.py` |
-| `FieldTypes` | `_vectors.py` |
-| `IndexKind` | `_vectors.py` |
-| `DistanceFunction` | `_vectors.py` |
-| `DISTANCE_FUNCTION_DIRECTION_HELPER` | `_vectors.py` |
-| `Embedding` | `_types.py` |
-| `GeneratedEmbeddings` | `_types.py` |
-| `EmbeddingGenerationOptions` | `_types.py` |
-| `SupportsGetEmbeddings` | `_clients.py` |
-
-### New AF-only names (no SK equivalent)
-
-| Name | Location | Purpose |
-|------|----------|---------|
-| `BaseEmbeddingClient` | `_clients.py` | ABC base for embedding implementations |
-| `EmbeddingInputT` | `_types.py` | TypeVar for generic embedding input (default `str`) |
-| `EmbeddingTelemetryLayer` | `observability.py` | MRO-based OTel tracing for embeddings |
-| `SupportsVectorUpsert` | `_vectors.py` | Protocol for collection CRUD |
-| `SupportsVectorSearch` | `_vectors.py` | Protocol for vector search |
-| `create_search_tool` | `_vectors.py` | Creates AF `FunctionTool` from vector search |
-
-## Source Files Reference (SK → AF mapping)
-
-### SK Source Files
-| SK File | Lines | Content |
-|---------|-------|---------|
-| `data/vector.py` | 2369 | All vector store abstractions, enums, decorator, search |
-| `data/_shared.py` | 184 | SearchOptions, KernelSearchResults, shared search types |
-| `data/text_search.py` | 349 | TextSearch base, TextSearchResult |
-| `connectors/ai/embedding_generator_base.py` | 50 | EmbeddingGeneratorBase ABC |
-| `connectors/in_memory.py` | 520 | InMemoryCollection, InMemoryStore |
-| `connectors/azure_ai_search.py` | 793 | Azure AI Search collection + store |
-| `connectors/azure_cosmos_db.py` | 1104 | Cosmos DB (Mongo + NoSQL) |
-| `connectors/redis.py` | 845 | Redis (Hashset + JSON) |
-| `connectors/qdrant.py` | 653 | Qdrant collection + store |
-| `connectors/postgres.py` | 987 | PostgreSQL collection + store |
-| `connectors/mongodb.py` | 633 | MongoDB Atlas collection + store |
-| `connectors/pinecone.py` | 691 | Pinecone collection + store |
-| `connectors/chroma.py` | 484 | Chroma collection + store |
-| `connectors/faiss.py` | 278 | FAISS (extends InMemory) |
-| `connectors/weaviate.py` | 804 | Weaviate collection + store |
-| `connectors/oracle.py` | 1267 | Oracle collection + store |
-| `connectors/sql_server.py` | 1132 | SQL Server collection + store |
-| `connectors/ai/open_ai/services/open_ai_text_embedding.py` | 91 | OpenAI embedding impl |
-| `connectors/ai/open_ai/services/open_ai_text_embedding_base.py` | 78 | OpenAI embedding base |
-| `connectors/brave.py` | ~200 | Brave TextSearch impl |
-| `connectors/google_search.py` | ~200 | Google TextSearch impl |
-
----
-
-## Implementation Phases
-
-### Phase 1: Core Embedding Abstractions & OpenAI Implementation ✅ DONE
-**Goal:** Establish the embedding generator abstraction and ship one working implementation.
-**Mergeable:** Yes — adds new types/protocols, no breaking changes.
-**Status:** Merged via PR #4153. Closes sub-issue #4163.
-
-#### 1.1 — Embedding types in `_types.py`
-- `EmbeddingInputT` TypeVar (default `str`) — generic input type for embedding generation
-- `EmbeddingT` TypeVar (default `list[float]`) — generic output embedding vector type
-- `Embedding[EmbeddingT]` generic class: `vector: EmbeddingT`, `model_id: str | None`, `dimensions: int | None` (explicit param or computed from vector length), `created_at: datetime | None`, `additional_properties: dict[str, Any]`
-- `GeneratedEmbeddings[EmbeddingT, EmbeddingOptionsT]` generic class: list-like container of `Embedding[EmbeddingT]` objects with `options: EmbeddingOptionsT | None` (the options used to generate), `usage: dict[str, Any] | None`, `additional_properties: dict[str, Any]`
-- `EmbeddingGenerationOptions` TypedDict (`total=False`): `dimensions: int`, `model_id: str` — follows the same pattern as `ChatOptions`. No `additional_properties` needed since it's a TypedDict and each implementation can extend with its own fields.
-
-#### 1.2 — Embedding generator protocol + base class in `_clients.py`
-- `SupportsGetEmbeddings(Protocol[EmbeddingInputT, EmbeddingT, OptionsContraT])`: generic over input, output, and options (all with defaults), `get_embeddings(values: Sequence[EmbeddingInputT], *, options: OptionsContraT | None = None) -> Awaitable[GeneratedEmbeddings[EmbeddingT]]`
-- `BaseEmbeddingClient(ABC, Generic[EmbeddingInputT, EmbeddingT, OptionsCoT])`: ABC base class mirroring `BaseChatClient` pattern
-  - `__init__` with `additional_properties`, etc.
-  - Abstract `get_embeddings(...)` for subclasses to implement directly (no `_inner_*` indirection — simpler than chat, no middleware needed)
-- `EmbeddingTelemetryLayer` in `observability.py` — MRO-based telemetry (no closure), `gen_ai.operation.name = "embeddings"`
-
-#### 1.3 — OpenAI embedding generator in `agent_framework/openai/` and `agent_framework/azure/`
-- `RawOpenAIEmbeddingClient` — implements `get_embeddings` via `_ensure_client()` factory
-- `OpenAIEmbeddingClient(OpenAIConfigMixin, EmbeddingTelemetryLayer[str, list[float], OptionsT], RawOpenAIEmbeddingClient[OptionsT])` — full client with config + telemetry layers
-- `OpenAIEmbeddingOptions(EmbeddingGenerationOptions)` — extends with `encoding_format`, `user`
-- `AzureOpenAIEmbeddingClient` in `agent_framework/azure/` — follows `AzureOpenAIChatClient` pattern with `AzureOpenAIConfigMixin`, `load_settings`, Entra ID credential support
-- `AzureOpenAISettings` extended with `embedding_deployment_name` (env var: `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`)
-
-#### 1.4 — Tests and samples
-- Unit tests for types, protocol, base class, OpenAI client, Azure OpenAI client
-- Integration tests for OpenAI and Azure OpenAI (gated behind credentials check, `@pytest.mark.flaky`)
-- Samples in `samples/02-agents/embeddings/` — `openai_embeddings.py`, `azure_openai_embeddings.py`
-
----
-
-### Phase 2: Embedding Generators for Existing Providers
-**Goal:** Add embedding generators to all existing AF provider packages that have chat clients.
-**Mergeable:** Yes — each is independent, added to existing provider packages.
-
-#### 2.1 — Azure AI Inference embedding (in `packages/azure-ai/`)
-#### 2.2 — Ollama embedding (in `packages/ollama/`)
-#### 2.3 — Anthropic embedding (in `packages/anthropic/`)
-#### 2.4 — Bedrock embedding (in `packages/bedrock/`)
-
----
-
-### Phase 3: Core Vector Store Abstractions
-**Goal:** Establish all vector store types, enums, the decorator, collection definition, and base classes.
-**Mergeable:** Yes — adds new abstractions, no breaking changes.
-
-#### 3.1 — Vector store enums and field types in `_vectors.py`
-- `FieldTypes` enum: `KEY`, `VECTOR`, `DATA`
-- `IndexKind` enum: `HNSW`, `FLAT`, `IVF_FLAT`, `DISK_ANN`, `QUANTIZED_FLAT`, `DYNAMIC`, `DEFAULT`
-- `DistanceFunction` enum: `COSINE_SIMILARITY`, `COSINE_DISTANCE`, `DOT_PROD`, `EUCLIDEAN_DISTANCE`, `EUCLIDEAN_SQUARED_DISTANCE`, `MANHATTAN`, `HAMMING`, `DEFAULT`
-- No `SearchType` enum — use `Literal["vector", "keyword_hybrid"]` instead, per AF convention of avoiding unnecessary imports
-- `VectorStoreField` plain class (not Pydantic)
-- `VectorStoreCollectionDefinition` class (not Pydantic internally, but supports Pydantic models as input)
-- `SearchOptions` plain class — includes `score_threshold: float | None` for filtering results by score (see note below)
-- `SearchResponse` generic class
-- `RecordFilterOptions` plain class
-- `DISTANCE_FUNCTION_DIRECTION_HELPER` dict
-
-#### 3.2 — `@vectorstoremodel` decorator
-- Port from SK, works with dataclasses, Pydantic models, plain classes, and dicts
-- Sets `__vectorstoremodel__` and `__vectorstoremodel_definition__` on the class
-- Remove SK-specific `kernel` prefix (`__kernel_vectorstoremodel__` → `__vectorstoremodel__`)
-
-#### 3.3 — Serialization/deserialization protocols
-- `SerializeMethodProtocol`, `ToDictFunctionProtocol`, `FromDictFunctionProtocol`, etc.
-- Port the record handler logic but without Pydantic base class — use plain class or ABC
-
-#### 3.4 — Vector store base classes in `_vectors.py`
-- `VectorStoreRecordHandler` — internal base class that handles serialization/deserialization between user data models and store-specific formats, plus embedding generation for vector fields. Both `BaseVectorCollection` and `BaseVectorSearch` extend this.
-- `BaseVectorCollection(VectorStoreRecordHandler)` — base for collections
-  - Uses `SupportsGetEmbeddings` instead of `EmbeddingGeneratorBase`
-  - Not a Pydantic model — use `__init__` with explicit params
-  - `upsert`, `get`, `delete`, `ensure_collection_exists`, `collection_exists`, `ensure_collection_deleted`
-  - Async context manager support
-- `BaseVectorStore` — base for stores
-  - `get_collection`, `list_collection_names`, `collection_exists`, `ensure_collection_deleted`
-  - Async context manager support
-
-#### 3.5 — Vector search base class
-- `BaseVectorSearch(VectorStoreRecordHandler)` — base for vector search
-  - Single `search(search_type=...)` method with `search_type: Literal["vector", "keyword_hybrid"]` parameter — no enum, just a literal
-  - `_inner_search` abstract method for implementations
-  - Filter building with lambda parser (AST-based)
-  - Vector generation from values using embedding generator
-
-#### 3.6 — Protocols for type checking
-- `SupportsVectorUpsert` — Protocol for upsert/get/delete operations
-- `SupportsVectorSearch` — Protocol for vector search (single `search()` with `search_type` parameter)
-- No separate `SupportsVectorHybridSearch` — search type is a parameter, not a separate capability
-- No protocol for `VectorStore` — it's a factory for collections, not a capability to duck-type against
-
-#### 3.7 — Exception types
-- Add vector store exceptions under `IntegrationException` or create new branch
-- `VectorStoreException`, `VectorStoreOperationException`, `VectorSearchException`, `VectorStoreModelException`, etc.
-
-#### 3.8 — `create_search_tool` on `BaseVectorSearch`
-- Method on `BaseVectorSearch` that creates an AF `FunctionTool` from the vector search
-- Wraps the single `search()` method, passing `search_type` parameter
-- Accepts: `name`, `description`, `search_type`, `top`, `skip`, `filter`, `string_mapper`
-- The tool takes a query string, vectorizes it, searches, and returns results as strings
-- Can also be a standalone factory function in `_vectors.py`
-
-#### 3.9 — Tests for all vector store abstractions
-- Unit tests for enums, field types, collection definition
-- Unit tests for decorator
-- Unit tests for serialization/deserialization
-- Unit tests for record handler
-
----
-
-### Phase 4: In-Memory Vector Store
-**Goal:** Provide a zero-dependency vector store for testing and development.
-**Mergeable:** Yes — first usable vector store.
-
-#### 4.1 — Port `InMemoryCollection` and `InMemoryStore` into core
-- Place in `agent_framework/_vectors.py` (alongside the abstractions)
-- Supports vector search (cosine similarity, etc.)
-- No external dependencies
-
-#### 4.2 — Port FAISS extension (optional, can be separate package)
-- Extends InMemory with FAISS indexing
-
-#### 4.3 — Tests and sample code
-
----
-
-### Phase 5: Vector Store Connectors — Tier 1 (High Priority)
-**Goal:** Ship the most commonly used vector store connectors.
-**Mergeable:** Yes — each connector is independent.
-
-Each connector follows the AF package structure:
-- New package under `packages/`
-- Own `pyproject.toml`, `tests/`, lazy loading in core
-
-#### 5.1 — Azure AI Search (`packages/azure-ai-search/`)
-- May extend existing package or be new
-- `AzureAISearchCollection`, `AzureAISearchStore`
-
-#### 5.2 — Qdrant (`packages/qdrant/`)
-- New package
-- `QdrantCollection`, `QdrantStore`
-
-#### 5.3 — Redis (`packages/redis/`)
-- May extend existing redis package
-- `RedisCollection` (JSON + Hashset variants), `RedisStore`
-
-#### 5.4 — PostgreSQL/pgvector (`packages/postgres/`)
-- New package
-- `PostgresCollection`, `PostgresStore`
-
----
-
-### Phase 6: Vector Store Connectors — Tier 2
-**Goal:** Ship remaining vector store connectors.
-**Mergeable:** Yes — each connector is independent.
-
-#### 6.1 — MongoDB Atlas (`packages/mongodb/`)
-#### 6.2 — Azure Cosmos DB (`packages/azure-cosmos-db/`)
-- Cosmos Mongo + Cosmos NoSQL
-#### 6.3 — Pinecone (`packages/pinecone/`)
-#### 6.4 — Chroma (`packages/chroma/`)
-#### 6.5 — Weaviate (`packages/weaviate/`)
-
----
-
-### Phase 7: Vector Store Connectors — Tier 3
-**Goal:** Ship niche or less common connectors.
-**Mergeable:** Yes — each connector is independent.
-
-#### 7.1 — Oracle (`packages/oracle/`)
-#### 7.2 — SQL Server (`packages/sql-server/`)
-#### 7.3 — FAISS (`packages/faiss/` or in core extending InMemory)
-
-> **Note:** When implementing any SQL-based connector (PostgreSQL, SQL Server, SQLite, Cosmos DB), review the .NET MEVD changes made by @roji (Shay Rojansky) in SK for design patterns, query building, filter translation, and feature parity: https://github.com/microsoft/semantic-kernel/pulls?q=is%3Apr+author%3Aroji+is%3Aclosed
-
----
-
-### Phase 8: Vector Store CRUD Tools
-**Goal:** Provide a full set of agent-usable tools for CRUD operations on vector store collections.
-**Mergeable:** Yes — adds tools without changing existing APIs.
-
-#### 8.1 — `create_upsert_tool` — tool for upserting records into a collection
-#### 8.2 — `create_get_tool` — tool for retrieving records by key
-- Key-based lookup only (by primary key), not a search tool
-- Documentation must clearly distinguish this from `create_search_tool`: get_tool retrieves specific records by their known key, while search_tool performs similarity/filtered search across the collection
-- Consider if this overlaps with filtered search and document when to use which
-#### 8.3 — `create_delete_tool` — tool for deleting records by key
-#### 8.4 — Tests and samples for CRUD tools
-
----
-
-### Phase 9: Additional Embedding Implementations (New Providers)
-**Goal:** Provide embedding generators for providers that don't yet have AF packages.
-**Mergeable:** Yes — each is independent, new packages.
-
-#### 9.1 — HuggingFace/ONNX embedding (new package or lab)
-#### 9.2 — Mistral AI embedding (new package)
-#### 9.3 — Google AI / Vertex AI embedding (new package)
-#### 9.4 — Nvidia embedding (new package)
-
----
-
-### Phase 10: TextSearch Abstractions & Implementations (Separate Work)
-**Goal:** Port text search (non-vector) abstractions and implementations.
-**Mergeable:** Yes — independent of vector stores.
-
-#### 10.1 — TextSearch base class and types
-- `SearchOptions`, `SearchResponse`, `TextSearchResult`
-- `TextSearch` base class with `search()` method
-- `create_search_function()` for kernel integration (may need AF equivalent)
-
-#### 10.2 — Brave Search implementation
-#### 10.3 — Google Search implementation
-#### 10.4 — Vector store text search bridge (connecting VectorSearch to TextSearch interface)
-
----
-
-## Key Considerations
-
-1. **No Pydantic for internal classes**: All AF internal classes should use plain classes. Pydantic is only used for user-facing input validation (e.g., vector store data models).
-
-2. **Protocol + Base class**: Follow AF's pattern of both a `Protocol` for duck-typing and a `Base` ABC for implementation, matching how `SupportsChatGetResponse` + `BaseChatClient` works.
-
-3. **Exception hierarchy**: Use AF's `IntegrationException` branch for vector store operations, since vector stores are external dependencies.
-
-4. **`from __future__ import annotations`**: Required in all files per AF coding standard.
-
-5. **No `**kwargs` escape hatches in public APIs**: For user-facing interfaces, use explicit named parameters per AF coding standard. Internal implementation details (e.g., cooperative multiple inheritance / MRO patterns) may use `**kwargs` where necessary, as long as they are not exposed in public signatures.
-
-6. **Lazy loading**: Connector packages use `__getattr__` lazy loading in core provider folders.
-
-7. **Reusable data models**: The `@vectorstoremodel` decorator and `VectorStoreCollectionDefinition` should be agnostic enough to work with both SK and AF. The core types (`FieldTypes`, `IndexKind`, `DistanceFunction`, `VectorStoreField`) should be identical or easily mapped.
-
-8. **`create_search_tool`**: The AF-native equivalent of SK's `create_search_function`. Instead of creating a `KernelFunction`, this creates an AF `FunctionTool` (via the `@tool` decorator pattern) from a vector search. This allows agents to use vector search as a tool during conversations. Design:
-   - `create_search_tool(name, description, search_type, ...)` → returns a `FunctionTool` that wraps `VectorSearch.search(search_type=...)`
-   - The tool accepts a query string, performs embedding + vector search, and returns results as strings
-   - Supports configurable string mappers, filter functions, top/skip defaults
-   - Lives in `_vectors.py` as a method on `BaseVectorSearch` and/or as a standalone factory function
-
-9. **CRUD tools**: A full set of create/read/update/delete tools for vector store collections, allowing agents to manage data in vector stores. Design:
-   - `create_upsert_tool(...)` → tool for upserting records
-   - `create_get_tool(...)` → tool for retrieving records by key
-   - `create_delete_tool(...)` → tool for deleting records
-   - These are separate from search and are placed in a later phase
-
-10. **Score threshold filtering**: `SearchOptions` includes `score_threshold: float | None` to filter search results by relevance score (ref: [SK .NET PR #13501](https://github.com/microsoft/semantic-kernel/pull/13501)). The semantics depend on the distance function: for similarity functions (cosine similarity, dot product), results *below* the threshold are filtered out; for distance functions (cosine distance, euclidean), results *above* the threshold are filtered out. Use `DISTANCE_FUNCTION_DIRECTION_HELPER` to determine direction. Connectors should implement this natively where the database supports it, falling back to client-side post-filtering otherwise.

dotnet/.github/skills/build-and-test/SKILL.md

@@ -1,130 +0,0 @@
----
-name: build-and-test
-description: How to build and test .NET projects in the Agent Framework repository. Use this when verifying or testing changes.
----
-
-- Only **UnitTest** projects need to be run locally; IntegrationTests require external dependencies.
-- See `../project-structure/SKILL.md` for project structure details.
-
-## Build, Test, and Lint Commands
-
-```bash
-# From dotnet/ directory
-dotnet restore --tl:off   # Restore dependencies for all projects
-dotnet build --tl:off     # Build all projects
-dotnet test               # Run all tests
-dotnet format             # Auto-fix formatting for all projects
-
-# Build/test/format a specific project (preferred for isolated/internal changes)
-dotnet build src/Microsoft.Agents.AI.<Package> --tl:off
-dotnet test --project tests/Microsoft.Agents.AI.<Package>.UnitTests
-dotnet format src/Microsoft.Agents.AI.<Package>
-
-# Run a single test
-# Replace the filter values with the appropriate assembly, namespace, class, and method names for the test you want to run and use * as a wildcard elsewhere, e.g. "/*/*/HttpClientTests/GetAsync_ReturnsSuccessStatusCode"
-# Use `--ignore-exit-code 8` to avoid failing the build when no tests are found for some projects
-dotnet test --filter-query "/<assemblyFilter>/<namespaceFilter>/<classFilter>/<methodFilter>" --ignore-exit-code 8
-
-# Run unit tests only
-# Use `--ignore-exit-code 8` to avoid failing the build when no tests are found for integration test projects
-dotnet test --filter-query "/*UnitTests*/*/*/*" --ignore-exit-code 8
-```
-
-Use `--tl:off` when building to avoid flickering when running commands in the agent.
-
-## Speeding Up Builds and Testing
-
-The full solution is large. Use these shortcuts:
-
-| Change type | What to do |
-|-------------|------------|
-| Isolated/Internal logic | Build only the affected project and its `*.UnitTests` project. Fix issues, then build the full solution and run all unit tests. |
-| Public API surface | Build the full solution and run all unit tests immediately. |
-
-Example: Building a single code project for all target frameworks
-
-```bash
-# From dotnet/ directory
-dotnet build ./src/Microsoft.Agents.AI.Abstractions
-```
-
-Example: Building a single code project for just .NET 10.
-
-```bash
-# From dotnet/ directory
-dotnet build ./src/Microsoft.Agents.AI.Abstractions -f net10.0
-```
-
-Example: Running tests for a single project using .NET 10.
-
-```bash
-# From dotnet/ directory
-dotnet test --project ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0
-```
-
-Example: Running a single test in a specific project using .NET 10.
-Provide the full namespace, class name, and method name for the test you want to run:
-
-```bash
-# From dotnet/ directory
-dotnet test --project ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0 --filter-query "/*/Microsoft.Agents.AI.Abstractions.UnitTests/AgentRunOptionsTests/CloningConstructorCopiesProperties"
-```
-
-### Multi-target framework tip
-
-Most projects target multiple .NET frameworks. If the affected code does **not** use `#if` directives for framework-specific logic, pass `-f net10.0` to speed up building and testing.
-
-### Package Restore tip
-
-`dotnet build` will try and restore packages for all projects on each build, which can be slow.
-Unless packages have been changed, or it's the first time building the solution, add `--no-restore` to the build command to skip this step and speed up builds.
-
-Just remember to run `dotnet restore` after pulling changes, making changes to project references, or when building for the first time.
-
-### Testing on Linux tip
-
-Unit tests target both .NET Framework as well as .NET Core. When running on Linux, only the .NET Core tests can be run, as .NET Framework is not supported on Linux.
-
-To run only the .NET Core tests, use the `-f net10.0` option with `dotnet test`.
-
-### Microsoft Testing Platform (MTP)
-
-Tests use the [Microsoft Testing Platform](https://learn.microsoft.com/dotnet/core/testing/unit-testing-platform-intro) via xUnit v3. Key differences from the legacy VSTest runner:
-
-- **`dotnet test` requires `--project`** to specify a test project directly (positional arguments are no longer supported).
-- **Test output** uses the MTP format (e.g., `[✓112/x0/↓0]` progress and `Test run summary: Passed!`).
-- **TRX reports** use `--report-xunit-trx` instead of `--logger trx`.
-- **Code coverage** uses `Microsoft.Testing.Extensions.CodeCoverage` with `--coverage --coverage-output-format cobertura`.
-- **Running a test project directly** is supported via `dotnet run --project <test-project>`. This bypasses the `dotnet test` infrastructure and runs the test executable directly with the MTP command line.
-
-- **Running tests across the solution** with a filter may cause some projects to match zero tests, which MTP treats as a failure (exit code 8). Use `--ignore-exit-code 8` to suppress this:
-
-```bash
-# Run all unit tests across the solution, ignoring projects with no matching tests
-dotnet test --solution ./agent-framework-dotnet.slnx --no-build -f net10.0 --ignore-exit-code 8
-```
-
-- **Running tests with `--solution` for a specific TFM** requires all projects in the solution to support that TFM. Not all projects target every framework (e.g., some are `net10.0`-only). Use `./dotnet/eng/scripts/New-FilteredSolution.ps1` to generate a filtered solution:
-
-```powershell
-# Generate a filtered solution for net472 and run tests
-$filtered = ./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net472
-dotnet test --solution $filtered --no-build -f net472 --ignore-exit-code 8
-
-# Exclude samples and keep only unit test projects
-./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net10.0 -ExcludeSamples -TestProjectNameFilter "*UnitTests*" -OutputPath dotnet/filtered-unit.slnx
-```
-
-```bash
-# Run tests via dotnet test (uses MTP under the hood)
-dotnet test --project ./tests/Microsoft.Agents.AI.UnitTests -f net10.0
-
-# Run tests with code coverage (Cobertura format)
-dotnet test --project ./tests/Microsoft.Agents.AI.UnitTests -f net10.0 --coverage --coverage-output-format cobertura --coverage-settings ./tests/coverage.runsettings
-
-# Run tests directly via dotnet run (MTP native command line)
-dotnet run --project ./tests/Microsoft.Agents.AI.UnitTests -f net10.0
-
-# Show MTP command line help
-dotnet run --project ./tests/Microsoft.Agents.AI.UnitTests -f net10.0 -- -?
-```

dotnet/.github/skills/project-structure/SKILL.md

@@ -1,31 +0,0 @@
----
-name: project-structure
-description: Explains the project structure of the agent-framework .NET solution
----
-
-# Agent Framework .NET Project Structure
-
-```
-dotnet/
-├── src/
-│   ├── Microsoft.Agents.AI/                      # Core AI agent implementations
-│   ├── Microsoft.Agents.AI.Abstractions/         # Core AI agent abstractions
-│   ├── Microsoft.Agents.AI.A2A/                  # Agent-to-Agent (A2A) provider
-│   ├── Microsoft.Agents.AI.OpenAI/               # OpenAI provider
-│   ├── Microsoft.Agents.AI.AzureAI/              # Azure AI Foundry Agents (v2) provider
-│   ├── Microsoft.Agents.AI.AzureAI.Persistent/   # Legacy Azure AI Foundry Agents (v1) provider
-│   ├── Microsoft.Agents.AI.Anthropic/            # Anthropic provider
-│   ├── Microsoft.Agents.AI.Workflows/            # Workflow orchestration
-│   └── ...                                       # Other packages
-├── samples/                                      # Sample applications
-└── tests/                                        # Unit and integration tests
-```
-
-## Main Folders
-
-| Folder | Contents |
-|--------|----------|
-| `src/` | Source code projects |
-| `tests/` | Test projects — named `<Source-Code-Project>.UnitTests` or `<Source-Code-Project>.IntegrationTests` |
-| `samples/` | Sample projects |
-| `src/Shared`, `src/LegacySupport` | Shared code files included by multiple source code projects (see README.md files in these folders or their subdirectories for instructions on how to include them in a project) |

dotnet/.github/skills/verify-dotnet-samples/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify-dotnet-samples
-description: How to build, run and verify the .NET sample projects in the Agent Framework repository. Use this when a user wants to verify that the samples still function as expected.
+description: > How to build, run and verify the .NET sample projects in the Agent Framework repository. Use this when a user wants to verify that the samples still function as expected.
 ---
 
 # Verifying .NET Sample Projects

dotnet/.vscode/settings.json

@@ -1,6 +1,5 @@
 {
     "dotnet.defaultSolution": "agent-framework-dotnet.slnx",
     "git.openRepositoryInParentFolders": "always",
-    "chat.agent.enabled": true,
-    "dotnet.automaticallySyncWithActiveItem": true
+    "chat.agent.enabled": true
 }

dotnet/AGENTS.md

@@ -4,32 +4,44 @@ Instructions for AI coding agents working in the .NET codebase.
 
 ## Build, Test, and Lint Commands
 
-See `./.github/skills/build-and-test/SKILL.md` for detailed instructions on building, testing, and linting projects.
+```bash
+# From dotnet/ directory
+dotnet build              # Build all projects
+dotnet test               # Run all tests
+dotnet format             # Auto-fix formatting
+
+# Build/test a specific project (preferred for isolated changes)
+dotnet build src/Microsoft.Agents.AI.<Package>
+dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests
+
+# Run a single test
+dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"
+```
+
+**Note**: Changes to core packages (`Microsoft.Agents.AI`, `Microsoft.Agents.AI.Abstractions`) affect dependent projects - run checks across the entire solution. For isolated changes, build/test only the affected project to save time.
 
 ## Project Structure
 
-See `./.github/skills/project-structure/SKILL.md` for an overview of the project structure.
-
-### Core types
-
-- `AIAgent`: The abstract base class that all agents derive from, providing common methods for interacting with an agent.
-- `AgentSession`: The abstract base class that all agent sessions derive from, representing a conversation with an agent.
-- `ChatClientAgent`: An `AIAgent` implementation that uses an `IChatClient` to send messages to an AI provider and receive responses.
-- `IChatClient`: Interface for sending messages to an AI provider and receiving responses. Used by `ChatClientAgent` and implemented by provider-specific packages.
-- `FunctionInvokingChatClient`: Decorator for `IChatClient` that adds function invocation capabilities.
-- `AITool`: Represents a tool that an agent/AI provider can use, with metadata and an execution delegate.
-- `AIFunction`: A specific type of `AITool` that represents a local function the agent/AI provider can call, with parameters and return types defined.
-- `ChatMessage`: Represents a message in a conversation.
-- `AIContent`: Represents content in a message, which can be text, a function call, tool output and more.
+```
+dotnet/
+├── src/
+│   ├── Microsoft.Agents.AI/              # Core AI agent abstractions
+│   ├── Microsoft.Agents.AI.Abstractions/ # Shared abstractions and interfaces
+│   ├── Microsoft.Agents.AI.OpenAI/       # OpenAI provider
+│   ├── Microsoft.Agents.AI.AzureAI/      # Azure AI provider
+│   ├── Microsoft.Agents.AI.Anthropic/    # Anthropic provider
+│   ├── Microsoft.Agents.AI.Workflows/    # Workflow orchestration
+│   └── ...                               # Other packages
+├── samples/                              # Sample applications
+└── tests/                                # Unit and integration tests
+```
 
 ### External Dependencies
 
-The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages)
-using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, `AIFunction`, `ChatMessage`, and `AIContent`.
+The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages) using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, and `AIContent`.
 
 ## Key Conventions
 
-- **Encoding**: All new files must be saved with UTF-8 encoding with BOM (Byte Order Mark). This is required for `dotnet format` to work correctly.
 - **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
 - **XML docs**: Required for all public methods and classes
 - **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask`
@@ -37,19 +49,8 @@ using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, `AIFunct
 - **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming
 - **Tests**: Add Arrange/Act/Assert comments; use Moq for mocking
 
-## Key Design Principles
-
-When developing or reviewing code, verify adherence to these key design principles:
-
-- **DRY**: Avoid code duplication by moving common logic into helper methods or helper classes.
-- **Single Responsibility**: Each class should have one clear responsibility.
-- **Encapsulation**: Keep implementation details private and expose only necessary public APIs.
-- **Strong Typing**: Use strong typing to ensure that code is self-documenting and to catch errors at compile time.
-
 ## Sample Structure
 
-Samples (in `./samples/` folder) should follow this structure:
-
 1. Copyright header: `// Copyright (c) Microsoft. All rights reserved.`
 2. Description comment explaining what the sample demonstrates
 3. Using statements
@@ -59,7 +60,6 @@ Samples (in `./samples/` folder) should follow this structure:
 Configuration via environment variables (never hardcode secrets). Keep samples simple and focused.
 
 When adding a new sample:
-
 - Create a standalone project in `samples/` with matching directory and project names
 - Include a README.md explaining what the sample does and how to run it
 - Add the project to the solution file

dotnet/Directory.Packages.props

@@ -11,18 +11,19 @@
   </PropertyGroup>
   <ItemGroup>
     <!-- Aspire.* -->
-    <PackageVersion Include="Anthropic" Version="12.8.0" />
-    <PackageVersion Include="Anthropic.Foundry" Version="0.4.2" />
+    <PackageVersion Include="Anthropic" Version="12.3.0" />
+    <PackageVersion Include="Anthropic.Foundry" Version="0.4.1" />
     <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
     <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
     <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0-beta.2" />
-    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
-    <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
-    <PackageVersion Include="Azure.Identity" Version="1.19.0" />
+    <PackageVersion Include="Azure.AI.Projects" Version="1.2.0-beta.5" />
+    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="1.0.0-beta.5" />
+    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.8" />
+    <PackageVersion Include="Azure.AI.OpenAI" Version="2.8.0-beta.1" />
+    <PackageVersion Include="Azure.Identity" Version="1.17.1" />
     <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.4.0" />
     <!-- Google Gemini  -->
     <PackageVersion Include="Google.GenAI" Version="0.11.0" />
@@ -32,19 +33,18 @@
     <!-- Newtonsoft.Json -->
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
     <!-- System.* -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.4" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
-    <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.4" />
-    <PackageVersion Include="System.ClientModel" Version="1.9.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.8.1" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.4" />
-    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.4" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.3" />
+    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.0" />
     <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.4" />
-    <PackageVersion Include="System.Text.Json" Version="10.0.4" />
-    <PackageVersion Include="System.Threading.Channels" Version="10.0.4" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.1" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.3" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.3" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
     <!-- OpenTelemetry -->
@@ -58,30 +58,24 @@
     <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
     <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
     <!-- Microsoft.AspNetCore.* -->
-    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.4.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.4.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.4.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.4.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.3.0-preview.1.26109.11" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.4.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.3.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.4.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.4" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.4" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.3" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
@@ -95,30 +89,29 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.29" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.23" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
     <PackageVersion Include="Microsoft.Agents.Authentication.Msal" Version="1.3.171-beta" />
     <PackageVersion Include="Microsoft.Agents.Hosting.AspNetCore" Version="1.3.171-beta" />
     <!-- A2A -->
-    <PackageVersion Include="A2A" Version="0.3.4-preview" />
-    <PackageVersion Include="A2A.AspNetCore" Version="0.3.4-preview" />
+    <PackageVersion Include="A2A" Version="0.3.3-preview" />
+    <PackageVersion Include="A2A.AspNetCore" Version="0.3.3-preview" />
     <!-- MCP -->
-    <PackageVersion Include="ModelContextProtocol" Version="1.1.0" />
+    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
     <!-- Inference SDKs -->
     <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.5.1" />
     <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
-    <PackageVersion Include="Microsoft.ML.Tokenizers" Version="2.0.0" />
     <PackageVersion Include="OllamaSharp" Version="5.4.8" />
-    <PackageVersion Include="OpenAI" Version="2.9.1" />
+    <PackageVersion Include="OpenAI" Version="2.8.0" />
     <!-- Identity -->
-    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.83.1" />
+    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
     <!-- Workflows -->
-    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.2.4.1" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.4.1" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.2.4.1" />
-    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.8.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.1.2.3" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.1.2.3" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.1.2.3" />
+    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.5.0-build.20251008-1002" />
     <!-- Durable Task -->
     <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.18.0" />
     <PackageVersion Include="Microsoft.DurableTask.Client.AzureManaged" Version="1.18.0" />
@@ -127,7 +120,7 @@
     <!-- Azure Functions -->
     <PackageVersion Include="Microsoft.Azure.Functions.Worker" Version="2.50.0" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="2.50.0" />
-    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.12.1" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.11.0" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" Version="1.0.1" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.3.0" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="2.1.0" />
@@ -142,14 +135,15 @@
     <PackageVersion Include="Microsoft.AspNetCore.TestHost" Condition="'$(TargetFramework)' == 'net10.0'" Version="10.0.0" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.0" />
     <PackageVersion Include="Moq" Version="[4.18.4]" />
-    <PackageVersion Include="xunit.v3.mtp-v2" Version="3.2.2" />
-    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
-    <PackageVersion Include="xRetry.v3" Version="1.0.0-rc3" />
-    <PackageVersion Include="Microsoft.Testing.Extensions.CodeCoverage" Version="18.4.1" />
+    <PackageVersion Include="xunit" Version="2.9.3" />
+    <PackageVersion Include="xunit.abstractions" Version="2.0.3" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.3" />
+    <PackageVersion Include="Xunit.SkippableFact" Version="1.5.23" />
+    <PackageVersion Include="xretry" Version="1.9.0" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.4" />
     <!-- Symbols -->
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <!-- Toolset -->
-    <PackageVersion Include="ReferenceTrimmer" Version="3.4.5" />
     <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.100" />
@@ -188,4 +182,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/README.md

@@ -1,20 +1,26 @@
 # Get Started with Microsoft Agent Framework for C# Developers
 
+## Samples
+
+- [Getting Started with Agents](./samples/GettingStarted/Agents): basic agent creation and tool usage
+- [Agent Provider Samples](./samples/GettingStarted/AgentProviders): samples showing different agent providers
+- [Workflow Samples](./samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
+
 ## Quickstart
 
 ### Basic Agent - .NET
 
 ```c#
+using System;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI.Responses;
 
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")!;
 
 var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
-    .GetResponsesClient(deploymentName)
+    .GetOpenAIResponseClient(deploymentName)
     .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
@@ -22,9 +28,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 
 ## Examples & Samples
 
-- [Getting Started with Agents](./samples/02-agents/Agents): basic agent creation and tool usage
-- [Agent Provider Samples](./samples/02-agents/AgentProviders): samples showing different agent providers
-- [Workflow Samples](./samples/03-workflows): advanced multi-agent patterns and workflow orchestration
+- [Getting Started with Agents](./samples/GettingStarted/Agents): basic agent creation and tool usage
+- [Agent Provider Samples](./samples/GettingStarted/AgentProviders): samples showing different agent providers
+- [Workflow Samples](./samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
 
 ## Agent Framework Documentation
 

dotnet/agent-framework-dotnet.slnx

@@ -1,216 +1,220 @@
-<Solution>
+<Solution>
   <Configurations>
     <BuildType Name="Debug" />
     <BuildType Name="Publish" />
     <BuildType Name="Release" />
   </Configurations>
   <Folder Name="/Samples/">
-    <File Path="samples/AGENTS.md" />
     <File Path="samples/README.md" />
   </Folder>
-  <Folder Name="/Samples/01-get-started/">
-    <Project Path="samples/01-get-started/01_hello_agent/01_hello_agent.csproj" />
-    <Project Path="samples/01-get-started/02_add_tools/02_add_tools.csproj" />
-    <Project Path="samples/01-get-started/03_multi_turn/03_multi_turn.csproj" />
-    <Project Path="samples/01-get-started/04_memory/04_memory.csproj" />
-    <Project Path="samples/01-get-started/05_first_workflow/05_first_workflow.csproj" />
-    <Project Path="samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj" />
+  <Folder Name="/Samples/A2AClientServer/">
+    <File Path="samples/A2AClientServer/README.md" />
+    <Project Path="samples/A2AClientServer/A2AClient/A2AClient.csproj" />
+    <Project Path="samples/A2AClientServer/A2AServer/A2AServer.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/">
-    <File Path="samples/02-agents/README.md" />
+  <Folder Name="/Samples/AgentWebChat/">
+    <Project Path="samples/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
+    <Project Path="samples/AgentWebChat/AgentWebChat.AppHost/AgentWebChat.AppHost.csproj" />
+    <Project Path="samples/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
+    <Project Path="samples/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentProviders/">
-    <File Path="samples/02-agents/AgentProviders/README.md" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIAssistants/Agent_With_OpenAIAssistants.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
+  <Folder Name="/Samples/AGUIClientServer/">
+    <Project Path="samples/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
+    <Project Path="samples/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
+    <Project Path="samples/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/Agents/">
-    <File Path="samples/02-agents/Agents/README.md" />
-    <Project Path="samples/02-agents/Agents/Agent_Step01_UsingFunctionToolsWithApprovals/Agent_Step01_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step02_StructuredOutput/Agent_Step02_StructuredOutput.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step03_PersistedConversations/Agent_Step03_PersistedConversations.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step04_3rdPartyChatHistoryStorage/Agent_Step04_3rdPartyChatHistoryStorage.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step05_Observability/Agent_Step05_Observability.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step06_DependencyInjection/Agent_Step06_DependencyInjection.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step07_AsMcpTool/Agent_Step07_AsMcpTool.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step08_UsingImages/Agent_Step08_UsingImages.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step09_AsFunctionTool/Agent_Step09_AsFunctionTool.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step10_BackgroundResponsesWithToolsAndPersistence/Agent_Step10_BackgroundResponsesWithToolsAndPersistence.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step11_Middleware/Agent_Step11_Middleware.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step12_Plugins/Agent_Step12_Plugins.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step13_ChatReduction/Agent_Step13_ChatReduction.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step14_BackgroundResponses/Agent_Step14_BackgroundResponses.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step15_DeepResearch/Agent_Step15_DeepResearch.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step16_Declarative/Agent_Step16_Declarative.csproj" />
-    <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" />
+  <Folder Name="/Samples/Durable/" />
+  <Folder Name="/Samples/Durable/Agents/" />
+  <Folder Name="/Samples/Durable/Agents/AzureFunctions/">
+    <File Path="samples/Durable/Agents/AzureFunctions/.editorconfig" />
+    <File Path="samples/Durable/Agents/AzureFunctions/README.md" />
+    <Project Path="samples/Durable/Agents/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
+    <Project Path="samples/Durable/Agents/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/Durable/Agents/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/Durable/Agents/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/Durable/Agents/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/Durable/Agents/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
+    <Project Path="samples/Durable/Agents/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
+    <Project Path="samples/Durable/Agents/AzureFunctions/08_ReliableStreaming/08_ReliableStreaming.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/DeclarativeAgents/">
-    <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
-  </Folder>
-  <Folder Name="/Samples/04-hosting/DurableWorkflows/" />
-  <Folder Name="/Samples/04-hosting/DurableWorkflows/ConsoleApps/">
-    <Project Path="samples/04-hosting/DurableWorkflows/ConsoleApps/01_SequentialWorkflow/01_SequentialWorkflow.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/ConsoleApps/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/ConsoleApps/03_ConditionalEdges/03_ConditionalEdges.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/ConsoleApps/04_WorkflowAndAgents/04_WorkflowAndAgents.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/ConsoleApps/05_WorkflowEvents/05_WorkflowEvents.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/ConsoleApps/06_WorkflowSharedState/06_WorkflowSharedState.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/ConsoleApps/07_SubWorkflows/07_SubWorkflows.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/ConsoleApps/08_WorkflowHITL/08_WorkflowHITL.csproj" />
-  </Folder>
-  <Folder Name="/Samples/04-hosting/DurableWorkflows/AzureFunctions/">
-    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/01_SequentialWorkflow/01_SequentialWorkflow.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/02_ConcurrentWorkflow/02_ConcurrentWorkflow.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/03_WorkflowHITL/03_WorkflowHITL.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/04_WorkflowMcpTool/04_WorkflowMcpTool.csproj" />
-    <Project Path="samples/04-hosting/DurableWorkflows/AzureFunctions/05_WorkflowAndAgents/05_WorkflowAndAgents.csproj" />
+  <Folder Name="/Samples/Durable/Agents/ConsoleApps/">
+    <File Path="samples/Durable/Agents/ConsoleApps/README.md" />
+    <Project Path="samples/Durable/Agents/ConsoleApps/01_SingleAgent/01_SingleAgent.csproj" />
+    <Project Path="samples/Durable/Agents/ConsoleApps/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/Durable/Agents/ConsoleApps/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/Durable/Agents/ConsoleApps/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/Durable/Agents/ConsoleApps/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/Durable/Agents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
+    <Project Path="samples/Durable/Agents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/">
     <File Path="samples/GettingStarted/README.md" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/">
-    <File Path="samples/02-agents/AGUI/README.md" />
+  <Folder Name="/Samples/GettingStarted/A2A/">
+    <File Path="samples/GettingStarted/A2A/README.md" />
+    <Project Path="samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step01_GettingStarted/">
-    <Project Path="samples/02-agents/AGUI/Step01_GettingStarted/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step01_GettingStarted/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentProviders/">
+    <File Path="samples/GettingStarted/AgentProviders/README.md" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIAssistants/Agent_With_OpenAIAssistants.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step02_BackendTools/">
-    <Project Path="samples/02-agents/AGUI/Step02_BackendTools/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step02_BackendTools/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/Agents/">
+    <File Path="samples/GettingStarted/Agents/README.md" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step01_Running/Agent_Step01_Running.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step02_MultiturnConversation/Agent_Step02_MultiturnConversation.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step03_UsingFunctionTools/Agent_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step04_UsingFunctionToolsWithApprovals/Agent_Step04_UsingFunctionToolsWithApprovals.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Agent_Step05_StructuredOutput.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step06_PersistedConversations/Agent_Step06_PersistedConversations.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step07_3rdPartyChatHistoryStorage/Agent_Step07_3rdPartyChatHistoryStorage.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step08_Observability/Agent_Step08_Observability.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step09_DependencyInjection/Agent_Step09_DependencyInjection.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/Agent_Step10_AsMcpTool.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step11_UsingImages/Agent_Step11_UsingImages.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step12_AsFunctionTool/Agent_Step12_AsFunctionTool.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step13_BackgroundResponsesWithToolsAndPersistence/Agent_Step13_BackgroundResponsesWithToolsAndPersistence.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step14_Middleware/Agent_Step14_Middleware.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step15_Plugins/Agent_Step15_Plugins.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Agent_Step16_ChatReduction.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Agent_Step17_BackgroundResponses.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step18_DeepResearch/Agent_Step18_DeepResearch.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step20_AdditionalAIContext/Agent_Step20_AdditionalAIContext.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step03_FrontendTools/">
-    <Project Path="samples/02-agents/AGUI/Step03_FrontendTools/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step03_FrontendTools/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/DeclarativeAgents/">
+    <Project Path="samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step04_HumanInLoop/">
-    <Project Path="samples/02-agents/AGUI/Step04_HumanInLoop/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step04_HumanInLoop/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/">
+    <File Path="samples/GettingStarted/AGUI/README.md" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentSkills/">
-    <File Path="samples/02-agents/AgentSkills/README.md" />
-    <Project Path="samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/Agent_Step01_FileBasedSkills.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step01_GettingStarted/">
+    <Project Path="samples/GettingStarted/AGUI/Step01_GettingStarted/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step01_GettingStarted/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
-    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step02_BackendTools/">
+    <Project Path="samples/GettingStarted/AGUI/Step02_BackendTools/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step02_BackendTools/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/DevUI/">
-    <File Path="samples/02-agents/DevUI/README.md" />
-    <Project Path="samples/02-agents/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step03_FrontendTools/">
+    <Project Path="samples/GettingStarted/AGUI/Step03_FrontendTools/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step03_FrontendTools/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithAnthropic/">
-    <File Path="samples/02-agents/AgentWithAnthropic/README.md" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step04_HumanInLoop/">
+    <Project Path="samples/GettingStarted/AGUI/Step04_HumanInLoop/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentsWithFoundry/">
-    <File Path="samples/02-agents/AgentsWithFoundry/README.md" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step00_FoundryAgentLifecycle/Agent_Step00_FoundryAgentLifecycle.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step01_Basics/Agent_Step01_Basics.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step02.1_MultiturnConversation/Agent_Step02.1_MultiturnConversation.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step02.2_MultiturnWithServerConversations/Agent_Step02.2_MultiturnWithServerConversations.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step03_UsingFunctionTools/Agent_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step04_UsingFunctionToolsWithApprovals/Agent_Step04_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step05_StructuredOutput/Agent_Step05_StructuredOutput.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step06_PersistedConversations/Agent_Step06_PersistedConversations.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step07_Observability/Agent_Step07_Observability.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step08_DependencyInjection/Agent_Step08_DependencyInjection.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step09_UsingMcpClientAsTools/Agent_Step09_UsingMcpClientAsTools.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step10_UsingImages/Agent_Step10_UsingImages.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step11_AsFunctionTool/Agent_Step11_AsFunctionTool.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step12_Middleware/Agent_Step12_Middleware.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step13_Plugins/Agent_Step13_Plugins.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step14_CodeInterpreter/Agent_Step14_CodeInterpreter.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step15_ComputerUse/Agent_Step15_ComputerUse.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step16_FileSearch/Agent_Step16_FileSearch.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step17_OpenAPITools/Agent_Step17_OpenAPITools.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step18_BingCustomSearch/Agent_Step18_BingCustomSearch.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step19_SharePoint/Agent_Step19_SharePoint.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step20_MicrosoftFabric/Agent_Step20_MicrosoftFabric.csproj" />
-    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step21_WebSearch/Agent_Step21_WebSearch.csproj" />
-    <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" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step05_StateManagement/">
+    <Project Path="samples/GettingStarted/AGUI/Step05_StateManagement/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step05_StateManagement/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithMemory/">
-    <File Path="samples/02-agents/AgentWithMemory/README.md" />
-    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
-    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
-    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj" />
-    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step05_BoundedChatHistory/AgentWithMemory_Step05_BoundedChatHistory.csproj" />
+  <Folder Name="/Samples/GettingStarted/DevUI/">
+    <File Path="samples/GettingStarted/DevUI/README.md" />
+    <Project Path="samples/GettingStarted/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithOpenAI/">
-    <File Path="samples/02-agents/AgentWithOpenAI/README.md" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentWithAnthropic/">
+    <File Path="samples/GettingStarted/AgentWithAnthropic/README.md" />
+    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithRAG/">
-    <File Path="samples/02-agents/AgentWithRAG/README.md" />
-    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj" />
-    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
-    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
-    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentWithMemory/">
+    <File Path="samples/GettingStarted/AgentWithMemory/README.md" />
+    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/AgentWithMemory_Step03_CustomMemory.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/ModelContextProtocol/">
-    <File Path="samples/02-agents/ModelContextProtocol/README.md" />
-    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
-    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
-    <Project Path="samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
-    <Project Path="samples/02-agents/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentWithOpenAI/">
+    <File Path="samples/GettingStarted/AgentWithOpenAI/README.md" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/Observability/">
-    <Project Path="samples/02-agents/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
+  <Folder Name="/Samples/Purview/" />
+  <Folder Name="/Samples/Purview/AgentWithPurview/">
+    <Project Path="samples/Purview/AgentWithPurview/AgentWithPurview.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/">
-    <File Path="samples/03-workflows/README.md" />
+  <Folder Name="/Samples/GettingStarted/AgentWithRAG/">
+    <File Path="samples/GettingStarted/AgentWithRAG/README.md" />
+    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Concurrent/">
-    <Project Path="samples/03-workflows/Concurrent/Concurrent/Concurrent.csproj" />
-    <Project Path="samples/03-workflows/Concurrent/MapReduce/MapReduce.csproj" />
+  <Folder Name="/Samples/GettingStarted/FoundryAgents/">
+    <File Path="samples/GettingStarted/FoundryAgents/README.md" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.1_Basics/FoundryAgents_Step01.1_Basics.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.2_Running/FoundryAgents_Step01.2_Running.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/FoundryAgents_Step02_MultiturnConversation.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/FoundryAgents_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/FoundryAgents_Step04_UsingFunctionToolsWithApprovals.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/FoundryAgents_Step05_StructuredOutput.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step06_PersistedConversations/FoundryAgents_Step06_PersistedConversations.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step07_Observability/FoundryAgents_Step07_Observability.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step08_DependencyInjection/FoundryAgents_Step08_DependencyInjection.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step09_UsingMcpClientAsTools/FoundryAgents_Step09_UsingMcpClientAsTools.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step10_UsingImages/FoundryAgents_Step10_UsingImages.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step11_AsFunctionTool/FoundryAgents_Step11_AsFunctionTool.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step12_Middleware/FoundryAgents_Step12_Middleware.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step13_Plugins/FoundryAgents_Step13_Plugins.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/FoundryAgents_Step14_CodeInterpreter.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/FoundryAgents_Step15_ComputerUse.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/ConditionalEdges/">
-    <Project Path="samples/03-workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj" />
-    <Project Path="samples/03-workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj" />
-    <Project Path="samples/03-workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj" />
+  <Folder Name="/Samples/GettingStarted/ModelContextProtocol/">
+    <File Path="samples/GettingStarted/ModelContextProtocol/README.md" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Declarative/">
-    <File Path="samples/03-workflows/Declarative/README.md" />
-    <Project Path="samples/03-workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
-    <Project Path="samples/03-workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
-    <Project Path="samples/03-workflows/Declarative/DeepResearch/DeepResearch.csproj" />
-    <Project Path="samples/03-workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
-    <Project Path="samples/03-workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
-    <Project Path="samples/03-workflows/Declarative/FunctionTools/FunctionTools.csproj" />
-    <Project Path="samples/03-workflows/Declarative/GenerateCode/GenerateCode.csproj" />
-    <Project Path="samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
-    <Project Path="samples/03-workflows/Declarative/InputArguments/InputArguments.csproj" />
-    <Project Path="samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
-    <Project Path="samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj" />
-    <Project Path="samples/03-workflows/Declarative/Marketing/Marketing.csproj" />
-    <Project Path="samples/03-workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
-    <Project Path="samples/03-workflows/Declarative/ToolApproval/ToolApproval.csproj" />
+  <Folder Name="/Samples/GettingStarted/Observability/">
+    <Project Path="samples/GettingStarted/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Declarative/Examples/">
+  <Folder Name="/Samples/GettingStarted/Workflows/">
+    <File Path="samples/GettingStarted/Workflows/README.md" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Concurrent/">
+    <Project Path="samples/GettingStarted/Workflows/Concurrent/Concurrent/Concurrent.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Concurrent/MapReduce/MapReduce.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/ConditionalEdges/">
+    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/">
+    <File Path="samples/GettingStarted/Workflows/Declarative/README.md" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/DeepResearch/DeepResearch.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/FunctionTools/FunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/GenerateCode/GenerateCode.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/InputArguments/InputArguments.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/Marketing/Marketing.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/ToolApproval/ToolApproval.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/Examples/">
     <File Path="../workflow-samples/CustomerSupport.yaml" />
     <File Path="../workflow-samples/DeepResearch.yaml" />
     <File Path="../workflow-samples/Marketing.yaml" />
@@ -218,118 +222,60 @@
     <File Path="../workflow-samples/README.md" />
     <File Path="../workflow-samples/wttr.json" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/SharedStates/">
-    <Project Path="samples/03-workflows/SharedStates/SharedStates.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/SharedStates/">
+    <Project Path="samples/GettingStarted/Workflows/SharedStates/SharedStates.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Loop/">
-    <Project Path="samples/03-workflows/Loop/Loop.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Loop/">
+    <Project Path="samples/GettingStarted/Workflows/Loop/Loop.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Agents/">
-    <Project Path="samples/03-workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj" />
-    <Project Path="samples/03-workflows/Agents/FoundryAgent/FoundryAgent.csproj" />
-    <Project Path="samples/03-workflows/Agents/GroupChatToolApproval/GroupChatToolApproval.csproj" />
-    <Project Path="samples/03-workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Agents/">
+    <Project Path="samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Agents/FoundryAgent/FoundryAgent.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Agents/GroupChatToolApproval/GroupChatToolApproval.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Checkpoint/">
-    <Project Path="samples/03-workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj" />
-    <Project Path="samples/03-workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj" />
-    <Project Path="samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Checkpoint/">
+    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/HumanInTheLoop/">
-    <Project Path="samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/HumanInTheLoop/">
+    <Project Path="samples/GettingStarted/Workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Observability/">
-    <Project Path="samples/03-workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
-    <Project Path="samples/03-workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
-    <Project Path="samples/03-workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Observability/">
+    <Project Path="samples/GettingStarted/Workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Visualization/">
-    <Project Path="samples/03-workflows/Visualization/Visualization.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Visualization/">
+    <Project Path="samples/GettingStarted/Workflows/Visualization/Visualization.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/_StartHere/">
-    <Project Path="samples/03-workflows/_StartHere/01_Streaming/01_Streaming.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/02_AgentsInWorkflows/02_AgentsInWorkflows.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/03_AgentWorkflowPatterns.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/04_MultiModelService/04_MultiModelService.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/05_SubWorkflows/05_SubWorkflows.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/06_MixedWorkflowAgentsAndExecutors/06_MixedWorkflowAgentsAndExecutors.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/07_WriterCriticWorkflow/07_WriterCriticWorkflow.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/_Foundational/">
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/01_ExecutorsAndEdges/01_ExecutorsAndEdges.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/02_Streaming/02_Streaming.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/03_AgentsInWorkflows/03_AgentsInWorkflows.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/04_AgentWorkflowPatterns/04_AgentWorkflowPatterns.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/05_MultiModelService/05_MultiModelService.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/06_SubWorkflows/06_SubWorkflows.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/07_MixedWorkflowAgentsAndExecutors/07_MixedWorkflowAgentsAndExecutors.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/08_WriterCriticWorkflow.csproj" />
   </Folder>
-  <Folder Name="/Samples/04-hosting/" />
-  <Folder Name="/Samples/04-hosting/DurableAgents/" />
-  <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
-    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/.editorconfig" />
-    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/README.md" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/08_ReliableStreaming/08_ReliableStreaming.csproj" />
+  <Folder Name="/Samples/HostedAgents/">
+    <Project Path="samples/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
+    <Project Path="samples/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
+    <Project Path="samples/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
   </Folder>
-  <Folder Name="/Samples/04-hosting/DurableAgents/ConsoleApps/">
-    <File Path="samples/04-hosting/DurableAgents/ConsoleApps/README.md" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/01_SingleAgent/01_SingleAgent.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
-  </Folder>
-  <Folder Name="/Samples/04-hosting/A2A/">
-    <File Path="samples/04-hosting/A2A/README.md" />
-    <Project Path="samples/04-hosting/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
-    <Project Path="samples/04-hosting/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
-  </Folder>  
-  <Folder Name="/Samples/05-end-to-end/">
-    <Project Path="samples/05-end-to-end/AgentWithPurview/AgentWithPurview.csproj" />
-    <Project Path="samples/05-end-to-end/M365Agent/M365Agent.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/A2AClientServer/">
-    <File Path="samples/05-end-to-end/A2AClientServer/README.md" />
-    <Project Path="samples/05-end-to-end/A2AClientServer/A2AClient/A2AClient.csproj" />
-    <Project Path="samples/05-end-to-end/A2AClientServer/A2AServer/A2AServer.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/AgentWebChat/">
-    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
-    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.AppHost/AgentWebChat.AppHost.csproj" />
-    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
-    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/AGUIClientServer/">
-    <File Path="samples/05-end-to-end/AGUIClientServer/README.md" />
-    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
-    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
-    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/HostedAgents/">
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentThreadAndHITL/AgentThreadAndHITL.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithLocalTools/AgentWithLocalTools.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/FoundryMultiAgent/FoundryMultiAgent.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/FoundrySingleAgent/FoundrySingleAgent.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/AspNetAgentAuthorization/">
-    <File Path="samples/05-end-to-end/AspNetAgentAuthorization/docker-compose.yml" />
-    <File Path="samples/05-end-to-end/AspNetAgentAuthorization/README.md" />
-    <Project Path="samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/RazorWebClient.csproj" />
-    <Project Path="samples/05-end-to-end/AspNetAgentAuthorization/Service/Service.csproj" />
+  <Folder Name="/Samples/M365Agent/">
+    <Project Path="samples/M365Agent/M365Agent.csproj" />
   </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".editorconfig" />
     <File Path=".gitignore" />
-    <File Path="AGENTS.md" />
     <File Path="Directory.Build.props" />
     <File Path="Directory.Build.targets" />
     <File Path="Directory.Packages.props" />
     <File Path="global.json" />
     <File Path="nuget.config" />
-    <File Path="README.md" />
   </Folder>
   <Folder Name="/Solution Items/.github/" />
   <Folder Name="/Solution Items/.github/upgrades/" />
@@ -338,6 +284,7 @@
   </Folder>
   <Folder Name="/Solution Items/.github/workflows/">
     <File Path="../.github/workflows/dotnet-build-and-test.yml" />
+    <File Path="../.github/workflows/dotnet-check-coverage.ps1" />
     <File Path="../.github/workflows/dotnet-format.yml" />
   </Folder>
   <Folder Name="/Solution Items/demos/">
@@ -360,10 +307,6 @@
     <File Path="../docs/decisions/0012-python-typeddict-options.md" />
     <File Path="../docs/decisions/0013-python-get-response-simplification.md" />
     <File Path="../docs/decisions/0014-feature-collections.md" />
-    <File Path="../docs/decisions/0015-agent-run-context.md" />
-    <File Path="../docs/decisions/0016-python-context-middleware.md" />
-    <File Path="../docs/decisions/0017-agent-additional-properties.md" />
-    <File Path="../docs/decisions/0018-agentthread-serialization.md" />
     <File Path="../docs/decisions/adr-short-template.md" />
     <File Path="../docs/decisions/adr-template.md" />
     <File Path="../docs/decisions/README.md" />
@@ -374,10 +317,6 @@
     <File Path="eng/MSBuild/Shared.props" />
     <File Path="eng/MSBuild/Shared.targets" />
   </Folder>
-  <Folder Name="/Solution Items/eng/scripts/">
-    <File Path="eng/scripts/dotnet-check-coverage.ps1" />
-    <File Path="eng/scripts/New-FilteredSolution.ps1" />
-  </Folder>
   <Folder Name="/Solution Items/nuget/">
     <File Path="nuget/icon.png" />
     <File Path="nuget/nuget-package.props" />
@@ -443,10 +382,6 @@
     <File Path="src/Shared/IntegrationTests/OpenAIConfiguration.cs" />
     <File Path="src/Shared/IntegrationTests/README.md" />
   </Folder>
-  <Folder Name="/Solution Items/src/Shared/IntegrationTestsAzureCredentials/">
-    <File Path="src/Shared/IntegrationTestsAzureCredentials/README.md" />
-    <File Path="src/Shared/IntegrationTestsAzureCredentials/TestAzureCliCredentials.cs" />
-  </Folder>
   <Folder Name="/Solution Items/src/Shared/Samples/">
     <File Path="src/Shared/Samples/BaseSample.cs" />
     <File Path="src/Shared/Samples/README.md" />
@@ -454,10 +389,6 @@
     <File Path="src/Shared/Samples/TextOutputHelperExtensions.cs" />
     <File Path="src/Shared/Samples/XunitLogger.cs" />
   </Folder>
-  <Folder Name="/Solution Items/src/Shared/Redaction/">
-    <File Path="src/Shared/Redaction/README.md" />
-    <File Path="src/Shared/Redaction/ReplacingRedactor.cs" />
-  </Folder>
   <Folder Name="/Solution Items/src/Shared/Throw/">
     <File Path="src/Shared/Throw/README.md" />
     <File Path="src/Shared/Throw/Throw.cs" />
@@ -474,6 +405,7 @@
     <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <Project Path="src/Microsoft.Agents.AI.AzureAI/Microsoft.Agents.AI.AzureAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
@@ -481,8 +413,6 @@
     <Project Path="src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.FoundryMemory/Microsoft.Agents.AI.FoundryMemory.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
@@ -493,10 +423,9 @@
     <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj" />
     <Project Path="src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj" />
   </Folder>
   <Folder Name="/Tests/" />
@@ -506,9 +435,8 @@
     <Project Path="tests/AzureAI.IntegrationTests/AzureAI.IntegrationTests.csproj" />
     <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
     <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
@@ -522,14 +450,13 @@
     <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Anthropic.UnitTests/Microsoft.Agents.AI.Anthropic.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.AzureAI.UnitTests/Microsoft.Agents.AI.AzureAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.UnitTests/Microsoft.Agents.AI.FoundryMemory.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />
@@ -539,9 +466,8 @@
     <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Generators.UnitTests/Microsoft.Agents.AI.Workflows.Generators.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
   </Folder>
-</Solution>
+</Solution>

dotnet/agent-framework-release.slnf

@@ -14,7 +14,6 @@
       "src\\Microsoft.Agents.AI.Declarative\\Microsoft.Agents.AI.Declarative.csproj",
       "src\\Microsoft.Agents.AI.DevUI\\Microsoft.Agents.AI.DevUI.csproj",
       "src\\Microsoft.Agents.AI.DurableTask\\Microsoft.Agents.AI.DurableTask.csproj",
-      "src\\Microsoft.Agents.AI.FoundryMemory\\Microsoft.Agents.AI.FoundryMemory.csproj",
       "src\\Microsoft.Agents.AI.Hosting.A2A.AspNetCore\\Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj",
       "src\\Microsoft.Agents.AI.Hosting.A2A\\Microsoft.Agents.AI.Hosting.A2A.csproj",
       "src\\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj",

dotnet/eng/MSBuild/Shared.props

@@ -8,9 +8,6 @@
   <ItemGroup Condition="'$(InjectSharedIntegrationTestCode)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\IntegrationTests\*.cs" LinkBase="Shared\IntegrationTests" />
   </ItemGroup>
-  <ItemGroup Condition="'$(InjectSharedIntegrationTestAzureCredentialsCode)' == 'true'">
-    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\IntegrationTestsAzureCredentials\*.cs" LinkBase="Shared\IntegrationTestsAzureCredentials" />
-  </ItemGroup>
   <ItemGroup Condition="'$(InjectSharedBuildTestCode)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\CodeTests\*.cs" LinkBase="Shared\CodeTests" />
   </ItemGroup>
@@ -29,7 +26,4 @@
   <ItemGroup Condition="'$(InjectSharedDiagnosticIds)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\DiagnosticIds\*.cs" LinkBase="Shared\DiagnosticIds" />
   </ItemGroup>
-  <ItemGroup Condition="'$(InjectSharedRedaction)' == 'true'">
-    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Redaction\*.cs" LinkBase="Shared\Redaction" />
-  </ItemGroup>
 </Project>

dotnet/eng/scripts/New-FilteredSolution.ps1

@@ -1,145 +0,0 @@
-#!/usr/bin/env pwsh
-# Copyright (c) Microsoft. All rights reserved.
-
-<#
-.SYNOPSIS
-    Generates a filtered .slnx solution file by removing projects that don't match the specified criteria.
-
-.DESCRIPTION
-    Parses a .slnx solution file and applies one or more filters:
-    - Removes projects that don't support the specified target framework (via MSBuild query).
-    - Optionally removes all sample projects (under samples/).
-    - Optionally filters test projects by name pattern (e.g., only *UnitTests*).
-    Writes the filtered solution to the specified output path and prints the path.
-
-.PARAMETER Solution
-    Path to the source .slnx solution file.
-
-.PARAMETER TargetFramework
-    The target framework to filter by (e.g., net10.0, net472).
-
-.PARAMETER Configuration
-    Optional MSBuild configuration used when querying TargetFrameworks. Defaults to Debug.
-
-.PARAMETER TestProjectNameFilter
-    Optional wildcard pattern to filter test project names (e.g., *UnitTests*, *IntegrationTests*).
-    When specified, only test projects whose filename matches this pattern are kept.
-
-.PARAMETER ExcludeSamples
-    When specified, removes all projects under the samples/ directory from the solution.
-
-.PARAMETER OutputPath
-    Optional output path for the filtered .slnx file. If not specified, a temp file is created.
-
-.EXAMPLE
-    # Generate a filtered solution and run tests
-    $filtered = ./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net472
-    dotnet test --solution $filtered --no-build -f net472
-
-.EXAMPLE
-    # Generate a solution with only unit test projects
-    ./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net10.0 -TestProjectNameFilter "*UnitTests*" -OutputPath filtered-unit.slnx
-
-.EXAMPLE
-    # Inline usage with dotnet test (PowerShell)
-    dotnet test --solution (./dotnet/eng/scripts/New-FilteredSolution.ps1 -Solution dotnet/agent-framework-dotnet.slnx -TargetFramework net472) --no-build -f net472
-#>
-
-[CmdletBinding()]
-param(
-    [Parameter(Mandatory)]
-    [string]$Solution,
-
-    [Parameter(Mandatory)]
-    [string]$TargetFramework,
-
-    [string]$Configuration = "Debug",
-
-    [string]$TestProjectNameFilter,
-
-    [switch]$ExcludeSamples,
-
-    [string]$OutputPath
-)
-
-$ErrorActionPreference = "Stop"
-
-# Resolve the solution path
-$solutionPath = Resolve-Path $Solution
-$solutionDir = Split-Path $solutionPath -Parent
-
-if (-not $OutputPath) {
-    $OutputPath = [System.IO.Path]::Combine([System.IO.Path]::GetTempPath(), "filtered-$(Split-Path $solutionPath -Leaf)")
-}
-
-# Parse the .slnx XML
-[xml]$slnx = Get-Content $solutionPath -Raw
-
-$removed = @()
-$kept = @()
-
-# Remove sample projects if requested
-if ($ExcludeSamples) {
-    $sampleProjects = $slnx.SelectNodes("//Project[contains(@Path, 'samples/')]")
-    foreach ($proj in $sampleProjects) {
-        $projRelPath = $proj.GetAttribute("Path")
-        Write-Verbose "Removing (sample): $projRelPath"
-        $removed += $projRelPath
-        $proj.ParentNode.RemoveChild($proj) | Out-Null
-    }
-    Write-Host "Removed $($sampleProjects.Count) sample project(s)." -ForegroundColor Yellow
-}
-
-# Filter all remaining projects by target framework
-$allProjects = $slnx.SelectNodes("//Project")
-
-foreach ($proj in $allProjects) {
-    $projRelPath = $proj.GetAttribute("Path")
-    $projFullPath = Join-Path $solutionDir $projRelPath
-    $projFileName = Split-Path $projRelPath -Leaf
-    $isTestProject = $projRelPath -like "*tests/*"
-
-    # Filter test projects by name pattern if specified
-    if ($isTestProject -and $TestProjectNameFilter -and ($projFileName -notlike $TestProjectNameFilter)) {
-        Write-Verbose "Removing (name filter): $projRelPath"
-        $removed += $projRelPath
-        $proj.ParentNode.RemoveChild($proj) | Out-Null
-        continue
-    }
-
-    if (-not (Test-Path $projFullPath)) {
-        Write-Verbose "Project not found, keeping in solution: $projRelPath"
-        $kept += $projRelPath
-        continue
-    }
-
-    # Query the project's target frameworks using MSBuild
-    $targetFrameworks = & dotnet msbuild $projFullPath -getProperty:TargetFrameworks -p:Configuration=$Configuration -nologo 2>$null
-    $targetFrameworks = $targetFrameworks.Trim()
-
-    if ($targetFrameworks -like "*$TargetFramework*") {
-        Write-Verbose "Keeping: $projRelPath (targets: $targetFrameworks)"
-        $kept += $projRelPath
-    }
-    else {
-        Write-Verbose "Removing: $projRelPath (targets: $targetFrameworks, missing: $TargetFramework)"
-        $removed += $projRelPath
-        $proj.ParentNode.RemoveChild($proj) | Out-Null
-    }
-}
-
-# Write the filtered solution
-$slnx.Save($OutputPath)
-
-# Report results to stderr so stdout is clean for piping
-Write-Host "Filtered solution written to: $OutputPath" -ForegroundColor Green
-if ($removed.Count -gt 0) {
-    Write-Host "Removed $($removed.Count) project(s):" -ForegroundColor Yellow
-    foreach ($r in $removed) {
-        Write-Host "  - $r" -ForegroundColor Yellow
-    }
-}
-Write-Host "Kept $($kept.Count) project(s)." -ForegroundColor Green
-
-# Output the path for piping
-Write-Output $OutputPath

dotnet/global.json

@@ -1,10 +1,7 @@
 {
     "sdk": {
-        "version": "10.0.200",
+        "version": "10.0.100",
         "rollForward": "minor",
         "allowPrerelease": false
-    },
-    "test": {
-        "runner": "Microsoft.Testing.Platform"
     }
 }

dotnet/nuget/nuget-package.props

@@ -2,11 +2,9 @@
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
     <VersionPrefix>1.0.0</VersionPrefix>
-    <RCNumber>4</RCNumber>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260311.1</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260311.1</PackageVersion>
-    <GitTag>1.0.0-rc4</GitTag>
+    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260212.1</PackageVersion>
+    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260212.1</PackageVersion>
+    <GitTag>1.0.0-preview.260212.1</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/01-get-started/01_hello_agent/01_hello_agent.csproj

@@ -1,21 +0,0 @@
-<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" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/01-get-started/05_first_workflow/05_first_workflow.csproj

@@ -1,14 +0,0 @@
-<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.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj

@@ -1,31 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <!-- The Functions build tools don't like namespaces that start with a number -->
-    <AssemblyName>HostedAgent</AssemblyName>
-    <RootNamespace>HostedAgent</RootNamespace>
-  </PropertyGroup>
-  <ItemGroup>
-    <FrameworkReference Include="Microsoft.AspNetCore.App" />
-  </ItemGroup>
-  <!-- Azure Functions packages -->
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
-  </ItemGroup>
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
-    <PackageReference Include="Azure.Identity" />
-  </ItemGroup>
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
-  </ItemGroup>
-</Project>

dotnet/samples/01-get-started/06_host_your_agent/Program.cs

@@ -1,45 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to host an AI agent with Azure Functions (DurableAgents).
-//
-// Prerequisites:
-//   - Azure Functions Core Tools
-//   - Azure OpenAI resource
-//
-// Environment variables:
-//   AZURE_OPENAI_ENDPOINT
-//   AZURE_OPENAI_DEPLOYMENT_NAME (defaults to "gpt-4o-mini")
-//
-// Run with: func start
-// Then call: POST http://localhost:7071/api/agents/HostedAgent/run
-
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Hosting.AzureFunctions;
-using Microsoft.Azure.Functions.Worker.Builder;
-using Microsoft.Extensions.Hosting;
-using OpenAI.Chat;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
-    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// Set up an AI agent following the standard Microsoft Agent Framework pattern.
-// 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)
-    .AsAIAgent(
-        instructions: "You are a helpful assistant hosted in Azure Functions.",
-        name: "HostedAgent");
-
-// Configure the function app to host the AI agent.
-// This will automatically generate HTTP API endpoints for the agent.
-using IHost app = FunctionsApplication
-    .CreateBuilder(args)
-    .ConfigureFunctionsWebApplication()
-    .ConfigureDurableAgents(options => options.AddAIAgent(agent, timeToLive: TimeSpan.FromHours(1)))
-    .Build();
-app.Run();

dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/Server.csproj

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

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/Agent_Step01_FileBasedSkills.csproj

@@ -1,32 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <NoWarn>$(NoWarn);MAAI001</NoWarn>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
-    <PackageReference Include="Azure.Identity" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <Compile Include="..\SubprocessScriptRunner.cs" Link="SubprocessScriptRunner.cs" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
-  </ItemGroup>
-
-  <!-- Copy skills directory to output -->
-  <ItemGroup>
-    <None Include="skills\**\*.*">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </None>
-  </ItemGroup>
-
-</Project>

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/Program.cs

@@ -1,48 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use file-based Agent Skills with a ChatClientAgent.
-// Skills are discovered from SKILL.md files on disk and follow the progressive disclosure pattern:
-// 1. Advertise — skill names and descriptions in the system prompt
-// 2. Load — full instructions loaded on demand via load_skill tool
-// 3. Read resources — reference files read via read_skill_resource tool
-// 4. Run scripts — scripts executed via run_skill_script tool with a subprocess executor
-//
-// This sample uses a unit-converter skill that converts between miles, kilometers, pounds, and kilograms.
-
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using OpenAI.Responses;
-
-// --- Configuration ---
-string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// --- Skills Provider ---
-// Discovers skills from the 'skills' directory containing SKILL.md files.
-// The script runner runs file-based scripts (e.g. Python) as local subprocesses.
-var skillsProvider = new AgentSkillsProvider(
-    Path.Combine(AppContext.BaseDirectory, "skills"),
-    SubprocessScriptRunner.RunAsync);
-// --- Agent Setup ---
-AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
-    .GetResponsesClient()
-    .AsAIAgent(new ChatClientAgentOptions
-    {
-        Name = "UnitConverterAgent",
-        ChatOptions = new()
-        {
-            Instructions = "You are a helpful assistant that can convert units.",
-        },
-        AIContextProviders = [skillsProvider],
-    },
-    model: deploymentName);
-
-// --- Example: Unit conversion ---
-Console.WriteLine("Converting units with file-based skills");
-Console.WriteLine(new string('-', 60));
-
-AgentResponse response = await agent.RunAsync(
-    "How many kilometers is a marathon (26.2 miles)? And how many pounds is 75 kilograms?");
-
-Console.WriteLine($"Agent: {response.Text}");

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/README.md

@@ -1,51 +0,0 @@
-# File-Based Agent Skills Sample
-
-This sample demonstrates how to use **file-based Agent Skills** with a `ChatClientAgent`.
-
-## What it demonstrates
-
-- Discovering skills from `SKILL.md` files on disk via `AgentFileSkillsSource`
-- The progressive disclosure pattern: advertise → load → read resources → run scripts
-- Using the `AgentSkillsProvider` constructor with a skill directory path and script executor
-- Running file-based scripts (Python) via a subprocess-based executor
-
-## Skills Included
-
-### unit-converter
-
-Converts between common units (miles↔km, pounds↔kg) using a multiplication factor.
-
-- `references/conversion-table.md` — Conversion factor table
-- `scripts/convert.py` — Python script that performs the conversion
-
-## Running the Sample
-
-### Prerequisites
-
-- .NET 10.0 SDK
-- Azure OpenAI endpoint with a deployed model
-- Python 3 installed and available as `python3` on your PATH
-
-### Setup
-
-```bash
-export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
-export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-### Run
-
-```bash
-dotnet run
-```
-
-### Expected Output
-
-```
-Converting units with file-based skills
-------------------------------------------------------------
-Agent: Here are your conversions:
-
-1. **26.2 miles → 42.16 km** (a marathon distance)
-2. **75 kg → 165.35 lbs**
-```

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/SKILL.md

@@ -1,11 +0,0 @@
----
-name: unit-converter
-description: Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.
----
-
-## Usage
-
-When the user requests a unit conversion:
-1. First, review `references/conversion-table.md` to find the correct factor
-2. Run the `scripts/convert.py` script with `--value <number> --factor <factor>` (e.g. `--value 26.2 --factor 1.60934`)
-3. Present the converted value clearly with both units

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/references/conversion-table.md

@@ -1,10 +0,0 @@
-# Conversion Tables
-
-Formula: **result = value × factor**
-
-| From        | To          | Factor   |
-|-------------|-------------|----------|
-| miles       | kilometers  | 1.60934  |
-| kilometers  | miles       | 0.621371 |
-| pounds      | kilograms   | 0.453592 |
-| kilograms   | pounds      | 2.20462  |

dotnet/samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/skills/unit-converter/scripts/convert.py

@@ -1,29 +0,0 @@
-# Unit conversion script
-# Converts a value using a multiplication factor: result = value × factor
-#
-# Usage:
-#   python scripts/convert.py --value 26.2 --factor 1.60934
-#   python scripts/convert.py --value 75 --factor 2.20462
-
-import argparse
-import json
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        description="Convert a value using a multiplication factor.",
-        epilog="Examples:\n"
-        "  python scripts/convert.py --value 26.2 --factor 1.60934\n"
-        "  python scripts/convert.py --value 75 --factor 2.20462",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-    )
-    parser.add_argument("--value", type=float, required=True, help="The numeric value to convert.")
-    parser.add_argument("--factor", type=float, required=True, help="The conversion factor from the table.")
-    args = parser.parse_args()
-
-    result = round(args.value * args.factor, 4)
-    print(json.dumps({"value": args.value, "factor": args.factor, "result": result}))
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,7 +0,0 @@
-# AgentSkills Samples
-
-Samples demonstrating Agent Skills capabilities.
-
-| Sample | Description |
-|--------|-------------|
-| [Agent_Step01_FileBasedSkills](Agent_Step01_FileBasedSkills/) | Define skills as `SKILL.md` files on disk with reference documents. Uses a unit-converter skill. |

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

@@ -1,137 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// Sample subprocess-based skill script runner.
-// Executes file-based skill scripts as local subprocesses.
-// This is provided for demonstration purposes only.
-
-using System.Diagnostics;
-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.
-/// </remarks>
-internal static class SubprocessScriptRunner
-{
-    /// <summary>
-    /// Runs a skill script as a local subprocess.
-    /// </summary>
-    public static async Task<object?> RunAsync(
-        AgentFileSkill skill,
-        AgentFileSkillScript script,
-        AIFunctionArguments arguments,
-        CancellationToken cancellationToken)
-    {
-        if (!File.Exists(script.FullPath))
-        {
-            return $"Error: Script file not found: {script.FullPath}";
-        }
-
-        string extension = Path.GetExtension(script.FullPath);
-        string? interpreter = extension switch
-        {
-            ".py" => "python3",
-            ".js" => "node",
-            ".sh" => "bash",
-            ".ps1" => "pwsh",
-            _ => null,
-        };
-
-        var startInfo = new ProcessStartInfo
-        {
-            RedirectStandardOutput = true,
-            RedirectStandardError = true,
-            UseShellExecute = false,
-            CreateNoWindow = true,
-            WorkingDirectory = Path.GetDirectoryName(script.FullPath) ?? ".",
-        };
-
-        if (interpreter is not null)
-        {
-            startInfo.FileName = interpreter;
-            startInfo.ArgumentList.Add(script.FullPath);
-        }
-        else
-        {
-            startInfo.FileName = script.FullPath;
-        }
-
-        if (arguments is not null)
-        {
-            foreach (var (key, value) in arguments)
-            {
-                if (value is bool boolValue)
-                {
-                    if (boolValue)
-                    {
-                        startInfo.ArgumentList.Add(NormalizeKey(key));
-                    }
-                }
-                else if (value is not null)
-                {
-                    startInfo.ArgumentList.Add(NormalizeKey(key));
-                    startInfo.ArgumentList.Add(value.ToString()!);
-                }
-            }
-        }
-
-        Process? process = null;
-        try
-        {
-            process = Process.Start(startInfo);
-            if (process is null)
-            {
-                return $"Error: Failed to start process for script '{script.Name}'.";
-            }
-
-            Task<string> outputTask = process.StandardOutput.ReadToEndAsync(cancellationToken);
-            Task<string> errorTask = process.StandardError.ReadToEndAsync(cancellationToken);
-
-            await process.WaitForExitAsync(cancellationToken).ConfigureAwait(false);
-
-            string output = await outputTask.ConfigureAwait(false);
-            string error = await errorTask.ConfigureAwait(false);
-
-            if (!string.IsNullOrEmpty(error))
-            {
-                output += $"\nStderr:\n{error}";
-            }
-
-            if (process.ExitCode != 0)
-            {
-                output += $"\nScript exited with code {process.ExitCode}";
-            }
-
-            return string.IsNullOrEmpty(output) ? "(no output)" : output.Trim();
-        }
-        catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
-        {
-            // Kill the process on cancellation to avoid leaving orphaned subprocesses.
-            process?.Kill(entireProcessTree: true);
-            throw;
-        }
-        catch (OperationCanceledException)
-        {
-            throw;
-        }
-        catch (Exception ex)
-        {
-            return $"Error: Failed to execute script '{script.Name}': {ex.Message}";
-        }
-        finally
-        {
-            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/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/Program.cs

@@ -1,85 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to use the FoundryMemoryProvider to persist and recall memories for an agent.
-// The sample stores conversation messages in an Azure AI Foundry memory store and retrieves relevant
-// memories for subsequent invocations, even across new sessions.
-//
-// Note: Memory extraction in Azure AI Foundry is asynchronous and takes time. This sample demonstrates
-// a simple polling approach to wait for memory updates to complete before querying.
-
-using System.Text.Json;
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.AzureAI;
-using Microsoft.Agents.AI.FoundryMemory;
-
-string foundryEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-string memoryStoreName = Environment.GetEnvironmentVariable("AZURE_AI_MEMORY_STORE_ID") ?? "memory-store-sample";
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-string embeddingModelName = Environment.GetEnvironmentVariable("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-ada-002";
-
-// Create an AIProjectClient for Foundry with Azure Identity authentication.
-// 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.
-DefaultAzureCredential credential = new();
-AIProjectClient projectClient = new(new Uri(foundryEndpoint), credential);
-
-// Get the ChatClient from the AIProjectClient's OpenAI property using the deployment name.
-// The stateInitializer can be used to customize the Foundry Memory scope per session and it will be called each time a session
-// is encountered by the FoundryMemoryProvider that does not already have state stored on the session.
-// If each session should have its own scope, you can create a new id per session via the stateInitializer, e.g.:
-// new FoundryMemoryProvider(projectClient, memoryStoreName, stateInitializer: _ => new(new FoundryMemoryProviderScope(Guid.NewGuid().ToString())), ...)
-// In our case we are storing memories scoped by user so that memories are retained across sessions.
-FoundryMemoryProvider memoryProvider = new(
-    projectClient,
-    memoryStoreName,
-    stateInitializer: _ => new(new FoundryMemoryProviderScope("sample-user-123")));
-
-FoundryAgent agent = projectClient.AsAIAgent(
-    new ChatClientAgentOptions()
-    {
-        Name = "TravelAssistantWithFoundryMemory",
-        ChatOptions = new()
-        {
-            ModelId = deploymentName,
-            Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details."
-        },
-        AIContextProviders = [memoryProvider]
-    });
-
-AgentSession session = await agent.CreateSessionAsync();
-
-Console.WriteLine("\n>> Setting up Foundry Memory Store\n");
-
-// Ensure the memory store exists (creates it with the specified models if needed).
-await memoryProvider.EnsureMemoryStoreCreatedAsync(deploymentName, embeddingModelName, "Sample memory store for travel assistant");
-
-// Clear any existing memories for this scope to demonstrate fresh behavior.
-await memoryProvider.EnsureStoredMemoriesDeletedAsync(session);
-
-Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
-Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
-
-// Memory extraction in Azure AI Foundry is asynchronous and takes time to process.
-// WhenUpdatesCompletedAsync polls all pending updates and waits for them to complete.
-Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
-await memoryProvider.WhenUpdatesCompletedAsync();
-
-Console.WriteLine("Updates completed.\n");
-
-Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));
-
-Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
-JsonElement serializedSession = await agent.SerializeSessionAsync(session);
-AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
-Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));
-
-Console.WriteLine("\n>> Start a new session that shares the same Foundry Memory scope\n");
-
-Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
-await memoryProvider.WhenUpdatesCompletedAsync();
-
-AgentSession newSession = await agent.CreateSessionAsync();
-Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newSession));

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/README.md

@@ -1,57 +0,0 @@
-# Agent with Memory Using Azure AI Foundry
-
-This sample demonstrates how to create and run an agent that uses Azure AI Foundry's managed memory service to extract and retrieve individual memories across sessions.
-
-## Features Demonstrated
-
-- Creating a `FoundryMemoryProvider` with Azure Identity authentication
-- Automatic memory store creation if it doesn't exist
-- Multi-turn conversations with automatic memory extraction
-- Memory retrieval to inform agent responses
-- Session serialization and deserialization
-- Memory persistence across completely new sessions
-
-## Prerequisites
-
-1. Azure subscription with Azure AI Foundry project
-2. Azure OpenAI resource with a chat model deployment (e.g., gpt-4o-mini) and an embedding model deployment (e.g., text-embedding-ada-002)
-3. .NET 10.0 SDK
-4. Azure CLI logged in (`az login`)
-
-## Environment Variables
-
-```bash
-# Azure AI Foundry project endpoint and memory store name
-export AZURE_AI_PROJECT_ENDPOINT="https://your-account.services.ai.azure.com/api/projects/your-project"
-export AZURE_AI_MEMORY_STORE_ID="my_memory_store"
-
-# Model deployment names (models deployed in your Foundry project)
-export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
-export AZURE_AI_EMBEDDING_DEPLOYMENT_NAME="text-embedding-ada-002"
-```
-
-## Run the Sample
-
-```bash
-dotnet run
-```
-
-## Expected Output
-
-The agent will:
-1. Create the memory store if it doesn't exist (using the specified chat and embedding models)
-2. Learn your name (Taylor), travel destination (Patagonia), timing (November), companions (sister), and interests (scenic viewpoints)
-3. Wait for Foundry Memory to index the memories
-4. Recall those details when asked about the trip
-5. Demonstrate memory persistence across session serialization/deserialization
-6. Show that a brand new session can still access the same memories
-
-## Key Differences from Mem0
-
-| Aspect | Mem0 | Azure AI Foundry Memory |
-|--------|------|------------------------|
-| Authentication | API Key | Azure Identity (DefaultAzureCredential) |
-| Scope | ApplicationId, UserId, AgentId, ThreadId | Single `Scope` string |
-| Memory Types | Single memory store | User Profile + Chat Summary |
-| Hosting | Mem0 cloud or self-hosted | Azure AI Foundry managed service |
-| Store Creation | N/A (automatic) | Explicit via `EnsureMemoryStoreCreatedAsync` |

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step05_BoundedChatHistory/BoundedChatHistoryProvider.cs

@@ -1,133 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.VectorData;
-
-namespace SampleApp;
-
-/// <summary>
-/// A <see cref="ChatHistoryProvider"/> that keeps a bounded window of recent messages in session state
-/// (via <see cref="InMemoryChatHistoryProvider"/>) and overflows older messages to a vector store
-/// (via <see cref="ChatHistoryMemoryProvider"/>). When providing chat history, it searches the vector
-/// store for relevant older messages and prepends them as a memory context message.
-/// </summary>
-/// <remarks>
-/// Only non-system messages are counted towards the session state limit and overflow mechanism. System messages are always retained in session state and are not included in the vector store.
-/// Function calls and function results are also dropped when truncation happens, both from in-memory state, and they are also not persisted to the vector store.
-/// </remarks>
-internal sealed class BoundedChatHistoryProvider : ChatHistoryProvider, IDisposable
-{
-    private readonly InMemoryChatHistoryProvider _chatHistoryProvider;
-    private readonly ChatHistoryMemoryProvider _memoryProvider;
-    private readonly TruncatingChatReducer _reducer;
-    private readonly string _contextPrompt;
-    private IReadOnlyList<string>? _stateKeys;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="BoundedChatHistoryProvider"/> class.
-    /// </summary>
-    /// <param name="maxSessionMessages">The maximum number of non-system messages to keep in session state before overflowing to the vector store.</param>
-    /// <param name="vectorStore">The vector store to use for storing and retrieving overflow chat history.</param>
-    /// <param name="collectionName">The name of the collection for storing overflow chat history in the vector store.</param>
-    /// <param name="vectorDimensions">The number of dimensions to use for the chat history vector store embeddings.</param>
-    /// <param name="stateInitializer">A delegate that initializes the memory provider state, providing the storage and search scopes.</param>
-    /// <param name="contextPrompt">Optional prompt to prefix memory search results. Defaults to a standard memory context prompt.</param>
-    public BoundedChatHistoryProvider(
-        int maxSessionMessages,
-        VectorStore vectorStore,
-        string collectionName,
-        int vectorDimensions,
-        Func<AgentSession?, ChatHistoryMemoryProvider.State> stateInitializer,
-        string? contextPrompt = null)
-    {
-        if (maxSessionMessages < 0)
-        {
-            throw new ArgumentOutOfRangeException(nameof(maxSessionMessages), "maxSessionMessages must be non-negative.");
-        }
-
-        this._reducer = new TruncatingChatReducer(maxSessionMessages);
-        this._chatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
-        {
-            ChatReducer = this._reducer,
-            ReducerTriggerEvent = InMemoryChatHistoryProviderOptions.ChatReducerTriggerEvent.AfterMessageAdded,
-            StorageInputRequestMessageFilter = msgs => msgs,
-        });
-        this._memoryProvider = new ChatHistoryMemoryProvider(
-            vectorStore,
-            collectionName,
-            vectorDimensions,
-            stateInitializer,
-            options: new ChatHistoryMemoryProviderOptions
-            {
-                SearchInputMessageFilter = msgs => msgs,
-                StorageInputRequestMessageFilter = msgs => msgs,
-            });
-        this._contextPrompt = contextPrompt
-            ?? "The following are memories from earlier in this conversation. Use them to inform your responses:";
-    }
-
-    /// <inheritdoc />
-    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= this._chatHistoryProvider.StateKeys.Concat(this._memoryProvider.StateKeys).ToArray();
-
-    /// <inheritdoc />
-    protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
-        InvokingContext context,
-        CancellationToken cancellationToken = default)
-    {
-        // Delegate to the inner provider's full lifecycle (retrieve, filter, stamp, merge with request messages).
-        var chatHistoryProviderInputContext = new InvokingContext(context.Agent, context.Session, []);
-        var allMessages = await this._chatHistoryProvider.InvokingAsync(chatHistoryProviderInputContext, cancellationToken).ConfigureAwait(false);
-
-        // Search the vector store for relevant older messages.
-        var aiContext = new AIContext { Messages = context.RequestMessages.ToList() };
-        var invokingContext = new AIContextProvider.InvokingContext(
-            context.Agent, context.Session, aiContext);
-
-        var result = await this._memoryProvider.InvokingAsync(invokingContext, cancellationToken).ConfigureAwait(false);
-
-        // Extract only the messages added by the memory provider (stamped with AIContextProvider source type).
-        var memoryMessages = result.Messages?
-            .Where(m => m.GetAgentRequestMessageSourceType() == AgentRequestMessageSourceType.AIContextProvider)
-            .ToList();
-
-        if (memoryMessages is { Count: > 0 })
-        {
-            var memoryText = string.Join("\n", memoryMessages.Select(m => m.Text).Where(t => !string.IsNullOrWhiteSpace(t)));
-
-            if (!string.IsNullOrWhiteSpace(memoryText))
-            {
-                var contextMessage = new ChatMessage(ChatRole.User, $"{this._contextPrompt}\n{memoryText}");
-                return new[] { contextMessage }.Concat(allMessages);
-            }
-        }
-
-        return allMessages;
-    }
-
-    /// <inheritdoc />
-    protected override async ValueTask StoreChatHistoryAsync(
-        InvokedContext context,
-        CancellationToken cancellationToken = default)
-    {
-        // Delegate storage to the in-memory provider. Its TruncatingChatReducer (AfterMessageAdded trigger)
-        // will automatically truncate to the configured maximum and expose any removed messages.
-        var innerContext = new InvokedContext(
-            context.Agent, context.Session, context.RequestMessages, context.ResponseMessages!);
-        await this._chatHistoryProvider.InvokedAsync(innerContext, cancellationToken).ConfigureAwait(false);
-
-        // Archive any messages that the reducer removed to the vector store.
-        if (this._reducer.RemovedMessages is { Count: > 0 })
-        {
-            var overflowContext = new AIContextProvider.InvokedContext(
-                context.Agent, context.Session, this._reducer.RemovedMessages, []);
-            await this._memoryProvider.InvokedAsync(overflowContext, cancellationToken).ConfigureAwait(false);
-        }
-    }
-
-    /// <inheritdoc/>
-    public void Dispose()
-    {
-        this._memoryProvider.Dispose();
-    }
-}

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step05_BoundedChatHistory/Program.cs

@@ -1,79 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create a bounded chat history provider that keeps a configurable number of
-// recent messages in session state and automatically overflows older messages to a vector store.
-// When the agent is invoked, it searches the vector store for relevant older messages and
-// prepends them as a "memory" context message before the recent session history.
-
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel.Connectors.InMemory;
-using OpenAI.Chat;
-using SampleApp;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-var embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-3-large";
-
-// 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 credential = new DefaultAzureCredential();
-
-// Create a vector store to store overflow chat messages.
-// For demonstration purposes, we are using an in-memory vector store.
-// Replace this with a persistent vector store implementation for production scenarios.
-VectorStore vectorStore = new InMemoryVectorStore(new InMemoryVectorStoreOptions()
-{
-    EmbeddingGenerator = new AzureOpenAIClient(new Uri(endpoint), credential)
-        .GetEmbeddingClient(embeddingDeploymentName)
-        .AsIEmbeddingGenerator()
-});
-
-var sessionId = Guid.NewGuid().ToString();
-
-// Create the BoundedChatHistoryProvider with a maximum of 4 non-system messages in session state.
-// It internally creates an InMemoryChatHistoryProvider with a TruncatingChatReducer and a
-// ChatHistoryMemoryProvider with the correct configuration to ensure overflow messages are
-// automatically archived to the vector store and recalled via semantic search.
-var boundedProvider = new BoundedChatHistoryProvider(
-    maxSessionMessages: 4,
-    vectorStore,
-    collectionName: "chathistory-overflow",
-    vectorDimensions: 3072,
-    session => new ChatHistoryMemoryProvider.State(
-        storageScope: new() { UserId = "UID1", SessionId = sessionId },
-        searchScope: new() { UserId = "UID1" }));
-
-// Create the agent with the bounded chat history provider.
-AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), credential)
-    .GetChatClient(deploymentName)
-    .AsAIAgent(new ChatClientAgentOptions
-    {
-        ChatOptions = new() { Instructions = "You are a helpful assistant. Answer questions concisely." },
-        Name = "Assistant",
-        ChatHistoryProvider = boundedProvider,
-    });
-
-// Start a conversation. The first several exchanges will fill up the session state window.
-AgentSession session = await agent.CreateSessionAsync();
-
-Console.WriteLine("--- Filling the session window (4 messages max) ---\n");
-
-Console.WriteLine(await agent.RunAsync("My favorite color is blue.", session));
-Console.WriteLine(await agent.RunAsync("I have a dog named Max.", session));
-
-// At this point the session state holds 4 messages (2 user + 2 assistant).
-// The next exchange will push the oldest messages into the vector store.
-Console.WriteLine("\n--- Next exchange will trigger overflow to vector store ---\n");
-
-Console.WriteLine(await agent.RunAsync("What is the capital of France?", session));
-
-// The oldest messages about favorite color have now been archived to the vector store.
-// Ask the agent something that requires recalling the overflowed information.
-Console.WriteLine("\n--- Asking about overflowed information (should recall from vector store) ---\n");
-
-Console.WriteLine(await agent.RunAsync("What is my favorite color?", session));

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step05_BoundedChatHistory/README.md

@@ -1,40 +0,0 @@
-# Bounded Chat History with Vector Store Overflow
-
-This sample demonstrates how to create a custom `ChatHistoryProvider` that keeps a bounded window of recent messages in session state and automatically overflows older messages to a vector store. When the agent is invoked, it searches the vector store for relevant older messages and prepends them as memory context.
-
-## Concepts
-
-- **`TruncatingChatReducer`**: A custom `IChatReducer` that keeps the most recent N messages and exposes removed messages via a `RemovedMessages` property.
-- **`BoundedChatHistoryProvider`**: A custom `ChatHistoryProvider` that composes:
-  - `InMemoryChatHistoryProvider` for fast session-state storage (bounded by the reducer)
-  - `ChatHistoryMemoryProvider` for vector-store overflow and semantic search of older messages
-
-## Prerequisites
-
-- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- An Azure OpenAI resource with:
-  - A chat deployment (e.g., `gpt-4o-mini`)
-  - An embedding deployment (e.g., `text-embedding-3-large`)
-
-## Configuration
-
-Set the following environment variables:
-
-| Variable | Description | Default |
-|---|---|---|
-| `AZURE_OPENAI_ENDPOINT` | Your Azure OpenAI endpoint URL | *(required)* |
-| `AZURE_OPENAI_DEPLOYMENT_NAME` | Chat model deployment name | `gpt-4o-mini` |
-| `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` | Embedding model deployment name | `text-embedding-3-large` |
-
-## Running the Sample
-
-```bash
-dotnet run
-```
-
-## How it Works
-
-1. The agent starts a conversation with a bounded session window of 4 non-system, non-function messages (i.e., user/assistant turns). System messages are always preserved, and function call/result messages are truncated and not preserved.
-2. As messages accumulate beyond the limit, the `TruncatingChatReducer` removes the oldest messages.
-3. The `BoundedChatHistoryProvider` detects the removed messages and stores them in a vector store via `ChatHistoryMemoryProvider`.
-4. On subsequent invocations, the provider searches the vector store for relevant older messages and prepends them as memory context, allowing the agent to recall information from earlier in the conversation.

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step05_BoundedChatHistory/TruncatingChatReducer.cs

@@ -1,65 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Extensions.AI;
-
-namespace SampleApp;
-
-/// <summary>
-/// A truncating chat reducer that keeps the most recent messages up to a configured maximum,
-/// preserving any leading system message. Removed messages are exposed via <see cref="RemovedMessages"/>
-/// so that a caller can archive them (e.g. to a vector store).
-/// </summary>
-internal sealed class TruncatingChatReducer : IChatReducer
-{
-    private readonly int _maxMessages;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="TruncatingChatReducer"/> class.
-    /// </summary>
-    /// <param name="maxMessages">The maximum number of non-system messages to retain.</param>
-    public TruncatingChatReducer(int maxMessages)
-    {
-        this._maxMessages = maxMessages > 0 ? maxMessages : throw new ArgumentOutOfRangeException(nameof(maxMessages));
-    }
-
-    /// <summary>
-    /// Gets the messages that were removed during the most recent call to <see cref="ReduceAsync"/>.
-    /// </summary>
-    public IReadOnlyList<ChatMessage> RemovedMessages { get; private set; } = [];
-
-    /// <inheritdoc />
-    public Task<IEnumerable<ChatMessage>> ReduceAsync(IEnumerable<ChatMessage> messages, CancellationToken cancellationToken)
-    {
-        _ = messages ?? throw new ArgumentNullException(nameof(messages));
-
-        ChatMessage? systemMessage = null;
-        Queue<ChatMessage> retained = new(capacity: this._maxMessages);
-        List<ChatMessage> removed = [];
-
-        foreach (var message in messages)
-        {
-            if (message.Role == ChatRole.System)
-            {
-                // Preserve the first system message outside the counting window.
-                systemMessage ??= message;
-            }
-            else if (!message.Contents.Any(c => c is FunctionCallContent or FunctionResultContent))
-            {
-                if (retained.Count >= this._maxMessages)
-                {
-                    removed.Add(retained.Dequeue());
-                }
-
-                retained.Enqueue(message);
-            }
-        }
-
-        this.RemovedMessages = removed;
-
-        IEnumerable<ChatMessage> result = systemMessage is not null
-            ? new[] { systemMessage }.Concat(retained)
-            : retained;
-
-        return Task.FromResult(result);
-    }
-}

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

@@ -1,13 +0,0 @@
-# Agent Framework Retrieval Augmented Generation (RAG)
-
-These samples show how to create an agent with the Agent Framework that uses Memory to remember previous conversations or facts from previous conversations.
-
-|Sample|Description|
-|---|---|
-|[Chat History memory](./AgentWithMemory_Step01_ChatHistoryMemory/)|This sample demonstrates how to enable an agent to remember messages from previous conversations.|
-|[Memory with MemoryStore](./AgentWithMemory_Step02_MemoryUsingMem0/)|This sample demonstrates how to create and run an agent that uses the Mem0 service to extract and retrieve individual memories.|
-|[Custom Memory Implementation](../../01-get-started/04_memory/)|This sample demonstrates how to create a custom memory component and attach it to an agent.|
-|[Memory with Azure AI Foundry](./AgentWithMemory_Step04_MemoryUsingFoundry/)|This sample demonstrates how to create and run an agent that uses Azure AI Foundry's managed memory service to extract and retrieve individual memories.|
-|[Bounded Chat History with Overflow](./AgentWithMemory_Step05_BoundedChatHistory/)|This sample demonstrates how to create a bounded chat history provider that overflows older messages to a vector store and recalls them as memories.|
-
-> **See also**: [Memory Search with Foundry Agents](../AgentsWithFoundry/Agent_Step22_MemorySearch/) - demonstrates using the built-in Memory Search tool with Azure Foundry agents.

dotnet/samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Program.cs

@@ -1,17 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create and use a simple AI agent with OpenAI as the backend.
-
-using System.ClientModel;
-using Microsoft.Agents.AI;
-using OpenAI.Responses;
-
-var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
-var model = Environment.GetEnvironmentVariable("OPENAI_CHAT_MODEL_NAME") ?? "gpt-4o-mini";
-
-AIAgent agent =
-    new ResponsesClient(new ApiKeyCredential(apiKey))
-    .AsAIAgent(model: model, instructions: "You are good at telling jokes.", name: "Joker");
-
-// Once you have the agent, you can invoke it like any other AIAgent.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

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

@@ -1,120 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use a CompactionProvider with a compaction pipeline
-// as an AIContextProvider for an agent's in-run context management. The pipeline chains multiple
-// compaction strategies from gentle to aggressive:
-//   1. ToolResultCompactionStrategy - Collapses old tool-call groups into concise summaries
-//   2. SummarizationCompactionStrategy - LLM-compresses older conversation spans
-//   3. SlidingWindowCompactionStrategy - Keeps only the most recent N user turns
-//   4. TruncationCompactionStrategy - Emergency token-budget backstop
-
-using System.ComponentModel;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Compaction;
-using Microsoft.Extensions.AI;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// 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.
-AzureOpenAIClient openAIClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-// Create a chat client for the agent and a separate one for the summarization strategy.
-// Using the same model for simplicity; in production, use a smaller/cheaper model for summarization.
-IChatClient agentChatClient = openAIClient.GetChatClient(deploymentName).AsIChatClient();
-IChatClient summarizerChatClient = openAIClient.GetChatClient(deploymentName).AsIChatClient();
-
-// Define a tool the agent can use, so we can see tool-result compaction in action.
-[Description("Look up the current price of a product by name.")]
-static string LookupPrice([Description("The product name to look up.")] string productName) =>
-    productName.ToUpperInvariant() switch
-    {
-        "LAPTOP" => "The laptop costs $999.99.",
-        "KEYBOARD" => "The keyboard costs $79.99.",
-        "MOUSE" => "The mouse costs $29.99.",
-        _ => $"Sorry, I don't have pricing for '{productName}'."
-    };
-
-// Configure the compaction pipeline with one of each strategy, ordered least to most aggressive.
-PipelineCompactionStrategy compactionPipeline =
-    new(// 1. Gentle: collapse old tool-call groups into short summaries
-        new ToolResultCompactionStrategy(CompactionTriggers.MessagesExceed(7)),
-
-        // 2. Moderate: use an LLM to summarize older conversation spans into a concise message
-        new SummarizationCompactionStrategy(summarizerChatClient, CompactionTriggers.TokensExceed(0x500)),
-
-        // 3. Aggressive: keep only the last N user turns and their responses
-        new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(4)),
-
-        // 4. Emergency: drop oldest groups until under the token budget
-        new TruncationCompactionStrategy(CompactionTriggers.TokensExceed(0x8000)));
-
-// Create the agent with a CompactionProvider that uses the compaction pipeline.
-AIAgent agent =
-    agentChatClient
-        .AsBuilder()
-        // Note: Adding the CompactionProvider at the builder level means it will be applied to all agents
-        // built from this builder and will manage context for both agent messages and tool calls.
-        .UseAIContextProviders(new CompactionProvider(compactionPipeline))
-        .BuildAIAgent(
-            new ChatClientAgentOptions
-            {
-                Name = "ShoppingAssistant",
-                ChatOptions = new()
-                {
-                    Instructions =
-                        """
-                        You are a helpful, but long winded, shopping assistant.
-                        Help the user look up prices and compare products.
-                        When responding, Be sure to be extra descriptive and use as
-                        many words as possible without sounding ridiculous.
-                        """,
-                    Tools = [AIFunctionFactory.Create(LookupPrice)]
-                },
-                // Note: AIContextProviders may be specified here instead of ChatClientBuilder.UseAIContextProviders.
-                // Specifying compaction at the agent level skips compaction in the function calling loop.
-                //AIContextProviders = [new CompactionProvider(compactionPipeline)]
-            });
-
-AgentSession session = await agent.CreateSessionAsync();
-
-// Helper to print chat history size
-void PrintChatHistory()
-{
-    if (session.TryGetInMemoryChatHistory(out var history))
-    {
-        Console.ForegroundColor = ConsoleColor.Cyan;
-        Console.WriteLine($"\n[Messages: #{history.Count}]\n");
-        Console.ResetColor();
-    }
-}
-
-// Run a multi-turn conversation with tool calls to exercise the pipeline.
-string[] prompts =
-[
-    "What's the price of a laptop?",
-    "How about a keyboard?",
-    "And a mouse?",
-    "Which product is the cheapest?",
-    "Can you compare the laptop and the keyboard for me?",
-    "What was the first product I asked about?",
-    "Thank you!",
-];
-
-foreach (string prompt in prompts)
-{
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[User] ");
-    Console.ResetColor();
-    Console.WriteLine(prompt);
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-    Console.WriteLine(await agent.RunAsync(prompt, session));
-
-    PrintChatHistory();
-}

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

@@ -1,132 +0,0 @@
-# Compaction Pipeline
-
-This sample demonstrates how to use a `CompactionProvider` with a `PipelineCompactionStrategy` to manage long conversation histories in a token-efficient way. The pipeline chains four compaction strategies, ordered from gentle to aggressive, so that the least disruptive strategy runs first and more aggressive strategies only activate when necessary.
-
-## What This Sample Shows
-
-- **`CompactionProvider`** — an `AIContextProvider` that applies a compaction strategy before each agent invocation, keeping only the most relevant messages within the model's context window
-- **`PipelineCompactionStrategy`** — chains multiple compaction strategies into an ordered pipeline; each strategy evaluates its own trigger independently and operates on the output of the previous one
-- **`ToolResultCompactionStrategy`** — collapses older tool-call groups into concise inline summaries, activated by a message-count trigger
-- **`SummarizationCompactionStrategy`** — uses an LLM to compress older conversation spans into a single summary message, activated by a token-count trigger
-- **`SlidingWindowCompactionStrategy`** — retains only the most recent N user turns and their responses, activated by a turn-count trigger
-- **`TruncationCompactionStrategy`** — emergency backstop that drops the oldest groups until the conversation fits within a hard token budget
-- **`CompactionTriggers`** — factory methods (`MessagesExceed`, `TokensExceed`, `TurnsExceed`, `GroupsExceed`, `HasToolCalls`, `All`, `Any`) that control when each strategy activates
-
-## Concepts
-
-### Message groups
-
-The compaction engine organizes messages into atomic *groups* that are treated as indivisible units during compaction. A group is either:
-
-| Group kind | Contents |
-|---|---|
-| `System` | System prompt message(s) |
-| `User` | A single user message |
-| `ToolCall` | One assistant message with tool calls + the matching tool result messages |
-| `AssistantText` | A single assistant text-only message |
-| `Summary` | One or more messages summarizing earlier conversation spans, produced by compaction strategies |
-
-`Summary` groups (`CompactionGroupKind.Summary`) are created by compaction strategies (for example, `SummarizationCompactionStrategy`) and do not originate directly from user or assistant messages.
-Strategies exclude entire groups rather than individual messages, preserving the tool-call/result pairing required by most model APIs.
-
-### Compaction triggers
-
-A `CompactionTrigger` is a predicate evaluated against the current `MessageIndex`. When the trigger fires, the strategy performs compaction; when it does not fire, the strategy is skipped. Available triggers are:
-
-| Trigger | Activates when… |
-|---|---|
-| `CompactionTriggers.Always` | Always (unconditional) |
-| `CompactionTriggers.Never` | Never (disabled) |
-| `CompactionTriggers.MessagesExceed(n)` | Included message count > n |
-| `CompactionTriggers.TokensExceed(n)` | Included token count > n |
-| `CompactionTriggers.TurnsExceed(n)` | Included user-turn count > n |
-| `CompactionTriggers.GroupsExceed(n)` | Included group count > n |
-| `CompactionTriggers.HasToolCalls()` | At least one included tool-call group exists |
-| `CompactionTriggers.All(...)` | All supplied triggers fire (logical AND) |
-| `CompactionTriggers.Any(...)` | Any supplied trigger fires (logical OR) |
-
-### Pipeline ordering
-
-Order strategies from **least aggressive** to **most aggressive**. The pipeline runs every strategy whose trigger is met. Earlier strategies reduce the conversation gently so that later, more destructive strategies may not need to activate at all.
-
-```
-1. ToolResultCompactionStrategy  – gentle:    replaces verbose tool results with a short label
-2. SummarizationCompactionStrategy – moderate: LLM-summarizes older turns
-3. SlidingWindowCompactionStrategy – aggressive: drops turns beyond the window
-4. TruncationCompactionStrategy   – emergency:  hard token-budget enforcement
-```
-
-## Prerequisites
-
-- .NET 10 SDK or later
-- Azure OpenAI service endpoint and model deployment
-- Azure CLI installed and authenticated
-
-**Note**: This sample uses `DefaultAzureCredential`. Sign in with `az login` before running. For production, prefer a specific credential such as `ManagedIdentityCredential`. For more information, see the [Azure CLI authentication documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-## Environment Variables
-
-```powershell
-$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"  # Required
-$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"                       # Optional, defaults to gpt-4o-mini
-```
-
-## Running the Sample
-
-```powershell
-cd dotnet/samples/02-agents/Agents/Agent_Step18_CompactionPipeline
-dotnet run
-```
-
-## Expected Behavior
-
-The sample runs a seven-turn shopping-assistant conversation with tool calls. After each turn it prints the full message count so you can observe the pipeline compaction doesn't alter the source conversation.
-
-Each of the four compaction strategies has a deliberately low threshold so that it activates during the short demonstration conversation. In a production scenario you would raise the thresholds to match your model's context window and cost requirements.
-
-## Customizing the Pipeline
-
-### Using a single strategy
-
-If you only need one compaction strategy, pass it directly to `CompactionProvider` without wrapping it in a pipeline:
-
-```csharp
-CompactionProvider provider =
-    new(new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(20)));
-```
-
-### Ad-hoc compaction outside the provider pipeline
-
-`CompactionProvider.CompactAsync` applies a strategy to an arbitrary list of messages without an active agent session:
-
-```csharp
-IEnumerable<ChatMessage> compacted = await CompactionProvider.CompactAsync(
-    new TruncationCompactionStrategy(CompactionTriggers.TokensExceed(8000)),
-    existingMessages);
-```
-
-### Using a different model for summarization
-
-The `SummarizationCompactionStrategy` accepts any `IChatClient`. Use a smaller, cheaper model to reduce summarization cost:
-
-```csharp
-IChatClient summarizerChatClient = openAIClient.GetChatClient("gpt-4o-mini").AsIChatClient();
-new SummarizationCompactionStrategy(summarizerChatClient, CompactionTriggers.TokensExceed(4000))
-```
-
-### Registering through `ChatClientAgentOptions`
-
-`CompactionProvider` can also be specified directly on `ChatClientAgentOptions` instead of calling `UseAIContextProviders` on the `ChatClientBuilder`:
-
-```csharp
-AIAgent agent = agentChatClient
-    .AsBuilder()
-    .BuildAIAgent(new ChatClientAgentOptions
-    {
-        AIContextProviders = [new CompactionProvider(compactionPipeline)]
-    });
-```
-
-This places the compaction provider at the agent level instead of the chat client level, which allows you to use different compaction strategies for different agents that share the same chat client.
-
-> Note: In this mode the `CompactionProvider` is not engaged during the tool calling loop. Agent-level `AIContextProviders` run before chat history is stored, so any synthetic summary messages produced by `CompactionProvider` can become part of the persisted history when using `ChatHistoryProvider`. If you want to compact only the request context while preserving the original stored history, register `CompactionProvider` on the `ChatClientBuilder` via `UseAIContextProviders(...)` instead of on `ChatClientAgentOptions`.

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

@@ -1,226 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how the ChatClientAgent persists chat history after each individual
-// call to the AI service.
-// When an agent uses tools, FunctionInvokingChatClient may loop multiple times
-// (service call → tool execution → service call), and intermediate messages (tool calls and
-// results) are persisted after each service call. This allows you to inspect or recover them
-// even if the process is interrupted mid-loop, but may also result in chat history that is not
-// yet finalized (e.g., tool calls without results) being persisted, which may be undesirable in some cases.
-//
-// To opt into end-of-run persistence instead (atomic run semantics), set
-// PersistChatHistoryAtEndOfRun = true on ChatClientAgentOptions.
-//
-// The sample runs two multi-turn conversations: one using non-streaming (RunAsync) and one
-// using streaming (RunStreamingAsync), to demonstrate correct behavior in both modes.
-
-using System.ComponentModel;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Responses;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-var store = Environment.GetEnvironmentVariable("AZURE_OPENAI_RESPONSES_STORE") ?? "false";
-
-// 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.
-AzureOpenAIClient openAIClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-// Define multiple tools so the model makes several tool calls in a single run.
-[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.",
-        "DUBLIN" => "Dublin: 43°F, overcast with fog.",
-        _ => $"{city}: weather data not available."
-    };
-
-[Description("Get the current time in 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",
-        "DUBLIN" => "Dublin: 5:00 PM GMT",
-        _ => $"{city}: time data not available."
-    };
-
-// Create the agent — per-service-call persistence is the default behavior.
-// The in-memory ChatHistoryProvider is used by default when the service does not require service stored chat
-// history, so for those cases, we can inspect the chat history via session.TryGetInMemoryChatHistory().
-IChatClient chatClient = string.Equals(store, "TRUE", StringComparison.OrdinalIgnoreCase) ?
-    openAIClient.GetResponsesClient().AsIChatClient(deploymentName) :
-    openAIClient.GetResponsesClient().AsIChatClientWithStoredOutputDisabled(deploymentName);
-AIAgent agent = chatClient.AsAIAgent(
-    new ChatClientAgentOptions
-    {
-        Name = "WeatherAssistant",
-        ChatOptions = new()
-        {
-            Instructions = "You are a helpful assistant. When asked about multiple cities, call the appropriate tool for each city.",
-            Tools = [AIFunctionFactory.Create(GetWeather), AIFunctionFactory.Create(GetTime)]
-        },
-    });
-
-await RunNonStreamingAsync();
-await RunStreamingAsync();
-
-async Task RunNonStreamingAsync()
-{
-    int lastChatHistorySize = 0;
-    string lastConversationId = string.Empty;
-
-    Console.ForegroundColor = ConsoleColor.Yellow;
-    Console.WriteLine("\n=== Non-Streaming Mode ===");
-    Console.ResetColor();
-
-    AgentSession session = await agent.CreateSessionAsync();
-
-    // First turn — ask about multiple cities so the model calls tools.
-    const string Prompt = "What's the weather and time in Seattle, New York, and London?";
-    PrintUserMessage(Prompt);
-
-    var response = await agent.RunAsync(Prompt, session);
-    PrintAgentResponse(response.Text);
-    PrintChatHistory(session, "After run", ref lastChatHistorySize, ref lastConversationId);
-
-    // Second turn — follow-up to verify chat history is correct.
-    const string FollowUp1 = "And Dublin?";
-    PrintUserMessage(FollowUp1);
-
-    response = await agent.RunAsync(FollowUp1, session);
-    PrintAgentResponse(response.Text);
-    PrintChatHistory(session, "After second run", ref lastChatHistorySize, ref lastConversationId);
-
-    // Third turn — follow-up to verify chat history is correct.
-    const string FollowUp2 = "Which city is the warmest?";
-    PrintUserMessage(FollowUp2);
-
-    response = await agent.RunAsync(FollowUp2, session);
-    PrintAgentResponse(response.Text);
-    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
-}
-
-async Task RunStreamingAsync()
-{
-    int lastChatHistorySize = 0;
-    string lastConversationId = string.Empty;
-
-    Console.ForegroundColor = ConsoleColor.Yellow;
-    Console.WriteLine("\n=== Streaming Mode ===");
-    Console.ResetColor();
-
-    AgentSession session = await agent.CreateSessionAsync();
-
-    // First turn — ask about multiple cities so the model calls tools.
-    const string Prompt = "What's the weather and time in Seattle, New York, and London?";
-    PrintUserMessage(Prompt);
-
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-
-    await foreach (var update in agent.RunStreamingAsync(Prompt, session))
-    {
-        Console.Write(update);
-
-        // During streaming we should be able to see updates to the chat history
-        // before the full run completes, as each service call is made and persisted.
-        PrintChatHistory(session, "During run", ref lastChatHistorySize, ref lastConversationId);
-    }
-
-    Console.WriteLine();
-    PrintChatHistory(session, "After run", ref lastChatHistorySize, ref lastConversationId);
-
-    // Second turn — follow-up to verify chat history is correct.
-    const string FollowUp1 = "And Dublin?";
-    PrintUserMessage(FollowUp1);
-
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-
-    await foreach (var update in agent.RunStreamingAsync(FollowUp1, session))
-    {
-        Console.Write(update);
-
-        // During streaming we should be able to see updates to the chat history
-        // before the full run completes, as each service call is made and persisted.
-        PrintChatHistory(session, "During second run", ref lastChatHistorySize, ref lastConversationId);
-    }
-
-    Console.WriteLine();
-    PrintChatHistory(session, "After second run", ref lastChatHistorySize, ref lastConversationId);
-
-    // Third turn — follow-up to verify chat history is correct.
-    const string FollowUp2 = "Which city is the warmest?";
-    PrintUserMessage(FollowUp2);
-
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-
-    await foreach (var update in agent.RunStreamingAsync(FollowUp2, session))
-    {
-        Console.Write(update);
-
-        // During streaming we should be able to see updates to the chat history
-        // before the full run completes, as each service call is made and persisted.
-        PrintChatHistory(session, "During third run", ref lastChatHistorySize, ref lastConversationId);
-    }
-
-    Console.WriteLine();
-    PrintChatHistory(session, "After third run", ref lastChatHistorySize, ref lastConversationId);
-}
-
-void PrintUserMessage(string message)
-{
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[User] ");
-    Console.ResetColor();
-    Console.WriteLine(message);
-}
-
-void PrintAgentResponse(string? text)
-{
-    Console.ForegroundColor = ConsoleColor.Cyan;
-    Console.Write("\n[Agent] ");
-    Console.ResetColor();
-    Console.WriteLine(text);
-}
-
-// Helper to print the current chat history from the session.
-void PrintChatHistory(AgentSession session, string label, ref int lastChatHistorySize, ref string lastConversationId)
-{
-    if (session.TryGetInMemoryChatHistory(out var history) && history.Count != lastChatHistorySize)
-    {
-        Console.ForegroundColor = ConsoleColor.DarkGray;
-        Console.WriteLine($"\n  [{label} — Chat history: {history.Count} message(s)]");
-        foreach (var msg in history)
-        {
-            var preview = msg.Text?.Length > 80 ? msg.Text[..80] + "…" : msg.Text;
-            var contentTypes = string.Join(", ", msg.Contents.Select(c => c.GetType().Name));
-            Console.WriteLine($"    {msg.Role,-12} | {(string.IsNullOrWhiteSpace(preview) ? $"[{contentTypes}]" : preview)}");
-        }
-
-        Console.ResetColor();
-
-        lastChatHistorySize = history.Count;
-    }
-
-    if (session is ChatClientAgentSession ccaSession && ccaSession.ConversationId is not null && ccaSession.ConversationId != lastConversationId)
-    {
-        Console.ForegroundColor = ConsoleColor.DarkGray;
-        Console.WriteLine($"  [{label} — Conversation ID: {ccaSession.ConversationId}]");
-        Console.ResetColor();
-        lastConversationId = ccaSession.ConversationId;
-    }
-}

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

@@ -1,63 +0,0 @@
-# In-Function-Loop Checkpointing
-
-This sample demonstrates how `ChatClientAgent` persists chat history after each individual call to the AI service by default. This per-service-call persistence ensures intermediate progress is saved during the function invocation loop.
-
-## What This Sample Shows
-
-When an agent uses tools, the `FunctionInvokingChatClient` loops multiple times (service call → tool execution → service call → …). By default, chat history is persisted after each service call via the `ChatHistoryPersistingChatClient` decorator:
-
-- A `ChatHistoryPersistingChatClient` decorator is automatically inserted into the chat client pipeline
-- After each service call, the decorator notifies the `ChatHistoryProvider` (and any `AIContextProvider` instances) with the new messages
-- Only **new** messages are sent to providers on each notification — messages that were already persisted in an earlier call within the same run are deduplicated automatically
-
-To opt into end-of-run persistence instead (atomic run semantics), set `PersistChatHistoryAtEndOfRun = true` on `ChatClientAgentOptions`. In that mode, the decorator marks messages with metadata rather than persisting them immediately, and `ChatClientAgent` persists only the marked messages at the end of the run.
-
-Per-service-call persistence is useful for:
-- **Crash recovery** — if the process is interrupted mid-loop, the intermediate tool calls and results are already persisted
-- **Observability** — you can inspect the chat history while the agent is still running (e.g., during streaming)
-- **Long-running tool loops** — agents with many sequential tool calls benefit from incremental persistence
-
-## How It Works
-
-The sample asks the agent about the weather and time in three cities. The model calls the `GetWeather` and `GetTime` tools for each city, resulting in multiple service calls within a single `RunStreamingAsync` invocation. After the run completes, the sample prints the full chat history to show all the intermediate messages that were persisted along the way.
-
-### Pipeline Architecture
-
-```
-ChatClientAgent
-  └─ FunctionInvokingChatClient    (handles tool call loop)
-       └─ ChatHistoryPersistingChatClient  (persists after each service call)
-            └─ Leaf IChatClient            (Azure OpenAI)
-```
-
-## Prerequisites
-
-- .NET 10 SDK or later
-- Azure OpenAI service endpoint and model deployment
-- Azure CLI installed and authenticated
-
-**Note**: This sample uses `DefaultAzureCredential`. Sign in with `az login` before running. For production, prefer a specific credential such as `ManagedIdentityCredential`. For more information, see the [Azure CLI authentication documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-## Environment Variables
-
-```powershell
-$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"  # Required
-$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"                       # Optional, defaults to gpt-4o-mini
-```
-
-## Running the Sample
-
-```powershell
-cd dotnet/samples/02-agents/Agents/Agent_Step19_InFunctionLoopCheckpointing
-dotnet run
-```
-
-## Expected Behavior
-
-The sample runs two conversation turns:
-
-1. **First turn** — asks about weather and time in three cities. The model calls `GetWeather` and `GetTime` tools (potentially in parallel or sequentially), then provides a summary. The chat history dump after the run shows all the intermediate tool call and result messages.
-
-2. **Second turn** — asks a follow-up question ("Which city is the warmest?") that uses the persisted conversation context. The chat history dump shows the full accumulated conversation.
-
-The chat history printout uses `session.TryGetInMemoryChatHistory()` to inspect the in-memory storage.

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

@@ -1,36 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create, use, and clean up a FoundryAgent backed by a server-side
-// versioned agent in Azure AI Foundry. It demonstrates the full lifecycle:
-// create agent version -> wrap as FoundryAgent -> run -> delete.
-
-using Azure.AI.Projects;
-using Azure.AI.Projects.Agents;
-using Azure.Identity;
-using Microsoft.Agents.AI.AzureAI;
-
-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-4o-mini";
-
-const string JokerName = "JokerAgent";
-
-// Create the AIProjectClient to manage server-side agents.
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential());
-
-// Create a server-side agent version using the native SDK.
-AgentVersion agentVersion = await aiProjectClient.Agents.CreateAgentVersionAsync(
-    JokerName,
-    new AgentVersionCreationOptions(
-        new PromptAgentDefinition(model: deploymentName)
-        {
-            Instructions = "You are good at telling jokes.",
-        }));
-
-// Wrap the agent version as a FoundryAgent using the AsAIAgent extension.
-FoundryAgent agent = aiProjectClient.AsAIAgent(agentVersion);
-
-// Once you have the agent, you can invoke it like any other AIAgent.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
-
-// Cleanup: deletes the agent and all its versions.
-await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);

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

@@ -1,23 +0,0 @@
-# Agent Step 00 - FoundryAgent Lifecycle
-
-This sample demonstrates the full lifecycle of a `FoundryAgent` backed by a server-side versioned agent in Microsoft Foundry: create → run → delete.
-
-## Prerequisites
-
-- A Microsoft Foundry project endpoint
-- A model deployment name (defaults to `gpt-4o-mini`)
-- Azure CLI installed and authenticated
-
-## Environment Variables
-
-| Variable | Description | Required |
-| --- | --- | --- |
-| `AZURE_AI_PROJECT_ENDPOINT` | Microsoft Foundry project endpoint | Yes |
-| `AZURE_AI_MODEL_DEPLOYMENT_NAME` | Model deployment name | No (defaults to `gpt-4o-mini`) |
-
-## Running the sample
-
-```powershell
-cd dotnet/samples/02-agents/AgentsWithFoundry
-dotnet run --project .\Agent_Step00_FoundryAgentLifecycle
-```

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

@@ -1,15 +0,0 @@
-<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.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-
-</Project>

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

@@ -1,20 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// 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;
-
-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-4o-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.
-AIAgent agent =
-    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
-    .AsAIAgent(model: deploymentName, instructions: "You are good at telling jokes.", name: "JokerAgent");
-
-// Once you have the agent, you can invoke it like any other AIAgent.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

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

@@ -1,55 +0,0 @@
-# Creating and Running a Basic Agent with the Responses API
-
-This sample demonstrates how to create and run a basic AI agent using the `ChatClientAgent`, which uses the Microsoft Foundry Responses API directly without creating server-side agent definitions.
-
-## What this sample demonstrates
-
-- Creating a `ChatClientAgent` with instructions and a model
-- Running a simple single-turn conversation
-- No server-side agent creation or cleanup required
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Microsoft Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Microsoft Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-## Run the sample
-
-Navigate to the AgentsWithFoundry sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/AgentsWithFoundry
-dotnet run --project .\Agent_Step01_Basics
-```
-
-## Alternative: Composable approach
-
-You can also create the same agent by composing the underlying `IChatClient` directly. This gives you full control over the chat client pipeline:
-
-```csharp
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-AIAgent agent = new ChatClientAgent(
-    chatClient: aiProjectClient.GetProjectOpenAIClient().GetProjectResponsesClient().AsIChatClient(deploymentName),
-    instructions: "You are good at telling jokes.",
-    name: "JokerAgent");
-```
-
-This approach is useful when you need to customize the chat client pipeline or swap providers (e.g., Anthropic, OpenAI) while keeping the same agent code.

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step02.1_MultiturnConversation/Program.cs

@@ -1,26 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create a multi-turn conversation agent using sessions.
-// Context is preserved across multiple runs via response ID chaining in the session.
-
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-
-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-4o-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.
-AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
-    .AsAIAgent(deploymentName, instructions: "You are good at telling jokes.", name: "JokerAgent");
-
-// Create a session to maintain context across multiple runs.
-AgentSession session = await agent.CreateSessionAsync();
-
-// First turn
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
-
-// Second turn — the agent remembers the first turn via the session.
-Console.WriteLine(await agent.RunAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", session));

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step02.1_MultiturnConversation/README.md

@@ -1,36 +0,0 @@
-# Multi-turn Conversation
-
-This sample demonstrates how to implement multi-turn conversations where context is preserved across multiple agent runs using sessions and response ID chaining.
-
-## What this sample demonstrates
-
-- Creating an agent with instructions
-- Using sessions to maintain conversation context across multiple runs
-- Response ID chaining for multi-turn conversations
-- No server-side conversation creation required
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Microsoft Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Microsoft Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-## Run the sample
-
-Navigate to the AgentsWithFoundry sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/AgentsWithFoundry
-dotnet run --project .\Agent_Step02.1_MultiturnConversation
-```

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step02.2_MultiturnWithServerConversations/Agent_Step02.2_MultiturnWithServerConversations.csproj

@@ -1,15 +0,0 @@
-<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.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step02.2_MultiturnWithServerConversations/Program.cs

@@ -1,34 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to use server-side conversations with a FoundryAgent.
-// Server-side conversations persist on the Foundry service and are visible in the Foundry Project UI.
-// Use this when you need conversation history to be stored and accessible server-side.
-
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.AzureAI;
-
-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-4o-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.
-FoundryAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
-    .AsAIAgent(deploymentName, instructions: "You are good at telling jokes.", name: "JokerAgent");
-
-// CreateConversationSessionAsync creates a server-side ProjectConversation
-// that persists on the Foundry service and is visible in the Foundry Project UI.
-AgentSession session = await agent.CreateConversationSessionAsync();
-
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
-Console.WriteLine(await agent.RunAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", session));
-
-// Streaming with server-side conversation context.
-await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("Tell me another joke, but about a ninja this time.", session))
-{
-    Console.Write(update);
-}
-
-Console.WriteLine();

dotnet/samples/02-agents/AgentsWithFoundry/Agent_Step02.2_MultiturnWithServerConversations/README.md

@@ -1,36 +0,0 @@
-# Multi-turn Conversation with Server-Side Conversations
-
-This sample demonstrates how to use server-side conversations with a `FoundryAgent`. Server-side conversations persist on the Foundry service and are visible in the Foundry Project UI, making them ideal when you need conversation history to be stored and accessible server-side.
-
-## What this sample demonstrates
-
-- Creating a `FoundryAgent` with instructions
-- Using `CreateConversationSessionAsync` to create a server-side `ProjectConversation`
-- Multi-turn conversations with both text and streaming output
-- Server-side conversation persistence visible in the Foundry Project UI
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Microsoft Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Microsoft Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-## Run the sample
-
-Navigate to the AgentsWithFoundry sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/AgentsWithFoundry
-dotnet run --project .\Agent_Step02.2_MultiturnWithServerConversations
-```

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

@@ -1,15 +0,0 @@
-<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.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-
-</Project>

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

@@ -1,41 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use function tools.
-
-using System.ComponentModel;
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-[Description("Get the weather for a given location.")]
-static string GetWeather([Description("The location to get the weather for.")] string location)
-    => $"The weather in {location} is cloudy with a high of 15°C.";
-
-// Define the function tool.
-AITool tool = AIFunctionFactory.Create(GetWeather);
-
-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-4o-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.
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-// Create a AIAgent with function tools.
-AIAgent agent = aiProjectClient.AsAIAgent(deploymentName,
-    instructions: "You are a helpful assistant that can get weather information.",
-    name: "WeatherAssistant",
-    tools: [tool]);
-
-// Non-streaming agent interaction with function tools.
-AgentSession session = await agent.CreateSessionAsync();
-Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", session));
-
-// Streaming agent interaction with function tools.
-session = await agent.CreateSessionAsync();
-await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("What is the weather like in Amsterdam?", session))
-{
-    Console.Write(update);
-}

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

@@ -1,37 +0,0 @@
-# Using Function Tools with the Responses API
-
-This sample demonstrates how to use function tools with the `ChatClientAgent`, allowing the agent to call custom functions to retrieve information.
-
-## What this sample demonstrates
-
-- Creating function tools using `AIFunctionFactory`
-- Passing function tools to a `ChatClientAgent`
-- Running agents with function tools (text output)
-- Running agents with function tools (streaming output)
-- No server-side agent creation or cleanup required
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Microsoft Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Microsoft Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-## Run the sample
-
-Navigate to the AgentsWithFoundry sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/AgentsWithFoundry
-dotnet run --project .\Agent_Step03_UsingFunctionTools
-```

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

@@ -1,15 +0,0 @@
-<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.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-
-</Project>

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

@@ -1,30 +0,0 @@
-# Using Function Tools with Approvals via the Responses API
-
-This sample demonstrates how to use function tools that require human-in-the-loop approval before execution.
-
-## What this sample demonstrates
-
-- Creating function tools that require approval using `ApprovalRequiredAIFunction`
-- Handling approval requests from the agent
-- Passing approval responses back to the agent
-- No server-side agent creation or cleanup required
-
-## Prerequisites
-
-- .NET 10 SDK or later
-- Microsoft Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (`az login`)
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-## Run the sample
-
-```powershell
-cd dotnet/samples/02-agents/AgentsWithFoundry
-dotnet run --project .\Agent_Step04_UsingFunctionToolsWithApprovals
-```

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

@@ -1,15 +0,0 @@
-<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.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-
-</Project>

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

@@ -1,71 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to configure an agent to produce structured output.
-
-using System.ComponentModel;
-using System.Text.Json;
-using System.Text.Json.Serialization;
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using SampleApp;
-
-#pragma warning disable CA5399
-
-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-4o-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.
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-AIAgent agent = aiProjectClient.AsAIAgent(new ChatClientAgentOptions
-{
-    Name = "StructuredOutputAssistant",
-    ChatOptions = new()
-    {
-        ModelId = deploymentName,
-        Instructions = "You are a helpful assistant that extracts structured information about people.",
-        ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>()
-    }
-});
-
-// Set PersonInfo as the type parameter of RunAsync method to specify the expected structured output.
-AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-
-// Access the structured output via the Result property of the agent response.
-Console.WriteLine("Assistant Output:");
-Console.WriteLine($"Name: {response.Result.Name}");
-Console.WriteLine($"Age: {response.Result.Age}");
-Console.WriteLine($"Occupation: {response.Result.Occupation}");
-
-// Invoke the agent with streaming support, then deserialize the assembled response.
-IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Please provide information about Jane Doe, who is a 28-year-old data scientist.");
-
-PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>((await updates.ToAgentResponseAsync()).Text, JsonSerializerOptions.Web)
-    ?? throw new InvalidOperationException("Failed to deserialize the streamed response into PersonInfo.");
-
-Console.WriteLine("\nStreaming Assistant Output:");
-Console.WriteLine($"Name: {personInfo.Name}");
-Console.WriteLine($"Age: {personInfo.Age}");
-Console.WriteLine($"Occupation: {personInfo.Occupation}");
-
-namespace SampleApp
-{
-    /// <summary>
-    /// Represents information about a person.
-    /// </summary>
-    [Description("Information about a person including their name, age, and occupation")]
-    public class PersonInfo
-    {
-        [JsonPropertyName("name")]
-        public string? Name { get; set; }
-
-        [JsonPropertyName("age")]
-        public int? Age { get; set; }
-
-        [JsonPropertyName("occupation")]
-        public string? Occupation { get; set; }
-    }
-}

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

@@ -1,29 +0,0 @@
-# Structured Output with the Responses API
-
-This sample demonstrates how to configure an agent to produce structured output using JSON schema.
-
-## What this sample demonstrates
-
-- Using `RunAsync<T>()` to get typed structured output from the agent
-- Deserializing streamed responses into structured types
-- No server-side agent creation or cleanup required
-
-## Prerequisites
-
-- .NET 10 SDK or later
-- Microsoft Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (`az login`)
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project"
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-## Run the sample
-
-```powershell
-cd dotnet/samples/02-agents/AgentsWithFoundry
-dotnet run --project .\Agent_Step05_StructuredOutput
-```

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

@@ -1,15 +0,0 @@
-<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.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-
-</Project>