Ügynöki készségek

Az Ügynökkészség olyan utasítások, szkriptek és erőforrások hordozható csomagjai, amelyek speciális képességeket és tartományi szakértelmet biztosítanak az ügynököknek. A készségek egy nyílt specifikációt követnek, és egy fokozatos részletezési mintát valósítanak meg, így az ügynökök csak a szükséges kontextust töltik be, amikor arra szükségük van.

A következő esetekben használja az ügynöki készségeket:

• Csomagtartomány-szakértelem – A specializált ismeretek (költségszabályzatok, jogi munkafolyamatok, adatelemzési folyamatok) újrafelhasználható, hordozható csomagokként való rögzítése.
• Ügynöki képességek kiterjesztése – Új képességeket adhat az ügynököknek az alapvető utasítások módosítása nélkül.
• Konzisztenciának biztosítása – A többlépéses feladatokat megismételhető, naplózható munkafolyamatokká alakíthatja.
• Interoperabilitás engedélyezése – Ugyanazt a készséget használja fel a különböző Agent Skills-kompatibilis termékek között.

Képességstruktúra

A skill egy könyvtár, amely egy SKILL.md nevű fájlt tartalmaz, opcionális alkönyvtárakkal az erőforrások számára.

expense-report/
├── SKILL.md                          # Required — frontmatter + instructions
├── scripts/
│   └── validate.py                   # Executable code agents can run
├── references/
│   └── POLICY_FAQ.md                 # Reference documents loaded on demand
└── assets/
    └── expense-report-template.md    # Templates and static resources

SKILL.md formátum

A SKILL.md fájlnak TARTALMAZNIa kell a YAML-előtétet, majd a Markdown-tartalmat:

---
name: expense-report
description: File and validate employee expense reports according to company policy. Use when asked about expense submissions, reimbursement rules, or spending limits.
license: Apache-2.0
compatibility: Requires python3
metadata:
  author: contoso-finance
  version: "2.1"
---

szakterület	Kötelező	Description
name	Igen	Legfeljebb 64 karakter. Csak kisbetűk, számok és kötőjelek. Nem kezdődhet és nem végződhet kötőjellel, és nem tartalmazhat egymást követő kötőjeleket. Meg kell egyeznie a szülőkönyvtár nevével.
description	Igen	Mit csinál a képesség, és mikor kell használni. Legfeljebb 1024 karakter. Olyan kulcsszavakat kell tartalmaznia, amelyek segítenek az ügynököknek azonosítani a releváns feladatokat.
license	Nem	Licencnév vagy hivatkozás egy csomagban létrehozott licencfájlra.
compatibility	Nem	Legfeljebb 500 karakter. Környezeti követelményeket jelez (tervezett termék, rendszercsomagok, hálózati hozzáférés stb.).
metadata	Nem	Tetszőleges kulcs-érték leképezés további metaadatokhoz.
allowed-tools	Nem	A képesség által használható előre jóváhagyott eszközök szóközzel tagolt listája. Kísérleti – a támogatás az ügynök implementációitól függően változhat.

Az előtér utáni Markdown-törzs tartalmazza a jártassági utasításokat – részletes útmutatást, példákat a bemenetekre és kimenetekre, gyakori peremes eseteket vagy bármilyen olyan tartalmat, amely segít az ügynöknek a feladat végrehajtásában. Tartsa SKILL.md 500 sor alatt, és a részletes referenciaanyagot külön fájlokba helyezze át.

Fokozatos közzététel

Az Ügynökkészség négyfázisú progresszív közzétételi mintát használ a környezethasználat minimalizálásához:

1. Hirdetés (képességenként ~100 token) – A képességek neveit és leírásait minden futtatás kezdetén a rendszer utasításba illesztjük be, így az ügynök tisztában van az elérhető képességekkel.
2. Betöltés (< 5000 token ajánlott) – Ha egy feladat egyezik egy képesség tartományával, az ügynök meghívja az load_skill eszközt a teljes SKILL.md törzs részletes útmutatással való lekéréséhez.
3. Erőforrások olvasása (igény szerint) – Az ügynök meghívja az read_skill_resource eszközt, hogy csak szükség esetén kérje le a kiegészítő fájlokat (hivatkozásokat, sablonokat, eszközöket).
4. Szkriptek futtatása (szükség szerint) – A run_skill_script eszközt az ügynök meghívja egy képességgel csomagolt szkriptek végrehajtására.

