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 üç aşamalı bir açıklama deseni 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 .

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.

Bir temsilciye beceri sağlama

Agent Framework, dosya sistemi dizinlerindeki becerileri keşfeden ve bunları bağlam sağlayıcısı olarak aracıların kullanımına sağlayan bir beceri sağlayıcısı içerir. Yapılandırılmış yolları dosyalar için SKILL.md özyinelemeli olarak (en fazla iki düzey derinde) arar, biçimlerini ve kaynaklarını doğrular ve araçları aracıya sunar: load_skill, read_skill_resourceve (betikler mevcut olduğunda) run_skill_script.

Uyarı

Betik yürütme henüz C# dilinde desteklenmiyor ve gelecek bir sürüme eklenecek.

Temel kurulum

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

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

Ajanı çağırma

Aracı yapılandırıldıktan sonra, kullanılabilir becerileri otomatik olarak bulur ve bir görev eşleştiğinde bunları kullanır:

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

Temel kurulum

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:

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

Ajanı çağırma

Aracı yapılandırıldıktan sonra, kullanılabilir becerileri otomatik olarak bulur ve bir görev eşleştiğinde bunları kullanır:

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

Birden çok beceri dizini

Bir yol listesi belirterek birden çok dizinde arama yapabilirsiniz.

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

Her yol, bir beceri klasörüne (içinde SKILL.md barındıran) veya beceri alt dizinlerine sahip bir üst klasöre işaret edebilir. Sağlayıcı en fazla iki seviye derinliğine kadar arama yapar.

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

Uyarı

Özel şablon, beceri listesinin eklendiği bir {0} yer tutucu içermelidir. 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.

Kod tanımlı beceriler

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

Betiğin yürütülmesi

Beceriler, aracın run_skill_script aracı aracılığıyla çalıştırdığı yürütülebilir betikleri içerebilir. Betiğin nasıl çalıştırıldığı, nasıl tanımlandığına bağlıdır:

• Kod tanımlı betikler (@skill.script aracılığıyla kaydedilen) süreç içinde doğrudan fonksiyon çağrıları şeklinde çalıştırılır. Çalıştırıcı gerekmez.
• Dosya tabanlı betikler (.py beceri dizinlerinde keşfedilen dosyalar), betiğin nasıl çalıştırıldığını belirleyen SkillScriptRunner — (skill, script, args) -> Any ile eşleşen herhangi bir çağrılabilir — gerektirir (örneğin, yerel bir alt işlem olarak).

Dosya tabanlı script yürütme

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.

Betik onayı

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.

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

Bağlam Sağlayıcıları

İlgili içerik

• Temsilci Becerileri Belirtilmesi
• Bağlam Sağlayıcıları
• Araçlara Genel Bakış