Competenze dell'agente

Le competenze dell'agente sono pacchetti portabili di istruzioni, script e risorse che offrono agli agenti funzionalità specializzate e competenze di dominio. Le competenze seguono una specifica aperta e implementano un modello di divulgazione progressiva in modo che gli agenti carichino solo il contesto di cui hanno bisogno, quando necessario.

Usare le competenze dell'agente quando si vuole:

• Competenze di dominio — Acquisire conoscenze specializzate (politiche di spesa, flussi di lavoro legali, pipeline di analisi dati) sotto forma di pacchetti riutilizzabili e portabili.
• Estendere le funzionalità degli agenti : offrire agli agenti nuove capacità senza modificare le istruzioni di base.
• Garantire la coerenza : trasformare le attività in più passaggi in flussi di lavoro ripetibili e controllabili.
• Abilitare l'interoperabilità: riutilizzare la stessa competenza in diversi prodotti compatibili con le competenze dell'agente.

Struttura delle competenze

Un'abilità è una directory contenente un file SKILL.md con sottodirectory facoltative per le risorse.

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

formato SKILL.md

Il SKILL.md file deve contenere il frontmatter YAML seguito dal contenuto 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"
---

Campo	Obbligatorio	Descrzione
name	Sì	Massimo 64 caratteri. Solo lettere minuscole, numeri e trattini. Non deve iniziare o terminare con un trattino o contenere trattini consecutivi. Deve corrispondere al nome della directory principale.
description	Sì	Cosa fa la competenza e quando usarla. Massimo 1024 caratteri. Deve includere parole chiave che consentono agli agenti di identificare le attività pertinenti.
license	NO	Nome della licenza o riferimento a un file di licenza in bundle.
compatibility	NO	Massimo 500 caratteri. Indica i requisiti di ambiente (prodotto, pacchetti di sistema, accesso alla rete e così via).
metadata	NO	Mappatura chiave-valore arbitraria per metadati aggiuntivi.
allowed-tools	NO	Elenco delimitato da spazi di strumenti pre-approvati che l'abilità può utilizzare. Sperimentale: il supporto può variare tra le implementazioni dell'agente.

Il corpo markdown dopo il frontmatter contiene le istruzioni delle competenze, indicazioni dettagliate, esempi di input e output, casi limite comuni o qualsiasi contenuto che aiuti l'agente a svolgere l'attività. Mantenere SKILL.md sotto 500 righe e spostare materiale di riferimento dettagliato in file separati.

Divulgazione progressiva

Le competenze dell'agente usano un modello di divulgazione progressiva a tre fasi per ridurre al minimo l'utilizzo del contesto:

1. Annuncio (~100 token per competenza): i nomi e le descrizioni delle competenze vengono inseriti nella richiesta di sistema all'inizio di ogni esecuzione, quindi l'agente sa quali competenze sono disponibili.
2. Carica (< 5000 token consigliati): quando un'attività si allinea al dominio di una competenza, l'agente utilizza lo strumento load_skill per recuperare il corpo completo di SKILL.md con istruzioni dettagliate.
3. Leggere le risorse (in base alle esigenze): l'agente chiama lo read_skill_resource strumento per recuperare file supplementari (riferimenti, modelli, asset) solo quando necessario.

Questo modello mantiene snella la finestra di contesto dell'agente, concedendole l'accesso a conoscenze di dominio approfondite su richiesta.

Uso di FileAgentSkillsProvider

FileAgentSkillsProvider scopre le competenze dalle directory del file system e le rende disponibili agli agenti come provider di contesto. Cerca i percorsi configurati in modo ricorsivo (fino a due livelli profondi) per SKILL.md i file, convalida il formato e le risorse ed espone due strumenti all'agente: load_skill e read_skill_resource.

Annotazioni

L'esecuzione di script non è ancora supportata da FileAgentSkillsProvider e verrà aggiunta in una versione futura.

Configurazione di base

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

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

Richiamo dell'agente

Dopo la configurazione, l'agente individua automaticamente le competenze disponibili e le usa quando un'attività corrisponde:

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

Configurazione di base

Crea un FileAgentSkillsProvider che punta a una directory contenente le tue competenze e aggiungilo ai fornitori di contesto dell'agente:

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

# Discover skills from the 'skills' directory
skills_provider = FileAgentSkillsProvider(
    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],
)

Richiamo dell'agente

Dopo la configurazione, l'agente individua automaticamente le competenze disponibili e le usa quando un'attività corrisponde:

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

Molteplici directory di competenze

È possibile cercare più directory passando un elenco di percorsi:

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

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

Ogni percorso può puntare a una singola cartella della skill (contenente un SKILL.md) o a una cartella padre con sottodirectory della skill. Il provider cerca fino a due livelli di profondità.

Richiesta di sistema personalizzata

Per impostazione predefinita, FileAgentSkillsProvider inserisce un prompt di sistema che elenca le competenze disponibili e indica all'agente di usare load_skill e read_skill_resource. È possibile personalizzare questa richiesta:

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

Annotazioni

Il modello personalizzato deve contenere un {0} segnaposto in cui viene inserito l'elenco di competenze. Le parentesi graffe letterali devono essere precedute da un carattere di escape come {{ e }}.

skills_provider = FileAgentSkillsProvider(
    skill_paths=Path(__file__).parent / "skills",
    skills_instruction_prompt=(
        "You have skills available. Here they are:\n{0}\n"
        "Use the `load_skill` function to get skill instructions.\n"
        "Use the `read_skill_resource` function to read skill files."
    ),
)

Annotazioni

Il modello personalizzato deve contenere un {0} segnaposto in cui viene inserito l'elenco di competenze.

Considerazioni relative alla sicurezza

FileAgentSkillsProvider legge solo il contenuto statico dal file system e include le misure di sicurezza seguenti:

• Escape XML : i metadati delle competenze (nomi e descrizioni) vengono preceduti da un carattere di escape XML prima di essere inseriti nel prompt del sistema, impedendo l'inserimento di richieste tramite il frontmatter della competenza.
• Protezione dell'attraversamento del percorso: le risorse verificano che il percorso del file risolto rimanga all'interno della directory della skill, bloccando ../ i tentativi di escape.
• Protezione dei collegamenti simbolici — ogni segmento del percorso viene controllato per i collegamenti simbolici che potrebbero essere risolti all'esterno della directory della skill.
• Convalida all'individuazione : tutte le risorse a cui viene fatto riferimento vengono convalidate quando vengono caricate le competenze. Le competenze con risorse mancanti o non valide vengono escluse e registrate.

Avviso

Usare solo le competenze di origini attendibili. Le istruzioni delle competenze vengono inserite nel contesto dell'agente e possono influenzare il comportamento dell'agente.

Passaggi successivi

Provider di contesto

Contenuti correlati

• Specifica delle competenze dell'agente
• Provider di contesto
• Panoramica degli strumenti