Agentvaardigheden

Basisinstallatie

Maak een FileAgentSkillsProvider 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 SkillsProvider 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)

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

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

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

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 Skill exemplaar met een naam, beschrijving en instructie-inhoud. Optioneel SkillResource exemplaren toevoegen 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 @skill.resource decorator om een functie als resource te registreren. De functie wordt aangeroepen elke keer dat de agent de resource leest, zodat het kan zorgen voor actuele gegevens. Synchronisatie- en asynchrone functies worden ondersteund:

import os
from agent_framework import 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)"

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

Met code gedefinieerde scripts

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

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

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

Combinatie van vaardigheden op basis van bestanden en code

Geef zowel skill_paths als skills door aan één SkillsProvider. 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],
)

Scriptuitvoering

Vaardigheden kunnen uitvoerbare scripts bevatten die door de agent worden uitgevoerd via het run_skill_script hulpprogramma. Hoe een script wordt uitgevoerd, is afhankelijk van hoe het is gedefinieerd:

• Met code gedefinieerde scripts (geregistreerd via @skill.script) worden in het proces uitgevoerd als directe functie-aanroepen. Er is geen hardloper nodig.
• Bestandsgebaseerde scripts (bestanden gedetecteerd in skill-mappen) vereisen een callable — elke aanroepbare functie die overeenkomt met — dat bepaalt hoe het script wordt uitgevoerd (bijvoorbeeld als een lokaal subproces).

Scriptuitvoering op basis van bestanden

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

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

De runner ontvangt de opgeloste Skill, SkillScripten een optionele args woordenlijst. Bestandsgebaseerde scripts worden automatisch gedetecteerd uit .py bestanden in vaardigheidsmappen.

Goedkeuring van script

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

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)

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