Keterampilan Agen

Keterampilan Agen adalah paket petunjuk, skrip, dan sumber daya portabel yang memberi agen kemampuan khusus dan keahlian domain. Keterampilan mengikuti spesifikasi terbuka dan menerapkan pola pengungkapan progresif sehingga agen hanya memuat konteks yang mereka butuhkan, ketika mereka membutuhkannya.

Gunakan Keterampilan Agen saat Anda ingin:

• Keahlian domain dalam bentuk paket — Memanfaatkan pengetahuan khusus (kebijakan pengeluaran, alur kerja hukum, alur analisis data) dalam paket portabel yang dapat digunakan kembali.
• Perluas kemampuan agen — Berikan agen kemampuan baru tanpa mengubah instruksi inti mereka.
• Pastikan konsistensi — Ubah tugas multi-langkah menjadi alur kerja yang dapat diaudit berulang.
• Aktifkan interoperabilitas — Gunakan kembali keterampilan yang sama di berbagai produk yang kompatibel dengan Keterampilan Agen.

Struktur keterampilan

Keterampilan adalah direktori yang SKILL.md berisi file dengan subdirektori opsional untuk sumber daya:

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

format SKILL.md

File SKILL.md harus berisi frontmatter YAML diikuti dengan konten markdown:

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

Bidang	Diperlukan	Deskripsi
name	Yes	Maksimal 64 karakter. Huruf kecil, angka, dan tanda hubung saja. Tidak boleh dimulai atau diakhir dengan tanda hubung atau berisi tanda hubung berturut-turut. Harus cocok dengan nama direktori induk.
description	Yes	Apa fungsi keterampilan ini dan kapan harus digunakan. Maksimal 1024 karakter. Harus menyertakan kata kunci yang membantu agen mengidentifikasi tugas yang relevan.
license	Tidak.	Nama lisensi atau referensi ke file lisensi yang dibundel.
compatibility	Tidak.	Maksimal 500 karakter. Menunjukkan persyaratan lingkungan (produk yang dimaksudkan, paket sistem, akses jaringan, dll.).
metadata	Tidak.	Pemetaan nilai kunci arbitrer untuk metadata tambahan.
allowed-tools	Tidak.	Daftar alat yang dipisahkan oleh spasi yang telah disetujui sebelumnya yang dapat digunakan kemampuan. Eksperimental — dukungan antar implementasi agen dapat bervariasi.

Isi markdown setelah frontmatter berisi instruksi keterampilan — panduan langkah demi langkah, contoh input dan output, kasus tepi umum, atau konten apa pun yang membantu agen melakukan tugas. Simpan SKILL.md di bawah 500 baris dan pindahkan materi referensi terperinci ke file terpisah.

Pengungkapan progresif

Keterampilan Agen menggunakan pola pengungkapan progresif empat tahap untuk meminimalkan penggunaan konteks:

1. Iklankan (~100 token per keterampilan) — Nama dan deskripsi keterampilan disuntikkan ke dalam prompt sistem di awal setiap eksekusi, sehingga agen tahu keterampilan apa yang tersedia.
2. Muat (< 5000 token yang direkomendasikan) — Ketika suatu tugas cocok dengan domain keterampilan, agen memanggil load_skill alat untuk mengambil isi SKILL.md lengkap dengan instruksi terperinci.
3. Membaca sumber daya (sesuai kebutuhan) — Agen memanggil read_skill_resource alat untuk mengambil file tambahan (referensi, templat, aset) hanya jika diperlukan.
4. Jalankan skrip (sesuai kebutuhan) — Agen perangkat lunak memanggil run_skill_script perangkat untuk menjalankan skrip yang dibundel dengan fungsi.

Pola ini membuat jendela konteks agen tetap ramping sambil memberinya akses ke pengetahuan domain yang mendalam sesuai permintaan.

Nota

load_skill selalu diiklankan. read_skill_resource hanya diiklankan ketika setidaknya satu keterampilan memiliki sumber daya. run_skill_script hanya diiklankan ketika setidaknya satu kemampuan menggunakan skrip.

