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í třífázový vzor progresivního zpřístupnění 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é.

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í.

Poskytování dovedností agentovi

Agent Framework obsahuje poskytovatele dovedností, který zjišťuje dovednosti z adresářů systému souborů a zpřístupňuje je agentům jako poskytovatel kontextu. Prohledává nakonfigurované cesty rekurzivně (až do dvou úrovní hloubky) pro SKILL.md soubory, ověřuje jejich formát a prostředky a zveřejňuje nástroje pro agenta: load_skill, read_skill_resourcea (když jsou přítomny skripty) run_skill_script.

Poznámka:

Spouštění skriptů ještě není v jazyce C# podporováno a bude přidáno v budoucí verzi.

Základní nastavení

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

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

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

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

Vyvolání agenta

Po nakonfigurování agent automaticky zjistí dostupné dovednosti a použije je, když se úkol shoduje:

// The agent loads the expense-report skill and reads the FAQ resource
AgentResponse response = await agent.RunAsync(
    "Are tips reimbursable? I left a 25% tip on a taxi ride.");
Console.WriteLine(response.Text);

Základní nastavení

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

from pathlib import Path
from agent_framework import SkillsProvider
from agent_framework.azure import AzureOpenAIChatClient
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 = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
    name="SkillsAgent",
    instructions="You are a helpful assistant.",
    context_providers=[skills_provider],
)

Vyvolání agenta

Po nakonfigurování agent automaticky zjistí dostupné dovednosti a použije je, když se úkol shoduje:

# The agent loads the expense-report skill and reads the FAQ resource
response = await agent.run(
    "Are tips reimbursable? I left a 25% tip on a taxi ride."
)
print(response.text)

Více adresářů dovedností

Můžete prohledávat více adresářů předáním seznamu cest:

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

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

Každá cesta může odkazovat na složku jednotlivých dovedností (obsahující SKILL.md) nebo nadřazenou složku s podadresáři dovedností. Poskytovatel prohledává do hloubky až dvou úrovní.

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 FileAgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
    options: new FileAgentSkillsProviderOptions
    {
        SkillsInstructionPrompt = """
            You have skills available. Here they are:
            {0}
            Use the `load_skill` function to get skill instructions.
            Use the `read_skill_resource` function to read skill files.
            """
    });

Poznámka:

Vlastní šablona musí obsahovat {0} zástupný symbol, do kterého se vloží seznam dovedností. 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.

Dovednosti definované kódem

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

Spouštění skriptů

Dovednosti můžou zahrnovat spustitelné skripty, které agent spouští prostřednictvím run_skill_script nástroje. Způsob spuštění skriptu závisí na tom, jak byl definován:

• Skripty definované kódem (zaregistrované prostřednictvím @skill.script) se spouštějí v procesu jako přímá volání funkcí. Není potřeba žádný běžec.
• Skripty založené na souborech (.py soubory zjištěné v adresářích dovedností) vyžadují SkillScriptRunner ( jakékoli volatelné shody (skill, script, args) -> Any ), které určují způsob spuštění skriptu (například jako místní podproces).

Spouštění skriptů založených na souborech

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.

Schválení skriptu

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.

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

Zprostředkovatelé kontextu

Související obsah

• Specifikace dovedností agenta
• Zprostředkovatelé kontextu
• Přehled nástrojů