Dovednosti agenta

Dovednosti agenta jsou přenosné balíčky instrukcí, skriptů a prostředků, které poskytují agentům specializované schopnosti a odborné znalosti domény. Dovednosti dodržují otevřenou specifikaci a implementují model progresivního zpřístupnění, takže agenti načítají jenom kontext, který potřebují, když ho potřebují.

Dovednosti agenta použijte v případech, kdy chcete:

• Balíčky odborných znalostí v oblasti domén – zachycení specializovaných znalostí (zásady pro výdaje, právní pracovní postupy, datové analytické kanály) jako opakovaně použitelné, přenosné balíčky.
• Rozšiřte možnosti agenta – udělte agentům nové schopnosti beze změny základních pokynů.
• Zajištění konzistence – Převod vícekrokových úloh na opakovatelné a auditovatelné pracovní postupy
• Povolte interoperabilitu – opakovaně používejte stejnou dovednost v různých produktech kompatibilních s funkcemi Agent Skills.

Struktura dovedností

Skill je adresář obsahující SKILL.md soubor s volitelnými podadresáři pro prostředky:

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

formát SKILL.md

Soubor SKILL.md musí obsahovat frontmatter YAML následovaný obsahem markdownu:

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

Obor	Povinné	Description
name	Ano	Maximálně 64 znaků. Malá písmena, číslice a spojovníky. Nesmí začínat ani končit pomlčkou nebo obsahovat po sobě jdoucí pomlčky. Musí odpovídat názvu nadřazeného adresáře.
description	Ano	Co dovednost dělá a kdy ji používat. Maximálně 1024 znaků. Měla by obsahovat klíčová slova, která pomáhají agentům identifikovat relevantní úlohy.
license	Ne	Název licence nebo odkaz na soubor sbalené licence.
compatibility	Ne	Maximálně 500 znaků. Označuje požadavky na prostředí (zamýšlený produkt, systémové balíčky, přístup k síti atd.).
metadata	Ne	Libovolné mapování klíčů a hodnot pro doplňková metadata
allowed-tools	Ne	Seznam nástrojů předem schválených ke použití dovedností, oddělený mezerami. Experimentální – podpora se může mezi implementacemi agenta lišit.

Tělo markdownu za frontmatterem obsahuje instrukce pro dovednosti – podrobné pokyny, příklady vstupů a výstupů, typické mezní případy nebo jakýkoli obsah, který pomáhá uživateli provádět úlohu. Udržujte SKILL.md pod 500 řádků a přesuňte podrobný referenční materiál do samostatných souborů.

Progresivní zveřejnění

Dovednosti agentů používají model postupného zpřístupnění ve čtyřech fázích k minimalizaci využití kontextu:

1. Inzerování (~100 tokenů na dovednost) – názvy dovedností a popisy se vloží do systémové výzvy na začátku každého spuštění, takže agent ví, jaké dovednosti jsou k dispozici.
2. Načtení (< doporučeno 5000 tokenů) – Pokud úkol odpovídá doméně dovednosti, agent zavolá load_skill nástroj pro načtení celého těla SKILL.md s podrobnými pokyny.
3. Čtení prostředků (podle potřeby) – agent volá read_skill_resource nástroj, aby načítal doplňkové soubory (odkazy, šablony, prostředky) jen když je to nutné.
4. Spouštění skriptů (podle potřeby) – agent volá run_skill_script nástroj ke spouštění skriptů, které jsou součástí dovednosti.

Tento vzor udržuje štíhlé kontextové okno agenta, zatímco mu poskytuje přístup k hlubokým znalostem domény na vyžádání.

Poznámka:

load_skill je vždy inzerován. read_skill_resource je inzerováno pouze pokud alespoň jedna schopnost má prostředky. run_skill_script inzeruje se pouze v případech, kdy alespoň jedna dovednost obsahuje skripty.

Poskytování dovedností agentovi

