chore: import upstream snapshot with attribution

python/samples/02-agents/skills/mixed_skills/README.md

@@ -0,0 +1,118 @@
+# Mixed Skills — Code, Class, and File Skills
+
+This sample demonstrates how to combine **code-defined skills**,
+**class-based skills**, and **file-based skills** in a single agent using
+`SkillsProvider`.
+
+## Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Code skill** | A `Skill` created in Python with `@skill.script` decorators for in-process callable functions and `@skill.resource` for dynamic content |
+| **Class skill** | A self-contained skill class extending `ClassSkill`, bundling instructions, resources, and scripts |
+| **File skill** | A skill discovered from a `SKILL.md` file on disk, with reference documents and executable script files |
+| **`script_runner`** | A callable (sync or async) satisfying the `SkillScriptRunner` protocol — required when file skills have scripts |
+| **`SkillsProvider`** | Registers code-defined, class-based, and file-based skills in a single provider |
+
+## Skills in This Sample
+
+### volume-converter (code skill)
+
+Defined entirely in Python code using decorators:
+
+- **`@skill.resource`** — `conversion-table`: gallons↔liters conversion factors
+- **`@skill.script`** — `convert`: converts a value using a multiplication factor
+
+Code scripts run **in-process** — no subprocess or external runner needed.
+
+### temperature-converter (class skill)
+
+Defined as a `TemperatureConverterSkill` class extending `ClassSkill`:
+
+- **`@ClassSkill.resource`** — `temperature-conversion-formulas`: °F↔°C↔K formulas
+- **`@ClassSkill.script`** — `convert-temperature`: converts between temperature scales
+
+Class-based scripts run **in-process** — no subprocess or external runner needed.
+
+### unit-converter (file skill)
+
+Discovered from `skills/unit-converter/SKILL.md`:
+
+- **Reference**: `references/CONVERSION_TABLES.md` — supported unit conversions and their factors
+- **Script**: `scripts/convert.py` — converts a value using a multiplication factor (e.g. miles to kilometers)
+
+File scripts are executed as **local Python subprocesses** via the
+`script_runner` callback.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  SkillsProvider(                                            │
+│    DeduplicatingSkillsSource(                               │
+│      AggregatingSkillsSource([                              │
+│        FileSkillsSource("./skills",       # file skills     │
+│            script_runner=runner),                            │
+│        InMemorySkillsSource([                               │
+│            volume_skill,                  # code skill      │
+│            temp_converter,                # class skill     │
+│        ]),                                                  │
+│      ])                                                     │
+│    )                                                        │
+│  )                                                          │
+└─────────────┬───────────────────────────────────────────────┘
+              │
+              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  script_runner(skill, script, args)                          │
+│                                                             │
+│  • Code scripts (@skill.script) → in-process call           │
+│  • Class scripts (@ClassSkill.script) → in-process call     │
+│  • File scripts (scripts/*.py) → subprocess via             │
+│    the callback function                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Prerequisites
+
+Set environment variables (or create a `.env` file):
+
+```
+FOUNDRY_PROJECT_ENDPOINT=https://your-project.openai.azure.com/
+AZURE_OPENAI_MODEL=gpt-4o-mini
+```
+
+Authenticate with Azure CLI:
+
+```bash
+az login
+```
+
+## Running the Sample
+
+```bash
+cd python
+uv run samples/02-agents/skills/mixed_skills/mixed_skills.py
+```
+
+## Directory Structure
+
+```
+mixed_skills/
+├── mixed_skills.py                # Main sample — wires code + file skills together
+├── README.md
+└── skills/
+    └── unit-converter/            # File-based skill (discovered from SKILL.md)
+        ├── SKILL.md
+        ├── references/
+        │   └── CONVERSION_TABLES.md
+        └── scripts/
+            └── convert.py
+```
+
+## Learn More
+
+- [File-Based Skills Sample](../file_based_skill/)
+- [Code-Defined Skills Sample](../code_defined_skill/)
+- [Script Approval Sample](../script_approval/)
+- [Agent Skills Specification](https://agentskills.io/)

python/samples/02-agents/skills/mixed_skills/mixed_skills.py

@@ -0,0 +1,248 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+import json
+import os
+import sys
+from pathlib import Path
+from textwrap import dedent
+from typing import Any
+
+from agent_framework import (
+    Agent,
+    AggregatingSkillsSource,
+    ClassSkill,
+    DeduplicatingSkillsSource,
+    FileSkillsSource,
+    InlineSkill,
+    InMemorySkillsSource,
+    SkillFrontmatter,
+    SkillsProvider,
+    ToolApprovalMiddleware,
+)
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+# Add the skills folder root to sys.path so the shared subprocess_script_runner can be imported
+_SKILLS_ROOT = str(Path(__file__).resolve().parent.parent)
+if _SKILLS_ROOT not in sys.path:
+    sys.path.insert(0, _SKILLS_ROOT)
+
+from subprocess_script_runner import subprocess_script_runner  # pyrefly: ignore[missing-import]  # noqa: E402
+
+"""
+Mixed Skills — Code, class, and file skills in a single agent
+
+This sample demonstrates how to combine **code-defined skills** (with
+``@skill.script`` and ``@skill.resource`` decorators), **class-based skills**
+(subclassing ``ClassSkill``), and **file-based skills** (discovered from
+``SKILL.md`` files on disk) in a single agent using ``SkillsProvider`` and
+a ``SkillScriptRunner`` callable.
+
+Key concepts shown:
+- Code skills with ``@skill.script``: executable Python functions the agent
+  can invoke directly in-process.
+- Code skills with ``@skill.resource``: dynamic content the agent can read
+  on demand.
+- Class skills: self-contained skill classes extending ``ClassSkill``.
+- File skills from disk: ``SKILL.md`` files with reference documents and
+  executable script files.
+- ``script_runner``: routes **file-based** script execution
+  through a callback, enabling custom handling (e.g. subprocess calls).
+  Code-defined and class-based scripts run in-process automatically.
+
+The sample registers three skills:
+1. **volume-converter** (code skill) — converts between gallons and liters using
+   ``@skill.script`` for conversion and ``@skill.resource`` for the factor table.
+2. **temperature-converter** (class skill) — converts between temperature scales
+   (°F↔°C↔K) using a ``ClassSkill`` subclass.
+3. **unit-converter** (file skill) — converts between common units (miles↔km,
+   pounds↔kg) via a subprocess-executed Python script discovered from
+   ``skills/unit-converter/SKILL.md``.
+"""
+
+# Load environment variables from .env file
+load_dotenv()
+
+# ---------------------------------------------------------------------------
+# 1. Define a code skill with @skill.script and @skill.resource decorators
+# ---------------------------------------------------------------------------
+
+volume_converter_skill = InlineSkill(
+    frontmatter=SkillFrontmatter(
+        name="volume-converter", description="Convert between gallons and liters using a conversion factor"
+    ),
+    instructions=dedent("""\
+        Use this skill when the user asks to convert between gallons and liters.
+
+        1. Review the conversion-table resource to find the correct factor.
+        2. Use the convert script, passing the value and factor.
+    """),
+)
+
+
+@volume_converter_skill.resource(name="conversion-table", description="Volume conversion factors")
+def volume_table() -> Any:
+    """Return the volume conversion factor table."""
+    return dedent("""\
+        # Volume Conversion Table
+
+        Formula: **result = value × factor**
+
+        | From    | To     | Factor  |
+        |---------|--------|---------|
+        | gallons | liters | 3.78541 |
+        | liters  | gallons| 0.264172|
+    """)
+
+
+@volume_converter_skill.script(name="convert", description="Convert a value: result = value × factor")
+def convert_volume(value: float, factor: float) -> str:
+    """Convert a value using a multiplication factor.
+
+    Args:
+        value: The numeric value to convert.
+        factor: Conversion factor from the table.
+
+    Returns:
+        JSON string with the conversion result.
+    """
+    result = round(value * factor, 4)
+    return json.dumps({"value": value, "factor": factor, "result": result})
+
+
+# ---------------------------------------------------------------------------
+# 2. Define a class-based skill for temperature conversion
+# ---------------------------------------------------------------------------
+
+
+class TemperatureConverterSkill(ClassSkill):
+    """A temperature-converter skill defined as a Python class.
+
+    Converts between temperature scales (Fahrenheit, Celsius, Kelvin).
+    Resources and scripts are discovered automatically via decorators.
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            frontmatter=SkillFrontmatter(
+                name="temperature-converter",
+                description="Convert between temperature scales (Fahrenheit, Celsius, Kelvin).",
+            )
+        )
+
+    @property
+    def instructions(self) -> str:
+        return dedent("""\
+            Use this skill when the user asks to convert temperatures.
+
+            1. Read the temperature-conversion-formulas resource to find the factor and offset
+               for the requested conversion.
+            2. Use the convert-temperature script, passing value, factor, and offset.
+            3. Present the result clearly with both temperature scales.
+        """)
+
+    @ClassSkill.resource(name="temperature-conversion-formulas")
+    def formulas(self) -> str:
+        """Temperature conversion formulas reference table."""
+        return dedent("""\
+            # Temperature Conversion Formulas
+
+            Formula: **result = value × factor + offset**
+
+            | From        | To          | Factor   | Offset    |
+            |-------------|-------------|----------|-----------|
+            | Fahrenheit  | Celsius     | 0.555556 | -17.7778  |
+            | Celsius     | Fahrenheit  | 1.8      | 32        |
+            | Celsius     | Kelvin      | 1        | 273.15    |
+            | Kelvin      | Celsius     | 1        | -273.15   |
+        """)
+
+    @ClassSkill.script(name="convert-temperature")
+    def convert_temperature(self, value: float, factor: float, offset: float = 0) -> str:
+        """Convert a temperature value using factor and offset from the formulas resource.
+
+        Args:
+            value: The numeric temperature value to convert.
+            factor: Conversion factor from the formulas resource.
+            offset: Offset to add after multiplying (default 0).
+
+        Returns:
+            JSON string with the conversion result.
+        """
+        result = round(value * factor + offset, 4)
+        return json.dumps({"value": value, "factor": factor, "offset": offset, "result": result})
+
+
+# ---------------------------------------------------------------------------
+# 3. Wire everything together and run the agent
+# ---------------------------------------------------------------------------
+
+
+async def main() -> None:
+    """Run the combined skills demo."""
+    endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
+    deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")
+
+    # Create the chat client
+    client = FoundryChatClient(
+        project_endpoint=endpoint,
+        model=deployment,
+        credential=AzureCliCredential(),
+    )
+
+    # Create the SkillsProvider with code, class, and file skills.
+    # The script_runner handles file-based scripts; code-defined and
+    # class-based scripts run in-process automatically.
+    temperature_converter = TemperatureConverterSkill()
+
+    skills_provider = SkillsProvider(
+        DeduplicatingSkillsSource(
+            AggregatingSkillsSource([
+                FileSkillsSource(
+                    str(Path(__file__).parent / "skills"),
+                    script_runner=subprocess_script_runner,
+                ),
+                InMemorySkillsSource([volume_converter_skill, temperature_converter]),
+            ])
+        )
+    )
+
+    # Run the agent. All skill tools require approval by default; auto-approve
+    # them so the sample runs unattended. See the script_approval /
+    # skills_auto_approval samples for approval handling.
+    async with Agent(
+        client=client,
+        instructions="You are a helpful assistant that can convert units, volumes, and temperatures.",
+        context_providers=[skills_provider],
+        middleware=[ToolApprovalMiddleware(auto_approval_rules=[SkillsProvider.all_tools_auto_approval_rule])],
+    ) as agent:
+        # Ask the agent to use all three skills
+        print("Converting with mixed skills (file + code + class)")
+        print("-" * 60)
+        session = agent.create_session()
+        response = await agent.run(
+            "I need three conversions: "
+            "1) How many kilometers is a marathon (26.2 miles)? "
+            "2) How many liters is a 5-gallon bucket? "
+            "3) What is 98.6°F in Celsius?",
+            session=session,
+        )
+        print(f"Agent: {response}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+Converting with mixed skills (file + code + class)
+------------------------------------------------------------
+Agent: Here are your conversions:
+
+1. **26.2 miles → 42.16 km** (a marathon distance)
+2. **5 gallons → 18.93 liters**
+3. **98.6°F → 37.0°C**
+"""

python/samples/02-agents/skills/mixed_skills/skills/unit-converter/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: unit-converter
+description: Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.
+license: MIT
+compatibility: Works with any model that supports tool use.
+allowed-tools: convert
+metadata:
+  author: agent-framework-samples
+  version: "1.0"
+---
+
+## Usage
+
+When the user requests a unit conversion:
+1. First, review `references/CONVERSION_TABLES.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

python/samples/02-agents/skills/mixed_skills/skills/unit-converter/references/CONVERSION_TABLES.md

@@ -0,0 +1,10 @@
+# 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  |

python/samples/02-agents/skills/mixed_skills/skills/unit-converter/scripts/convert.py

@@ -0,0 +1,28 @@
+# 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()