Adicionando habilidades

A página anterior mostrava como as ferramentas permitem que os agentes ajam – chamando funções, consultando APIs, pesquisando na Web. Mas à medida que você cria mais agentes, surge um padrão: o mesmo cluster de ferramentas, instruções e material de referência continua aparecendo juntos. Uma funcionalidade de "registrar 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 gastos. Você acaba copiando esse pacote de agente para agente e ele fica fora de sincronia.

Habilidades resolvem esse problema. Uma habilidade é 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 habilidades seguem uma especificação aberta para que sejam reutilizáveis entre agentes, equipes e até mesmo produtos.

Quando usar

Adicione competências ao seu agente quando:

  • Você tem um cluster 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 experiência de domínio e você deseja uma única fonte de verdade em vez de instruções duplicadas.
  • Você deseja compartilhar e distribuir recursos de agente entre equipes, projetos ou organizações como pacotes independentes.
  • Você precisa gerenciar o contexto com eficiência – as habilidades usam a divulgação progressiva para que os agentes carreguem apenas os detalhes necessários, quando precisarem.

Considerações

Consideração Detalhes
Reutilização Uma habilidade é um pacote autônomo. Uma vez criado, qualquer agente pode pegá-lo — sem copiar e colar, sem descompasso entre cópias.
Eficiência de contexto As habilidades usam a divulgação progressiva: o agente vê uma breve descrição (aproximadamente 100 tokens) antecipadamente e carrega instruções completas somente quando relevante. Isso mantém a janela de contexto enxuta quando a habilidade não é necessária.
Custo de abstração As habilidades adicionam uma camada de abstração sobre as ferramentas. Para uma única ferramenta autônoma, adicionar um envoltório de habilidade é uma sobrecarga desnecessária.
Esforço de design Você precisa pensar sobre os limites de habilidades antecipadamente: o que pertence dentro da habilidade e o que fica fora. Limites ruins levam a competências muito amplas (desperdício de contexto) ou muito estreitas (perdendo o benefício do agrupamento).

Como as habilidades diferem das ferramentas

Ferramentas e habilidades são complementares, não concorrentes. Compreender a diferença ajuda a decidir quando utilizar cada um.

Uma ferramenta é uma única ação que pode ser chamada : uma função com um nome, uma descrição e um esquema de parâmetro. Quando o modelo decide que uma ferramenta é necessária, ela gera uma chamada estruturada, o Agent Framework a executa e o resultado volta para o modelo. As ferramentas são os átomos do comportamento do agente.

Uma habilidade é um pacote de conhecimento de domínio. Eles podem incluir:

  • Instruções – diretrizes passo a passo, regras de decisão e exemplos que informam ao agente como abordar um domínio.
  • Material de referência – documentos de política, perguntas frequentes, modelos e outros conhecimentos que o agente pode consultar sob demanda.
  • Scripts — código executável que o agente pode executar para executar operações específicas (por exemplo, um script de validação que verifica os dados de despesas em relação às regras de política).

A principal diferença é um dos escopos: uma ferramenta dá ao agente a capacidade de executar uma ação; uma habilidade fornece ao agente o conhecimento e os recursos para lidar com um domínio inteiro.

Tool Habilidade
O que ele fornece Uma única ação que pode ser invocada Instruções + material de referência + scripts opcionais
Como o agente o usa Chama quando precisa agir Carrega-o quando encontra uma tarefa relevante, lê as instruções e pode invocar scripts ou consultar recursos
Custo de contexto O esquema de ferramentas está sempre no prompt Somente o nome e a descrição da habilidade (aproximadamente 100 tokens) estão no prompt; conteúdo completo é carregado sob demanda
Portabilidade Vinculado ao agente que o registra Pacote autocontido que qualquer agente compatível pode descobrir
Mais adequado para Ações individuais (consultar um banco de dados, enviar um email) Conhecimento de domínio (políticas de despesas, diretrizes de revisão de código, procedimentos de integração)

Dica

Pense em ferramentas como verbos (pesquisar, reservar, validar) e habilidades como experiência (conhecimento em reserva de viagens, conhecimento em políticas de despesas). Um agente usa ferramentas para agir e habilidades para saber como agir.

Como as habilidades funcionam: divulgação progressiva

As habilidades foram projetadas para serem eficientes em seu contexto. Em vez de injetar tudo no prompt antecipadamente, as habilidades usam um padrão de três estágios:

┌──────────────────────────────────────────────────────────────────┐
│  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.            │
└──────────────────────────────────────────────────────────────────┘

Esse padrão significa que um agente com 10 habilidades registradas paga cerca de 1.000 tokens de sobrecarga de contexto, não 50.000. O agente só aprofunda seu conhecimento quando a tarefa atual o exige.

Além disso, as habilidades são criadas com base na infraestrutura de ferramentas. O Agent Framework anuncia as habilidades disponíveis no prompt do sistema do agente e, em seguida, expõe load_skill e read_skill_resource como chamadas de ferramenta que o agente invoca para carregar conteúdo progressivamente.

Dica

Para obter detalhes completos sobre estrutura de habilidades, configuração e exemplos de código, consulte a referência de Habilidades do Agente .

Quando usar habilidades versus outros padrões

À medida que seu agente se torna mais capaz, você tem várias maneiras de organizar seu comportamento. Veja como as habilidades se comparam às ferramentas:

Padrão Mais adequado para Exemplo
Ferramentas individuais Ações pontuais que não precisam de contexto compartilhado Uma get_weather ferramenta funcional
Habilidades Experiência de domínio com instruções, referências e scripts opcionais Uma habilidade de "relatório de despesas" com documentos de política, scripts de validação e instruções de arquivamento passo a passo

Armadilhas comuns

Perigo oculto Orientações
Habilidades excessivamente amplas Uma competência chamada "tudo sobre finanças" que tenta cobrir contabilidade, impostos, relatórios de despesas e folha de pagamento terá instruções muito longas e desfocadas. Mantenha as habilidades focadas em um domínio.
Ignorando a revisão de segurança As instruções de habilidade são injetadas no contexto do agente e os scripts executam código. Tratar habilidades como dependências de terceiros – examine-as antes de implantar. Consulte as práticas recomendadas de segurança na referência de habilidades.
Ignorando a divulgação progressiva Se o seu SKILL.md for de 2.000 linhas, o agente pagará um alto custo de contexto quando carregar a habilidade. Mantenha as instruções concisas e mova o material de referência detalhado para arquivos de recursos separados para tirar pleno proveito da divulgação progressiva.

Próximas Etapas 

Depois que o agente tiver ferramentas e habilidades, a próxima etapa é adicionar middleware – comportamentos transversais, como diretrizes de segurança, registro de log e filtragem de conteúdo, que se aplicam a cada interação sem modificar a lógica central do agente.

Adicionando Middleware

Vá mais fundo:

  • Last updated on