Competenze dell'agente

Competenze basate sui file

Creare un collegamento a una directory contenente le skill, e aggiungerlo ai fornitori di contesto dell'agente. Passare un esecutore di script per abilitare l'esecuzione di script basati su file presenti nelle directory delle abilità.

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

Molteplici directory di competenze

È possibile indirizzare il provider a un'unica directory padre: ogni sottodirectory contenente un SKILL.md viene rilevata automaticamente come skill:

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

In alternativa, passare un elenco di percorsi per eseguire ricerche in più directory radice:

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

Il provider cerca fino a due livelli di profondità.

Personalizzazione dell'individuazione delle risorse

Per impostazione predefinita, il provider riconosce le risorse con estensioni .md, .json, .yaml, .yml, .csv, .xml e .txt nelle sottodirectory references e assets. Usare AgentFileSkillsSourceOptions per modificare queste impostazioni predefinite:

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

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

Esecuzione degli script

Passare SubprocessScriptRunner.RunAsync come secondo argomento a AgentSkillsProvider per abilitare l'esecuzione di script basati su file.

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

SubprocessScriptRunner.RunAsync è approssimativamente equivalente ai seguenti:

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

Il runner esegue ogni script individuato come sottoprocesso locale. Gli script basati su file prevedono argomenti come matrice JSON di stringhe. Ogni elemento della matrice diventa un argomento della riga di comando posizionale.

Personalizzazione dell'individuazione di script

Per impostazione predefinita, il provider riconosce gli script con estensioni .py, .js, .sh, .ps1, .cs, e .csx nella sottodirectory scripts. Usare AgentFileSkillsSourceOptions per modificare queste impostazioni predefinite:

Passare AgentFileSkillsSourceOptions al AgentSkillsProvider costruttore o a UseFileSkill / UseFileSkills nel generatore:

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

Competenze basate sui file

Usare la SkillsProvider.from_paths() factory per individuare le competenze nelle directory contenenti file SKILL.md e aggiungere il provider ai provider di contesto dell'agente:

import os
from pathlib import Path
from agent_framework import Agent, SkillsProvider
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

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

# Create an agent with the skills provider
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
deployment = os.environ.get("FOUNDRY_MODEL", "gpt-4o-mini")

client = FoundryChatClient(
    project_endpoint=endpoint,
    model=deployment,
    credential=AzureCliCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful assistant.",
    context_providers=[skills_provider],
)

Molteplici directory di competenze

È possibile indirizzare il provider a un'unica directory padre: ogni sottodirectory contenente un SKILL.md viene rilevata automaticamente come skill:

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

In alternativa, passare un elenco di percorsi per eseguire ricerche in più directory radice:

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

Il provider cerca fino a due livelli di profondità.

Personalizzazione del rilevamento delle risorse e degli script

Per impostazione predefinita, le risorse vengono individuate nelle sottodirectory references/ e assets/ e gli script da scripts/, secondo la specifica agentskills.io. Le estensioni delle risorse riconosciute sono , , .md, , .json.yaml, e .yml. .csv.xml.txt Usare resource_directories, script_directoriese resource_extensions per personalizzare queste impostazioni predefinite:

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
    resource_extensions=(".md", ".txt"),
    resource_directories=["docs", "templates"],
    script_directories=["scripts", "tools"],
)

Usare "." per includere i file a livello radice della competenza oltre alle sottodirectory.

Esecuzione degli script

Per abilitare l'esecuzione di script basati su file, passare un script_runner a SkillsProvider.from_paths(). È possibile usare qualsiasi funzione o metodo sincrono o asincrono che soddisfi il protocollo SkillScriptRunner:

from pathlib import Path
from agent_framework import FileSkill, FileSkillScript, SkillsProvider

def my_runner(
    skill: FileSkill,
    script: FileSkillScript,
    args: dict | list[str] | None = None,
) -> str:
    """Run a file-based script as a subprocess."""
    import subprocess, sys
    script_path = Path(script.full_path)
    cmd = [sys.executable, str(script_path)]
    if isinstance(args, list):
        cmd.extend(args)
    result = subprocess.run(
        cmd, capture_output=True, text=True, timeout=30, cwd=str(script_path.parent)
    )
    return result.stdout.strip()

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

