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 puntare il provider a una singola directory padre: ogni sottodirectory contenente un SKILL.md oggetto viene individuato automaticamente come competenza:

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;

static async Task<string> RunAsync(AgentSkill skill, AgentSkillScript script, IDictionary<string, object?>? args)
{
    var psi = new ProcessStartInfo("python3")
    {
        RedirectStandardOutput = true,
        UseShellExecute = false,
    };
    psi.ArgumentList.Add(Path.Combine(skill.Path, script.Path));
    if (args != null)
    {
        foreach (var (key, value) in args)
        {
            if (value is not null)
            {
                psi.ArgumentList.Add($"--{key}");
                psi.ArgumentList.Add(value.ToString()!);
            }
        }
    }
    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, passando gli argomenti JSON forniti dall'agente come opzioni della riga di comando.

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 su file

Crea un SkillsProvider puntatore a una directory contenente le competenze e aggiungilo ai provider di contesto dell'agente:

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

Molteplici directory di competenze

È possibile indirizzare il provider a una singola cartella principale: ogni sottocartella contenente un SKILL.md viene individuata automaticamente come abilità.

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

In alternativa, passare un elenco di percorsi per eseguire ricerche in più directory principali.

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

Il provider cerca fino a due livelli di profondità.

Personalizzazione dell'individuazione delle risorse

Per impostazione predefinita, SkillsProvider riconosce le risorse con estensioni .md, , .json.yaml.yml, .csv, .xml, e ..txt Analizza tutte le sottodirectory all'interno di ogni cartella della competenza. Passare resource_extensions per modificare i tipi di file riconosciuti:

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

Esecuzione degli script

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

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

L'esecutore riceve l'oggetto Skill, SkillScript e un dizionario facoltativo args. Gli script basati su file vengono individuati automaticamente dai .py file nelle directory degli 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.

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

Competenza di codice di base

Creare un'istanza Skill con un nome, una descrizione e un contenuto dell'istruzione. Facoltativamente, allegare SkillResource istanze al contenuto statico:

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

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

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 un executor di script. Sono supportate sia le funzioni di sincronizzazione che asincrone:

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

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.

Combinazione di competenze basate su file e definite dal codice

Passa sia skill_paths che skills a un singolo SkillsProvider. Le competenze basate su file vengono individuate per prime; se una competenza definita dal codice ha lo stesso nome di una competenza basata su file esistente, la competenza definita dal codice viene ignorata:

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

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

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

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:

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)

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

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

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

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(). Ciò consente alle funzioni della competenza di accedere al contesto dell'applicazione, ad esempio la configurazione, l'identità utente o i 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"},
)

Funzioni delle risorse 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:

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

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

Funzioni script con kwargs

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

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.