mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
SergeyMenshykh
1d94518f37
* Python: Add ClassSkill for class-based skill definitions Add ClassSkill abstract base class with decorator-based resource and script discovery, porting .NET's AgentClassSkill (PRs #5027 and #5183) to Python. - Add ClassSkill(Skill, ABC) with instructions abstract property, cached content/resources/scripts properties - Add @ClassSkill.resource and @ClassSkill.script static method decorators for auto-discovery of methods and properties - Extract _build_skill_content() and _create_resource_element() shared helpers from InlineSkill for reuse - Add _discover_marked_members() for scanning class hierarchies - Add _make_method_name() for Python-to-skill name conversion - Add class_based_skill sample (UnitConverterSkill) - Update mixed_skills sample with TemperatureConverterSkill - Add 58 new tests covering ClassSkill, decorator discovery, property resources, inheritance, kwargs forwarding, and duplicate detection - Export ClassSkill from agent_framework public API Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: replace try/except/continue with assignment to satisfy bandit B112 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * address PR review feedback - Walk cls.__mro__ in _discover_marked_members for inherited property resources - Use inspect.getattr_static for MRO-aware is_property check - Return defensive copies from resources/scripts properties - Raise TypeError on wrong decorator stacking order (@resource above @property) - Log warning instead of silently swallowing descriptor errors during discovery - Validate explicit name= at decoration time via _validate_member_name - Add tests for all of the above Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Fix temperature converter skill: make resource necessary for script Refactor TemperatureConverterSkill so the agent must read the formulas resource (factor/offset) before calling the script, aligning with the volume-converter pattern. - Resource: numeric factor/offset table instead of symbolic formulas - Script: generic linear transform (value * factor + offset) - Instructions: updated to reflect new workflow Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
5.0 KiB
5.0 KiB
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:
az login
Running the Sample
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