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

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

Memberikan keterampilan kepada agen

Kerangka Kerja Agen mencakup penyedia keterampilan yang menemukan keterampilan dari direktori sistem file dan membuatnya tersedia untuk agen sebagai penyedia konteks. Ini mencari jalur yang dikonfigurasi secara rekursif (hingga dua tingkat dalam) untuk file SKILL.md, memvalidasi format dan sumber daya mereka, dan mengekspos alat ke agen: load_skill, read_skill_resource, dan (ketika skrip tersedia) run_skill_script.

Nota

Eksekusi skrip belum didukung di C# dan akan ditambahkan dalam rilis mendatang.

Penyiapan Awal

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

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;

// Discover skills from the 'skills' directory
var skillsProvider = new FileAgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));

// Create an agent with the skills provider
AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint), new DefaultAzureCredential())
    .GetResponsesClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "SkillsAgent",
        ChatOptions = new()
        {
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    });

Memanggil agen

Setelah dikonfigurasi, agen secara otomatis menemukan keterampilan yang tersedia dan menggunakannya saat tugas cocok:

// The agent loads the expense-report skill and reads the FAQ resource
AgentResponse response = await agent.RunAsync(
    "Are tips reimbursable? I left a 25% tip on a taxi ride.");
Console.WriteLine(response.Text);

Penyiapan Awal

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

from pathlib import Path
from agent_framework import SkillsProvider
from agent_framework.azure import AzureOpenAIChatClient
from azure.identity.aio import AzureCliCredential

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

# Create an agent with the skills provider
agent = AzureOpenAIChatClient(credential=AzureCliCredential()).as_agent(
    name="SkillsAgent",
    instructions="You are a helpful assistant.",
    context_providers=[skills_provider],
)

Memanggil agen

Setelah dikonfigurasi, agen secara otomatis menemukan keterampilan yang tersedia dan menggunakannya saat tugas cocok:

# The agent loads the expense-report skill and reads the FAQ resource
response = await agent.run(
    "Are tips reimbursable? I left a 25% tip on a taxi ride."
)
print(response.text)

Beberapa direktori keterampilan

Anda dapat mencari beberapa direktori dengan meneruskan daftar jalur:

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

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

Setiap jalur dapat menunjuk ke folder keterampilan individual (berisi SKILL.md) atau folder induk dengan subdirektori keterampilan. Penyedia mencari hingga dua tingkat dalam.

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 FileAgentSkillsProvider(
    skillPath: Path.Combine(AppContext.BaseDirectory, "skills"),
    options: new FileAgentSkillsProviderOptions
    {
        SkillsInstructionPrompt = """
            You have skills available. Here they are:
            {0}
            Use the `load_skill` function to get skill instructions.
            Use the `read_skill_resource` function to read skill files.
            """
    });

Nota

Templat kustom harus berisi {0} tempat penampung tempat daftar keterampilan disisipkan. 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.

Keterampilan berbasis kode

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

Pelaksanaan Skrip

Keterampilan dapat mencakup skrip yang dapat dieksekusi yang dijalankan agen melalui alat.run_skill_script Bagaimana skrip berjalan tergantung pada bagaimana skrip didefinisikan:

• Skrip yang ditentukan oleh kode (terdaftar melalui @skill.script) berjalan dalam proses sebagai panggilan fungsi secara langsung. Tidak memerlukan pelari.
• Skrip berbasis file (.py file yang ditemukan di direktori keterampilan) memerlukan SkillScriptRunner — pencocokan (skill, script, args) -> Any yang dapat dipanggil — yang menentukan bagaimana skrip dijalankan (misalnya, sebagai subprosces lokal).

Eksekusi skrip berbasis file

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.

Persetujuan skrip

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.

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 — dan keterampilan dapat mencakup skrip — menerapkan tingkat peninjauan dan tata kelola yang sama dengan 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

Penyedia Konteks

Konten terkait

• Spesifikasi Keterampilan Agen
• Penyedia Konteks
• Gambaran Umum Alat