L'esecutore riceve gli argomenti risolti FileSkill, FileSkillScript e un argomento facoltativo args. Gli script basati su file prevedono argomenti come matrice JSON di stringhe. Ogni elemento della matrice diventa un argomento della riga di comando posizionale. Gli script vengono rilevati automaticamente nei file .py nella sottodirectory scripts/ di ogni skill.

Oltre alle competenze basate su file individuate dai SKILL.md file, è possibile definire le competenze interamente nel codice usando AgentInlineSkill. Le competenze definite dal codice sono utili quando:

• Il contenuto della competenza viene generato in modo dinamico( ad esempio, la lettura da un database o un ambiente).
• Si vogliono mantenere le definizioni delle competenze insieme al codice dell'applicazione che le usa.
• Sono necessarie risorse che eseguono la logica in fase di lettura anziché gestire i file statici.
• Le definizioni delle competenze devono essere costruite in fase di esecuzione dai dati , ad esempio creando una competenza personalizzata per ogni sessione utente in base al ruolo o alle autorizzazioni.
• Una competenza deve chiudere lo stato del sito di chiamata (variabili locali, chiuse) anziché risolvere i servizi da un contenitore di inserimento delle dipendenze.

Competenza di codice di base

Creare un oggetto AgentInlineSkill con un nome, una descrizione e istruzioni. Collegare le risorse usando .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);

Risorse dinamiche

Passare un delegato factory a .AddResource() per calcolare il contenuto in fase di esecuzione. Il delegato viene richiamato ogni volta che l'agente legge la risorsa:

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

Script definiti dal codice

Usare .AddScript() per registrare un delegato come script eseguibile. Gli script definiti dal codice vengono eseguiti in-process come chiamate delegate dirette. Non è necessario alcun esecutore di script. I parametri tipizzati del delegato vengono convertiti automaticamente in uno Schema JSON che l'agente usa per passare gli argomenti.

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

Oltre alle competenze basate su file individuate dai file SKILL.md, è possibile definire le competenze interamente nel codice Python usando InlineSkill. Le competenze definite dal codice sono utili quando:

• Il contenuto della competenza viene generato in modo dinamico( ad esempio, la lettura da un database o un ambiente).
• Si vogliono mantenere le definizioni delle competenze insieme al codice dell'applicazione che le usa.
• Sono necessarie risorse che eseguono la logica in fase di lettura anziché gestire i file statici.
• Le definizioni delle competenze devono essere costruite in fase di esecuzione dai dati , ad esempio creando una competenza personalizzata per ogni sessione utente in base al ruolo o alle autorizzazioni.
• Una competenza deve chiudere lo stato del sito di chiamata (variabili locali, chiuse) anziché risolvere i servizi tramite **kwargs.

Competenza di codice di base

Creare un'istanza InlineSkill con un oggetto SkillFrontmatter (contenente il nome e la descrizione) e il contenuto delle istruzioni. Facoltativamente, allegare InlineSkillResource istanze al contenuto statico:

from textwrap import dedent
from agent_framework import InlineSkill, InlineSkillResource, SkillFrontmatter, SkillsProvider

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

Risorse dinamiche

Usa il decoratore @skill.resource per registrare una funzione come risorsa. La funzione viene chiamata ogni volta che l'agente legge la risorsa, in modo che possa restituire dati aggiornati. Sono supportate sia le funzioni di sincronizzazione che asincrone:

import os
from agent_framework import InlineSkill, SkillFrontmatter

