Adição de Competências

A página anterior mostrou como as ferramentas permitem que os agentes atuem — chamando funções, consultando APIs, pesquisando na web. Mas à medida que se constrói mais agentes, surge um padrão: o mesmo conjunto de ferramentas, instruções e material de referência continua a aparecer em conjunto. Uma funcionalidade de "apresentar um relatório de despesas" não é apenas uma ferramenta — é um script de validação, um conjunto de documentos de política, instruções passo a passo sobre como preencher o formulário e conhecimento sobre limites de despesa. Você acaba por copiar e colar este pacote de agente para agente, e ele perde a sincronização.

As competências resolvem este problema. Uma skill é um pacote portátil que agrupa instruções, material de referência e scripts opcionais em uma única unidade que qualquer agente pode descobrir e carregar sob demanda. As competências seguem uma especificação aberta , por isso são reutilizáveis entre agentes, equipas e até produtos.

Quando utilizar isto

Adicione competências ao seu agente quando:

  • Tem um conjunto de conhecimentos relacionados — instruções, documentos de referência e scripts — que logicamente pertencem juntos (por exemplo, "relatórios de despesas" ou "diretrizes de revisão de código").
  • Vários agentes precisam da mesma especialização e tu queres uma única fonte de verdade em vez de instruções duplicadas.
  • Quer partilhar e distribuir as capacidades dos agentes entre equipas, projetos ou organizações como pacotes autónomos.
  • É preciso gerir o contexto de forma eficiente — as competências usam divulgação progressiva para que os agentes só carreguem os detalhes de que precisam, quando precisam.

Considerações

Consideração Detalhes
Reutilização Uma competência é um pacote autónomo. Uma vez criado, qualquer agente pode apanhá-lo — sem copiar e colar, sem discrepâncias entre as cópias.
Eficiência do contexto As funcionalidades usam divulgação progressiva: o agente vê uma breve descrição (~100 tokens) de forma inicial e carrega as instruções completas apenas quando for relevante. Isto mantém a janela de contexto leve quando a capacidade não é necessária.
Custo de abstração As competências acrescentam uma camada de abstração por cima das ferramentas. Para uma única ferramenta de função autónoma, adicionar um skill wrapper é um overhead desnecessário.
Esforço de design Tens de pensar nos limites das competências desde o início: o que pertence dentro da competência e o que fica fora. Limites fracos levam a competências demasiado amplas (desperdiçando contexto) ou demasiado estreitas (perdendo o benefício de agrupar).

Como as competências diferem das ferramentas

As ferramentas e competências são complementares, não competitivas. Compreender a distinção ajuda a decidir quando escolher cada um.

Uma ferramenta é uma única ação chamável — uma função com um nome, descrição e esquema de parâmetros. Quando o modelo decide que uma ferramenta é necessária, gera uma chamada estruturada, o Agent Framework executa-a e o resultado regressa ao modelo. As ferramentas são os átomos do comportamento do agente.

Uma competência é um conjunto de conhecimentos de área. Podem incluir:

  • Instruções — orientações passo a passo, regras de decisão e exemplos que indicam ao agente como abordar um domínio.
  • Material de referência — documentos de política, FAQs, modelos e outros conhecimentos que o agente pode consultar a pedido.
  • Scripts — código executável que o agente pode executar para realizar operações específicas (por exemplo, um script de validação que verifica os dados de despesas contra as regras da política).

A diferença chave está no âmbito: uma ferramenta dá ao agente a capacidade de realizar uma ação; Uma competência dá ao agente o conhecimento e os recursos para lidar com um domínio inteiro.

Tool Skill
O que oferece Uma única ação chamável Instruções + material de referência + scripts opcionais
Como o agente o utiliza Chama-o quando precisa de agir Carrega quando encontra uma tarefa relevante, lê as instruções e poderá executar scripts ou consultar recursos.
Custo de contexto O esquema da ferramenta está sempre no prompt. Apenas o nome e a descrição da habilidade (~100 fichas) estão no prompt; O conteúdo completo é carregado sob demanda
Portabilidade Está ligado ao agente que o regista Pacote autónomo que qualquer agente compatível pode descobrir
Melhor para Ações individuais (consultar uma base de dados, enviar um email) Especialização em domínio (políticas de despesas, diretrizes de revisão de código, procedimentos de integração)