Ez a minta lean tartja az ügynök környezeti ablakát, miközben igény szerint hozzáférést biztosít a mély szaktudáshoz.

Megjegyzés:

load_skill mindig meg van hirdetve. read_skill_resource csak akkor van meghirdetve, ha legalább egy képesség rendelkezik erőforrásokkal. run_skill_script csak akkor van meghirdetve, ha legalább egy képesség rendelkezik szkriptekkel.

Ügynök kompetenciáinak fejlesztése

AgentSkillsProvider (C#) és SkillsProvider (Python) olyan környezetszolgáltatók, amelyek a készségeket elérhetővé teszik az ügynökök számára. Három készségforrást támogatnak:

• Fájlalapú – a fájlrendszerkönyvtárakban lévő fájlokból SKILL.md felderített készségek
• Kód által definiált – a kódba ágyazott készségek AgentInlineSkill (C#) vagy Skill (Python) használatával
• Osztályalapú — készségek, amelyeket egy C# osztály tartalmaz, amely AgentClassSkill<T>-ból származik (csak C#).

Több forrás egy szolgáltatóban való keveréséhez használja AgentSkillsProviderBuilder (csak C# – lásd : Builder: advanced multi-source scenarios).

Fájlalapú készségek

Hozzon létre egy AgentSkillsProvider , a készségeit tartalmazó könyvtárra mutató mutatót, és adja hozzá az ügynök környezetszolgáltatóihoz. Adjon át egy szkriptfuttatót a képességkönyvtárakban található fájlalapú szkriptek végrehajtásának engedélyezéséhez:

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);

Figyelmeztetés

DefaultAzureCredential a fejlesztéshez kényelmes, de a termelési környezetben gondos megfontolást igényel. Éles környezetben fontolja meg egy adott hitelesítő adat (pl. ManagedIdentityCredential) használatát a késési problémák elkerülése, a hitelesítő adatok nem szándékos próbálgatásának és a tartalék mechanizmusokból eredő esetleges biztonsági kockázatok elkerülése érdekében.

Több készségkönyvtár

A szolgáltatót egyetlen szülőkönyvtárra irányíthatja – az azt tartalmazó SKILL.md alkönyvtárak automatikusan felderíthetők képességként:

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

Vagy adja meg az elérési utak listáját több gyökérkönyvtár kereséséhez:

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

A szolgáltató legfeljebb két szint mélyére keres.

Erőforrás-felderítés testreszabása

Alapértelmezés szerint a szolgáltató felismeri az .md, .json, .yaml, .yml, .csv, .xml és .txt bővítményekkel rendelkező erőforrásokat az references és assets alkönyvtárakban. Az alábbi alapértelmezett beállítások módosítására használható AgentFileSkillsSourceOptions :

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

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

Szkript végrehajtása

Adja meg a SubprocessScriptRunner.RunAsync-t második argumentumként a AgentSkillsProvider számára a fájlalapú szkriptek végrehajtásának engedélyezéséhez.

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

SubprocessScriptRunner.RunAsync nagyjából megegyezik a következő értékével:

// 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();
}

A futó minden felderített szkriptet helyi alfolyamatként futtat. A fájlalapú szkriptek az argumentumokat sztringek JSON-tömbjeként várják – minden tömbelem pozícióbeli parancssori argumentum lesz.

Figyelmeztetés

SubprocessScriptRunner csak szemléltetés céljából van megadva. Éles használat esetén fontolja meg a következő hozzáadását:

• Sandboxing (például konténerek vagy elkülönített végrehajtási környezetek)
• Erőforráskorlátok (CPU, memória, fali óra időtúllépése)
• Végrehajtható szkriptek bemeneti ellenőrzése és engedélyezési listázása
• Strukturált naplózás és ellenőrzési nyomok

Szkriptfelderítés testreszabása

A szolgáltató alapértelmezés szerint felismeri a bővítményekkel .py, .js, , .sh, .ps1, , .csés .csx az scripts alkönyvtárban lévő szkripteket. Az alábbi alapértelmezett beállítások módosítására használható AgentFileSkillsSourceOptions :

Adja át AgentFileSkillsSourceOptions a konstruktornakAgentSkillsProvider vagy UseFileSkill / a kivitelezőnek:UseFileSkills

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();

Fájlalapú készségek

Hozzon létre egy SkillsProvider , a készségeit tartalmazó könyvtárra mutató mutatót, és adja hozzá az ügynök környezetszolgáltatóihoz:

import os
from pathlib import Path
from agent_framework import SkillsProvider
from agent_framework.openai import OpenAIChatCompletionClient
from azure.identity.aio import AzureCliCredential

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

# Create an agent with the skills provider
agent = OpenAIChatCompletionClient(
    model=os.environ["AZURE_OPENAI_CHAT_COMPLETION_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
).as_agent(
    name="SkillsAgent",
    instructions="You are a helpful assistant.",
    context_providers=[skills_provider],
)

Több készségkönyvtár

A szolgáltatót egyetlen szülőmappára irányíthatja – a rendszer automatikusan felismeri az összes SKILL.md tartalmazó almappát, és készségként azonosítja azokat.

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

Vagy adja meg az elérési utak listáját több gyökérkönyvtár kereséséhez:

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

A szolgáltató legfeljebb két szint mélyére keres.

Erőforrás-felderítés testreszabása

Alapértelmezés szerint a SkillsProvider, .md, .json, .yaml, .yml, .csv, .xml és .txt kiterjesztésekkel rendelkező forrásokat ismeri fel. Az egyes képességmappákban lévő összes alkönyvtárat megvizsgálja. Pass resource_extensions a felismert fájltípusok módosításához:

skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    resource_extensions=(".md", ".txt"),
)

Szkript végrehajtása

A fájlalapú szkriptek végrehajtásának engedélyezéséhez adjon át egy paramétert script_runner a SkillsProvider-nak. Bármely, a SkillScriptRunner protokollnak megfelelő szinkronizálás vagy aszinkron hívás használható:

from pathlib import Path
from agent_framework import Skill, SkillScript, SkillsProvider

def my_runner(skill: Skill, script: SkillScript, args: dict | None = None) -> str:
    """Run a file-based script as a subprocess."""
    import subprocess, sys
    cmd = [sys.executable, str(Path(skill.path) / script.path)]
    if args:
        for key, value in args.items():
            if value is not None:
                cmd.extend([f"--{key}", str(value)])
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
    return result.stdout.strip()

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

A futó megkapja a feloldott Skill, SkillScript, és egy opcionális args szótárat. A fájlalapú szkripteket a rendszer automatikusan felderíti a képességkönyvtárakban lévő fájlokból .py .

Figyelmeztetés

A fenti futó csak bemutató célokra érhető el. Éles használat esetén fontolja meg a következő hozzáadását:

• Sandboxing (például konténerek, seccomp, vagy firejail)
• Erőforráskorlátok (CPU, memória, fali óra időtúllépése)
• Végrehajtható szkriptek bemeneti ellenőrzése és engedélyezési listázása
• Strukturált naplózás és ellenőrzési nyomok

Megjegyzés:

Ha meg vannak adva a fájlalapú jártasságok parancsfájlokkal, de nincs script_runner beállítva, SkillsProvider egy ValueError-t generál.

Kódalapú készségek

A SKILL.md fájlokból felderített fájlalapú képességek mellett a képességeket teljes mértékben kódban is definiálhatja AgentInlineSkill használatával. A kód által definiált készségek akkor hasznosak, ha:

• A készségtartalmak dinamikusan jönnek létre (például egy adatbázisból vagy környezetből olvasnak).
• A készségdefiníciókat az őket használó alkalmazáskód mellett szeretné megőrizni.
• Olyan erőforrásokra van szüksége, amelyek olvasási időben hajtják végre a logikát a statikus fájlok kiszolgálása helyett.

Alapszintű kódismeret

Hozzon létre egy AgentInlineSkill nevet, leírást és útmutatást. Erőforrásokat csatoljon a .AddResource() használatával.

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);