AgentSkillsProvider (C#) a SkillsProvider (Python) jsou poskytovatelé kontextu, kteří zpřístupní dovednosti agentům. Podporují tři zdroje dovedností:

• Založené na souborech – dovednosti zjištěné ze SKILL.md souborů v adresářích systému souborů
• Definovaný kód – dovednosti definované v kódu pomocí AgentInlineSkill (C#) nebo Skill (Python)
• Založené na třídě – dovednosti zapouzdřené ve třídě jazyka C# odvozené z AgentClassSkill<T> jazyka C# (pouze jazyk C#)

Pro kombinování více zdrojů v jednom poskytovateli použijte AgentSkillsProviderBuilder (jenom C# – viz Tvůrce: pokročilé scénáře s více zdroji).

Dovednosti založené na souborech

Vytvořte AgentSkillsProvider odkaz na adresář obsahující vaše dovednosti a přidejte ho do poskytovatelů kontextu agenta. Předáním spouštěče skriptů povolte spouštění skriptů založených na souborech nalezených v adresářích dovedností:

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

Výstraha

DefaultAzureCredential je vhodný pro vývoj, ale vyžaduje pečlivé zvážení v produkčním prostředí. V produkčním prostředí zvažte použití konkrétních přihlašovacích údajů (např ManagedIdentityCredential. ) k zabránění problémům s latencí, neúmyslnému testování přihlašovacích údajů a potenciálním bezpečnostním rizikům z náhradních mechanismů.

Více adresářů dovedností

Poskytovatele můžete nasměrovat na jeden hlavní adresář – každá podsložka, která obsahuje SKILL.md, je automaticky rozpoznána jako dovednost.

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

Nebo předejte seznam cest pro vyhledávání více kořenových adresářů:

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

Poskytovatel prohledává do hloubky až dvou úrovní.

Přizpůsobení detekce zdrojů

Ve výchozím nastavení poskytovatel rozpozná prostředky s rozšířeními .md, .json, .yaml, .yml, .csv, , .xml, a .txt v references a assets podadresářích. Slouží AgentFileSkillsSourceOptions ke změně těchto výchozích hodnot:

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

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

Spouštění skriptů

Předat SubprocessScriptRunner.RunAsync jako druhý argument do AgentSkillsProvider pro povolení spouštění souborových skriptů.

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

SubprocessScriptRunner.RunAsync přibližně odpovídá následujícímu:

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

Spouštěč spouští každý zjištěný skript jako místní podproces. Skripty založené na souborech očekávají argumenty jako pole řetězců JSON – každý prvek pole se stane pozičním argumentem příkazového řádku.

Výstraha

SubprocessScriptRunner je k dispozici pouze pro demonstrační účely. Pro použití v produkčním prostředí zvažte přidání:

• Sandboxing (například kontejnery nebo izolovaná spouštěcí prostředí)
• Limity prostředků (procesor, paměť, vypršení časového limitu hodin)
• Ověření vstupu a výpis spustitelných skriptů
• Strukturované protokolování a záznamy auditu

Přizpůsobení zjišťování skriptů

Ve výchozím nastavení poskytovatel rozpozná skripty s rozšířeními .py, .js, .sh, .ps1.csa .csx v scripts podadresáři. Slouží AgentFileSkillsSourceOptions ke změně těchto výchozích hodnot:

Předejte konstruktoru nebo tvůrciAgentFileSkillsSourceOptionsAgentSkillsProviderUseFileSkill: / 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();

Dovednosti založené na souborech

Vytvořte SkillsProvider ukazující na adresář obsahující vaše dovednosti a přidejte ho do kontextových poskytovatelů agenta.

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],
)

Více adresářů dovedností

Poskytovatele můžete nasměrovat na jednu nadřazenou složku – každá podsložka, která obsahuje SKILL.md, se automaticky rozpozná jako dovednost.

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

Nebo předejte seznam cest pro vyhledávání více kořenových adresářů:

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

Poskytovatel prohledává do hloubky až dvou úrovní.

Přizpůsobení detekce zdrojů

Ve výchozím nastavení SkillsProvider rozpozná prostředky pomocí rozšíření .md, .json, .yaml, .yml, .csv, .xml a .txt. Prohledá všechny podadresáře v rámci každé složky dovedností. Předáním resource_extensions změn rozpoznané typy souborů:

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

Spouštění skriptů

Pokud chcete povolit spouštění skriptů založených na souborech, předejte script_runner do SkillsProvidersouboru . Můžete použít jakoukoli synchronní nebo asynchronní funkci nebo metodu, které splňují SkillScriptRunner protokol:

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

Běžec obdrží vyřešený Skill, SkillScript, a volitelný args slovník. Skripty založené na souborech se automaticky zjistí ze .py souborů v adresářích dovedností.

Výstraha

Výše uvedený běžec je k dispozici pouze pro demonstrační účely. Pro použití v produkčním prostředí zvažte přidání:

• Sandboxing (například kontejnery, seccomp nebo firejail)
• Limity prostředků (procesor, paměť, vypršení časového limitu hodin)
• Ověření vstupu a výpis spustitelných skriptů
• Strukturované protokolování a záznamy auditu

Poznámka:

Pokud jsou k dispozici dovednosti založené na souborech se skripty, ale script_runner nejsou nastaveny, SkillsProvider vyvolá ValueError.

Dovednosti definované kódem

Kromě souborových dovedností zjištěných ze SKILL.md souborů můžete definovat dovednosti zcela v kódu pomocí AgentInlineSkill. Dovednosti definované kódem jsou užitečné v následujících případech:

• Obsah dovedností se generuje dynamicky (například čtení z databáze nebo prostředí).
• Chcete zachovat definice dovedností společně s kódem aplikace, který je používá.
• Potřebujete prostředky, které spouští logiku v době čtení, a ne obsluhují statické soubory.

Základní dovednosti kódu

Vytvořte název AgentInlineSkill , popis a pokyny. Připojte prostředky pomocí .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);