Sugestão

Pense nas ferramentas como verbos (pesquisar, reservar, validar) e nas competências como competências (conhecimento sobre reservas de viagens, conhecimento sobre políticas de despesas). Um agente usa ferramentas para agir e competências para saber como agir.

Como funcionam as competências: divulgação progressiva

As competências são desenhadas para serem eficientes em termos de contexto. Em vez de inserir tudo no prompt logo no início, as funcionalidades usam um padrão de três etapas:

┌──────────────────────────────────────────────────────────────────┐
│  Stage 1: Advertise                                              │
│  Agent sees skill names and descriptions (~100 tokens each)      │
│  in its system prompt at the start of every run.                 │
└──────────────┬───────────────────────────────────────────────────┘
               ▼ (task matches a skill's domain)
┌──────────────────────────────────────────────────────────────────┐
│  Stage 2: Load                                                   │
│  Agent calls load_skill to get the full instructions             │
│  (< 5000 tokens recommended).                                   │
└──────────────┬───────────────────────────────────────────────────┘
               ▼ (agent needs more detail)
┌──────────────────────────────────────────────────────────────────┐
│  Stage 3: Read resources                                         │
│  Agent calls read_skill_resource to fetch supplementary files    │
│  (FAQs, templates, reference docs) only when needed.            │
└──────────────────────────────────────────────────────────────────┘

Este padrão significa que um agente com 10 competências registadas paga cerca de 1.000 tokens de sobrecarga de contexto — não 50.000. O agente só aprofunda o seu conhecimento quando a tarefa atual o exige.

Além disso, as competências são construídas sobre a infraestrutura de ferramentas. O Agent Framework anuncia as competências disponíveis no prompt do sistema do agente, depois expõe load_skill e read_skill_resource como chamadas de ferramenta que o agente invoca para carregar conteúdo progressivamente.

Sugestão

Para detalhes completos sobre estrutura de competências, configuração e exemplos de código, consulte a referência Agent Skills .

Quando usar habilidades vs. outros padrões

À medida que o seu agente se torna mais capaz, tem várias formas de organizar o seu comportamento. Eis como as competências se comparam às ferramentas:

Padrão Melhor para Exemplo
Ferramentas individuais Ações pontuais que não precisam de contexto partilhado Uma get_weather ferramenta funcional
Competências Especialização no domínio com instruções, referências e scripts opcionais Uma competência de "relatório de despesas" com documentos de política, scripts de validação e instruções passo a passo para o registo

Dificuldades comuns

Armadilha Orientações
Competências demasiado amplas Uma competência chamada "tudo sobre finanças", que tenta cobrir contabilidade, impostos, relatórios de despesas e processamento de salários, terá instruções demasiado longas e pouco focadas. Mantém as competências focadas num único domínio.
Saltar a revisão de segurança As instruções de skill são injetadas no contexto do agente e os scripts executam código. Trate as competências como dependências de terceiros — reveja-as antes de implementar. Consulte as melhores práticas de segurança na referência de competências.
Ignorar a divulgação progressiva Se o seu SKILL.md tem 2.000 linhas, o agente paga um custo de contexto elevado quando carrega a funcionalidade. Mantenha as instruções concisas e transfera o material de referência detalhado para ficheiros de recursos separados para tirar pleno proveito da divulgação progressiva.

Passos seguintes

Uma vez que o seu agente tenha ferramentas e competências, o passo seguinte é adicionar middleware — comportamentos cruzados como proteções, registos e filtragem de conteúdos que se aplicam a todas as interações sem alterar a lógica central do seu agente.

Adição de Middleware

Vai mais fundo:

  • Last updated on