Aracı Becerileri

Aracı Becerileri , aracılara özel özellikler ve etki alanı uzmanlığı sağlayan taşınabilir yönergeler, betikler ve kaynak paketleridir. Beceriler açık belirtimi izler ve aşamalı bir açıklama deseni uygular, böylece aracılar ihtiyaç duyduklarında yalnızca ihtiyaç duydukları bağlamı yükler.

Aşağıdaki durumlarda Aracı Becerileri'ni kullanın:

• Paket etki alanı uzmanlığı — Özel bilgileri (gider ilkeleri, yasal iş akışları, veri analizi işlem hatları) yeniden kullanılabilir, taşınabilir paketler olarak yakalayın.
• Aracı özelliklerini genişletme — Aracılara temel yönergelerini değiştirmeden yeni yetenekler verin.
• Tutarlılığı sağlama — Çok adımlı görevleri yinelenebilir, denetlenebilir iş akışlarına dönüştürün.
• Birlikte çalışabilirliği etkinleştirme — Aynı beceriyi farklı Aracı Becerileri uyumlu ürünlerde yeniden kullanabilirsiniz.

Beceri yapısı

Beceri, kaynaklar için isteğe bağlı alt dizinleri olan bir SKILL.md dosya içeren dizindir:

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 biçimi

Dosyada SKILL.md YAML frontmatter ve ardından markdown içeriği bulunmalıdır:

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

Veri Alanı	Gerekli	Description
name	Evet	En fazla 64 karakter. Yalnızca küçük harfler, sayılar ve kısa çizgiler. Kısa çizgiyle başlamamalı veya bitmemelidir veya ardışık kısa çizgi içermemelidir. Üst dizin adıyla eşleşmelidir.
description	Evet	Becerinin ne yaptığı ve ne zaman kullanılacağı. En fazla 1024 karakter. Aracıların ilgili görevleri tanımlamalarına yardımcı olan anahtar sözcükler içermelidir.
license	Hayı	Paketlenmiş bir lisans dosyasına lisans adı veya başvurusu.
compatibility	Hayı	En fazla 500 karakter. Ortam gereksinimlerini (hedeflenen ürün, sistem paketleri, ağ erişimi vb.) gösterir.
metadata	Hayı	Ek meta veriler için rastgele anahtar-değer eşlemesi.
allowed-tools	Hayı	Becerinin kullanabileceği önceden onaylanan araçların yer sınırlandırılmış listesi. Deneysel — destek aracı uygulamaları arasında farklılık gösterebilir.

Ön maddeden sonraki markdown gövdesi beceri yönergelerini içerir: adım adım yönergeler, giriş ve çıkış örnekleri, yaygın kenar durumları veya aracının görevi gerçekleştirmesine yardımcı olan herhangi bir içerik. SKILL.md 500 satırdan az olacak şekilde tutun ve ayrıntılı başvuru malzemelerini ayrı dosyalara taşıyın.

Aşamalı açıklama

Aracı Becerileri, bağlam kullanımını en aza indirmek için dört aşamalı kademeli bir açıklama modeli kullanır.

1. Tanıtma (beceri başına yaklaşık 100 belirteç) — Beceri adları ve açıklamaları her çalıştırmanın başlangıcında sistem istemine eklenir, böylece aracı hangi becerilerin kullanılabilir olduğunu bilir.
2. Yükle (< 5000 belirteç önerilir) — Bir görev bir becerinin etki alanıyla eşleştiğinde, aracı, ayrıntılı yönergeler içeren tam SKILL.md gövdesini almak için load_skill aracını kullanır.
3. Kaynakları okuma (gerektiği gibi) — Aracı, yalnızca gerektiğinde ek dosyaları (başvurular, şablonlar, varlıklar) getirmek için aracı çağırır read_skill_resource .
4. Betikleri çalıştır (gerektiği gibi) — Aracı, beceriyle birlikte gelen betikleri yürütmek için run_skill_script aracını çağırır.

Bu desen, aracıya isteğe bağlı derin etki alanı bilgilerine erişim sağlarken bağlam penceresinin yalın kalmasını sağlar.

Uyarı

load_skill her zaman reklam edilir. read_skill_resource yalnızca en az bir beceri kaynağı olduğunda tanıtılır. run_skill_script yalnızca en az bir beceride betik olduğunda tanıtılır.

