Agentvaardigheden

Bestandsgebaseerde vaardigheden

Maak een AgentSkillsProvider verwijzing naar een map met uw vaardigheden en voeg deze toe aan de contextproviders van de agent. Stel een scriptrunner in om de uitvoering van bestandsscripts in skill-mappen mogelijk te maken.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using OpenAI.Responses;

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

// Discover skills from the 'skills' directory
var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"));

// Create an agent with the skills provider
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetResponsesClient()
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "SkillsAgent",
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    },
    model: deploymentName);

Meerdere vaardighedencatalogi

U kunt de provider naar één bovenliggende map verwijzen: elke submap die een SKILL.md bevat, wordt automatisch herkend als een vaardigheid:

var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "all-skills"));

U kunt ook een lijst met paden doorgeven om in meerdere hoofdmappen te zoeken:

var skillsProvider = new AgentSkillsProvider(
    [
        Path.Combine(AppContext.BaseDirectory, "company-skills"),
        Path.Combine(AppContext.BaseDirectory, "team-skills"),
    ]);

De provider doorzoekt maximaal twee niveaus diep.

Resourcedetectie aanpassen

Standaard herkent de provider resources met extensies .md, .json, .yaml, , .yml, .csv, .xmlen .txt in references en assets submappen. Gebruik AgentFileSkillsSourceOptions dit om deze standaardinstellingen te wijzigen:

var fileOptions = new AgentFileSkillsSourceOptions
{
    AllowedResourceExtensions = [".md", ".txt"],
    ResourceDirectories = ["docs", "templates"],
};

var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"),
    fileOptions: fileOptions);

Scriptuitvoering

Geef SubprocessScriptRunner.RunAsync als het tweede argument door naar AgentSkillsProvider om de uitvoering van bestandsgebaseerde scripts in te schakelen:

var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"),
    SubprocessScriptRunner.RunAsync);

SubprocessScriptRunner.RunAsync komt ongeveer overeen met het volgende:

// Simplified equivalent of what SubprocessScriptRunner.RunAsync does internally
using System.Diagnostics;
using System.Text.Json;

static async Task<string> RunAsync(
    AgentFileSkill skill,
    AgentFileSkillScript script,
    JsonElement? args,
    IServiceProvider? serviceProvider)
{
    var psi = new ProcessStartInfo("python3")
    {
        RedirectStandardOutput = true,
        UseShellExecute = false,
    };
    psi.ArgumentList.Add(Path.Combine(skill.Path, script.Path));
    if (args is { ValueKind: JsonValueKind.Array } json)
    {
        foreach (var element in json.EnumerateArray())
        {
            psi.ArgumentList.Add(element.GetString()!);
        }
    }
    using var process = Process.Start(psi)!;
    string output = await process.StandardOutput.ReadToEndAsync();
    await process.WaitForExitAsync();
    return output.Trim();
}

De runner voert elk gedetecteerd script uit als een lokaal subproces. Scripts op basis van bestanden verwachten argumenten als een JSON-matrix met tekenreeksen. Elk matrixelement wordt een positioneel opdrachtregelargument.

Scriptdetectie aanpassen

Standaard herkent de provider scripts met extensies .py, .js, .sh, .ps1, .cs en .csx in de scripts subdirectory. Gebruik AgentFileSkillsSourceOptions dit om deze standaardinstellingen te wijzigen:

Geef AgentFileSkillsSourceOptions aan de AgentSkillsProvider constructor of aan UseFileSkill / UseFileSkills de builder:

var fileOptions = new AgentFileSkillsSourceOptions
{
    AllowedScriptExtensions = [".py"],
    ScriptDirectories = ["scripts", "tools"],
};

// Via constructor
var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"),
    fileOptions: fileOptions);

// Via builder
var skillsProvider = new AgentSkillsProviderBuilder()
    .UseFileSkill(Path.Combine(AppContext.BaseDirectory, "skills"), options: fileOptions)
    .Build();

Bestandsgebaseerde vaardigheden

Gebruik de SkillsProvider.from_paths() factory om vaardigheden te ontdekken uit mappen met SKILL.md bestanden en voeg de provider toe aan de contextproviders van de agent:

import os
from pathlib import Path
from agent_framework import Agent, SkillsProvider
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

# Discover skills from the 'skills' directory
skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
)

# Create an agent with the skills provider
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")

client = FoundryChatClient(
    project_endpoint=endpoint,
    model=deployment,
    credential=AzureCliCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful assistant.",
    context_providers=[skills_provider],
)

Meerdere vaardighedencatalogi

