O que são AI Skills & Tools

🔧 O que é uma Skill?

No contexto de agentes de IA, um skill (também chamado de tool or function) é uma capacidade empacotada e reutilizável que um LLM pode invocar para interagir com o mundo fora de sua janela de contexto. Skills fazem a ponte entre a compreensão de linguagem e a ação no mundo real.

Toda skill tem quatro componentes:

• Name — um identificador único que o modelo usa para referenciar a skill (por exemplo, web_search)
• Description — texto em linguagem natural explicando o que a skill faz e quando usá-la; o LLM lê isso para decidir quando chamar a skill
• Esquema de entrada — uma definição estruturada dos argumentos (JSON Schema); o modelo preenche estes com base na tarefa
• Implementation — o código real que roda: uma chamada de API, consulta ao banco de dados, comando de shell ou qualquer outra operação

Exemplo: A get_weather skill tem a descrição "Busca o clima atual para uma cidade", aceita { "city": "string" } como entrada, e chama uma API de clima. O LLM nunca vê a chave da API ou a chamada HTTP — ele apenas recebe o resultado de volta como texto.

⚙️ Como o Chamado de Ferramentas Funciona

Quando um agente tem acesso a skills, o LLM não as chama diretamente — ele requests uma chamada gerando uma saída estruturada. O runtime (o código da sua aplicação) executa a chamada real e retorna o resultado. Aqui está o ciclo completo:

1. Registro de ferramenta — Seu código envia ao modelo uma lista de skills disponíveis com suas descrições e schemas
2. Raciocínio do modelo — O LLM lê a tarefa e as ferramentas disponíveis, decide qual ferramenta chamar e com quais argumentos
3. Pedido de chamada de ferramenta — O modelo produz uma mensagem estruturada de "tool call" (por exemplo, { "tool": "web_search", "args": { "query": "current Gemini models" } })
4. Execution — O código do seu runtime chama a função, API ou serviço real
5. Injeção de resultado — O resultado é adicionado de volta ao contexto da conversa
6. Raciocínio contínuo — O modelo lê o resultado e ou chama outra ferramenta, faz uma pergunta de acompanhamento, ou gera a resposta final

Este loop pode se repetir muitas vezes em um único turno. Uma tarefa agente complexa pode chamar 10–20 ferramentas em sequência antes de produzir uma resposta final.

📊 Skills vs Plugins vs MCP Servers

A terminologia evoluiu rapidamente. Eis como os conceitos se relacionam historicamente:

Distinção chave: O uso tradicional de ferramentas é definido inline no código da sua aplicação. MCP servers são processos autônomos que expõem ferramentas por um protocolo padronizado — tornando-os reutilizáveis através de diferentes clientes de IA (Claude Desktop, Cursor, VS Code, agentes customizados). Leia mais: O que é MCP.

🗂️ Categorias de Ferramentas & Níveis de Risco

Nem todas as ferramentas apresentam o mesmo risco. Agrupar por nível de risco ajuda a definir o espaço de ação e onde adicionar checkpoints human-in-the-loop:

🏗️ Anatomia de uma Boa Skill

A decisão de design mais importante para uma skill é sua description. O LLM lê as descrições para decidir qual ferramenta chamar — uma descrição mal escrita leva à seleção errada da ferramenta, chamadas perdidas ou argumentos ambíguos.

O que torna uma descrição eficaz

• Seja explícito sobre quando usá-la — "Use this tool when the user asks about real-time data or current events" é melhor do que "Searches the web"
• Declare o que ela NÃO faz — "Não retorna dados históricos com mais de 30 dias"
• Descreva o formato de saída — "Retorna um array JSON de resultados de busca com os campos title, url e snippet"
• Mantenha abaixo de 200 palavras — descrições maiores que ~200 tokens podem sobrecarregar a atenção do modelo quando muitas ferramentas estão registradas

Princípios de design de schema

• Obrigatório vs opcional — Marque campos como obrigatórios somente se realmente necessário; campos opcionais com defaults reduzem erros do modelo
• Use enums para valores restritos — "format": {"enum": ["json", "markdown", "text"]} previne valores alucinatórios
• Prefira ferramentas idempotentes — Ferramentas que podem ser reexecutadas com segurança (leituras, consultas) são mais seguras do que ações de única execução (envios, exclusões)
• Retorne dados estruturados — Respostas JSON são mais fáceis para o modelo raciocinar do que blobs de texto não estruturado

💡 Exemplos do Mundo Real

✅ Boas Práticas

Permissões mínimas

Conceda a cada agente somente as ferramentas que ele precisa para sua tarefa específica. Um agente que responde perguntas frequentes não precisa de write_file or send_email. Quanto menor o espaço de ação, menor a área de impacto se o agente for manipulado. Veja: Agência Excessiva.

Audite todas as chamadas de ferramenta

Registre toda chamada de ferramenta com seus argumentos e resultado. Isso possibilita depuração, atribuição de custos, e detecção de comportamento anômalo (por exemplo, um agente lendo ~/.ssh/ quando deveria acessar apenas o diretório do projeto). Plataformas AgentOps como LangSmith tornam isso fácil.

Humano-no-loop para ações irreversíveis

Qualquer ação que seja difícil ou impossível de desfazer — enviar mensagens, excluir dados, fazer compras — deve exigir confirmação humana explícita antes da execução. Construa checkpoints HITL no runtime do seu agente, não apenas no prompt. Prompts podem ser sobrescritos; código não pode.

Cuidado com envenenamento de ferramenta

Se você permitir que agentes instalem ou descubram MCP servers dinamicamente, um servidor malicioso pode registrar uma ferramenta com uma descrição que contenha instruções ocultas. Sempre revise descrições de ferramentas antes de adicioná-las ao registro do seu agente. Veja: Envenenamento de Ferramenta.

Escreva retornos de erro claros

Quando uma ferramenta falha, retorne um erro estruturado com contexto suficiente para o modelo se recuperar ou escalar — não um rastreamento de pilha (stack trace) cru. Exemplo: { "error": "rate_limited", "retry_after": 5 }. Um erro bem descrito permite que o agente tente novamente, use uma ferramenta de fallback ou informe o usuário com elegância.