Dinamikus erőforrások

Adjon át egy gyári delegáltat .AddResource() a tartalom futásidőben történő kiszámításához. A meghatalmazott minden alkalommal meghívódik, amikor az ügynök beolvassa az erőforrást:

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)");

Kód által definiált szkriptek

A meghatalmazottak végrehajtható szkriptként való regisztrálására szolgál .AddScript() . A kód által definiált szkriptek közvetlen delegált hívásokként futnak a folyamatban . Nincs szükség szkriptfuttatóra. A meghatalmazott beírt paraméterei automatikusan JSON-sémává alakulnak, amelyet az ügynök argumentumok átadására használ:

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);

Megjegyzés:

Ha egyetlen szolgáltatóban szeretné kombinálni a kódalapú készségeket a fájlalapú vagy osztályalapú készségekkel, használja AgentSkillsProviderBuilder a buildert: speciális, több forrásból álló forgatókönyveket.

A SKILL.md fájlokból felderített fájlalapú készségek mellett a készségeket teljes egészében Python kódban is definiálhatja. A kód által definiált készségek akkor hasznosak, ha:

• A készségtartalmak dinamikusan jönnek létre (például egy adatbázisból vagy környezetből olvasnak).
• A készségdefiníciókat az őket használó alkalmazáskód mellett szeretné megőrizni.
• Olyan erőforrásokra van szüksége, amelyek olvasási időben hajtják végre a logikát a statikus fájlok kiszolgálása helyett.