U kunt de provider naar één bovenliggende map verwijzen: elke submap die een SKILL.md bevat, wordt automatisch herkend als een vaardigheid:

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "all-skills"
)

U kunt ook een lijst met paden doorgeven om in meerdere hoofdmappen te zoeken:

skills_provider = SkillsProvider.from_paths(
    skill_paths=[
        Path(__file__).parent / "company-skills",
        Path(__file__).parent / "team-skills",
    ]
)

De provider doorzoekt maximaal twee niveaus diep.

Resource- en scriptdetectie aanpassen

Standaard worden resources gedetecteerd uit references/ en assets/ submappen en scripts uit scripts/, volgens de agentskills.io specificatie. Herkende resource-extensies zijn .md, .json, .yaml, .yml, .csv, .xml en .txt. Gebruik resource_directories, script_directoriesen resource_extensions om deze standaardwaarden aan te passen:

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
    resource_extensions=(".md", ".txt"),
    resource_directories=["docs", "templates"],
    script_directories=["scripts", "tools"],
)

Gebruik "." om bestanden in de hoofdmap van de vaardigheid op te nemen, naast de submappen.

Scriptuitvoering

Als u het uitvoeren van op bestanden gebaseerde scripts wilt inschakelen, geeft u een script_runner door aan SkillsProvider.from_paths(). Elke synchrone of asynchrone oproep die voldoet aan het SkillScriptRunner protocol kan worden gebruikt.

from pathlib import Path
from agent_framework import FileSkill, FileSkillScript, SkillsProvider

def my_runner(
    skill: FileSkill,
    script: FileSkillScript,
    args: dict | list[str] | None = None,
) -> str:
    """Run a file-based script as a subprocess."""
    import subprocess, sys
    script_path = Path(script.full_path)
    cmd = [sys.executable, str(script_path)]
    if isinstance(args, list):
        cmd.extend(args)
    result = subprocess.run(
        cmd, capture_output=True, text=True, timeout=30, cwd=str(script_path.parent)
    )
    return result.stdout.strip()

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
    script_runner=my_runner,
)

De runner ontvangt het opgeloste FileSkillargument FileSkillScripten een optioneel args argument. Scripts op basis van bestanden verwachten argumenten als een JSON-matrix met tekenreeksen. Elk matrixelement wordt een positioneel opdrachtregelargument. Scripts worden automatisch gedetecteerd uit .py bestanden in de scripts/ submap van elke vaardigheidsmap.

Naast op bestanden gebaseerde vaardigheden die zijn gedetecteerd op basis van SKILL.md bestanden, kunt u vaardigheden volledig definiëren in code met behulp van AgentInlineSkill. Door code gedefinieerde vaardigheden zijn handig wanneer:

• Inhoud van vaardigheden wordt dynamisch gegenereerd (bijvoorbeeld lezen uit een database of omgeving).
• U wilt vaardigheidsdefinities naast de toepassingscode die deze gebruikt, behouden.
• U hebt resources nodig die logica op leestijd uitvoeren in plaats van statische bestanden te leveren.
• Vaardigheidsdefinities moeten tijdens runtime worden samengesteld op basis van gegevens , bijvoorbeeld het maken van een persoonlijke vaardigheid voor elke gebruikerssessie op basis van hun rol of machtigingen.
• Een vaardigheid moet de status van de aanroepplaats vastleggen (lokale variabelen, closures) in plaats van services uit een DI-container op te halen.

Basiscodevaardigheden

Maak een AgentInlineSkill met een naam, beschrijving en instructies. Resources koppelen met behulp van .AddResource():

using Microsoft.Agents.AI;

var codeStyleSkill = new AgentInlineSkill(
    name: "code-style",
    description: "Coding style guidelines and conventions for the team",
    instructions: """
        Use this skill when answering questions about coding style, conventions, or best practices for the team.
        1. Read the style-guide resource for the full set of rules.
        2. Answer based on those rules, quoting the relevant guideline where helpful.
        """)
    .AddResource(
        "style-guide",
        """
        # Team Coding Style Guide
        - Use 4-space indentation (no tabs)
        - Maximum line length: 120 characters
        - Use type annotations on all public methods
        """);

var skillsProvider = new AgentSkillsProvider(codeStyleSkill);

Dynamische middelen

Geef een factory-delegate door aan .AddResource() om de inhoud tijdens uitvoering te berekenen. De gemachtigde wordt telkens aangeroepen wanneer de agent de resource leest:

