Agent-Fähigkeiten

Grundlegende Einrichtung

Erstellen Sie einen Zeiger auf ein FileAgentSkillsProvider Verzeichnis, das Ihre Skills enthält, und fügen Sie es den Kontextanbietern des Agents hinzu.

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

Aufrufen des Agenten

Nach der Konfiguration ermittelt der Agent automatisch verfügbare Fähigkeiten und verwendet diese, wenn eine Aufgabe übereinstimmt:

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

Grundlegende Einrichtung

Erstellen Sie einen Zeiger auf ein SkillsProvider Verzeichnis, das Ihre Skills enthält, und fügen Sie es den Kontextanbietern des Agents hinzu.

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

Aufrufen des Agenten

Nach der Konfiguration ermittelt der Agent automatisch verfügbare Fähigkeiten und verwendet diese, wenn eine Aufgabe übereinstimmt:

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

Codedefinierte Fähigkeiten

Zusätzlich zu dateibasierten Fähigkeiten, die von SKILL.md Dateien ermittelt werden, können Sie Fähigkeiten vollständig in Python Code definieren. Codedefinierte Fähigkeiten sind nützlich, wenn:

• Qualifikationsinhalte werden dynamisch generiert (z. B. lesen aus einer Datenbank oder Umgebung).
• Sie möchten Qualifikationsdefinitionen zusammen mit dem Anwendungscode beibehalten, der sie verwendet.
• Sie benötigen Ressourcen, die Logik zum Lesezeitpunkt ausführen, anstatt statische Dateien zu verarbeiten.

Grundlegende Codekompetenz

Erstellen Sie eine Skill Instanz mit einem Namen, einer Beschreibung und einem Anweisungsinhalt. Optional fügen Sie Instanzen mit statischem Inhalt an 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])

Dynamische Ressourcen

Verwenden Sie den @skill.resource Dekorateur, um eine Funktion als Ressource zu registrieren. Die Funktion wird jedes Mal aufgerufen, wenn der Agent die Ressource liest, sodass sie aktuelle Daten zurückgeben kann. Sowohl Synchronisierungsfunktionen als auch asynchrone Funktionen werden unterstützt:

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

Wenn der Dekorateur ohne Argumente verwendet wird (@skill.resource), wird der Funktionsname zum Ressourcennamen, und die Docstring wird zur Beschreibung. Hiermit @skill.resource(name="...", description="...") legen Sie sie explizit fest.

Codedefinierte Skripts

Verwenden Sie den @skill.script Dekorateur, um eine Funktion als ausführbares Skript auf einer Fähigkeit zu registrieren. Codedefinierte Skripts werden im Prozess ausgeführt und erfordern keinen Skriptausführer. Sowohl Synchronisierungsfunktionen als auch asynchrone Funktionen werden unterstützt:

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

Wenn der Dekorateur ohne Argumente verwendet wird (@skill.script), wird der Funktionsname zum Skriptnamen, und die Docstring wird zur Beschreibung. Die eingegebenen Parameter der Funktion werden automatisch in ein JSON-Schema konvertiert, das der Agent zum Übergeben von Argumenten verwendet.

Kombinieren von dateibasierten und codedefinierten Fähigkeiten

Übergeben Sie sowohl skill_paths als auch skills an ein einzelnes SkillsProvider. Dateibasierte Fähigkeiten werden zuerst entdeckt; Wenn eine codedefinierte Qualifikation denselben Namen wie eine vorhandene dateibasierte Qualifikation hat, wird die codedefinierte Qualifikation übersprungen:

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

Skriptausführung

Fähigkeiten können ausführbare Skripts enthalten, die der Agent über das run_skill_script Tool ausführt. Wie ein Skript ausgeführt wird, hängt davon ab, wie es definiert wurde:

• Codedefinierte Skripts (registriert über @skill.script) werden in Prozess als direkte Funktionsaufrufe ausgeführt. Es ist kein Läufer erforderlich.
• Dateibasierte Skripts (.py Dateien, die in Qualifikationsverzeichnissen ermittelt werden) erfordern einen SkillScriptRunner — alle aufrufbaren Übereinstimmungen (skill, script, args) -> Any — die bestimmt, wie das Skript ausgeführt wird (z. B. als lokaler Unterprozess).

Dateibasierte Skriptausführung

Um die Ausführung von dateibasierten Skripts zu aktivieren, übergeben Sie eine script_runner an SkillsProvider. Alle Synchronisierungs- oder asynchronen Aufrufe, die das SkillScriptRunner Protokoll erfüllen, können verwendet werden:

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

Der Läufer empfängt das aufgelöste Skill, SkillScript und ein optionales args Wörterbuch. Dateibasierte Skripts werden automatisch aus .py Dateien in Qualifikationsverzeichnissen ermittelt.

Skriptgenehmigung

Verwenden Sie require_script_approval=True auf SkillsProvider, um alle Skriptausführungen mit menschlicher Genehmigung umzuleiten. Anstatt sofort auszuführen, hält der Agent an und gibt Genehmigungsanforderungen zurück:

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)

Wenn ein Skript abgelehnt wird (approved=False), wird der Agent darüber informiert, dass der Benutzer abgelehnt wurde und entsprechend reagieren kann.