Alapszintű kódismeret

Hozzon létre egy példányt Skill névvel, leírással és utasítástartalommal. Opcionálisan csatolhat SkillResource példányokat statikus tartalommal.

from textwrap import dedent
from agent_framework import Skill, SkillResource, SkillsProvider

code_style_skill = Skill(
    name="code-style",
    description="Coding style guidelines and conventions for the team",
    content=dedent("""\
        Use this skill when answering questions about coding style,
        conventions, or best practices for the team.
    """),
    resources=[
        SkillResource(
            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(skills=[code_style_skill])

Dinamikus erőforrások

@skill.resource A dekorátor használatával regisztrálhat egy függvényt erőforrásként. A függvényt minden alkalommal meghívjuk, amikor az ügynök beolvassa az erőforrást, így up-to-date adatokat tud visszaadni. A szinkronizálási és az aszinkron függvények egyaránt támogatottak:

import os
from agent_framework import Skill

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

@project_info_skill.resource
def environment() -> Any:
    """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() -> Any:
    """Return the team roster."""
    return "Alice Chen (Tech Lead), Bob Smith (Backend Engineer)"

Ha a dekoratőr argumentumok nélkül van használatban (@skill.resource), a függvény neve lesz az erőforrás neve, és a dokumentáció lesz a leírás. Használja a @skill.resource(name="...", description="...")-t, hogy explicit módon állítsa be őket.

Kód által definiált szkriptek

Használja a @skill.script dekorátort, hogy egy függvényt végrehajtható szkriptként regisztráljon egy képességben. A kód által definiált szkriptek folyamatban futnak, és nem igényelnek szkript-végrehajtót. A szinkronizálási és az aszinkron függvények egyaránt támogatottak:

from agent_framework import Skill

unit_converter_skill = Skill(
    name="unit-converter",
    description="Convert between common units using a conversion factor",
    content="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})

Ha a dekoratőr argumentumok nélkül használatos (@skill.script), akkor a függvény neve lesz a szkript neve, és a dokumentációs sztring lesz a leírás. A függvény beírt paraméterei automatikusan JSON-sémává alakulnak, amelyet az ügynök argumentumok átadására használ.

Fájlalapú és kódalapú készségek kombinálása

Adja át mindkettőt, skill_paths és skills, egy SkillsProvider-be. A fájlalapú készségeket először a rendszer felderíti; ha egy kód által definiált képesség neve megegyezik egy meglévő fájlalapú képesség nevével, a kód által definiált képesség kimarad:

from pathlib import Path
from agent_framework import Skill, SkillsProvider

my_skill = Skill(
    name="my-code-skill",
    description="A code-defined skill",
    content="Instructions for the skill.",
)

skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    skills=[my_skill],
)

Osztályalapú készségek

Az osztályalapú képességek lehetővé teszik, hogy az összes készségösszetevőt – nevet, leírást, utasításokat, erőforrásokat és szkripteket – egyetlen C#-osztályba csomagolja. Származtassa a AgentClassSkill<T>-ből (ahol az osztály a T), és lássa el annotációkkal a tulajdonságokat [AgentSkillResource] és a metódusokat [AgentSkillScript] az automatikus felfedezéshez.

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 });
    }
}

Az osztályalapú jártasság regisztrálása a következővel AgentSkillsProvider:

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

Amikor az [AgentSkillResource] attribútumot egy tulajdonságra vagy metódusra alkalmazza a rendszer, a visszaadott érték lesz az erőforrás tartalma, amikor az ügynök beolvassa az erőforrást – használjon egy metódust, amikor a tartalmat olvasáskor kell kiszámítani. Amikor [AgentSkillScript] egy metódusra alkalmazza a rendszer, a metódus akkor lesz meghívva, amikor az ügynök meghívja a szkriptet. [Description] használja a System.ComponentModel minden egyes erőforrás és szkript leírására az ügynök számára.

Megjegyzés:

AgentClassSkill<T> emellett támogatja a Resources és Scripts gyűjteményekként való felülbírálást olyan forgatókönyvek esetében, ahol az attribútumalapú felderítés nem megfelelő.

Builder: speciális többforrásos forgatókönyvek

Egyszerű, egyforrásos forgatókönyvekhez használja közvetlenül a AgentSkillsProvider konstruktorokat. Akkor használja AgentSkillsProviderBuilder , ha az alábbiak bármelyikére van szüksége:

• Vegyes képességtípusok – egyetlen szolgáltató fájlalapú, kódalapú (AgentInlineSkill) és osztályalapú (AgentClassSkill) készségeinek kombinálása.
• Képességszűrés – a képességek belefoglalása vagy kizárása egy predikátum használatával.

Vegyes képességtípusok

Egy szolgáltatónál egyesítheti mindhárom készségtípust a UseFileSkill, UseSkill és UseFileScriptRunner láncolásával.

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();

Képességek szűrése

Csak a feltételeknek megfelelő készségek befoglalására használható UseFilter – például egy megosztott címtárból való betöltéshez, de kizárja a kísérleti képességeket:

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();

Szkript jóváhagyása

A AgentSkillsProviderOptions.ScriptApproval használatával minden szkript végrehajtását emberi jóváhagyáshoz kötheti. Ha engedélyezve van, az ügynök az azonnali végrehajtás helyett szünetelteti és visszaadja a jóváhagyási kérelmet:

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

Ha engedélyezni szeretné a szkriptek jóváhagyását egy szerkesztő által konfigurált szolgáltatón, használja a következőt UseScriptApproval:

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

Használja a require_script_approval=True a SkillsProvider elemen az összes szkript végrehajtásának emberi jóváhagyás mögé helyezéséhez. Ahelyett, hogy azonnal végrehajtanák, az ügynök felfüggeszti és visszaadja a jóváhagyási kérelmeket:

from agent_framework import Agent, Skill, SkillsProvider

# Create provider with approval enabled
skills_provider = SkillsProvider(
    skills=[my_skill],
    require_script_approval=True,
)

# Run the agent — script calls pause for approval
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)

Ha egy szkriptet elutasítanak (approved=False), az ügynök értesítést kap arról, hogy a felhasználó elutasította a parancsot, és ennek megfelelően tud válaszolni.

Testreszabott rendszerfelszólítás

Alapértelmezés szerint a képességszolgáltató egy rendszerkérést injektál, amely felsorolja a rendelkezésre álló készségeket, és utasítja az ügynököt, hogy használja load_skill és read_skill_resource. Ezt a kérést testre szabhatja:

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}
            """
    });

Megjegyzés:

Az egyéni sablonnak tartalmaznia {skills} kell (képességlista), {resource_instructions} (erőforrás-eszközmutató) és {script_instructions} (szkripteszköz-tipp) helyőrzőket. A literális kapcsos zárójeleket escape-elni kell {{ és }}.

skills_provider = SkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    instruction_template=(
        "You have skills available. Here they are:\n{skills}\n"
        "Use the `load_skill` function to get skill instructions.\n"
        "Use the `read_skill_resource` function to read skill files."
    ),
)