project_info_skill = InlineSkill(
    frontmatter=SkillFrontmatter(
        name="project-info",
        description="Project status and configuration information",
    ),
    instructions="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)"

Quando l'elemento Decorator viene usato senza argomenti (@skill.resource), il nome della funzione diventa il nome della risorsa e la docstring diventa la descrizione. Usare @skill.resource(name="...", description="...") per impostarli in modo esplicito.

Script definiti dal codice

Usare il decoratore @skill.script per registrare una funzione come script eseguibile in una skill. Gli script definiti dal codice vengono eseguiti in-process e non richiedono uno script runner. Sono supportate sia le funzioni di sincronizzazione che asincrone:

from agent_framework import InlineSkill, SkillFrontmatter

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

Quando l'elemento Decorator viene usato senza argomenti (@skill.script), il nome della funzione diventa il nome dello script e la docstring diventa la descrizione. I parametri tipizzato della funzione vengono convertiti automaticamente in uno schema JSON usato dall'agente per passare argomenti.

Competenze basate su classi

Le competenze basate su classi consentono di aggregare tutti i componenti della competenza, ovvero nome, descrizione, istruzioni, risorse e script, in una singola classe C#. Questo li rende facili da impacchettare e distribuire come pacchetti NuGet: i team possono creare e distribuire le skill in modo indipendente e gli utenti possono aggiungerle con dotnet add package e una singola chiamata a .UseSkill(). Deriva da AgentClassSkill<T> (dove T è la tua classe), quindi annota le proprietà con [AgentSkillResource] e i metodi con [AgentSkillScript] per l'individuazione automatica.

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

Registrare la competenza basata sulla classe con AgentSkillsProvider:

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

Quando l'attributo [AgentSkillResource] viene applicato a una proprietà o a un metodo, il relativo valore restituito viene usato come contenuto della risorsa quando l'agente legge la risorsa. Usare un metodo quando il contenuto deve essere calcolato in fase di lettura. Quando [AgentSkillScript] viene applicato a un metodo, il metodo viene richiamato quando l'agente chiama lo script. Usare [Description] da System.ComponentModel per descrivere ogni risorsa e script per l'agente.

Competenze basate su classi

Le competenze basate su classi consentono di aggregare tutti i componenti della competenza, ovvero nome, descrizione, istruzioni, risorse e script, in una singola classe Python. Questo li rende facili da impacchettare e distribuire come pacchetti PyPI: i team possono creare e distribuire competenze in modo indipendente e gli utilizzatori possono aggiungerli con pip install e una sola chiamata a SkillsProvider(). Crea una sottoclasse di ClassSkill, quindi usa i decoratori @ClassSkill.resource e @ClassSkill.script per il rilevamento automatico:

import json
from textwrap import dedent
from agent_framework import ClassSkill, SkillFrontmatter

class UnitConverterSkill(ClassSkill):
    """A unit-converter skill defined as a Python class."""

    def __init__(self) -> None:
        super().__init__(
            frontmatter=SkillFrontmatter(
                name="unit-converter",
                description=(
                    "Convert between common units using a multiplication factor. "
                    "Use when asked to convert miles, kilometers, pounds, or kilograms."
                ),
            ),
        )

    @property
    def instructions(self) -> str:
        return dedent("""\
            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.
        """)

    @property
    @ClassSkill.resource
    def conversion_table(self) -> str:
        """Lookup table of multiplication factors for common unit conversions."""
        return dedent("""\
            # 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  |
        """)

    @ClassSkill.script(name="convert", description="Multiplies a value by a conversion factor.")
    def convert_units(self, value: float, factor: float) -> str:
        """Convert a value using a multiplication factor."""
        result = round(value * factor, 4)
        return json.dumps({"value": value, "factor": factor, "result": result})

Registrare la competenza basata sulla classe con SkillsProvider:

from agent_framework import SkillsProvider

skill = UnitConverterSkill()
skills_provider = SkillsProvider(skill)

Quando @ClassSkill.resource viene applicato come decoratore senza argomenti, il nome del metodo diventa il nome della risorsa (con i trattini bassi convertiti in trattini) e la docstring diventa la descrizione. Usare @ClassSkill.resource(name="...", description="...") per impostarli in modo esplicito. Lo stesso modello si applica a @ClassSkill.script.

Le risorse possono essere definite come metodi regolari o @property descrittori. Quando si usa @property, posizionare @property per primo e @ClassSkill.resource per secondo. I valori restituiti delle risorse vengono memorizzati nella cache dopo il primo accesso.

Generatore: scenari avanzati con più origini

Per scenari di origine singola semplici, usare direttamente i AgentSkillsProvider costruttori. Usare AgentSkillsProviderBuilder quando è necessario uno dei seguenti elementi:

• Tipi di competenze misti : combinare competenze basate su file, definite dal codice (AgentInlineSkill) e basate su classi (AgentClassSkill) in un singolo provider.
• Filtro delle competenze: includere o escludere competenze usando un predicato.

Tipi di competenze misti

Combinare tutti e tre i tipi di competenza in un provider concatenando UseFileSkill, UseSkille 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();

Filtro delle competenze

Usare UseFilter per includere solo le competenze che soddisfano i criteri, ad esempio per caricare le competenze da una directory condivisa, ma escludere quelle sperimentali:

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

Composizione delle origini: scenari avanzati con origini multiple

Per scenari semplici con una singola competenza o un elenco di competenze, passarli direttamente al SkillsProvider costruttore. Per le competenze basate su file, utilizzare la classe SkillsProvider.from_paths() factory. Per scenari avanzati, comporre classi di origine per controllare l'individuazione, il filtro e la deduplicazione:

• FileSkillsSource - individua le abilità dai file SKILL.md presenti sul disco.
• InMemorySkillsSource - esegue il wrapping di tutte Skill le istanze (definite dal codice o basate su classi) in memoria.
• AggregatingSkillsSource - combina più origini in una.
• FilteringSkillsSource - applica un predicato per includere o escludere le competenze.
• DeduplicatingSkillsSource - rimuove i nomi delle competenze duplicati (senza distinzione tra maiuscole e minuscole; prevale la prima occorrenza).

Tipi di competenze misti

Combinare competenze basate su file, definite dal codice e basate su classi in un provider usando AggregatingSkillsSource. L'esempio seguente usa oggetti segnaposto:

• volume_converter_skill - qualsiasi istanza di InlineSkill, creata come illustrato in Skill definite dal codice.
• TemperatureConverterSkill - qualsiasi ClassSkill sottoclasse, compilata come illustrato in Competenze basate su classi.
• my_runner - un SkillScriptRunner richiamabile, definito come illustrato in Esecuzione dello script.

from pathlib import Path
from agent_framework import (
    AggregatingSkillsSource,
    DeduplicatingSkillsSource,
    FileSkillsSource,
    InMemorySkillsSource,
    SkillsProvider,
)

temperature_converter_skill = TemperatureConverterSkill()

skills_provider = SkillsProvider(
    DeduplicatingSkillsSource(
        AggregatingSkillsSource([
            FileSkillsSource(
                Path(__file__).parent / "skills",
                script_runner=my_runner,
            ),
            InMemorySkillsSource([volume_converter_skill, temperature_converter_skill]),
        ])
    )
)

Filtro delle competenze

Usa FilteringSkillsSource per controllare quali competenze vede l'agente. Il predicato riceve ogni Skill e restituisce True per includerlo. Ad esempio, per caricare le competenze da una directory condivisa ma nasconderne una sperimentale:

from pathlib import Path
from agent_framework import (
    DeduplicatingSkillsSource,
    FileSkillsSource,
    FilteringSkillsSource,
    SkillsProvider,
)

skills_provider = SkillsProvider(
    DeduplicatingSkillsSource(
        FilteringSkillsSource(
            FileSkillsSource(Path(__file__).parent / "skills"),
            predicate=lambda skill: skill.frontmatter.name != "experimental-tools",
        )
    )
)

Usare AgentSkillsProviderOptions.ScriptApproval per controllare tutte le esecuzioni di script previa approvazione umana. Se abilitata, l'agente sospende e restituisce una richiesta di approvazione anziché eseguirlo immediatamente:

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

Per abilitare l'approvazione degli script in un provider configurato dal generatore, usare UseScriptApproval:

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

Usare require_script_approval=True su SkillsProvider per limitare tutte le esecuzioni di script soggette ad approvazione umana. Anziché eseguirlo immediatamente, l'agente sospende e restituisce le richieste di approvazione tramite result.user_input_requests:

from textwrap import dedent
from agent_framework import Agent, InlineSkill, SkillFrontmatter, SkillsProvider

deployment_skill = InlineSkill(
    frontmatter=SkillFrontmatter(
        name="deployment",
        description="Tools for deploying application versions to production",
    ),
    instructions=dedent("""\
        Use this skill when the user asks to deploy an application.
        Run the deploy script with the version and environment parameters.
    """),
)

@deployment_skill.script
def deploy(version: str, environment: str = "staging") -> str:
    """Deploy the application to the specified environment."""
    return f"Deployed version {version} to {environment}"

skills_provider = SkillsProvider(deployment_skill, require_script_approval=True)

async with Agent(
    client=client,
    instructions="You are a deployment assistant.",
    context_providers=[skills_provider],
) as agent:
    # Use a session so the agent retains context across approval round-trips
    session = agent.create_session()

    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)

    print(result)

