Agentvaardigheden

Agentvaardigheden zijn draagbare pakketten met instructies, scripts en resources die agents gespecialiseerde mogelijkheden en domeinexpertise bieden. Vaardigheden volgen een open specificatie en implementeren een progressief openbaarmakingspatroon, zodat agents alleen de context laden die ze nodig hebben, wanneer ze het nodig hebben.

Gebruik agentvaardigheden als u het volgende wilt doen:

• Expertise van pakketdomein - Leg gespecialiseerde kennis vast (onkostenbeleid, juridische werkstromen, pijplijnen voor gegevensanalyse) als herbruikbare, draagbare pakketten.
• Mogelijkheden van agents uitbreiden : geef agents nieuwe mogelijkheden zonder de belangrijkste instructies te wijzigen.
• Consistentie garanderen : verander taken met meerdere stappen in herhaalbare, controleerbare werkstromen.
• Interoperabiliteit inschakelen : gebruik dezelfde vaardigheid voor verschillende producten die compatibel zijn met agentvaardigheden.

Vaardigheidsstructuur

Een vaardigheid is een directory met een bestand en optionele submappen voor resources.

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

Het bestand moet YAML-frontmatter bevatten, gevolgd door Markdown-inhoud:

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

Veld	Verplicht	Description
name	Ja	Maximaal 64 tekens. Alleen kleine letters, cijfers en koppeltekens. Mag niet beginnen of eindigen met een afbreekstreepje of opeenvolgende afbreekstreepjes bevatten. Moet overeenkomen met de naam van de bovenliggende map.
description	Ja	Wat de vaardigheid doet en wanneer u deze moet gebruiken. Maximaal 1024 tekens. Moet trefwoorden bevatten waarmee agents relevante taken kunnen identificeren.
license	Nee.	Licentienaam of verwijzing naar een gebundeld licentiebestand.
compatibility	Nee.	Maximaal 500 tekens. Geeft de omgevingsvereisten aan (bedoeld product, systeempakketten, netwerktoegang, enzovoort).
metadata	Nee.	Willekeurige sleutelwaardetoewijzing voor aanvullende metagegevens.
allowed-tools	Nee.	Door spaties gescheiden lijst met vooraf goedgekeurde hulpmiddelen die de vaardigheid kan gebruiken. Experimenteel: ondersteuning kan variëren tussen agent-implementaties.

De Markdown-hoofdtekst na de frontmatter bevat de vaardigheidsinstructies, stapsgewijze richtlijnen, voorbeelden van invoer en uitvoer, algemene randcases of inhoud waarmee de agent de taak kan uitvoeren. Houd onder de 500 regels en verplaats gedetailleerd referentiemateriaal naar aparte bestanden.

Progressieve openbaarmaking

Agentvaardigheden gebruiken een patroon voor progressieve openbaarmaking in drie fasen om het contextgebruik te minimaliseren:

1. Adverteren (~100 tokens per vaardigheid): namen en beschrijvingen van vaardigheden worden aan het begin van elke uitvoering in de systeemprompt geïnjecteerd, zodat de agent weet welke vaardigheden beschikbaar zijn.
2. Laden ( 5000 tokens aanbevolen): wanneer een taak overeenkomt met het domein van een vaardigheid, roept de agent het hulpprogramma aan om de volledige SKILL.md hoofdtekst op te halen met gedetailleerde instructies.
3. Resources lezen (indien nodig): de agent roept het hulpprogramma aan om aanvullende bestanden (verwijzingen, sjablonen, assets) op te halen wanneer dat nodig is.

Dit patroon houdt het contextvenster van de agent compact, terwijl de agent op aanvraag toegang krijgt tot diepgaande domeinkennis.

Vaardigheden bieden aan een agent

Het Agent Framework bevat een provider van vaardigheden die vaardigheden detecteert uit bestandssysteemmappen en deze beschikbaar maakt voor agents als contextprovider. Het doorzoekt geconfigureerde paden recursief (maximaal twee niveaus diep) voor bestanden, valideert de indeling en resources en maakt twee hulpprogramma's beschikbaar voor de agent: en .

Opmerking

De uitvoering van scripts wordt nog niet ondersteund en wordt toegevoegd in een toekomstige release.

Basisinstallatie

Maak een verwijzing naar een map met uw vaardigheden en voeg deze toe aan de contextproviders van de agent:

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

De agent aanroepen

Zodra de agent is geconfigureerd, detecteert de agent automatisch beschikbare vaardigheden en gebruikt deze wanneer een taak overeenkomt:

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

Basisinstallatie

Maak een verwijzing naar een map met uw vaardigheden en voeg deze toe aan de contextproviders van de agent:

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

De agent aanroepen

Zodra de agent is geconfigureerd, detecteert de agent automatisch beschikbare vaardigheden en gebruikt deze wanneer een taak overeenkomt:

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

Meerdere vaardighedencatalogi

U kunt meerdere mappen doorzoeken door een lijst met paden door te geven:

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

Elk pad kan verwijzen naar een afzonderlijke vaardigheidsmap (met een ) of een bovenliggende map met submappen voor vaardigheden. De provider doorzoekt maximaal twee niveaus diep.

Aangepaste systeemprompt

Standaard injecteert de vaardighedenprovider een systeemprompt waarin de beschikbare vaardigheden worden vermeld en de agent wordt geïnstrueerd om deze te gebruiken. U kunt deze prompt aanpassen:

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

Opmerking