Megjegyzés:

Az egyéni sablonnak tartalmaznia kell egy {skills} helyőrzőt, ahová beszúrja a képességlistát, és egy {runner_instructions} helyőrzőt, ahová a szkripttel kapcsolatos utasításokat szúrja be.

Gyorsítótárazási viselkedés

Alapértelmezés szerint a képességeszközök és utasítások gyorsítótárazva lesznek az első build után. Állítsa be a DisableCaching = true-t a AgentSkillsProviderOptions-en, hogy minden meghíváskor kényszerítse az újraépítést.

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

Megjegyzés:

A gyorsítótárazás letiltása akkor hasznos a fejlesztés során, ha a képességtartalmak gyakran változnak. Éles környezetben hagyja engedélyezve a gyorsítótárazást (az alapértelmezett) a jobb teljesítmény érdekében.

Függőséginjektálás

A készségerőforrás- és szkriptdelegáltak deklarálhatnak egy paramétert IServiceProvider , amelyet az Ügynök-keretrendszer automatikusan injektál. Ez lehetővé teszi, hogy a készségek alkalmazásszolgáltatásokat használhassanak - például adatbázis-ügyfeleket, konfigurációt vagy üzleti logikát - anélkül, hogy a képességdefinícióban ne kelljen őket belekódolni.