Quando uno script viene rifiutato (approved=False), l'agente viene informato che l'utente ha rifiutato e può rispondere di conseguenza.

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

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
    instruction_template=(
        "You have skills available. Here they are:\n{skills}\n"
        "{resource_instructions}\n"
        "{runner_instructions}"
    ),
)

Comportamento di memorizzazione nella cache

Per impostazione predefinita, gli strumenti e le istruzioni delle competenze vengono memorizzati nella cache dopo la prima compilazione. Imposta DisableCaching = true su AgentSkillsProviderOptions per forzare una ricompilazione a ogni invocazione:

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

Comportamento di memorizzazione nella cache

Per impostazione predefinita, gli strumenti e le istruzioni delle competenze vengono memorizzati nella cache dopo la prima compilazione. Impostare disable_caching=True per forzare una ricompilazione per ogni chiamata:

skills_provider = SkillsProvider.from_paths(
    skill_paths=Path(__file__).parent / "skills",
    disable_caching=True,
)

disable_caching è disponibile anche nel SkillsProvider costruttore per le competenze definite dal codice e basate su classi.

Le risorse di abilità e i delegati di script possono dichiarare un parametro IServiceProvider che l'Agent Framework inserisce automaticamente. In questo modo, le competenze consentono di risolvere i servizi dell'applicazione, ad esempio i client di database, la configurazione o la logica di business, senza codificarli nella definizione della competenza.

