PydanticAI Skills

Pydantic AI Skills — Documentação

📌 Visão Geral

Pydantic AI Skills é um framework padrão e componível para construir e gerenciar Agent Skills dentro do ecossistema Pydantic AI. Ele permite estender agentes de IA com capacidades modulares e reutilizáveis, organizadas como “skills” (habilidades).

Skills permitem que um agente:

• Descubra e carregue capacidades específicas conforme necessário.
• Organize instruções, recursos e scripts em diretórios modulares.
• Estenda o comportamento do agente sem codificar todo o conhecimento diretamente no agente.

📍 Principais Conceitos

🧠 O que são “Agent Skills”?

Agent Skills são coleções modulares contendo:

• Instruções para o agente.
• Scripts executáveis (Python).
• Recursos adicionais e documentação.

Elas permitem que agentes carreguem capacidades específicas sob demanda, melhorando escalabilidade, organização e clareza do sistema.

✨ Características Principais

• Descoberta Progressiva: skills são listadas e carregadas apenas quando necessário.
• Design Modular: cada skill é um diretório auto-contido com sua lógica.
• Execução de Scripts: skills podem incluir scripts Python executáveis.
• Gerenciamento de Recursos: suporte à documentação e arquivos auxiliares.
• Tipo Seguro: construído sobre a base de tipagem e validação do Pydantic AI.
• Integração Simples: interface clara para agentes acessarem skills como ferramentas.

🚀 Exemplo Rápido

from pydantic_ai import Agent, RunContext
from pydantic_ai_skills import SkillsToolset
 
# Inicializa o toolset de skills
skills_toolset = SkillsToolset(directories=["./skills"])
 
# Cria o agente com skills
agent = Agent(
    model='openai:gpt-5.2',
    instructions="Você é um assistente de pesquisa útil.",
    toolsets=[skills_toolset]
)
 
# Adiciona as instruções de skills ao agente
@agent.instructions
async def add_skills(ctx: RunContext) -> str | None:
    return await skills_toolset.get_instructions(ctx)
 
# Usa o agente
result = await agent.run(
    "Quais são os 3 últimos artigos no arXiv sobre aprendizado de máquina?"
)
print(result.output)

Esse exemplo mostra como integrar um toolset de skills a um agente e utilizá-lo em uma consulta prática.

⚙️ Como Funciona

O fluxo básico para um agente com skills é:

1. Descoberta: o toolset varre diretórios em busca de pastas contendo um arquivo SKILL.md.
2. Registro: cada skill é registrada como uma ferramenta disponível para o agente.
3. Carregamento Progressivo: o agente pode:
   • Listar habilidades disponíveis (list_skills()).
   • Carregar instruções detalhadas (load_skill(name)).
   • Ler recursos extras (read_skill_resource(skill_name, resource_name)).
   • Executar scripts da skill (run_skill_script(skill_name, script_name, args)).

🤔 Por que usar Skills?

Em vez de criar agentes com instruções extensas e monolíticas, as skills permitem separar responsabilidades e carregar apenas o conhecimento necessário para cada tarefa.

Isso resulta em agentes mais:

• Enxutos
• Fáceis de manter
• Reutilizáveis
• Adaptáveis a novos contextos

📌 Benefícios

• Manutenção facilitada: skills podem ser atualizadas sem alterar o agente principal.
• Escalabilidade: novas funcionalidades são adicionadas criando novas skills.
• Clareza: cada skill tem um propósito bem definido.
• Reutilização: a mesma skill pode ser usada por múltiplos agentes.
• Testabilidade: skills podem ser testadas de forma isolada.

⚠️ Considerações de Segurança

Skills podem conter scripts executáveis, portanto:

• Utilize apenas skills de fontes confiáveis.
• Faça auditoria de código antes de executar skills de terceiros.
• Evite conceder permissões excessivas ao ambiente onde o agente roda.

📦 Instalação

Instalação via pip:

pip install pydantic-ai-skills

Instalação com dependências de teste:

pip install pydantic-ai-skills[test]

🛠 Estrutura do Repositório

O repositório do projeto inclui:

• Exemplos de skills (ex.: busca no arXiv).
• Código-fonte do pacote pydantic_ai_skills.
• Testes automatizados.
• Documentação em formato navegável e exemplos práticos.

🔗 Referências

• Site do projeto: https://dougtrajano.github.io/pydantic-ai-skills/
• Repositório GitHub: https://github.com/DougTrajano/pydantic-ai-skills