Ferramentas Nativas — Visão Geral
Ferramentas dão ao agente ações além de escrever uma resposta. Uma ferramenta nativa é implementada pelo próprio SquadOS: o agente recebe seu contrato de entrada e saída e pode chamá-la quando o contexto e a configuração permitem. Algumas funcionam sem ajuste; outras exigem modelo, escopo ou destinos válidos.
Antes de adicionar
Section titled “Antes de adicionar”O agente precisa estar salvo. Durante a criação, Ferramentas mostra a orientação para salvar primeiro porque cada vínculo precisa do ID do agente.
Para adicionar, configurar ou remover uma ferramenta nativa, a função efetiva precisa de agents.write naquele agente. Recursos da organização podem exigir permissões adicionais:
| Recurso conectado ao agente | Permissões de escrita |
|---|---|
| Ferramenta nativa do seletor | agents.write |
| Bases e AutoLearn, geridos em Conhecimento | agents.write e bases.write |
| Composio, ferramenta HTTP da organização ou servidor MCP | agents.write e tools.write |
Uma pessoa com tools.view, mas sem tools.write, ainda pode ver uma integração no seletor atual e receber erro ao tentar vinculá-la. Nesse caso, peça a um administrador para revisar a função; não reconecte a conta nem recrie a ferramenta.
Abrir o seletor
Section titled “Abrir o seletor”- Abra Agentes e selecione um agente salvo.
- Entre em Ferramentas.
- Clique em Adicionar Ferramenta.
O seletor monta grupos diferentes conforme os recursos disponíveis para a organização:
| Grupo | Conteúdo |
|---|---|
| Ferramentas da Organização | Ferramentas HTTP já criadas na organização |
| Servidores MCP | Servidores conectados e suas ações descobertas |
| Ferramentas Nativas | Ferramentas do SquadOS que ainda não estão ligadas ao agente |
| Outras Ferramentas | Integrações Composio ativas em Ferramentas no menu administrativo |
Os grupos de organização e MCP não aparecem quando não há item disponível. Uma ferramenta nativa já adicionada também sai do seletor até ser removida do agente.
Depois da adição, o card volta à lista de Ferramentas. O ponto verde significa Configurado; o amarelo significa Configuração incompleta. Ferramentas com formulário abrem esse formulário logo após a inclusão. As demais são adicionadas ativas em um clique.
Catálogo nativo do seletor
Section titled “Catálogo nativo do seletor”Estas são as opções públicas atuais, ordenadas pelo nome traduzido na interface:
| Ferramenta | O que permite ao agente fazer | Ajuste após adicionar |
|---|---|---|
| Anotações | Ler e atualizar memória estruturada do contato ou da conversa | Nenhum |
| AutoPrompt | Propor ou aplicar mudanças nas próprias instruções | Escolher Propor e aguardar aprovação — o padrão — ou aplicação automática; o acesso ao contexto da organização é separado |
| Data e Hora Atual | Consultar data e hora no fuso efetivo da organização | O painel mostra o fuso da organização e o caminho para alterá-lo |
| Gerar Imagem com LLM | Gerar uma imagem a partir de instruções textuais | Selecionar um modelo de imagem; sem ele, o card fica amarelo e a ferramenta não entra no runtime |
| HTML para Imagem | Renderizar HTML e CSS como imagem | Defaults de HTML, largura, altura e formato são opcionais |
| Tags da conversa | Ler, aplicar e remover tags que descrevem o assunto da conversa | Nenhum |
| Tags do contato | Ler, aplicar, remover e criar sob demanda tags do contato | Nenhum |
| Transferir Conversa | Transferir para outro agente ou atendimento humano conforme o motivo | Criar ao menos um contexto com orientação e destino; horários e condições podem limitar cada rota |
Arquivos também existe no registro, mas continua em preview e só aparece no seletor para superadministradores. Ela precisa de um escopo por arquivos ou tags; pode consultar o acervo da organização e, quando autorizado, arquivar conteúdo produzido. O acervo ainda não possui um guia próprio nesta documentação.
Capacidades geridas em outras seções
Section titled “Capacidades geridas em outras seções”Nem toda ferramenta do runtime é plugada na aba Ferramentas:
- Consultar Base de Conhecimento é ligada em Conhecimento quando bases são vinculadas ao agente.
- AutoLearn também é controlado em Conhecimento e registra oportunidades para revisão quando o agente não encontra uma resposta adequada.
- Buscar em conversas anteriores fica em Avançado, ligado por padrão. Só pode pesquisar título, tópicos e resumo das conversas individuais anteriores da própria pessoa com o mesmo agente no Hub; não lê mensagens, salas, conversas diretas entre pessoas, outros usuários ou outros agentes.
- Resposta privada do Instagram é disponibilizada automaticamente apenas durante um comentário do Instagram cuja caixa tenha Resposta privada por DM ativa. Ela não aparece no seletor do agente.
Blocos de contexto também ficam em Conhecimento, mas não são uma chamada de ferramenta: o conteúdo selecionado entra diretamente nas instruções do agente.
Ferramentas da organização não são nativas do seletor
Section titled “Ferramentas da organização não são nativas do seletor”- Composio conecta serviços de terceiros. Primeiro uma conta e suas ações são ativadas em Ferramentas no menu administrativo; depois a integração pode ser vinculada ao agente em Outras Ferramentas. Veja Ferramentas da organização.
- Ferramentas HTTP da organização são chamadas REST reutilizáveis. Elas aparecem em Ferramentas da Organização e também podem ser criadas pelo fluxo Nova Ferramenta quando a pessoa tem acesso. Veja Ferramentas HTTP Customizadas.
- Servidores MCP expõem um conjunto de ações descobertas. O seletor abre uma etapa para escolher quais ações daquele servidor serão anexadas ao agente.
O tipo técnico legado http_api continua registrado apenas para ferramentas HTTP antigas. Não adicione Chamada HTTP como se fosse uma opção nativa independente: crie ou escolha a ferramenta HTTP da organização.
Como o agente recebe e escolhe ferramentas
Section titled “Como o agente recebe e escolhe ferramentas”Em cada turno, o pipeline carrega somente vínculos ativos e monta os contratos que serão enviados ao modelo. Algumas ferramentas ainda têm requisitos de contexto: por exemplo, Tags do contato só funciona quando há um contato, Buscar em conversas anteriores só entra em uma conversa individual do Hub e Transferir Conversa oferece apenas rotas válidas naquele momento.
O modelo recebe o nome técnico, a descrição e os parâmetros — não uma garantia de que chamará a ferramenta. Para aumentar a previsibilidade:
- Mantenha apenas as ferramentas necessárias; cada contrato ocupa contexto.
- Em Prompt, abra o cartão de ferramentas ativas e copie a sugestão com a referência
{{tool:nome_tecnico}}quando houver. - Diga em que situação chamar a ferramenta, quais dados pode enviar e o que fazer em caso de erro ou resultado vazio.
- Em Modelo, use um modelo que suporte ferramentas. Os diagnósticos do prompt sinalizam um modelo incompatível.
- Ajuste Máximo de tool calls em Configurações Avançadas quando a tarefa precisar encadear várias ações.
- Salve e valide com Testar Agente antes de ligar um canal externo.
Um ponto verde confirma a configuração conhecida pela interface, não o sucesso de uma chamada real. O teste precisa cobrir entradas válidas, resultado vazio, falha externa e qualquer efeito persistente.
Ferramentas aposentadas
Section titled “Ferramentas aposentadas”- Intervenção Humana e Transferir para agente não aparecem para agentes novos. As definições continuam registradas apenas para abrir e remover vínculos legados. Use Transferir Conversa em novas configurações.
- Enviar Múltiplas Mensagens virou Dividir resposta em várias mensagens, em Configurações Avançadas.
- Finalizar conversa e Analisar satisfação foram retiradas do editor e do runtime; não as cite em prompts novos.