Setup

Registrare i servizi dell'applicazione e passare l'oggetto compilato IServiceProvider all'agente tramite il services parametro :

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

Competenze definite dal codice con inserimento delle dipendenze

Dichiarare IServiceProvider come parametro in AddResource o AddScript delegati: il framework risolve e lo inserisce automaticamente quando l'agente legge una risorsa o esegue uno script:

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

Competenze basate su classi con l'inserimento delle dipendenze

Annotare i metodi con [AgentSkillResource] o [AgentSkillScript] e dichiarare un IServiceProvider parametro: il framework individua questi membri tramite reflection e inserisce automaticamente il provider di servizi:

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

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

Funzioni di risorsa e di script che accettano **kwargs ricevono automaticamente gli argomenti di parole chiave a tempo di esecuzione passati a agent.run(). In questo modo, le funzioni della competenza accedono al contesto dell'applicazione, ad esempio configurazione, identità utente o client del servizio, senza codificarli nella definizione della competenza.

Passaggio di argomenti di runtime

Passare function_invocation_kwargs a agent.run() per fornire argomenti di parole chiave inoltrati dal framework alle funzioni di risorsa e script:

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

Competenze definite nel codice con kwargs

Quando una funzione di risorsa dichiara **kwargs, il framework inoltra gli argomenti della parola chiave di runtime ogni volta che l'agente legge la risorsa:

import os
from typing import Any
from agent_framework import InlineSkill, SkillFrontmatter

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

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

Le funzioni delle risorse senza **kwargs vengono chiamate senza argomenti e non ricevono il contesto di runtime.

Quando una funzione script dichiara **kwargs, il framework inoltra gli argomenti dell'istanza di runtime insieme all'oggetto args fornito dall'agente.

import json
from typing import Any
from agent_framework import InlineSkill, SkillFrontmatter

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

L'agente fornisce value e factor tramite la chiamata argsallo strumento . L'applicazione fornisce precision tramite function_invocation_kwargs. Funzioni script senza **kwargs ricevono solo gli argomenti forniti dall'agente.

Abilità basate su classi con kwargs

I metodi della skill basati su classe possono anche accettare **kwargs per ricevere argomenti di runtime. Il modello funziona allo stesso modo: dichiarare **kwargs nei metodi di risorsa o nei metodi di script:

from typing import Any
from agent_framework import ClassSkill, SkillFrontmatter

class WeightConverterSkill(ClassSkill):
    def __init__(self) -> None:
        super().__init__(
            frontmatter=SkillFrontmatter(
                name="weight-converter",
                description="Convert between weight units (pounds and kilograms).",
            ),
        )

    @property
    def instructions(self) -> str:
        return "Use this skill to convert between pounds and kilograms."

    @ClassSkill.resource(name="weight-table")
    def get_weight_table(self, **kwargs: Any) -> str:
        """Weight conversion factors, scoped to caller context."""
        user_id = kwargs.get("user_id", "anonymous")
        return f"Weight table for {user_id}: | lbs | kg | 0.453592 |"

    @ClassSkill.script(name="convert")
    def convert(self, value: float, factor: float, **kwargs: Any) -> str:
        """Convert a weight value."""
        import json
        precision = kwargs.get("precision", 4)
        result = round(value * factor, precision)
        return json.dumps({"value": value, "factor": factor, "result": result})