Aptitudes del agente

Las aptitudes del agente son paquetes portátiles de instrucciones, scripts y recursos que proporcionan a los agentes funcionalidades especializadas y conocimientos sobre dominios. Las aptitudes siguen una especificación abierta e implementan un patrón de divulgación progresiva para que los agentes carguen solo el contexto que necesitan, cuando lo necesiten.

Utilice habilidades del agente cuando las necesite:

• Empaquetar el dominio de la experiencia: capte conocimientos especializados (políticas de gastos, flujos de trabajo legales, pipelines de análisis de datos) como paquetes reutilizables y portátiles.
• Ampliar las funcionalidades del agente : proporcione nuevas capacidades a los agentes sin cambiar sus instrucciones principales.
• Garantizar la coherencia : convierta las tareas de varios pasos en flujos de trabajo repetibles y auditables.
• Habilitar la interoperabilidad : reutilice la misma aptitud en diferentes productos compatibles con aptitudes del agente.

Estructura de aptitudes

Una aptitud es un directorio que contiene un archivo con subdirectorios opcionales para los recursos:

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

El archivo debe contener el frontmatter de YAML seguido del contenido de 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"
---

El cuerpo de Markdown después de la frontmatter contiene las instrucciones de habilidades, instrucciones paso a paso, ejemplos de entradas y salidas, casos límite comunes o cualquier contenido que ayude al agente a realizar la tarea. Mantenga en menos de 500 líneas y mueva el material de referencia detallado a archivos independientes.

Divulgación progresiva

Las habilidades del agente usan un patrón de revelación progresiva de tres fases para reducir el uso del contexto.

1. Publicidad (~100 tokens por aptitud): los nombres y las descripciones de las aptitudes se insertan en la indicación del sistema al principio de cada ejecución, de modo que el agente sepa qué aptitudes están disponibles.
2. Cargar ( 5000 tokens recomendados): cuando una tarea coincide con el dominio de una aptitud, el agente llama a la herramienta para recuperar el cuerpo completo del SKILL.md con instrucciones detalladas.
3. Recursos de lectura (según sea necesario): el agente llama a la herramienta para capturar archivos complementarios (referencias, plantillas, recursos) solo cuando sea necesario.

Este patrón mantiene la ventana de contexto del agente ligera al tiempo que proporciona acceso a conocimientos profundos de dominio bajo demanda.

Proporcionar aptitudes a un agente

Agent Framework incluye un proveedor de aptitudes que detecta aptitudes de directorios del sistema de archivos y los pone a disposición de los agentes como proveedor de contexto. Busca de forma recursiva las rutas de acceso configuradas (hasta dos niveles en profundidad) para los archivos, valida su formato y sus recursos y expone dos herramientas al agente: y .

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

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

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

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

Varios directorios de aptitudes

Puede buscar varios directorios pasando una lista de rutas de acceso:

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

Cada ruta de acceso puede apuntar a una carpeta de aptitudes individual (que contiene un ) o una carpeta primaria con subdirectorios de aptitud. El proveedor busca hasta dos niveles en profundidad.

Mensaje del sistema personalizado

De forma predeterminada, el proveedor de aptitudes inserta una solicitud del sistema que enumera las aptitudes disponibles e indica al agente que use y . Puede personalizar este mensaje:

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

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

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() -> str:
    """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() -> str:
    """Return the team roster."""
    return "Alice Chen (Tech Lead), Bob Smith (Backend Engineer)"

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

Procedimientos recomendados de seguridad

Las aptitudes del agente deben tratarse como cualquier código de terceros que incorpore al proyecto. Dado que las instrucciones de habilidades se insertan en el contexto del agente, y las habilidades pueden incluir scripts, es esencial aplicar el mismo nivel de revisión y gobernanza como lo haría con una dependencia de código abierto.

• Revisar antes de usar : lea todo el contenido de las aptitudes (, scripts y recursos) antes de la implementación. Compruebe que el comportamiento real de un script coincide con su intención indicada. Busque instrucciones adversarias que intenten omitir las directrices de seguridad, exfiltrar datos o modificar archivos de configuración de agentes.
• Confianza de origen : instale solo aptitudes de autores de confianza o colaboradores internos examinados. Prefiere aptitudes con un claro origen, control de versiones y mantenimiento activo. Esté atento a los nombres de habilidades suplantados que imitan paquetes de software populares.
• Ejecuta en sandbox habilidades que incluyan scripts ejecutables en entornos aislados. Limite el acceso del sistema de archivos, la red y el nivel de sistema solo a lo que requiere la aptitud. Requerir confirmación explícita del usuario antes de ejecutar operaciones potencialmente confidenciales.
• Auditoría y registro : registre qué aptitudes se cargan, qué recursos se leen y qué scripts se ejecutan. Esto le proporciona una pista de auditoría para rastrear el comportamiento del agente hasta contenido específico de habilidades si algo sale mal.

Cuándo usar aptitudes frente a flujos de trabajo

Los flujos de trabajo de Agent Skills y Agent Framework amplían lo que pueden hacer los agentes, pero funcionan de maneras fundamentalmente diferentes. Elija el enfoque que mejor se adapte a sus requisitos:

• Control : con una aptitud, la inteligencia artificial decide cómo ejecutar las instrucciones. Esto es ideal cuando quieres que el agente sea creativo o adaptable. Con un flujo de trabajo, se define explícitamente la trayectoria de ejecución. Use flujos de trabajo cuando necesite un comportamiento determinista y predecible.
• Resiliencia, una habilidad que se ejecuta en un solo turno de agente. Si se produce un error en algo, se debe reintentar toda la operación. Los flujos de trabajo admiten puntos de control, por lo que pueden reanudarse desde el último paso correcto después de un error. Elija flujos de trabajo cuando el costo de volver a ejecutar todo el proceso sea alto.
• Efectos secundarios — Las habilidades son adecuadas cuando las operaciones son idempotentes o de bajo riesgo. Prefiere flujos de trabajo cuando los pasos producen efectos secundarios (enviar correos electrónicos, cobrar pagos) que no deben repetirse en el reintento.
• Complejidad : las aptitudes son las mejores para las tareas centradas y de dominio único que un agente puede controlar. Los flujos de trabajo son más adecuados para los procesos empresariales de varios pasos que coordinan varios agentes, aprobaciones humanas o integraciones de sistemas externos.

Pasos siguientes

Contenido relacionado

• Especificación de aptitudes del agente
• Proveedores de contexto
• Información general sobre las herramientas