Ferramentas e Skills

Ferramentas dão ao agente capacidades além de responder texto. Uma Skill, no fluxo de importação, é diferente: ela fornece instruções para criar ou propor mudanças no prompt, mas não instala código nem conecta ferramentas automaticamente.

Antes de configurar

Salve o agente primeiro. A aba Ferramentas só permite adicionar recursos depois que o agente existe. Para editar o agente, é preciso ter Editar agentes (agents.write) no escopo correspondente.

Recursos da organização também dependem das permissões de Ferramentas. Hoje o seletor pode exibir integrações para uma função que não tenha tools.write, e o erro só aparece ao tentar vinculá-las. Se isso acontecer, peça a um administrador a permissão adequada; a limitação está registrada no dossiê como BUG-TOL-077.

O que aparece na aba Ferramentas

A lista reúne as ferramentas anexadas ao agente, ordenadas por nome. Cada linha mostra nome, um ponto de status e as ações Editar e Remover.

• Verde — Configurado: a configuração mínima exigida para aquele tipo está presente.
• Amarelo — Configuração incompleta: falta uma configuração necessária. Em uma integração Composio, por exemplo, é preciso escolher uma conta e ao menos uma ação.

O ponto não é um teste de funcionamento do serviço externo. Valide a ferramenta no editor e depois use o painel Teste seu agente antes de ativá-lo.

Bases de conhecimento, AutoLearn e a busca de conversas anteriores não são gerenciados nesta lista. Use as seções Conhecimento e Avançado do editor, conforme o recurso.

Adicionar uma ferramenta

Selecione Adicionar Ferramenta. O seletor pode mostrar quatro grupos:

1. Ferramentas da Organização: endpoints HTTP já criados para a organização.
2. Servidores MCP: servidores cadastrados pela organização; ao selecionar um, escolha quais ferramentas descobertas o agente poderá usar.
3. Ferramentas Nativas: capacidades incorporadas ao SquadOS que ainda não estão anexadas ao agente.
4. Outras Ferramentas: integrações Composio ativas na organização e ainda não ligadas ao agente.

Os grupos HTTP e MCP só aparecem quando há um recurso disponível. Se não houver integração Composio disponível, Ativar ferramentas em Admin abre /admin/tools.

Administradores também podem usar Nova Ferramenta sem sair do editor para criar um endpoint HTTP ou servidor MCP. O recurso criado já segue para o vínculo com o agente.

O que acontece depois da seleção

• Nativa: a ferramenta é adicionada. Se tiver opções, um drawer de configuração abre; algumas ferramentas sem opções ficam prontas imediatamente.
• HTTP da organização: o vínculo usa a configuração central. No agente, você pode preencher apenas os overrides de parâmetros expostos e abrir Admin > Ferramentas para editar a definição compartilhada.
• MCP: o drawer começa com todas as ferramentas descobertas selecionadas em um vínculo novo. Revise a lista e salve; vínculos existentes preservam a seleção anterior e sinalizam novas ferramentas descobertas.
• Composio: primeiro selecione as ações permitidas e depois a conta conectada. A curadoria feita em Admin > Ferramentas limita as ações que podem ser escolhidas no agente.

Consulte Ferramentas Nativas — Visão Geral, Ferramentas HTTP Customizadas e Ferramentas da Organização para os contratos específicos.

Como o agente escolhe uma ferramenta

O modelo recebe o nome técnico, a descrição e o schema dos argumentos permitidos, além do prompt e do histórico da conversa. Escreva descrições que expliquem:

• o resultado produzido;
• quando usar e quando não usar;
• quais dados pedir antes da chamada;
• se a operação consulta ou altera dados;
• como confirmar uma ação sensível com o usuário.

Conecte somente o necessário. Ferramentas extras ocupam contexto e aumentam a chance de o modelo escolher a ação errada.

Criar um agente a partir de uma Skill

Criar a partir de Skill fica na página Agentes, ao lado de Novo Agente. O recurso está em preview e, na configuração atual, aparece somente para superadministradores que também possam editar agentes.

O importador aceita .md, .markdown, .skill, .txt e uma pasta compactada em .zip. O upload pode ter até 1 MiB; o texto principal, até 100 KiB e 40 partes com título. Em um ZIP, o SquadOS procura SKILL.md ou outro Markdown, lê apenas recursos textuais compatíveis e não executa programas nem abre binários.

Depois de escolher o arquivo, o SquadOS:

1. extrai nome, descrição e partes com título;
2. tenta adaptar o procedimento às capacidades conhecidas da plataforma;
3. informa passos ajustados ou removidos, ferramentas que talvez precisem ser ligadas e arquivos ignorados;
4. deixa escolher entre criar um agente novo ou sugerir mudanças a um agente existente.

As ferramentas sugeridas são orientação: conecte e configure cada uma manualmente.

Agente novo

O agente nasce desligado, com o texto importado como prompt e o modelo padrão da plataforma. Abra o editor, leia as instruções completas, conecte as ferramentas necessárias, teste e só então ative.

Agente existente

O arquivo precisa ter partes com título (##). Cada parte vira uma proposta na aba Sugestões do agente. O prompt não muda até uma pessoa aprovar cada proposta.

Revisão de segurança da Skill

Trate toda Skill externa como conteúdo não confiável. Ela pode conter instruções para ignorar regras, revelar dados ou usar ferramentas de forma indevida.

Na implementação auditada, a prévia mostra nome, descrição, títulos das partes e o relatório de adaptação, mas não mostra o corpo completo que será gravado. Se a adaptação ficar indisponível, o texto original ainda pode seguir para importação. Portanto:

1. leia o arquivo-fonte antes de confirmar;
2. para agente novo, revise o prompt completo no editor antes de ativar;
3. para agente existente, leia o diff de cada sugestão antes de aprovar;
4. confira manualmente as ferramentas recomendadas — o inventário da adaptação pode não reconhecer HTTP e MCP já cadastrados;
5. se o envio de sugestões falhar, abra a aba Sugestões antes de repetir: partes anteriores podem já ter sido criadas.

Essas limitações estão registradas como BUG-SKL-107, BUG-SKL-108 e BUG-SKL-109 e não foram corrigidas pela documentação.

Checklist antes de ativar

• Remova instruções que peçam segredos, exportação de dados ou ações fora do objetivo do agente.
• Confirme nomes e schemas das ferramentas no editor atual.
• Restrinja ações Composio e ferramentas MCP ao mínimo necessário.
• Faça chamadas de leitura e escrita em ambiente seguro e verifique o efeito real.
• Confirme mensagens de erro, ausência de dados e necessidade de aprovação humana.
• Ative o agente somente depois de revisar o prompt salvo e o teste completo.