De aangepaste sjabloon moet een tijdelijke aanduiding bevatten waarin de lijst met vaardigheden wordt ingevoegd. Letterlijke accolades moeten worden ontsnapt met en .

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

Opmerking

De aangepaste sjabloon moet een tijdelijke aanduiding bevatten waarin de lijst met vaardigheden wordt ingevoegd.

Door code gedefinieerde vaardigheden

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

• Inhoud van vaardigheden wordt dynamisch gegenereerd (bijvoorbeeld lezen uit een database of omgeving).
• U wilt vaardigheidsdefinities naast de toepassingscode die deze gebruikt, behouden.
• U hebt resources nodig die logica op leestijd uitvoeren in plaats van statische bestanden te leveren.

Basiscodevaardigheden

Maak een exemplaar met een naam, beschrijving en instructie-inhoud. Voeg eventueel exemplaren toe met statische inhoud:

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

Dynamische middelen

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

import os
from agent_framework import 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() -> str:
    """Get current environment configuration."""
    env = os.environ.get("APP_ENV", "development")
    region = os.environ.get("APP_REGION", "us-east-1")
    return f"Environment: {env}, Region: {region}"

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

Wanneer de decorator zonder argumenten wordt gebruikt (), wordt de naam van de functie de resourcenaam en wordt de docstring de beschrijving. Gebruik dit om ze expliciet in te stellen.

Combinatie van vaardigheden op basis van bestanden en code

Geef beide en één door naar een enkele. Vaardigheden op basis van bestanden worden eerst ontdekt; als een door code gedefinieerde vaardigheid dezelfde naam heeft als een bestaande op bestanden gebaseerde vaardigheid, wordt de door code gedefinieerde vaardigheid overgeslagen:

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

Aanbevolen procedures voor beveiliging

Agent Skills dienen te worden behandeld als code van derden die u in uw project invoert. Omdat vaardigheidsinstructies worden geïnjecteerd in de context van de agent, en vaardigheden kunnen scripts bevatten, is het toepassen van hetzelfde beoordelingsniveau en governance essentieel voor een opensource-afhankelijkheid.

• Controleer voor gebruik : lees alle vaardigheidsinhoud (, scripts en resources) voordat u implementeert. Controleer of het werkelijke gedrag van een script overeenkomt met de vermelde intentie. Controleer op instructies met kwade bedoelingen die proberen veiligheidsrichtlijnen te omzeilen, data te exfiltreren of agentconfiguratiebestanden te wijzigen.
• Bronvertrouwen : installeer alleen vaardigheden van vertrouwde auteurs of gecontroleerde interne inzenders. Geef de voorkeur aan vaardigheden met duidelijke herkomst, versiebeheer en actief onderhoud. Kijk naar getypeerde vaardigheidsnamen die populaire pakketten nabootsen.
• Sandboxing : voer vaardigheden uit die uitvoerbare scripts bevatten in geïsoleerde omgevingen. Beperk het bestandssysteem, het netwerk en het systeemniveau tot alleen wat de vaardigheid vereist. Expliciete gebruikersbevestiging vereisen voordat mogelijk gevoelige bewerkingen worden uitgevoerd.
• Controle en logboekregistratie : noteer welke vaardigheden worden geladen, welke resources worden gelezen en welke scripts worden uitgevoerd. Dit geeft u een audit trail om het gedrag van agents te traceren naar specifieke vaardigheden als er iets misgaat.

Wanneer u vaardigheden versus werkstromen gebruikt

Agentvaardigheden en Agent Framework-werkstromen breiden beide uit wat agenten kunnen doen, maar werken op fundamenteel verschillende manieren. Kies de methode die het beste overeenkomt met uw vereisten:

• Controle : met een vaardigheid bepaalt de AI hoe de instructies moeten worden uitgevoerd. Dit is ideaal als u wilt dat de agent creatief of adaptief is. Met een werkstroom definieert u expliciet het uitvoeringspad. Gebruik werkstromen wanneer u deterministisch, voorspelbaar gedrag nodig hebt.
• Veerkracht: een vaardigheid wordt uitgevoerd binnen één agent-beurt. Als er iets mislukt, moet de hele bewerking opnieuw worden uitgevoerd. Werkstromen ondersteunen controlepunten, zodat ze kunnen hervatten vanaf de laatste geslaagde stap na een fout. Kies werkstromen wanneer de kosten voor het opnieuw uitvoeren van het hele proces hoog zijn.
• Effecten — Vaardigheden zijn geschikt wanneer bewerkingen idempotent zijn of een laag risico hebben. Geef de voorkeur aan werkstromen wanneer stappen bijwerkingen opleveren (e-mailberichten verzenden, betalingen in rekening brengen) die niet moeten worden herhaald bij opnieuw proberen.
• Complexiteit : vaardigheden zijn het beste voor gerichte taken met één domein die door één agent kunnen worden verwerkt. Werkstromen zijn beter geschikt voor bedrijfsprocessen met meerdere stappen die meerdere agents, menselijke goedkeuringen of externe systeemintegraties coördineren.

Aanbeveling

Als u wilt dat de AI erachter komt hoe een taak moet worden uitgevoerd, gebruikt u een vaardigheid. Als u wilt garanderen welke stappen worden uitgevoerd en in welke volgorde, gebruikt u een werkstroom.

Volgende stappen

Contextproviders

Verwante inhoud

• Specificatie van agentvaardigheden
• Contextproviders
• Overzicht van hulpprogramma's