Dynamické prostředky

Předat delegáta továrny .AddResource(), aby se obsah vypočítal během běhu programu. Delegát se vyvolá pokaždé, když agent přečte zdroj.

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

Skripty definované kódem

Slouží .AddScript() k registraci delegáta jako spustitelného skriptu. Skripty definované kódem běží v procesu jako přímá volání delegáta. Není potřeba žádný spouštěč skriptů. Zadané parametry delegáta se automaticky převedou na schéma JSON, které agent používá k předávání argumentů:

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

Poznámka:

Pokud chcete zkombinovat dovednosti definované kódem se souborovými dovednostmi nebo dovednostmi založenými na třídě v jednom poskytovateli, použijte AgentSkillsProviderBuilder – viz Tvůrce: pokročilé scénáře s více zdroji.

Kromě dovedností založených na souborech zjištěných v souborech SKILL.md můžete definovat dovednosti zcela v kódu Python. Dovednosti definované kódem jsou užitečné v následujících případech:

• Obsah dovedností se generuje dynamicky (například čtení z databáze nebo prostředí).
• Chcete zachovat definice dovedností společně s kódem aplikace, který je používá.
• Potřebujete prostředky, které spouští logiku v době čtení, a ne obsluhují statické soubory.

Základní dovednosti kódu

Vytvořte Skill instanci s názvem, popisem a obsahem instrukcí. Volitelně připojte SkillResource instance se statickým obsahem:

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

Dynamické prostředky

Pomocí dekorátoru @skill.resource zaregistrujte funkci jako zdroj. Funkce se volá pokaždé, když agent přečte prostředek, aby mohla vrátit aktuální data. Podporují se synchronizační i asynchronní funkce:

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

Když se dekorátor použije bez argumentů (@skill.resource), název funkce se stane názvem prostředku a docstring se stane popisem. Slouží @skill.resource(name="...", description="...") k jejich explicitní nastavení.

Skripty definované kódem

Pomocí dekorátoru @skill.script zaregistrujte funkci jako spustitelný skript pro dovednosti. Skripty definované kódem běží v procesu a nevyžadují exekutor skriptu. Podporují se synchronizační i asynchronní funkce:

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

Když se dekorátor použije bez argumentů (@skill.script), název funkce se změní na název skriptu a řetězec docstring se stane popisem. Typové parametry funkce se automaticky převedou na schéma JSON, které agent používá k předávání argumentů.

Kombinování dovedností založených na souborech a definovaných kódem

Předat jak skill_paths, tak skills do jediného SkillsProvider. Nejprve jsou zjištěny dovednosti založené na souborech; Pokud má dovednost definovaná kódem stejný název jako existující dovednost založená na souboru, přeskočí se dovednost definovaná kódem:

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],
)

Dovednosti dle tříd

Dovednosti založené na třídách umožňují seskupovat všechny komponenty dovedností – název, popis, pokyny, prostředky a skripty – do jedné třídy jazyka C#. Odvozujte z AgentClassSkill<T> třídy (kde T je vaše třída), a pak anotujte vlastnosti s metodami [AgentSkillResource][AgentSkillScript] pro automatické zjišťování:

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

Zaregistrujte dovednost založenou na předmětu pomocí AgentSkillsProvider:

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

[AgentSkillResource] Když se atribut použije na vlastnost nebo metodu, jeho návratová hodnota se použije jako obsah prostředku, když agent přečte prostředek – použijte metodu, když se obsah musí vypočítat v době čtení. Metoda je vyvolána, když agent volá skript, pokud je [AgentSkillScript] použit na metodu. Použijte [Description] z System.ComponentModel k popisu jednotlivých prostředků a skriptů pro agenta.

Poznámka:

AgentClassSkill<T> také podporuje přepisování Resources a Scripts jako kolekcí pro situace, kde není zjišťování založené na atributech vhodné.

Tvůrce: pokročilé scénáře s více zdroji

