Compétences de l’agent

Configuration de base

Créez un FileAgentSkillsProvider pointant vers un répertoire contenant vos compétences et ajoutez-le aux fournisseurs de contexte de l’agent.

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

Invocation de l’agent

Une fois configuré, l’agent découvre automatiquement les compétences disponibles et les utilise lorsqu’une tâche correspond :

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

Configuration de base

Créez un SkillsProvider pointant vers un répertoire contenant vos compétences et ajoutez-le aux fournisseurs de contexte de l’agent.

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

Invocation de l’agent

Une fois configuré, l’agent découvre automatiquement les compétences disponibles et les utilise lorsqu’une tâche correspond :

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

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

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

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

Compétences définies par le code

En plus des compétences basées sur des fichiers découvertes à partir de fichiers SKILL.md, vous pouvez définir des compétences entièrement dans Python code. Les compétences définies par le code sont utiles quand :

• Le contenu de compétence est généré dynamiquement (par exemple, lecture à partir d’une base de données ou d’un environnement).
• Vous souhaitez conserver les définitions de compétences en même temps que le code d’application qui les utilise.
• Vous avez besoin de ressources qui exécutent la logique au moment de la lecture plutôt que de servir des fichiers statiques.

Compétence de code de base

Créez une instance avec un Skill nom, une description et un contenu d’instruction. Attachez éventuellement des SkillResource instances avec du contenu statique :

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

Ressources dynamiques

Utilisez le @skill.resource décorateur pour inscrire une fonction en tant que ressource. La fonction est appelée chaque fois que l’agent lit la ressource, afin qu’elle puisse retourner des données up-to-date. Les fonctions de synchronisation et asynchrone sont prises en charge :

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

Lorsque le décorateur est utilisé sans arguments (@skill.resource), le nom de la fonction devient le nom de la ressource et la documentation devient la description. Permet @skill.resource(name="...", description="...") de les définir explicitement.

Scripts définis par le code

Utilisez le décorateur @skill.script pour enregistrer une fonction en tant que script exécutable sur une fonctionnalité. Les scripts définis par le code s’exécutent en cours et ne nécessitent pas d’exécuteur de script. Les fonctions de synchronisation et asynchrone sont prises en charge :

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

Lorsque le décorateur est utilisé sans arguments (@skill.script), le nom de la fonction devient le nom du script et la documentation devient la description. Les paramètres typés de la fonction sont automatiquement convertis en schéma JSON que l’agent utilise pour passer des arguments.

Combinaison de compétences basées sur des fichiers et définies par le code

Passez les deux skill_paths et skills à un seul SkillsProvider. Les compétences basées sur des fichiers sont découvertes en premier ; si une compétence définie par le code porte le même nom qu’une compétence existante basée sur un fichier, la compétence définie par le code est ignorée :

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

Exécution des scripts

Les compétences peuvent inclure des scripts exécutables exécutés par l’agent via l’outil run_skill_script . La façon dont un script s’exécute dépend de la façon dont il a été défini :

• Les scripts définis par le code (inscrits via @skill.script) s’exécutent en processus sous forme d’appels de fonction directs. Aucun coureur n’est nécessaire.
• Les scripts basés sur des fichiers (.py fichiers découverts dans les répertoires de compétences) nécessitent un SkillScriptRunner — tout appelable correspondant à (skill, script, args) -> Any — qui détermine comment le script est exécuté (par exemple, en tant que sous-processus local).

Exécution de script basé sur des fichiers

Pour activer l’exécution de scripts basés sur des fichiers, passez-à script_runner à SkillsProvider. Toute synchronisation ou appel asynchrone qui satisfait le SkillScriptRunner protocole peut être utilisé :

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

L’exécuteur reçoit Skill résolu, SkillScript, et un dictionnaire facultatif args. Les scripts basés sur des fichiers sont automatiquement détectés à partir de .py fichiers dans les répertoires de compétences.

Approbation de script

Utilisez require_script_approval=True sur SkillsProvider pour contrôler l'exécution de tous les scripts après l'approbation humaine. Au lieu d’exécuter immédiatement, l’agent suspend et retourne des demandes d’approbation :

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)

Lorsqu’un script est rejeté (approved=False), l’agent est informé que l’utilisateur a refusé et peut répondre en conséquence.