var projectInfoSkill = new AgentInlineSkill(
    name: "project-info",
    description: "Project status and configuration information",
    instructions: """
        Use this skill for questions about the current project.
        1. Read the environment resource for deployment configuration details.
        2. Read the team-roster resource for information about team members.
        """)
    .AddResource("environment", () =>
    {
        string env = Environment.GetEnvironmentVariable("APP_ENV") ?? "development";
        string region = Environment.GetEnvironmentVariable("APP_REGION") ?? "us-east-1";
        return $"Environment: {env}, Region: {region}";
    })
    .AddResource(
        "team-roster",
        "Alice Chen (Tech Lead), Bob Smith (Backend Engineer)");

Met code gedefinieerde scripts

Gebruik .AddScript() om een delegate te registreren als een uitvoerbaar script. Met code gedefinieerde scripts worden in het proces uitgevoerd als directe gemachtigde aanroepen. Er is geen scriptrunner nodig. De getypte parameters van de gemachtigde worden automatisch geconverteerd naar een JSON-schema dat de agent gebruikt om argumenten door te geven:

using System.Text.Json;

var unitConverterSkill = new AgentInlineSkill(
    name: "unit-converter",
    description: "Convert between common units using a conversion factor",
    instructions: """
        Use this skill when the user asks to convert between units.
        1. Review the conversion-table resource to find the correct factor.
        2. Use the convert script, passing the value and factor from the table.
        3. Present the result clearly with both units.
        """)
    .AddResource(
        "conversion-table",
        """
        # 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  |
        """)
    .AddScript("convert", (double value, double factor) =>
    {
        double result = Math.Round(value * factor, 4);
        return JsonSerializer.Serialize(new { value, factor, result });
    });

var skillsProvider = new AgentSkillsProvider(unitConverterSkill);

Naast op bestanden gebaseerde vaardigheden die zijn gedetecteerd uit SKILL.md-bestanden, kunt u vaardigheden volledig definiëren in Python code met behulp van InlineSkill. Door code gedefinieerde vaardigheden zijn handig wanneer:

• Inhoud van vaardigheden wordt dynamisch gegenereerd (bijvoorbeeld lezen uit een database of omgeving).
• U wilt vaardigheidsdefinities naast de toepassingscode die deze gebruikt, behouden.
• U hebt resources nodig die logica op leestijd uitvoeren in plaats van statische bestanden te leveren.
• Vaardigheidsdefinities moeten tijdens runtime worden samengesteld op basis van gegevens , bijvoorbeeld het maken van een persoonlijke vaardigheid voor elke gebruikerssessie op basis van hun rol of machtigingen.
• Een vaardigheid moet de status van de oproepsite (lokale variabelen, sluitingen) sluiten in plaats van services op te lossen via **kwargs.

Basiscodevaardigheden

Maak een InlineSkill instantie met een SkillFrontmatter (met de naam en beschrijving) en inhoud met instructies. Optioneel InlineSkillResource exemplaren toevoegen met statische inhoud:

from textwrap import dedent
from agent_framework import InlineSkill, InlineSkillResource, SkillFrontmatter, SkillsProvider

code_style_skill = InlineSkill(
    frontmatter=SkillFrontmatter(
        name="code-style",
        description="Coding style guidelines and conventions for the team",
    ),
    instructions=dedent("""\
        Use this skill when answering questions about coding style,
        conventions, or best practices for the team.
    """),
    resources=[
        InlineSkillResource(
            name="style-guide",
            content=dedent("""\
                # Team Coding Style Guide
                - Use 4-space indentation (no tabs)
                - Maximum line length: 120 characters
                - Use type annotations on all public functions
            """),
        ),
    ],
)

skills_provider = SkillsProvider(code_style_skill)

Dynamische middelen

Gebruik de @skill.resource decorator om een functie als resource te registreren. De functie wordt aangeroepen elke keer dat de agent de resource leest, zodat het kan zorgen voor actuele gegevens. Synchronisatie- en asynchrone functies worden ondersteund:

import os
from agent_framework import InlineSkill, SkillFrontmatter

project_info_skill = InlineSkill(
    frontmatter=SkillFrontmatter(
        name="project-info",
        description="Project status and configuration information",
    ),
    instructions="Use this skill for questions about the current project.",
)

@project_info_skill.resource
def environment() -> str:
    """Get current environment configuration."""
    env = os.environ.get("APP_ENV", "development")
    region = os.environ.get("APP_REGION", "us-east-1")
    return f"Environment: {env}, Region: {region}"

@project_info_skill.resource(name="team-roster", description="Current team members")
def get_team_roster() -> str:
    """Return the team roster."""
    return "Alice Chen (Tech Lead), Bob Smith (Backend Engineer)"