Pro jednoduché scénáře s jedním zdrojem použijte AgentSkillsProvider konstruktory přímo. Použijte AgentSkillsProviderBuilder , když potřebujete některou z následujících možností:

• Smíšené typy dovedností – kombinují dovednosti založené na souborech, definované kódem (AgentInlineSkill) a dovednosti založené naAgentClassSkill třídách v jednom poskytovateli.
• Filtrování dovedností – zahrnutí nebo vyloučení dovedností pomocí predikátu

Typy smíšených dovedností

Zkombinujte všechny tři typy dovedností v jednom poskytovateli zřetězováním UseFileSkill, UseSkilla 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();

Filtrování dovedností

Použijte UseFilter k zahrnutí pouze těch dovedností, které splňují vaše kritéria — například pro načtení dovedností ze sdíleného adresáře, ale vyloučení experimentálních:

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

Schválení skriptu

Použijte AgentSkillsProviderOptions.ScriptApproval k zajištění, že veškeré spuštění skriptu bude probíhat pod lidským schválením. Pokud je tato možnost povolená, agent se pozastaví a místo okamžitého spuštění vrátí žádost o schválení:

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

Pokud chcete povolit schvalování skriptů u zprostředkovatele nakonfigurovaného tvůrcem, použijte UseScriptApproval:

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

Použijte require_script_approval=True na SkillsProvider k zajištění, že veškeré spuštění skriptu bude podléhat schválení člověka. Místo okamžitého provedení agent nejprve pozastaví akci a poté vrátí žádosti o schválení.

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)

Když je skript odmítnut (approved=False), agent je informován, že uživatel odmítl a může odpovídajícím způsobem reagovat.

Výzva pro přizpůsobený systém

Ve výchozím nastavení poskytovatel dovedností vloží systémovou výzvu, která obsahuje seznam dostupných dovedností a dává agentovi pokyn, aby používal load_skill a read_skill_resource. Tuto výzvu můžete přizpůsobit:

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

Poznámka:

Vlastní šablona musí obsahovat zástupné symboly {skills} (seznam dovedností), {resource_instructions} (nápověda nástroje prostředků) a {script_instructions} (nápověda nástroje skriptu). Doslovné složené závorky musí být eskapované jako {{ a }}.

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."
    ),
)

Poznámka:

Vlastní šablona musí obsahovat {skills} zástupný symbol, do kterého se vloží seznam dovedností, a {runner_instructions} zástupný symbol, do kterého se vloží pokyny související se skripty.

Chování při ukládání do mezipaměti

Standardně se nástroje a pokyny pro dovednosti ukládají po prvním sestavení do mezipaměti. Nastavte DisableCaching = true na AgentSkillsProviderOptions tak, aby při každém vyvolání vynutil opětovné sestavení:

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

Poznámka:

Zakázání ukládání do mezipaměti je užitečné při vývoji, když se obsah dovedností často mění. V produkčním prostředí ponechte ukládání do mezipaměti povolené (výchozí) kvůli lepšímu výkonu.

Injekce závislostí

Delegáti zdrojů dovedností a skriptů mohou deklarovat IServiceProvider parametr, který Agent Framework automaticky vloží. Díky tomu mohou dovednosti řešit aplikační služby , jako jsou databázové klienty, konfigurace nebo obchodní logika, aniž by je pevně zakódovaly do definice dovednosti.

Setup

Zaregistrujte aplikační služby a předávejte sestavený IServiceProvider agentovi prostřednictvím parametru services.

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

Dovednosti definované kódem pomocí DI

Deklarujte IServiceProvider jako parametr v rámci AddResource nebo AddScript delegátů — framework ji automaticky vyřeší a vloží, když agent přečte prostředek nebo spustí skript:

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

Dovednosti založené na třídách s DI

Přidávání poznámek k metodám nebo [AgentSkillResource][AgentSkillScript] deklarování parametru IServiceProvider – architektura tyto členy zjišťuje prostřednictvím reflexe a automaticky vloží zprostředkovatele služeb:

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

Návod

Dovednosti založené na třídách můžou také řešit závislosti prostřednictvím jejich konstruktoru. Zaregistrujte třídu dovedností v kontejneru ServiceCollection a získejte ji z kontejneru místo přímého volání new.

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

To je užitečné, když třída dovedností sama potřebuje vložené služby nad rámec toho, co používají delegáti prostředků a skriptů.

Funkce pro zdroje a skripty, které přijmou **kwargs, automaticky obdrží modulu runtime klíčové argumenty ve formě klíčového slova, předané do agent.run(). Díky tomu budou funkce dovedností přistupovat k kontextu aplikace , jako je konfigurace, identita uživatele nebo klienti služeb, aniž by je pevně zakódovaly do definice dovednosti.