Setup

Regisztrálja az alkalmazásszolgáltatásokat, és adja át a beépített IServiceProvider-t az ügynöknek a services paraméter segítségével.

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);

Kóddal meghatározott készségek DI-vel

Declare IServiceProvider paraméterként a AddResource vagy AddScript delegálásnál — a keretrendszer automatikusan feloldja és beilleszti, amikor az ügynök beolvas egy erőforrást vagy futtat egy szkriptet.

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);
    });

Osztályalapú készségek DI-vel

Annotálja a metódusokat [AgentSkillResource] vagy [AgentSkillScript] elemekkel, és deklaráljon egy IServiceProvider paramétert — a keretrendszer reflexió útján felderíti ezeket a tagokat, és automatikusan injektálja a szolgáltatót:

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);
    }
}

Jótanács

Az osztályalapú készségek a konstruktoron keresztül is megoldhatják a függőségeket. Regisztrálja a képességosztályt a ServiceCollection tárolóban, és oldja fel a közvetlen hívás new helyett:

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

Ez akkor hasznos, ha a képességosztálynak az erőforrás- és szkriptdelegáltak által használtnál több injektált szolgáltatásra van szüksége.

Azok az erőforrás- és szkriptfüggvények, amelyek elfogadják a futásidejű kulcsszóargumentumokat, automatikusan megkapják azokat, amikor átadásra kerülnek **kwargs-hez agent.run(). Ez lehetővé teszi, hogy a képességfüggvények anélkül férhessenek hozzá az alkalmazáskörnyezethez – például konfigurációhoz, felhasználói identitáshoz vagy szolgáltatásügyfelekhez –, hogy a képességdefinícióba nem kódoltuk őket.

Futásidejű argumentumok átadása

Adja át a kulcsszóargumentumokat function_invocation_kwargs-nak/nek agent.run()-ból/ből, amelyeket a keretrendszer továbbít az erőforrás- és szkriptfüggvényeknek:

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

Erőforrásfüggvények kwargokkal

Amikor egy erőforrásfüggvény deklarál **kwargs, a keretrendszer minden alkalommal továbbítja a futtatókörnyezet kulcsszóargumentumait, amikor az ügynök beolvassa az erőforrást:

from typing import Any
from agent_framework import Skill

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