Wanneer de decorator zonder argumenten wordt gebruikt (@skill.resource), wordt de naam van de functie de resourcenaam en wordt de docstring de beschrijving. Gebruik @skill.resource(name="...", description="...") dit om ze expliciet in te stellen.

Met code gedefinieerde scripts

Gebruik de @skill.script decorator om een functie te registreren als een uitvoerbaar script voor een vaardigheid. Met code gedefinieerde scripts worden in het proces uitgevoerd en zijn geen scriptrunner vereist. Synchronisatie- en asynchrone functies worden ondersteund:

from agent_framework import InlineSkill, SkillFrontmatter

unit_converter_skill = InlineSkill(
    frontmatter=SkillFrontmatter(
        name="unit-converter",
        description="Convert between common units using a conversion factor",
    ),
    instructions="Use the convert script to perform unit conversions.",
)

@unit_converter_skill.script(name="convert", description="Convert a value: result = value × factor")
def convert_units(value: float, factor: float) -> str:
    """Convert a value using a multiplication factor."""
    import json
    result = round(value * factor, 4)
    return json.dumps({"value": value, "factor": factor, "result": result})

Wanneer de decorator zonder argumenten wordt gebruikt (@skill.script), wordt de naam van de functie de scriptnaam en wordt de docstring de beschrijving. De getypte parameters van de functie worden automatisch geconverteerd naar een JSON-schema dat de agent gebruikt om argumenten door te geven.

Klassengebaseerde vaardigheden

Met vaardigheden op basis van klassen kunt u alle vaardigheidsonderdelen - naam, beschrijving, instructies, resources en scripts - bundelen in één C#-klasse. Hierdoor kunnen ze eenvoudig worden verpakt en gedistribueerd als NuGet-pakketten: teams kunnen onafhankelijk vaardigheden ontwerpen en verzenden, en consumenten voegen ze toe met dotnet add package en één .UseSkill() aanroep. Oorsprong van AgentClassSkill<T> (waarin T uw klasse is), voeg vervolgens annotaties toe aan eigenschappen met [AgentSkillResource] en methoden met [AgentSkillScript] voor automatische detectie.

using System.ComponentModel;
using System.Text.Json;
using Microsoft.Agents.AI;

internal sealed class UnitConverterSkill : AgentClassSkill<UnitConverterSkill>
{
    public override AgentSkillFrontmatter Frontmatter { get; } = new(
        "unit-converter",
        "Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.");

    protected override string Instructions => """
        Use this skill when the user asks to convert between units.

        1. Review the conversion-table resource to find the correct factor.
        2. Use the convert script, passing the value and factor from the table.
        3. Present the result clearly with both units.
        """;

    [AgentSkillResource("conversion-table")]
    [Description("Lookup table of multiplication factors for common unit conversions.")]
    public string ConversionTable => """
        # 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  |
        """;

    [AgentSkillScript("convert")]
    [Description("Multiplies a value by a conversion factor and returns the result as JSON.")]
    private static string ConvertUnits(double value, double factor)
    {
        double result = Math.Round(value * factor, 4);
        return JsonSerializer.Serialize(new { value, factor, result });
    }
}

Registreer de klassen-gebaseerde vaardigheid met AgentSkillsProvider:

var skill = new UnitConverterSkill();
var skillsProvider = new AgentSkillsProvider(skill);

Wanneer het [AgentSkillResource] kenmerk wordt toegepast op een eigenschap of methode, wordt de retourwaarde gebruikt als de resource-inhoud wanneer de agent de resource leest. Gebruik een methode wanneer de inhoud tijdens het lezen moet worden berekend. Wanneer [AgentSkillScript] wordt toegepast op een methode, wordt de methode aangeroepen wanneer de agent het script aanroept. Gebruik [Description] van System.ComponentModel om elke resource en elk script voor de agent te beschrijven.

Klassengebaseerde vaardigheden

Met vaardigheden op basis van klassen kunt u alle vaardigheidsonderdelen - naam, beschrijving, instructies, resources en scripts - bundelen in één Python klasse. Hierdoor kunnen ze eenvoudig worden verpakt en gedistribueerd als PyPI-pakketten: teams kunnen onafhankelijk vaardigheden ontwerpen en verzenden, en consumenten voegen ze toe met pip install en één SkillsProvider() aanroep. Maak vervolgens een subklasse voor ClassSkill en gebruik daarna de decoratoren @ClassSkill.resource en @ClassSkill.script voor automatische detectie:

import json
from textwrap import dedent
from agent_framework import ClassSkill, SkillFrontmatter

class UnitConverterSkill(ClassSkill):
    """A unit-converter skill defined as a Python class."""

    def __init__(self) -> None:
        super().__init__(
            frontmatter=SkillFrontmatter(
                name="unit-converter",
                description=(
                    "Convert between common units using a multiplication factor. "
                    "Use when asked to convert miles, kilometers, pounds, or kilograms."
                ),
            ),
        )

    @property
    def instructions(self) -> str:
        return dedent("""\
            Use this skill when the user asks to convert between units.

            1. Review the conversion-table resource to find the correct factor.
            2. Use the convert script, passing the value and factor from the table.
            3. Present the result clearly with both units.
        """)

    @property
    @ClassSkill.resource
    def conversion_table(self) -> str:
        """Lookup table of multiplication factors for common unit conversions."""
        return dedent("""\
            # 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  |
        """)

    @ClassSkill.script(name="convert", description="Multiplies a value by a conversion factor.")
    def convert_units(self, value: float, factor: float) -> str:
        """Convert a value using a multiplication factor."""
        result = round(value * factor, 4)
        return json.dumps({"value": value, "factor": factor, "result": result})

Registreer de klassen-gebaseerde vaardigheid met SkillsProvider:

from agent_framework import SkillsProvider

skill = UnitConverterSkill()
skills_provider = SkillsProvider(skill)

Wanneer @ClassSkill.resource wordt toegepast als een kale decorator (zonder argumenten), wordt de methodenaam de naam van de resource (waarbij underscores worden omgezet in koppeltekens) en wordt de docstring de beschrijving. Gebruik @ClassSkill.resource(name="...", description="...") dit om ze expliciet in te stellen. Hetzelfde patroon is van toepassing op @ClassSkill.script.

Resources kunnen worden gedefinieerd als reguliere methoden of @property descriptoren. Wanneer u @property gebruikt, plaatst u @property als eerste en @ClassSkill.resource als tweede. Resource-retourwaarden worden in de cache opgeslagen na de eerste toegang.

Opbouwfunctie: geavanceerde scenario's met meerdere bronnen

Voor eenvoudige scenario's met één bron gebruikt u de AgentSkillsProvider constructors rechtstreeks. Gebruik AgentSkillsProviderBuilder dit wanneer u een van de volgende zaken nodig hebt:

• Gemengde vaardigheidstypen - combineer op bestanden gebaseerde, in code gedefinieerde (AgentInlineSkill) en op klassen gebaseerde (AgentClassSkill) vaardigheden in één provider.
• Vaardigheden filteren : vaardigheden opnemen of uitsluiten met behulp van een predicaat.

Typen gemengde vaardigheden

Combineer alle drie de vaardigheidstypen in één provider door te koppelen UseFileSkill, UseSkillen UseFileScriptRunner:

var skillsProvider = new AgentSkillsProviderBuilder()
    .UseFileSkill(Path.Combine(AppContext.BaseDirectory, "skills"))  // file-based skills
    .UseSkill(volumeConverterSkill)                                  // AgentInlineSkill
    .UseSkill(temperatureConverter)                                  // AgentClassSkill
    .UseFileScriptRunner(SubprocessScriptRunner.RunAsync)            // runner for file scripts
    .Build();

Vaardigheidsfilters

Gebruik UseFilter dit om alleen de vaardigheden op te nemen die voldoen aan uw criteria, bijvoorbeeld om vaardigheden uit een gedeelde map te laden, maar experimentele vaardigheden uit te sluiten:

var approvedSkillNames = new HashSet<string> { "expense-report", "code-style" };

var skillsProvider = new AgentSkillsProviderBuilder()
    .UseFileSkill(Path.Combine(AppContext.BaseDirectory, "skills"))
    .UseFilter(skill => approvedSkillNames.Contains(skill.Frontmatter.Name))
    .Build();

Bronsamenstelling: geavanceerde scenario's met meerdere bronnen

Voor eenvoudige scenario's met één vaardigheid of een lijst met vaardigheden geeft u deze rechtstreeks door aan de SkillsProvider constructor. Gebruik bij bestandsgebaseerde vaardigheden de SkillsProvider.from_paths()-fabriek. Voor geavanceerde scenario's stelt u bronklassen op om detectie, filtering en ontdubbeling te beheren:

• FileSkillsSource - detecteert vaardigheden van SKILL.md bestanden op schijf.
• InMemorySkillsSource - verpakt alle Skill exemplaren (codegedefinieerde of klassegebaseerde) in het geheugen.
• AggregatingSkillsSource - combineert meerdere bronnen in één.
• FilteringSkillsSource - past een predicaat toe om vaardigheden op te nemen of uit te sluiten.
• DeduplicatingSkillsSource - verwijdert dubbele vaardigheidsnamen (hoofdletterongevoelig, de eerste blijft behouden).

Typen gemengde vaardigheden

Combineer op bestanden gebaseerde, codegedefinieerde en op klassen gebaseerde vaardigheden in één provider met AggregatingSkillsSource. In het onderstaande voorbeeld worden tijdelijke aanduidingen gebruikt:

• volume_converter_skill - elke InlineSkill instantie, opgebouwd zoals beschreven in In code gedefinieerde vaardigheden.
• TemperatureConverterSkill - elke ClassSkill subklasse, gebouwd zoals wordt weergegeven in op klassen gebaseerde vaardigheden.
• my_runner - een SkillScriptRunner aanroepbare functie, zoals gedefinieerd in Scriptuitvoering.

from pathlib import Path
from agent_framework import (
    AggregatingSkillsSource,
    DeduplicatingSkillsSource,
    FileSkillsSource,
    InMemorySkillsSource,
    SkillsProvider,
)

temperature_converter_skill = TemperatureConverterSkill()

skills_provider = SkillsProvider(
    DeduplicatingSkillsSource(
        AggregatingSkillsSource([
            FileSkillsSource(
                Path(__file__).parent / "skills",
                script_runner=my_runner,
            ),
            InMemorySkillsSource([volume_converter_skill, temperature_converter_skill]),
        ])
    )
)

Vaardigheidsfilters

Gebruik FilteringSkillsSource deze functie om te bepalen welke vaardigheden de agent ziet. Het predicaat ontvangt elke Skill en retourneert True om het op te nemen. Als u bijvoorbeeld vaardigheden wilt laden uit een gedeelde map, maar een experimenteel bestand wilt verbergen:

from pathlib import Path
from agent_framework import (
    DeduplicatingSkillsSource,
    FileSkillsSource,
    FilteringSkillsSource,
    SkillsProvider,
)

skills_provider = SkillsProvider(
    DeduplicatingSkillsSource(
        FilteringSkillsSource(
            FileSkillsSource(Path(__file__).parent / "skills"),
            predicate=lambda skill: skill.frontmatter.name != "experimental-tools",
        )
    )
)

Gebruik AgentSkillsProviderOptions.ScriptApproval om alle uitvoeringen van scripts achter menselijke goedkeuring te plaatsen. Wanneer de agent is ingeschakeld, wordt een goedkeuringsaanvraag onderbroken en geretourneerd in plaats van onmiddellijk uit te voeren:

var skillsProvider = new AgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
    options: new AgentSkillsProviderOptions
    {
        ScriptApproval = true,
    });

Als u scriptgoedkeuring wilt inschakelen voor een door de maker geconfigureerde provider, gebruikt u UseScriptApproval:

var skillsProvider = new AgentSkillsProviderBuilder()
    .UseFileSkill(Path.Combine(AppContext.BaseDirectory, "skills"))
    .UseScriptApproval(true)
    .Build();

Gebruik require_script_approval=True op SkillsProvider om alle uitvoering van scripts achter menselijke goedkeuring te plaatsen. In plaats van onmiddellijk uit te voeren, onderbreekt en retourneert de agent goedkeuringsaanvragen via result.user_input_requests:

from textwrap import dedent
from agent_framework import Agent, InlineSkill, SkillFrontmatter, SkillsProvider

deployment_skill = InlineSkill(
    frontmatter=SkillFrontmatter(
        name="deployment",
        description="Tools for deploying application versions to production",
    ),
    instructions=dedent("""\
        Use this skill when the user asks to deploy an application.
        Run the deploy script with the version and environment parameters.
    """),
)

@deployment_skill.script
def deploy(version: str, environment: str = "staging") -> str:
    """Deploy the application to the specified environment."""
    return f"Deployed version {version} to {environment}"

skills_provider = SkillsProvider(deployment_skill, require_script_approval=True)

async with Agent(
    client=client,
    instructions="You are a deployment assistant.",
    context_providers=[skills_provider],
) as agent:
    # Use a session so the agent retains context across approval round-trips
    session = agent.create_session()

    result = await agent.run(
        "Deploy version 2.5.0 to production",
        session=session,
    )

    # Handle approval requests
    while result.user_input_requests:
        for request in result.user_input_requests:
            print(f"Script: {request.function_call.name}")
            print(f"Args: {request.function_call.arguments}")

            approval = request.to_function_approval_response(approved=True)
            result = await agent.run(approval, session=session)

    print(result)