Memberikan keterampilan kepada agen

AgentSkillsProvider (C#) dan SkillsProvider (Python) adalah penyedia konteks yang menyediakan keterampilan bagi agen. Mereka mendukung tiga sumber keterampilan:

• Berbasis file — keterampilan yang terdeteksi dari SKILL.md file pada direktori sistem file
• Didefinisikan oleh Kode — keterampilan yang ditentukan sebaris dalam kode menggunakan AgentInlineSkill (C#) atau Skill (Python)
• Berbasis kelas — keterampilan yang dirangkum dalam kelas C# yang berasal dari AgentClassSkill<T> (hanya C#)

Untuk mencampur beberapa sumber dalam satu penyedia, gunakan AgentSkillsProviderBuilder (hanya C# — lihat Builder: skenario multi-sumber tingkat lanjut).

Keterampilan berbasis file

Buat penunjuk AgentSkillsProvider ke direktori yang berisi keterampilan Anda, dan tambahkan ke konteks penyedia agen. Berikan runner skrip untuk mengaktifkan eksekusi skrip berbasis file yang ditemukan di direktori skill.

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

Peringatan

DefaultAzureCredential nyaman untuk pengembangan tetapi membutuhkan pertimbangan yang cermat dalam produksi. Dalam produksi, pertimbangkan untuk menggunakan kredensial tertentu (misalnya, ManagedIdentityCredential) untuk menghindari masalah latensi, pemeriksaan kredensial yang tidak diinginkan, dan potensi risiko keamanan dari mekanisme fallback.

Beberapa direktori keterampilan

Anda dapat mengarahkan penyedia ke satu direktori induk — setiap subdirektori yang SKILL.md berisi secara otomatis ditemukan sebagai keterampilan:

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

Atau berikan daftar jalur untuk mencari beberapa direktori akar:

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

Penyedia mencari hingga dua tingkat dalam.

Menyesuaikan penemuan sumber daya

Secara default, penyedia mengenali sumber daya dengan ekstensi .md, , .json, .yaml, .yml.csv, .xml, dan .txt di references dan assets subdirektori. Gunakan AgentFileSkillsSourceOptions untuk mengubah default ini:

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

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

Pelaksanaan Skrip

Teruskan SubprocessScriptRunner.RunAsync sebagai argumen kedua untuk AgentSkillsProvider untuk mengaktifkan eksekusi skrip berbasis file:

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

SubprocessScriptRunner.RunAsync kira-kira setara dengan yang berikut:

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

Runner menjalankan setiap skrip yang ditemukan sebagai subproses lokal. Skrip berbasis file mengharapkan argumen dalam bentuk array string JSON — setiap elemen array menjadi argumen posisi di baris perintah.

Peringatan

SubprocessScriptRunner disediakan hanya untuk tujuan demonstrasi. Untuk penggunaan produksi, pertimbangkan untuk menambahkan:

• Sandboxing (misalnya, kontainer atau lingkungan eksekusi terisolasi)
• Batas sumber daya (CPU, memori, batas waktu jam dinding)
• Validasi input dan daftar izin skrip yang dapat dieksekusi
• Jejak pengelogan dan audit terstruktur

Menyesuaikan penemuan skrip

Secara default, penyedia mengenali skrip dengan ekstensi .py, , .js, .sh.ps1, .cs, dan .csx di scripts subdirektori. Gunakan AgentFileSkillsSourceOptions untuk mengubah default ini:

Teruskan AgentFileSkillsSourceOptions ke AgentSkillsProvider konstruktor atau ke UseFileSkill / UseFileSkills pada pembangun:

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

Keterampilan berbasis file

Buat SkillsProvider penunjuk ke direktori yang berisi keterampilan Anda, dan tambahkan ke penyedia konteks agen:

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

Beberapa direktori keterampilan

Anda dapat mengarahkan penyedia ke satu folder induk — setiap subfolder yang berisi SKILL.md secara otomatis ditemukan sebagai keahlian.

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

Atau berikan daftar jalur untuk mencari beberapa direktori akar:

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

Penyedia mencari hingga dua tingkat dalam.

Menyesuaikan penemuan sumber daya

Secara default, SkillsProvider mengenali sumber daya dengan ekstensi .md, , .json, .yaml.yml, .csv, .xml, dan .txt. Ini memindai semua subdirektori dalam setiap folder keterampilan. Gunakan resource_extensions untuk mengubah tipe file yang dikenali.

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

Pelaksanaan Skrip

Untuk mengaktifkan eksekusi skrip berbasis file, teruskan script_runner ke SkillsProvider. Setiap pemanggilan sinkron atau asinkron yang memenuhi protokol SkillScriptRunner dapat digunakan.

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

Pelari menerima Skill, SkillScript, dan args daftar istilah opsional yang telah diurai. Skrip-skrip berbasis file secara otomatis ditemukan dari .py file dalam direktori skill.

Peringatan

Pelari di atas disediakan hanya untuk tujuan demonstrasi. Untuk penggunaan produksi, pertimbangkan untuk menambahkan:

• Sandboxing (misalnya, kontainer, seccomp, atau firejail)
• Batas sumber daya (CPU, memori, batas waktu jam dinding)
• Validasi input dan daftar izin skrip yang dapat dieksekusi
• Jejak pengelogan dan audit terstruktur

Nota

Jika keterampilan berbasis file dengan skrip disediakan tetapi script_runner tidak diatur, SkillsProvider menimbulkan ValueError.

Keterampilan berbasis kode

Selain keterampilan berbasis file yang ditemukan dari SKILL.md file, Anda dapat menentukan keterampilan sepenuhnya dalam kode menggunakan AgentInlineSkill. Keterampilan yang ditentukan kode berguna ketika:

• Konten keterampilan dihasilkan secara dinamis (misalnya, membaca dari database atau lingkungan).
• Anda ingin menyimpan definisi keterampilan bersama kode aplikasi yang menggunakannya.
• Anda memerlukan sumber daya yang menjalankan logika pada waktu baca daripada melayani file statis.

Keterampilan kode dasar

Buat sebuah AgentInlineSkill dengan nama, deskripsi, dan instruksi. Lampirkan sumber daya menggunakan .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);

Sumber daya dinamis

Lewatkan delegasi pabrik ke .AddResource() untuk menghitung konten pada saat runtime. Delegasi dipanggil setiap kali agen membaca sumber daya:

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

Skrip yang ditentukan oleh kode

Gunakan .AddScript() untuk mendaftarkan delegasi sebagai skrip yang dapat dieksekusi. Skrip yang diatur oleh kode berjalan secara in-process sebagai panggilan delegasi langsung. Tidak diperlukan pelaksana skrip. Parameter yang diketik delegasi secara otomatis dikonversi menjadi Skema JSON yang digunakan agen untuk meneruskan argumen:

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

Nota

Untuk menggabungkan keterampilan yang ditentukan kode dengan keterampilan berbasis file atau berbasis kelas dalam satu penyedia, gunakan AgentSkillsProviderBuilder — lihat Builder: skenario multi-sumber tingkat lanjut.

Selain keterampilan berbasis file yang ditemukan dari file SKILL.md, Anda dapat menentukan keterampilan sepenuhnya dalam kode Python. Keterampilan yang ditentukan kode berguna ketika:

• Konten keterampilan dihasilkan secara dinamis (misalnya, membaca dari database atau lingkungan).
• Anda ingin menyimpan definisi keterampilan bersama kode aplikasi yang menggunakannya.
• Anda memerlukan sumber daya yang menjalankan logika pada waktu baca daripada melayani file statis.

Keterampilan kode dasar

Buat Skill instans dengan nama, deskripsi, dan konten instruksi. Opsional, lampirkan instans SkillResource dengan konten statis.

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

Sumber daya dinamis

Gunakan dekorator @skill.resource untuk mendaftarkan fungsi sebagai sumber daya. Fungsi ini dipanggil setiap kali agen membaca sumber daya, sehingga dapat mengembalikan data up-to-date. Fungsi sinkronisasi dan asinkron didukung:

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

Ketika dekorator digunakan tanpa argumen (@skill.resource), nama fungsi menjadi nama sumber daya dan docstring menjadi deskripsi. Gunakan @skill.resource(name="...", description="...") untuk mengaturnya secara eksplisit.

Skrip yang ditentukan oleh kode

Gunakan dekorator @skill.script untuk mendaftarkan fungsi sebagai skrip yang dapat dieksekusi pada fitur tersebut. Skrip yang didefinisikan oleh kode berjalan dalam proses dan tidak memerlukan eksekutor skrip. Fungsi sinkronisasi dan asinkron didukung:

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

Ketika dekorator digunakan tanpa argumen (@skill.script), nama fungsi menjadi nama skrip dan docstring menjadi deskripsi. Parameter yang diketik fungsi secara otomatis dikonversi menjadi Skema JSON yang digunakan agen untuk meneruskan argumen.

Menggabungkan keterampilan berbasis file dan didefinisikan oleh kode

Teruskan baik skill_paths dan skills ke satu SkillsProvider. Keterampilan berbasis file ditemukan terlebih dahulu; jika keterampilan yang ditentukan kode memiliki nama yang sama dengan keterampilan berbasis file yang ada, keterampilan yang ditentukan kode dilewati:

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

Keterampilan berbasis kelas

Keterampilan berbasis kelas memungkinkan Anda menggabungkan semua komponen keterampilan — nama, deskripsi, instruksi, sumber daya, dan skrip — ke dalam satu kelas C#. Berasal dari AgentClassSkill<T> (di mana T adalah kelas Anda), lalu anotasi properti dengan [AgentSkillResource] dan metode dengan [AgentSkillScript] untuk penemuan otomatis.

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

Daftarkan keterampilan berbasis kelas dengan AgentSkillsProvider:

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

[AgentSkillResource] Ketika atribut diterapkan ke properti atau metode, nilai pengembaliannya digunakan sebagai konten sumber daya saat agen membaca sumber daya — gunakan metode ketika konten perlu dihitung pada waktu baca. Ketika [AgentSkillScript] diterapkan ke metode, metode dipanggil ketika agen memanggil skrip. Gunakan [Description] dari System.ComponentModel untuk menjelaskan setiap sumber daya dan skrip untuk agen.

Nota

AgentClassSkill<T> juga mendukung menggantikan Resources dan Scripts sebagai koleksi untuk skenario di mana penemuan berbasis atribut tidak cocok.

Pembuat: skenario multi-sumber tingkat lanjut

Untuk skenario sumber tunggal yang sederhana, gunakan langsung konstruktor AgentSkillsProvider. Gunakan AgentSkillsProviderBuilder saat Anda memerlukan salah satu hal berikut:

• Jenis keterampilan campuran — menggabungkan keterampilan berbasis file, yang ditentukan kode (AgentInlineSkill), dan berbasis kelas (AgentClassSkill) dalam satu penyedia.
• Pemfilteran keterampilan — menyertakan atau mengecualikan keterampilan menggunakan predikat.

Jenis keterampilan campuran

Gabungkan ketiga jenis keterampilan dalam satu penyedia dengan menautkan UseFileSkill, , UseSkilldan 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();

Penyaringan keterampilan

Gunakan UseFilter untuk hanya menyertakan keterampilan yang memenuhi kriteria Anda — misalnya, untuk memuat keterampilan dari direktori bersama tetapi mengecualikan yang eksperimental:

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

Persetujuan skrip

Gunakan AgentSkillsProviderOptions.ScriptApproval untuk mengendalikan semua eksekusi skrip agar berada di bawah persetujuan manusia. Saat diaktifkan, agen menjeda proses dan mengembalikan permintaan persetujuan alih-alih langsung mengeksekusi.

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

Untuk mengaktifkan persetujuan skrip pada penyedia yang dikonfigurasi pembuat, gunakan UseScriptApproval:

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

Gunakan require_script_approval=True pada SkillsProvider untuk mengontrol semua eksekusi skrip di balik persetujuan manusia. Alih-alih segera dieksekusi, agen menjeda dan mengembalikan permintaan persetujuan:

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)

Ketika skrip ditolak (approved=False), agen diberi tahu bahwa pengguna menolak dan dapat merespons dengan sesuai.

Prompt sistem kustom

Secara default, penyedia keterampilan menyuntikkan permintaan sistem yang mencantumkan keterampilan yang tersedia dan menginstruksikan agen untuk menggunakan load_skill dan read_skill_resource. Anda dapat menyesuaikan perintah ini:

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

Nota

Templat kustom harus berisi tempat penampung {skills} (daftar keterampilan), {resource_instructions} (petunjuk alat sumber daya), dan {script_instructions} (petunjuk alat skrip). Kurung kurawal literal harus di-escape sebagai {{ dan }}.

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

Nota

Templat kustom harus berisi {skills} tempat penampung tempat daftar keterampilan dimasukkan dan {runner_instructions} tempat penampung tempat instruksi terkait skrip disisipkan.

Perilaku cache

Secara default, alat keterampilan dan instruksi di-cache setelah build pertama. Atur DisableCaching = trueAgentSkillsProviderOptions untuk memaksa pembangunan ulang pada setiap pemanggilan:

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

Nota

Menonaktifkan cache berguna selama pengembangan ketika konten skill sering berubah. Dalam produksi, pertahankan pencaching diaktifkan sebagai pengaturan default untuk kinerja yang lebih baik.

Injeksi Ketergantungan

Sumber daya keterampilan dan delegasi skrip dapat mendeklarasikan parameter IServiceProvider yang secara otomatis disuntikkan oleh Kerangka Kerja Agen. Hal ini memungkinkan keterampilan menyelesaikan layanan aplikasi — seperti klien database, konfigurasi, atau logika bisnis — tanpa mengodekan secara permanen ke dalam definisi keterampilan.

Siapkan

Daftarkan layanan aplikasi Anda dan teruskan hasil kompilasi IServiceProvider ke agen melalui parameter services:

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

Keterampilan yang ditentukan kode dengan DI

Nyatakan IServiceProvider sebagai parameter dalam AddResource atau AddScript delegasi — kerangka kerja menyelesaikan dan menyuntikkannya secara otomatis saat agen membaca sumber daya atau menjalankan skrip:

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

Keterampilan berbasis kelas dengan DI

Anotasi metode dengan [AgentSkillResource] atau [AgentSkillScript] dan deklarasikan IServiceProvider parameter — kerangka kerja menemukan anggota ini melalui pantulan dan menyuntikkan penyedia layanan secara otomatis:

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

Keterampilan berbasis kelas juga dapat menyelesaikan dependensi melalui konstruktornya. Daftarkan kelas kemampuan di ServiceCollection dan panggil dari kontainer alih-alih memanggil new secara langsung:

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

Ini berguna ketika kelas keterampilan itu sendiri membutuhkan layanan yang disuntikkan di luar apa yang digunakan oleh delegasi sumber daya dan skrip.

Fungsi sumber daya dan skrip yang menerima **kwargs secara otomatis menerima argumen kata kunci runtime yang diteruskan ke agent.run(). Ini memungkinkan fungsi keterampilan mengakses konteks aplikasi — seperti konfigurasi, identitas pengguna, atau klien layanan — tanpa mengkodekannya secara permanen ke dalam definisi keterampilan.

Meneruskan argumen runtime

Teruskan function_invocation_kwargs ke agent.run() untuk menyediakan argumen kata kunci yang diteruskan kerangka kerja ke fungsi sumber daya dan skrip:

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

Fungsi sumber daya dengan kwargs

Ketika fungsi sumber daya mendeklarasikan **kwargs, kerangka kerja meneruskan argumen kata kunci runtime setiap kali agen membaca sumber daya:

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

Fungsi sumber daya tanpa **kwargs dipanggil tanpa argumen dan tidak menerima konteks runtime.

Fungsi skrip dengan kwargs

Ketika fungsi skrip mendeklarasikan **kwargs, kerangka kerja meneruskan argumen kata kunci runtime bersama args yang disediakan oleh agen:

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

Agen menyediakan value dan factor melalui panggilan alat args; aplikasi menyediakan precision melalui function_invocation_kwargs. Fungsi skrip tanpa **kwargs hanya menerima argumen yang disediakan agen.

Praktik terbaik keamanan

Keterampilan Agen harus diperlakukan seperti kode pihak ketiga yang Anda bawa ke dalam proyek Anda. Karena instruksi keterampilan disuntikkan ke dalam konteks agen — yang dapat mencakup skrip — menerapkan tingkat peninjauan dan tata kelola yang sama seperti yang Anda terapkan pada dependensi sumber terbuka sangat penting.

• Tinjau sebelum digunakan — Baca semua konten keterampilan (SKILL.md, skrip, dan sumber daya) sebelum menyebarkan. Verifikasi bahwa perilaku aktual skrip cocok dengan niat yang dinyatakan. Periksa instruksi adversarial yang mencoba melewati pedoman keselamatan, menyelundupkan data, atau memodifikasi file konfigurasi agen.
• Kepercayaan sumber — Hanya pasang kemampuan dari penulis tepercaya atau kontributor internal yang ditinjau. Lebih suka kemampuan dengan sumber yang jelas, kontrol versi, dan pemeliharaan aktif. Waspadai nama kemampuan yang menyerupai nama paket populer.
• Sandboxing — Jalankan keterampilan yang menyertakan skrip yang dapat dieksekusi di lingkungan terisolasi. Batasi sistem file, jaringan, dan akses tingkat sistem hanya untuk apa yang dibutuhkan keterampilan. Memerlukan konfirmasi pengguna eksplisit sebelum menjalankan operasi yang berpotensi sensitif.
• Audit dan pengelogan — Catat keterampilan mana yang dimuat, sumber daya mana yang dibaca, dan skrip mana yang dijalankan. Ini memberi Anda jejak audit untuk menelusuri tingkah laku agen hingga ke konten keterampilan tertentu jika terjadi kesalahan.

Kapan menggunakan keterampilan vs. alur kerja

Keterampilan Agen dan Alur Kerja Kerangka Kerja Agen memperluas apa yang dapat dilakukan agen, tetapi mereka bekerja dengan cara yang pada dasarnya berbeda. Pilih pendekatan yang paling sesuai dengan kebutuhan Anda:

• Kontrol — Dengan keterampilan, AI memutuskan cara menjalankan instruksi. Ini sangat ideal ketika Anda ingin agen menjadi kreatif atau adaptif. Dengan alur kerja, Anda secara eksplisit menentukan jalur eksekusi. Gunakan alur kerja saat Anda memerlukan perilaku deterministik dan dapat diprediksi.
• Ketahanan — Keterampilan berjalan dalam satu giliran agen. Jika terjadi kegagalan, seluruh operasi harus dicoba kembali. Alur kerja mendukung checkpointing, sehingga dapat dilanjutkan dari langkah terakhir yang berhasil setelah kegagalan. Pilih alur kerja saat biaya eksekusi ulang seluruh proses tinggi.
• Efek samping — Keterampilan cocok ketika operasi idempotensi atau berisiko rendah. Lebih suka alur kerja ketika langkah-langkah menghasilkan efek samping (mengirim email, menagih pembayaran) yang tidak boleh diulang saat mencoba kembali.
• Kompleksitas — Keterampilan adalah yang terbaik untuk tugas domain tunggal terfokus yang dapat ditangani oleh satu agen. Alur kerja lebih cocok untuk proses bisnis multi-langkah yang mengoordinasikan beberapa agen, persetujuan manusia, atau integrasi sistem eksternal.

Tip

Sebagai aturan praktis: jika Anda ingin AI mencari tahu cara menyelesaikan tugas, gunakan keterampilan. Jika Anda perlu menjamin langkah-langkah apa yang dijalankan dan dalam urutan apa, gunakan alur kerja.

Langkah selanjutnya

CodeAct

Konten terkait

• Spesifikasi Keterampilan Agen
• CodeAct
• Penyedia Konteks
• Agen yang Aktif
• Gambaran Umum Alat