Bir temsilciye beceri sağlama

AgentSkillsProvider (C#) ve SkillsProvider (Python), becerileri aracılar için kullanılabilir hale getiren bağlam sağlayıcılarıdır. Üç beceri kaynağını destekler:

• Dosya tabanlı — dosya sistemi dizinlerindeki dosyalardan SKILL.md bulunan beceriler
• Code-defined — AgentInlineSkill (C#) veya Skill (Python) kullanılarak kodda satır içinde tanımlanan beceriler
• Sınıf tabanlı — öğesinden AgentClassSkill<T> türetilen bir C# sınıfında kapsüllenen beceriler (yalnızca C#

Bir sağlayıcıda birden çok kaynağı karıştırmak için kullanın AgentSkillsProviderBuilder (yalnızca C# — bkz . Oluşturucu: gelişmiş çok kaynaklı senaryolar).

Dosya tabanlı beceriler

Becerilerinizi içeren bir dizine işaret eden bir AgentSkillsProvider dizin oluşturun ve bunu aracının bağlam sağlayıcılarına ekleyin. Beceri dizinlerinde bulunan dosya tabanlı betiklerin yürütülmesini etkinleştirmek için bir betik çalıştırıcısı geçirin:

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

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

Birden çok beceri dizini

Sağlayıcıyı tek bir üst dizine yönlendirebilirsiniz — her bir alt dizin SKILL.md içeriyorsa, otomatik olarak bir beceri olarak tanınır.

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

Veya birden çok kök dizinde arama yapmak için yolların listesini geçirin:

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

Sağlayıcı en fazla iki seviye derinliğine kadar arama yapar.

Kaynak bulmayı özelleştirme

Varsayılan olarak, sağlayıcı, .md, .json, .yaml, .yml, .csv, .xml ve .txt uzantılarına sahip kaynakları references ve assets alt dizinlerinde tanır. Şu varsayılanları değiştirmek için kullanın AgentFileSkillsSourceOptions :

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

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

Betiğin yürütülmesi

Dosya tabanlı betiklerin yürütülmesini etkinleştirmek için SubprocessScriptRunner.RunAsync öğesini ikinci bağımsız değişken olarak AgentSkillsProvider'e geçirin.

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

SubprocessScriptRunner.RunAsync kabaca aşağıdakine eşdeğerdir:

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

Çalıştırıcı, bulunan her betiği yerel bir alt işlem olarak çalıştırır. Dosya tabanlı betikler bağımsız değişkenleri dizelerin JSON dizisi olarak bekler; her dizi öğesi konumsal bir komut satırı bağımsız değişkenine dönüşür.

Uyarı

SubprocessScriptRunner yalnızca tanıtım amacıyla sağlanır. Üretim kullanımı için şunları eklemeyi göz önünde bulundurun:

• Korumalı alan (Sandbox) (örneğin, kapsayıcılar veya yalıtılmış çalışma ortamları)
• Kaynak sınırları (CPU, bellek, duvar saati zaman aşımı)
• Giriş doğrulama ve yürütülebilir betiklerin izin listesi
• Yapılandırılmış günlük kaydı ve denetim izleri

Komut dosyası keşfini özelleştirme

Varsayılan olarak, sağlayıcı .py alt dizininde .js, .sh, .ps1, .cs, .csx ve scripts uzantılarını içeren betikleri tanır. Şu varsayılanları değiştirmek için kullanın AgentFileSkillsSourceOptions :

Oluşturucuya AgentFileSkillsSourceOptions veya oluşturucudaki AgentSkillsProviderUseFileSkill / UseFileSkills geçiriniz:

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

Dosya tabanlı beceriler

Becerilerinizi içeren bir dizine işaret eden bir SkillsProvider dizin oluşturun ve bunu aracının bağlam sağlayıcılarına ekleyin:

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

Birden çok beceri dizini

Sağlayıcıyı tek bir ana klasöre işaret edebilirsiniz; SKILL.md içeren her alt klasör otomatik olarak bir beceri olarak tanımlanır.

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

Veya birden çok kök dizinde arama yapmak için yolların listesini geçirin:

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

Sağlayıcı en fazla iki seviye derinliğine kadar arama yapar.

Kaynak bulmayı özelleştirme

Varsayılan olarak, SkillsProvider , .md.json, .yaml.yml, .csvve .xmluzantılı .txtkaynakları tanır. Her beceri klasöründeki tüm alt dizinleri tarar. Tanınan dosya türlerini değiştirmek için geçirin resource_extensions :

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

Betiğin yürütülmesi

Dosya tabanlı betiklerin yürütülmesini etkinleştirmek için script_runner'yı SkillsProvider'ye geçirin. Protokolü karşılayan herhangi bir senkron veya asenkron çağrılabilir SkillScriptRunner kullanılabilir:

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

Çalıştırıcı, çözümlenen Skill, SkillScript, ve isteğe bağlı args bir sözlüğü alır. Dosya tabanlı betikler, beceri dizinlerindeki .py dosyalardan otomatik olarak tespit edilir.

Uyarı

Yukarıdaki runner sadece gösterim amacıyla sunulmaktadır. Üretim kullanımı için şunları eklemeyi göz önünde bulundurun:

• Sanallaştırma (örneğin, kapsayıcılar, seccomp, veya firejail)
• Kaynak sınırları (CPU, bellek, duvar saati zaman aşımı)
• Giriş doğrulama ve yürütülebilir betiklerin izin listesi
• Yapılandırılmış günlük kaydı ve denetim izleri

Uyarı

Dosya tabanlı beceriler betiklerle sağlanıyorsa ancak script_runner ayarlanmadıysa, SkillsProvider bir ValueError oluşturur.

Kod tanımlı beceriler

Dosya tabanlı becerilere, SKILL.md dosyalarından elde edilenler de dahil olmak üzere, AgentInlineSkill kullanarak kodda becerileri tamamen tanımlayabilirsiniz. Kod tanımlı beceriler aşağıdaki durumlarda kullanışlıdır:

• Beceri içeriği dinamik olarak oluşturulur (örneğin, bir veritabanından veya ortamdan okuma).
• Beceri tanımlarını, bunları kullanan uygulama koduyla birlikte tutmak istiyorsunuz.
• Statik dosyalara hizmet etmek yerine okuma zamanında mantık yürüten kaynaklara ihtiyacınız vardır.

Temel kod becerisi

Ad, açıklama ve yönergeler içeren bir AgentInlineSkill oluşturun. Kaynakları .AddResource() kullanarak ekleme:

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

Dinamik kaynaklar

Çalışma zamanında içeriği hesaplamak için .AddResource()'a bir fabrika vekili geçirin. Temsilci, aracı kaynağı her okuduğunda çağrılır:

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

Kod tanımlı betikler

.AddScript() bir temsilciyi yürütülebilir bir script olarak kaydetmek için kullanın. Kod tanımlı betikler, doğrudan temsilci çağrıları olarak aynı işlem içinde çalışır. Betik çalıştırıcısı gerekmiyor. Temsilcinin türü belirtilen parametreleri, aracının bağımsız değişkenleri geçirmek için kullandığı bir JSON Şemasına otomatik olarak dönüştürülür:

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

Uyarı

Kod tanımlı becerileri tek bir sağlayıcıda dosya tabanlı veya sınıf tabanlı becerilerle birleştirmek için AgentSkillsProviderBuilder kullanın — bkz: Oluşturucu: gelişmiş çok kaynaklı senaryolar.

SKILL.md dosyalarından bulunan dosya tabanlı becerilere ek olarak, becerileri tamamen Python kodda tanımlayabilirsiniz. Kod tanımlı beceriler aşağıdaki durumlarda kullanışlıdır:

• Beceri içeriği dinamik olarak oluşturulur (örneğin, bir veritabanından veya ortamdan okuma).
• Beceri tanımlarını, bunları kullanan uygulama koduyla birlikte tutmak istiyorsunuz.
• Statik dosyalara hizmet etmek yerine okuma zamanında mantık yürüten kaynaklara ihtiyacınız vardır.

Temel kod becerisi

Skill Ad, açıklama ve yönerge içeriğine sahip bir örnek oluşturun. İsteğe bağlı olarak statik içeriğe sahip örnekler ekleyin SkillResource :

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

Dinamik kaynaklar

İşlevi bir kaynak olarak kaydetmek için @skill.resource dekoratörünü kullanın. İşlev, aracı her seferinde kaynağı okuduğunda çağrılır, bu sayede güncel verileri döndürebilir. Senkron ve asenkron fonksiyonlar desteklenir.

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

Dekoratör bağımsız değişken olmadan kullanıldığında ()@skill.resource işlev adı kaynak adı, docstring ise açıklama olur. Bunları açıkça ayarlamak için kullanın @skill.resource(name="...", description="...") .

Kod tanımlı betikler

@skill.script dekoratörü kullanarak bir işlevi, bir beceri üzerinde yürütülebilir bir betik olarak kaydedin. Kod tanımlı betikler işlem içinde çalışır ve bir betik yürütücüsü gerektirmez. Senkron ve asenkron fonksiyonlar desteklenir.

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

Dekoratör, bağımsız değişken olmadan (@skill.script) kullanıldığında, işlev adı betik adı, docstring ise açıklama olur. İşlevin yazılan parametreleri otomatik olarak aracının bağımsız değişkenleri geçirmek için kullandığı bir JSON Şemasına dönüştürülür.

Dosya tabanlı ve kod tanımlı becerileri birleştirme

hem skill_paths hem de skills öğesini tek SkillsProvider öğesine geçirin. Önce dosya tabanlı beceriler keşfedilir; eğer kod tanımlı bir beceri, önceden mevcut bir dosya tabanlı beceriyle aynı ada sahipse, kod tanımlı beceri atlanır.

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

Sınıf tabanlı beceriler

Sınıf tabanlı beceriler, ad, açıklama, yönergeler, kaynaklar ve betikler gibi tüm beceri bileşenlerini tek bir C# sınıfında paketlemenizi sağlar. AgentClassSkill<T> öğesinden türetin (sizin sınıfınız T olduğunda), ardından otomatik keşif için özelliklere [AgentSkillResource] ve yöntemlere [AgentSkillScript] ile açıklama ekleyin.

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

Sınıf tabanlı beceriyi AgentSkillsProvider ile kaydedin:

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

[AgentSkillResource] Öznitelik bir özelliğe veya yönteme uygulandığında, dönüş değeri aracı kaynağı okurken kaynak içeriği olarak kullanılır; içeriğin okuma zamanında hesaplanması gerektiğinde bir yöntem kullanın. [AgentSkillScript] bir metoda uygulandığında, aracı betiği çağırdığında yöntem çağrılır. Her bir kaynağı ve scripti tanımlamak için [Description] öğesini System.ComponentModel kullanın.

Uyarı

AgentClassSkill<T> ayrıca öznitelik tabanlı bulmanın uymadığı durumlar için Resources ve Scripts'yi koleksiyonlar olarak geçersiz kılmayı destekler.

Oluşturucu: gelişmiş çok kaynaklı senaryolar

Basit, tek kaynaklı senaryolar için oluşturucuları doğrudan kullanın AgentSkillsProvider . Aşağıdakilerden herhangi birine ihtiyacınız olduğunda kullanın AgentSkillsProviderBuilder :

• Karma beceri türleri — dosya tabanlı, kod tanımlı (AgentInlineSkill) ve sınıf tabanlı (AgentClassSkill) becerileri tek bir sağlayıcıda birleştirir.
• Beceri filtreleme — koşul kullanarak becerileri dahil etme veya dışlama.

Karma beceri türleri

, UseFileSkillve UseSkillzincirlerini bağlayarak UseFileScriptRunnerüç beceri türünü de tek bir sağlayıcıda birleştirin:

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

Beceri filtreleme

Yalnızca ölçütlerinize uyan becerileri dahil etmek için kullanın UseFilter ; örneğin paylaşılan bir dizinden beceri yüklemek ancak deneysel olanları hariç tutmak için:

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

Betik onayı

Tüm betik yürütmesini insan onayı ile kontrol altına almak için AgentSkillsProviderOptions.ScriptApproval kullanın. Etkinleştirildiğinde, o an uygulamayı durdurur ve hemen yürütmek yerine bir onay isteği gönderir.

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

Oluşturucu tarafından yapılandırılmış bir sağlayıcıda betik onayını etkinleştirmek için kullanın UseScriptApproval:

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

require_script_approval=True üzerinde SkillsProvider kullanarak tüm betik yürütmesini insan onayının arkasına alın. Aracı hemen yürütmek yerine duraklatılır ve onay isteklerini döndürür:

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)

Bir betik reddedildiğinde (approved=False ), aracıya kullanıcının reddettiği ve buna göre yanıt verebildiği bildirilir.

Özel sistem istemi

Varsayılan olarak, beceri sağlayıcısı kullanılabilir becerileri listeleyen bir sistem istemi ekler ve aracıya load_skill ve read_skill_resource kullanmasını ister. Bu istemi özelleştirebilirsiniz:

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

Uyarı

Özel şablonda {skills} (beceri listesi), {resource_instructions} (kaynak aracı ipucu) ve {script_instructions} (betik aracı ipucu) yer tutucuları bulunmalıdır. Değişmez köşeli ayraçlar {{ ve }} olarak kaçınılmalıdır.

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

Uyarı

Özel şablon, beceri listesinin eklendiği bir {skills} yer tutucu ve betikle ilgili yönergelerin eklendiği bir {runner_instructions} yer tutucu içermelidir.

Önbelleğe alma davranışı

Beceri araçları ve yönergeler varsayılan olarak ilk derlemeden sonra önbelleğe alınır. Her çağrıda zorunlu yeniden derleme için DisableCaching = true üzerinde AgentSkillsProviderOptions ayarlayın:

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

Uyarı

Beceri içeriği sık sık değiştiğinde geliştirme sırasında önbelleğe almayı devre dışı bırakmak yararlıdır. Üretimde, daha iyi performans için önbelleğe almayı etkin (varsayılan) bırakın.

Bağımlılık enjeksiyonu

Beceri kaynağı ve betik temsilcileri, Agent Framework'ün otomatik olarak enjekte ettiği bir IServiceProvider parametresini tanımlayabilir. Bu, becerilerin veritabanı istemcileri, yapılandırma veya iş mantığı gibi uygulama hizmetlerini beceri tanımına sabit kodlamadan çözmesine olanak tanır.

Kurulum

Uygulama hizmetlerinizi kaydedin ve aracıya IServiceProvider parametresi aracılığıyla derlenmiş services değerini geçirin.

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

DI ile kod tanımlı beceriler

IServiceProvider'yi AddResource veya AddScript temsilcilerinde bir parametre olarak bildir — aracı bir kaynağı okuduğunda veya bir betik çalıştırdığında çerçeve otomatik olarak çözümler ve ekler:

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

DI ile sınıf tabanlı beceriler

[AgentSkillResource] veya [AgentSkillScript] ile yöntemleri açıklayın ve bir IServiceProvider parametresi bildirin - çerçeve, yansıma yoluyla bu üyeleri bulur ve hizmet sağlayıcısını otomatik olarak ekler:

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

Tip

Sınıf tabanlı beceriler, bağımlılıkları oluşturucuları aracılığıyla da çözebilir. 'de ServiceCollection beceri sınıfını kaydedin ve doğrudan çağırmak new yerine kapsayıcıdan çözümleyin:

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

Beceri sınıfının, kaynak ve betik temsilcileri tarafından kullanılanların ötesinde enjekte edilen hizmetlere ihtiyaç duyduğunda bu, kullanışlıdır.

kabul eden **kwargs kaynak ve betik işlevleri, öğesine agent.run()geçirilen çalışma zamanı anahtar sözcüğü bağımsız değişkenlerini otomatik olarak alır. Bu, beceri işlevlerinin yapılandırma, kullanıcı kimliği veya hizmet istemcileri gibi uygulama bağlamını beceri tanımına sabit kodlamadan erişmesini sağlar.

Çalışma zamanı bağımsız değişkenlerini geçirme

function_invocation_kwargs'u agent.run()'e sağlayın, böylece çerçeve bunları kaynak ve betik işlevlerine anahtar sözcük bağımsız değişkenleri olarak iletebilir.

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

Kwargs ile kaynak işlevleri

Bir kaynak işlevi **kwargs bildirdiğinde, aracı kaynağı her okuduğunda çerçeve, çalışma zamanı sırasındaki anahtar kelime bağımsız değişkenlerini iletir.

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

**kwargs olmayan kaynak işlevleri, bağımsız değişken olmadan çağrılır ve çalışma zamanı bağlamı almaz.

Kwargs ile betik işlevleri

Bir betik işlevi **kwargs bildirdiğinde, çerçeve, çalışma zamanı anahtar sözcüğü bağımsız değişkenlerini, aracı tarafından sağlanan args ile birlikte iletir.

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

Aracı, value ve factorargs araç çağrısı aracılığıyla sağlar; uygulama ise precisionfunction_invocation_kwargs aracılığıyla sağlar. **kwargs olmadan betik işlevleri yalnızca aracı tarafından sağlanan bağımsız değişkenleri alır.

En iyi güvenlik uygulamaları

Aracı Becerileri, projenize getirdiğiniz herhangi bir üçüncü taraf kodu gibi ele alınmalıdır. Beceri yönergeleri aracının bağlamlarına eklendiğinden ve beceriler betikler içerebileceğinden, açık kaynak bağımlılığına uygulayacağınız aynı gözden geçirme ve idare düzeyini uygulamak çok önemlidir.

• Kullanmadan önce gözden geçirme — Dağıtmadan önce tüm beceri içeriğini (SKILL.md, betikleri ve kaynakları) okuyun. Komut dosyasının gerçek davranışının belirtilen amacıyla eşleştiğini doğrulayın. Güvenlik yönergelerini atlamaya, verileri dışarı aktarmaya veya aracı yapılandırma dosyalarını değiştirmeye çalışan saldırgan yönergeleri denetleyin.
• Kaynak güveni — Yalnızca güvenilen yazarların veya araştırılan iç katkıda bulunanların becerilerini yükleyin. Net kanıtlanmışlık, sürüm denetimi ve etkin bakım özelliklerine sahip becerileri tercih edin. Popüler paketlerin adlarını taklit ederek onları yanıltıcı şekilde kullanan sahte beceri adlarına dikkat edin.
• Sandboxing — Yürütülebilir betikler içeren becerileri yalıtılmış ortamlarda çalıştırın. Dosya sistemi, ağ ve sistem düzeyinde erişimi yalnızca becerinin gerektirdiğiyle sınırlayın. Hassas olabilecek işlemleri yürütmeden önce açık kullanıcı onayı gerektir.
• Denetim ve günlüğe kaydetme — Hangi becerilerin yüklendiğini, hangi kaynakların okunduğunu ve hangi betiklerin çalıştırıldığını kaydedin. Bu, bir sorun olması durumunda aracı davranışını belirli beceri içeriğine geri izlemeniz için bir denetim izi sağlar.

Becerilerin ve iş akışlarının ne zaman kullanılacağı

Aracı Becerileri ve Aracı Çerçevesi İş Akışları, aracıların yapabileceklerini genişletir, ancak temelde farklı şekillerde çalışır. Gereksinimlerinize en uygun yaklaşımı seçin:

• Denetim — Yapay zeka, bir beceriyle yönergelerin nasıl yürütüleceğine karar verir. Bu, aracının yaratıcı veya uyarlamalı olmasını istediğinizde idealdir. bir iş akışıyla, yürütme yolunu açıkça tanımlarsınız. Belirlenimci ve öngörülebilir davranışlara ihtiyaç duyduğunuzda iş akışlarını kullanın.
• Dayanıklılık — Beceri, tek bir ajan turunda çalışır. Bir şey başarısız olursa tüm işlem yeniden denenmelidir. İş akışları denetim noktası oluşturmayı desteklediğinden, hatadan sonraki son başarılı adımdan devam edebilir. İşlemin tamamını yeniden yürütme maliyeti yüksek olduğunda iş akışlarını seçin.
• Yan etkiler — İşlemler etkili veya düşük riskli olduğunda beceriler uygundur. Adımlar tekrar edilmemesi gereken yan etkiler (e-posta gönderme, ödeme alma) oluşturduğunda iş akışlarını tercih edin.
• Karmaşıklık — Beceriler, bir ajanın işleyebileceği odaklanmış, tek alan odaklı görevler için en iyisidir. İş akışları birden çok aracıyı, insan onayını veya dış sistem tümleştirmesini koordine eden çok adımlı iş süreçleri için daha uygundur.

Tip

Temel bir kural olarak: Yapay zekanın bir görevi nasıl yerine getirdiğini anlanmasını istiyorsanız bir beceri kullanın. Hangi adımların ve hangi sırayla yürütüleceklerini garanti etmeniz gerekiyorsa bir iş akışı kullanın.

Sonraki Adımlar

CodeAct

İlgili içerik

• Temsilci Becerileri Belirtilmesi
• CodeAct
• Bağlam Sağlayıcıları
• Çalışan Ajanlar
• Araçlara Genel Bakış