Wanneer een script wordt geweigerd (approved=False), wordt de agent geïnformeerd dat de gebruiker heeft geweigerd en dienovereenkomstig kan reageren.

var skillsProvider = new AgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
    options: new AgentSkillsProviderOptions
    {
        SkillsInstructionPrompt = """
            You have skills available. Here they are:
            {skills}
            {resource_instructions}
            {script_instructions}
            """
    });

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
    instruction_template=(
        "You have skills available. Here they are:\n{skills}\n"
        "{resource_instructions}\n"
        "{runner_instructions}"
    ),
)

Cachinggedrag

Standaard worden hulpprogramma's en instructies voor vaardigheden in de cache opgeslagen na de eerste build. Stel DisableCaching = true in op AgentSkillsProviderOptions om bij elke aanroep een herbouw af te dwingen:

var skillsProvider = new AgentSkillsProvider(
    Path.Combine(AppContext.BaseDirectory, "skills"),
    options: new AgentSkillsProviderOptions
    {
        DisableCaching = true,
    });

Cachinggedrag

Standaard worden hulpprogramma's en instructies voor vaardigheden in de cache opgeslagen na de eerste build. Stel disable_caching=True in om bij elke aanroep een herbouw af te dwingen:

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
    disable_caching=True,
)

disable_caching is ook beschikbaar op de SkillsProvider-constructor voor in code gedefinieerde en op klassen gebaseerde vaardigheden.

Gedelegeerden van vaardigheidsbronnen en scripts kunnen een IServiceProvider parameter declareren die het Agent Framework automatisch injecteert. Hierdoor kunnen vaardigheden toegang krijgen tot toepassingsservices, zoals databaseclients, configuratie of bedrijfslogica, zonder deze hardgecodeerd op te nemen in de vaardigheidsdefinitie.

Installatie

Registreer uw toepassingsservices en geef het gebouwde IServiceProvider door aan de agent via de services parameter:

using Microsoft.Extensions.DependencyInjection;

// Register application services
ServiceCollection services = new();
services.AddSingleton<ConversionService>();
IServiceProvider serviceProvider = services.BuildServiceProvider();

// Create the agent and pass the service provider
AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetResponsesClient()
    .AsAIAgent(
        options: new ChatClientAgentOptions
        {
            Name = "ConverterAgent",
            ChatOptions = new() { Instructions = "You are a helpful assistant." },
            AIContextProviders = [skillsProvider],
        },
        model: deploymentName,
        services: serviceProvider);

Door code gedefinieerde vaardigheden met DI

Declareer IServiceProvider als een parameter in AddResource- of AddScript-delegates: het framework lost deze automatisch op en injecteert die wanneer de agent een resource leest of een script uitvoert:

var distanceSkill = new AgentInlineSkill(
    name: "distance-converter",
    description: "Convert between distance units (miles and kilometers).",
    instructions: """
        Use this skill when the user asks to convert between miles and kilometers.
        1. Read the distance-table resource for conversion factors.
        2. Use the convert script to compute the result.
        """)
    .AddResource("distance-table", (IServiceProvider sp) =>
    {
        return sp.GetRequiredService<ConversionService>().GetDistanceTable();
    })
    .AddScript("convert", (double value, double factor, IServiceProvider sp) =>
    {
        return sp.GetRequiredService<ConversionService>().Convert(value, factor);
    });

Vaardigheden op basis van klassen met DI

Annoteer methoden met [AgentSkillResource] of [AgentSkillScript] en declareer een IServiceProvider-parameter: het framework ontdekt deze leden via reflectie en injecteert de serviceprovider automatisch:

internal sealed class WeightConverterSkill : AgentClassSkill<WeightConverterSkill>
{
    public override AgentSkillFrontmatter Frontmatter { get; } = new(
        "weight-converter",
        "Convert between weight units (pounds and kilograms).");

    protected override string Instructions => """
        Use this skill when the user asks to convert between pounds and kilograms.
        1. Read the weight-table resource for conversion factors.
        2. Use the convert script to compute the result.
        """;

    [AgentSkillResource("weight-table")]
    [Description("Lookup table of multiplication factors for weight conversions.")]
    private static string GetWeightTable(IServiceProvider serviceProvider)
    {
        return serviceProvider.GetRequiredService<ConversionService>().GetWeightTable();
    }