Předávání argumentů modulu runtime

Prostřednictvím function_invocation_kwargs předáte do agent.run() klíčové argumenty, které framework předává funkcím pro prostředky a skripty:

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

Funkce prostředků s klíčovými argumenty (kwargs)

Když funkce prostředku deklaruje **kwargs, architektura předává argumenty klíčového slova modulu runtime pokaždé, když agent přečte prostředek:

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

Prostředkové funkce bez **kwargs argumentů se volají bez argumentů a neobdrží žádný kontext za běhu.

Skriptovací funkce s kwargs

Když funkce skriptu deklaruje **kwargs, rámec předá argumenty klíčového slova modulu runtime args spolu s těmi, které poskytl agent:

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

Agent poskytuje value a factor prostřednictvím volání nástroje; aplikace poskytuje args prostřednictvím precisionfunction_invocation_kwargs. Funkce skriptu bez **kwargs příjmu pouze argumentů zadaných agentem.

Osvědčené postupy zabezpečení

Dovednosti agenta by se měly považovat za jakýkoli kód třetí strany, který do projektu přenesete. Vzhledem k tomu, že pokyny ke dovednostem se vloží do kontextu agenta – a dovednosti můžou zahrnovat skripty – použití stejné úrovně kontroly a zásad správného řízení, které byste použili u opensourcové závislosti, je nezbytné.

• Než začnete používat , přečtěte si veškerý obsah dovedností (SKILL.mdskripty a prostředky) před nasazením. Ověřte, že skutečné chování skriptu odpovídá jeho zadanému záměru. Zkontrolujte nežádoucí pokyny, které se pokoušejí obejít bezpečnostní pokyny, exfiltrovat data nebo upravit konfigurační soubory agenta.
• Důvěra ve zdroj – Instalujte dovednosti pouze od důvěryhodných autorů nebo prověřených interních přispěvatelů. Preferujte dovednosti s jasnou proveniencem, správou verzí a aktivní údržbou. Podívejte se na překlepové názvy dovedností, které napodobují oblíbené balíčky.
• Sandboxing — Provozujte funkce, které zahrnují spustitelné skripty, v izolovaných prostředích. Omezte přístup na úrovni systému souborů, sítě a systému jenom na to, co dovednost vyžaduje. Před spuštěním potenciálně citlivých operací budete vyžadovat explicitní potvrzení uživatele.
• Audit a protokolování – Zaznamenávání, které dovednosti jsou načtené, které prostředky jsou čteny a které skripty jsou spuštěné. To vám poskytne záznam auditu, který umožní sledovat chování agenta zpětně k specifickému obsahu dovedností, pokud se něco nepovede.

Kdy používat dovednosti vs. pracovní postupy

Dovednosti agentů a pracovní postupy rámce agenta rozšiřují schopnosti agentů, ale fungují v zásadě různými způsoby. Zvolte přístup, který nejlépe odpovídá vašim požadavkům:

• Řízení – S dovedností se AI rozhodne, jak provést instrukce. To je ideální, když chcete, aby agent byl kreativní nebo adaptivní. V pracovním postupu explicitně definujete cestu provádění. Pracovní postupy používejte v případě, že potřebujete deterministické a předvídatelné chování.
• Odolnost – dovednost běží v rámci jednoho tahu agenta. Pokud se něco nepovede, musí se celá operace opakovat. Pracovní postupy podporují checkpointing, takže mohou pokračovat od posledního úspěšného kroku po selhání. Zvolte pracovní postupy, když jsou náklady na opětovné spuštění celého procesu vysoké.
• Vedlejší účinky – schopnosti jsou vhodné, pokud jsou operace idempotentní nebo nízkorizikové. Upřednostňujte pracovní postupy, pokud kroky vytvářejí vedlejší účinky (odesílání e-mailů, účtování plateb), které by se neměly opakovat při opakování.
• Složitost – Dovednosti jsou nejvhodnější pro úlohy zaměřené na jednu doménu, které může jeden agent zpracovat. Pracovní postupy jsou vhodnější pro vícekrokové obchodní procesy, které koordinuje více agentů, schvalování lidí nebo integrace externího systému.

Návod

Obecně platí, že pokud chcete, aby umělé inteligence dokázali zjistit, jak provést úkol, použijte dovednost. Pokud potřebujete zaručit , jaké kroky se provádějí a v jakém pořadí, použijte pracovní postup.

Další kroky

CodeAct

Související obsah

• Specifikace dovedností agenta
• CodeAct
• Zprostředkovatelé kontextu
• Spouštění agentů
• Přehled nástrojů