@project_info_skill.resource(name="environment", description="Current environment configuration")
def environment(**kwargs: Any) -> Any:
    """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}"

Az **kwargs nélküli erőforrásfüggvényeket argumentumok nélkül hívják meg, és nem kapnak futási környezetet.

Szkriptfüggvények kwargokkal

Amikor egy szkriptfüggvény deklarál **kwargs, a keretrendszer továbbítja a futtatókörnyezet kulcsszóargumentumait, az ügynök által biztosított args-el együtt.

import json
from typing import Any
from agent_framework import Skill

converter_skill = Skill(
    name="unit-converter",
    description="Convert between common units using a conversion factor",
    content="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})

Az ügynök biztosítja a value és factor elemeket a args eszköz hívásán keresztül; az alkalmazás biztosítja a precision elemet a function_invocation_kwargs segítségével. A szkript a **kwargs nélkül úgy működik, hogy csak az ügynök által megadott argumentumokat kapja meg.

Ajánlott biztonsági eljárások

Az ügynöki készségeket úgy kell kezelni, mint bármely külső féltől származó kódot, amely a projektbe kerül. Mivel a készségutasítások az ügynök környezetébe kerülnek – és a készségek szkripteket is tartalmazhatnak –, a nyílt forráskódú függőségek esetében alapvető fontosságú, hogy ugyanazt a szintű felülvizsgálatot és szabályozást alkalmazza.

• Használat előtt tekintse át az összes készségtartalmat (SKILL.mdszkriptet és erőforrást) az üzembe helyezés előtt. Ellenőrizze, hogy a szkript tényleges viselkedése megegyezik-e a megadott szándékkal. Ellenőrizze azokat a támadó utasításokat, amelyek megkísérlik megkerülni a biztonsági irányelveket, kiszűrik az adatokat, vagy módosítják az ügynök konfigurációs fájljait.
• Forrásmegbízhatóság – Csak megbízható szerzőktől vagy ellenőrzött belső közreműködőktől származó készségek telepítése. Előnyben részesítheti a tiszta eredettel, a verziókövetéssel és az aktív karbantartással kapcsolatos készségeket. Figyeljen oda a népszerű csomagokat utánzani próbáló, elgépeléseken alapuló hamis funkciónevekre.
• Sandboxing – Olyan funkciók futtatása, amelyek végrehajtható szkripteket tartalmaznak izolált környezetekben. A fájlrendszer, a hálózat és a rendszerszintű hozzáférés korlátozása csak arra, amit a képesség igényel. A potenciálisan bizalmas műveletek végrehajtása előtt explicit felhasználói megerősítést igényel.
• Ellenőrzés és naplózás – Rögzíti, hogy mely képességek vannak betöltve, mely erőforrások vannak beolvasva, és mely szkriptek vannak végrehajtva. Ezzel naplózhatja, hogy az ügynök viselkedése visszakövethető-e egy adott képességtartalomra, ha valami hiba történik.

Mikor érdemes használni a készségeket és a munkafolyamatokat?

Az ügynöki készségek és az ügynök-keretrendszer munkafolyamatai kiterjesztik az ügynökök által elvégezhető műveleteket, de alapvetően eltérő módon működnek. Válassza ki a követelményeknek leginkább megfelelő megközelítést:

• Irányítás – Egy szakértelemmel az AI dönti el, hogyan hajtja végre az utasításokat. Ez akkor ideális, ha azt szeretné, hogy az ügynök kreatív vagy adaptív legyen. Munkafolyamat esetén explicit módon határozza meg a végrehajtási útvonalat. Akkor használjon munkafolyamatokat, ha determinisztikus, kiszámítható viselkedésre van szüksége.
• Rugalmasság – Egy képesség egyetlen ügynök fordulóján belül fut. Ha valami nem sikerül, a teljes műveletet újra kell próbálkozni. A munkafolyamatok támogatják az ellenőrzőpont-készítést, így a hiba utáni utolsó sikeres lépéstől folytathatják a munkát. Válassza ki a munkafolyamatokat, ha a teljes folyamat ismételt végrehajtásának költsége magas.
• Mellékhatások – A készségek akkor megfelelőek, ha a műveletek idempotensek vagy alacsony kockázatúak. Előnyben részesítse a munkafolyamatokat, ha a lépések olyan mellékhatásokat okoznak (e-mailek küldése, kifizetések felszámítása), amelyeket nem szabad megismételni újrapróbálkozáskor.
• Összetettség – A készségek a legjobbak az olyan koncentrált, egytartományos feladatokhoz, amelyeket egy ügynök képes kezelni. A munkafolyamatok jobban megfelelnek a többlépéses üzleti folyamatoknak, amelyek több ügynököt, emberi jóváhagyást vagy külső rendszerintegrációt koordinálnak.

Jótanács

Ökölszabályként: ha azt szeretné, hogy az AI kitalálja, hogyan kell elvégezni egy feladatot, használjon egy készséget. Ha garantálnia kell, hogy milyen lépéseket hajt végre és milyen sorrendben, használjon munkafolyamatot.

Következő lépések

CodeAct

Kapcsolódó tartalom

• Ügynöki készségek specifikációja
• CodeAct
• Kontextusszolgáltatók
• Ügynökök futtatása
• Eszközök áttekintése