Competências do Agente

As Competências do Agente são pacotes portáteis de instruções, scripts e recursos que conferem aos agentes capacidades especializadas e conhecimento de domínio. As competências seguem uma especificação aberta e implementam um padrão progressivo de divulgação para que os agentes carreguem apenas o contexto de que precisam, quando precisam.

Use as Habilidades de Agente quando quiser:

• Especialização no domínio de pacotes — Capturar conhecimento especializado (políticas de despesas, fluxos de trabalho legais, pipelines de análise de dados) como pacotes reutilizáveis e portáteis.
• Estenda as capacidades dos agentes — Dê aos agentes novas capacidades sem alterar as suas instruções principais.
• Garanta consistência — Transforme tarefas em vários passos em fluxos de trabalho repetíveis e auditáveis.
• Permitir a interoperabilidade — Reutilizar a mesma competência em diferentes produtos compatíveis com Competências de Agente.

Estrutura de competências

Uma habilidade é um diretório que contém um SKILL.md ficheiro com subdiretórios opcionais para 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

SKILL.md formato

O SKILL.md ficheiro deve conter material inicial YAML seguido de conteúdo marcado:

---
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	Obrigatório	Description
name	Yes	No máximo 64 caracteres. Apenas letras minúsculas, números e hífens. Não deve começar nem terminar com um hífen, nem conter hífens consecutivos. Deve corresponder ao nome do diretório principal.
description	Yes	O que a habilidade faz e quando a usar. Máximo 1024 caracteres. Deve incluir palavras-chave que ajudem os agentes a identificar tarefas relevantes.
license	Não	Nome da licença ou referência a um ficheiro de licença agrupado.
compatibility	Não	No máximo 500 caracteres. Indica os requisitos do ambiente (produto pretendido, pacotes do sistema, acesso à rede, etc.).
metadata	Não	Mapeamento chave-valor arbitrário para metadados adicionais.
allowed-tools	Não	Lista delimitada por espaço de ferramentas pré-aprovadas que a competência pode usar. Experimental — o suporte pode variar entre implementações de agentes.

O corpo de markdown após o frontmatter contém as instruções de habilidades — orientações passo a passo, exemplos de entradas e saídas, casos excecionais comuns ou qualquer conteúdo que ajude o agente a realizar a tarefa. Mantenha SKILL.md com menos de 500 linhas e transfira o material de referência detalhado para ficheiros separados.

Divulgação progressiva

As Competências do Agente utilizam um padrão progressivo de divulgação em três fases para minimizar o uso do contexto:

1. Publicitar (~100 tokens por habilidade) — Nomes e descrições das habilidades são inseridos no prompt do sistema no início de cada jogada, para que o agente saiba que habilidades estão disponíveis.
2. Load (< 5000 tokens recomendados) — Quando uma tarefa está dentro do domínio de uma aptidão, o agente usa a ferramenta load_skill para recuperar o corpo completo do SKILL.md com instruções detalhadas.
3. Leia recursos (conforme necessário) — O agente chama a read_skill_resource ferramenta para obter ficheiros suplementares (referências, modelos, recursos) apenas quando necessário.

Este padrão mantém a janela de contexto do agente enxuta, ao mesmo tempo que lhe dá acesso a conhecimento profundo do domínio sob demanda.

Usando o FileAgentSkillsProvider

O FileAgentSkillsProvider descobre competências a partir de diretórios do sistema de ficheiros e disponibiliza-as aos agentes como fornecedor de contexto. Pesquisa caminhos configurados recursivamente (até dois níveis de profundidade) por SKILL.md ficheiros, valida o seu formato e recursos, e expõe duas ferramentas ao agente: load_skill e read_skill_resource.

Observação

A execução de scripts ainda não é suportada pela FileAgentSkillsProvider e será adicionada numa versão futura.

Configuração básica

Crie um FileAgentSkillsProvider apontando para um diretório que contenha as suas competências e adicione-o aos provedores de contexto do 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],
    });

Invocação do agente

Uma vez configurado, o agente descobre automaticamente as competências disponíveis e utiliza-as quando uma tarefa corresponde:

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

Configuração básica

Crie um FileAgentSkillsProvider que aponte para um diretório contendo as suas competências e adicione-o aos fornecedores de contexto do 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],
)

Invocação do agente

Uma vez configurado, o agente descobre automaticamente as competências disponíveis e utiliza-as quando uma tarefa corresponde:

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

Múltiplos diretórios de competências

Pode pesquisar em vários diretórios passando uma lista de caminhos:

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

Cada caminho pode apontar para uma pasta individual de competências (contendo uma SKILL.md) ou para uma pasta pai com subdiretórios de competências. O prestador pesquisa até dois níveis de profundidade.

Indicação de sistema personalizada

Por defeito, FileAgentSkillsProvider injeta um prompt do sistema que lista as competências disponíveis e instrui o agente a usar load_skill e read_skill_resource. Pode personalizar este prompt:

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

Observação

O modelo personalizado deve conter um {0} marcador onde a lista de competências é inserida. Os parênteses literais devem ser escapados como {{ 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."
    ),
)

Observação

O modelo personalizado deve conter um {0} marcador onde a lista de competências é inserida.

Considerações de segurança

FileAgentSkillsProvider lê apenas conteúdo estático do sistema de ficheiros e inclui as seguintes medidas de segurança:

• XML-escaping — Os metadados de habilidade (nomes e descrições) são escapados em XML antes de serem injetados no prompt do sistema, impedindo a injeção no prompt através do frontmatter das habilidades.
• Proteção de percurso de caminho — As leituras de recursos validam que o caminho do ficheiro resolvido permanece dentro do diretório de habilidades, bloqueando ../ tentativas de escape.
• Protetores de links simbólicos — Cada segmento de caminho é verificado para links simbólicos que possam resolver-se fora do diretório da skill.
• Validação durante a descoberta — Todos os recursos referenciados são validados quando as funcionalidades são carregadas. Competências com recursos em falta ou inválidos são excluídas e registadas.

Advertência

Usa apenas competências de fontes confiáveis. As instruções de competência são inseridas no contexto do agente e podem influenciar o comportamento do agente.

Próximos passos

Fornecedores de Contexto

Conteúdo relacionado

• Especificação de Competências de Agente
• Fornecedores de Contexto
• Visão Geral das Ferramentas