    [AgentSkillScript("convert")]
    [Description("Multiplies a value by a conversion factor and returns the result as JSON.")]
    private static string Convert(double value, double factor, IServiceProvider serviceProvider)
    {
        return serviceProvider.GetRequiredService<ConversionService>().Convert(value, factor);
    }
}

services.AddSingleton<WeightConverterSkill>();
var weightSkill = serviceProvider.GetRequiredService<WeightConverterSkill>();

Resource- en scriptfuncties die **kwargs accepteren, ontvangen automatisch runtime-trefwoordargumenten die worden doorgegeven aan agent.run(). Hierdoor hebben vaardigheidsfuncties toegang tot toepassingscontext, zoals configuratie, gebruikersidentiteit of serviceclients, zonder ze hard te coderen in de vaardigheidsdefinitie.

Runtime-argumenten doorgeven

Geef function_invocation_kwargs door aan agent.run() om trefwoordargumenten te verstrekken die het framework doorstuurt naar resource- en scriptfuncties.

response = await agent.run(
    "How many kilometers is 26.2 miles?",
    function_invocation_kwargs={"precision": 2, "user_id": "alice"},
)

In code gedefinieerde vaardigheden met kwargs

Wanneer een resourcefunctie declareert **kwargs, stuurt het framework de argumenten voor runtime-trefwoorden door telkens wanneer de agent de resource leest:

import os
from typing import Any
from agent_framework import InlineSkill, SkillFrontmatter

project_info_skill = InlineSkill(
    frontmatter=SkillFrontmatter(
        name="project-info",
        description="Project status and configuration information",
    ),
    instructions="Use this skill for questions about the current project.",
)

@project_info_skill.resource(name="environment", description="Current environment configuration")
def environment(**kwargs: Any) -> str:
    """Return environment config, optionally scoped to a user."""
    user_id = kwargs.get("user_id", "anonymous")
    env = os.environ.get("APP_ENV", "development")
    return f"Environment: {env}, Caller: {user_id}"

Resourcefuncties zonder **kwargs worden aangeroepen zonder argumenten en krijgen geen runtimecontext.

Wanneer een scriptfunctie declareert **kwargs, stuurt het framework de argumenten van het runtime-trefwoord door naast de args opgegeven door de agent:

import json
from typing import Any
from agent_framework import InlineSkill, SkillFrontmatter

converter_skill = InlineSkill(
    frontmatter=SkillFrontmatter(
        name="unit-converter",
        description="Convert between common units using a conversion factor",
    ),
    instructions="Use the convert script to perform unit conversions.",
)

@converter_skill.script(name="convert", description="Convert a value: result = value × factor")
def convert_units(value: float, factor: float, **kwargs: Any) -> str:
    """Convert a value using a multiplication factor.

    Args:
        value: The numeric value to convert (provided by the agent).
        factor: Conversion factor (provided by the agent).
        **kwargs: Runtime keyword arguments from agent.run().
    """
    precision = kwargs.get("precision", 4)
    result = round(value * factor, precision)
    return json.dumps({"value": value, "factor": factor, "result": result})

De agent biedt value en factor via de aanroep argsvan het hulpprogramma; de toepassing biedt precision via function_invocation_kwargs. Scriptfuncties zonder **kwargs ontvangen alleen de argumenten die door de agent worden opgegeven.

Klassegebaseerde vaardigheden met kwargs

Klassegebaseerde vaardigheidsmethoden kunnen ook **kwargs accepteren om argumenten tijdens runtime te ontvangen. Het patroon werkt op dezelfde manier: declareren **kwargs voor resourcemethoden of scriptmethoden:

from typing import Any
from agent_framework import ClassSkill, SkillFrontmatter

class WeightConverterSkill(ClassSkill):
    def __init__(self) -> None:
        super().__init__(
            frontmatter=SkillFrontmatter(
                name="weight-converter",
                description="Convert between weight units (pounds and kilograms).",
            ),
        )

    @property
    def instructions(self) -> str:
        return "Use this skill to convert between pounds and kilograms."

    @ClassSkill.resource(name="weight-table")
    def get_weight_table(self, **kwargs: Any) -> str:
        """Weight conversion factors, scoped to caller context."""
        user_id = kwargs.get("user_id", "anonymous")
        return f"Weight table for {user_id}: | lbs | kg | 0.453592 |"

    @ClassSkill.script(name="convert")
    def convert(self, value: float, factor: float, **kwargs: Any) -> str:
        """Convert a weight value."""
        import json
        precision = kwargs.get("precision", 4)
        result = round(value * factor, precision)
        return json.dumps({"value": value, "factor": factor, "result": result})