Ferramentas de chat

O Chat pode permitir que o modelo chame ferramentas. Um turno com elas ativadas executa um loop nativo de várias rodadas: o modelo solicita, o Libre WebUI executa sob a identidade e permissões do usuário, o resultado volta ao modelo e o loop continua até a resposta — no máximo oito rodadas e oito chamadas por rodada. Parar cancela a chamada do modelo, qualquer ferramenta em andamento e aprovações pendentes.

As chamadas são registradas como eventos normalizados (chat.tool-call.v1, chat.tool-result.v1, chat.approval.v1) que fluem igualmente pelo WebSocket privado e pelo stream durável. Atualizar ou reconectar reproduz o mesmo estado. O turno concluído guarda suas chamadas, com prévias limitadas dos resultados, na mensagem do assistente.

Ativar ferramentas

Elas ficam desativadas por padrão. Um administrador as abre em Configurações → Gerenciamento de Usuários (somente administradores ou todos). Cada turno então opta pelo ícone de chave inglesa no compositor, que abre um seletor com interruptor geral e uma caixa por ferramenta integrada e servidor. O turno usa exatamente as selecionadas. O seletor pode restringir o que um perfil vincula, nunca ampliar. Chats privados (anônimos) não oferecem ferramentas, pois uma chamada é uma ação externa que pode deixar aprovações e auditoria.

Um perfil de assistente (persona) pode limitar as ferramentas oferecidas: servidores vinculados, um subconjunto das integradas, habilidades e coleções de conhecimento restringem o que o modelo vê.

Ferramentas integradas

Treze ferramentas próprias acompanham o Chat. Todas são somente leitura, exceto as que alteram notas e calendário, sujeitas à aprovação por efeito colateral:

• web_search — mecanismo configurado pelo administrador, respeitando o modo de acesso à web.
• search_documents — busca híbrida em documentos e coleções, inclusive compartilhadas. Vínculos do perfil podem limitar coleções; cada passagem é citada com trecho e localização.
• list_documents — lista documentos no escopo com IDs, tipos e tamanhos para o modelo escolher.
• read_document — lê uma janela limitada por ID e deslocamento, rotulada com a origem.
• load_skill — carrega instruções completas de uma habilidade pelo slug. A descrição traz o manifesto das habilidades ativas, mantendo-as preguiçosas até serem necessárias. Arquivos auxiliares aparecem no inventário ao final.
• read_skill_file — lê um arquivo auxiliar pelo slug e caminho relativo, evitando custo de contexto até abri-lo.
• list_notes — lista notas próprias e compartilhadas com IDs.
• read_note — lê todo o conteúdo de uma nota por ID.
• create_note — cria uma nota (efeito colateral, exige aprovação).
• update_note — substitui conteúdo e preserva o estado anterior como revisão restaurável (efeito colateral, exige aprovação).
• list_calendar_events — lista eventos próprios e compartilhados em um intervalo epoch-millisecond.
• create_calendar_event — cria evento (efeito colateral, exige aprovação).
• delete_calendar_event — exclui evento por ID (efeito colateral, exige aprovação).

Servidores de ferramentas

Administradores registram servidores externos em Configurações → Ferramentas; modelos iniciais preenchem o formulário, inclusive com uma API pública segura de demonstração:

• OpenAPI: uma especificação JSON OpenAPI 3.x é obtida uma vez e fixada com SHA-256. Cada operação vira ferramenta; GET é somente leitura e as demais têm efeito colateral até um administrador sobrescrever por ferramenta. A execução reconstrói a chamada da operação fixada — os argumentos do modelo nunca escolhem o destino.
• MCP (Streamable HTTP): a lista é obtida por JSON-RPC e fixada da mesma forma. annotations.readOnlyHint marca leitura. MCP stdio não é suportado de propósito; processos externos não rodam dentro do processo web.

Um inventário alterado só entra em vigor quando o administrador atualiza o servidor, avançando a revisão e preservando substituições. A disponibilidade pode ser somente administradores, todos ou baseada em permissões a usuários/grupos pelo modelo comum.

Credenciais

Servidores autenticados usam credenciais por usuário (Bearer ou cabeçalho nomeado). Cada segredo é criptografado com dados autenticados adicionais que o vinculam ao usuário e servidor exatos, inserido por cada usuário em Configurações → Ferramentas e nunca compartilhado entre contas.

Política de saída

Cada solicitação resolve seu destino, recusa espaços privado, loopback e de metadados e fixa a conexão ao endereço resolvido para impedir DNS rebind. Redirecionamentos são recusados, respostas têm limite e cada chamada tem tempo máximo rígido. Hosts internos exatos podem ser permitidos em TOOLS_PRIVATE_NETWORK_ALLOWLIST (separados por vírgula); continuam fixados e limitados. A saída retorna ao modelo como texto não confiável.

Aprovações

Ferramentas de leitura executam sem perguntar. Uma com efeito colateral pausa o turno e oferece: permitir uma vez, neste chat, sempre para esta ferramenta neste servidor, ou negar. Decisões são duráveis; uma permissão "sempre" sobrevive a reinícios e pode ser revogada. Uma solicitação pendente expira em dois minutos, vista pelo modelo como negação. Negações e timeouts nunca executam a chamada. Cada decisão e chamada deixa um evento de auditoria com dados sensíveis removidos.

Exemplos

Primeiro ligue a chave inglesa no compositor; cada exemplo é uma mensagem normal.

web_search — pesquisar

O que mudou na versão mais recente do SQLite? Pesquise na web antes de responder.

O modelo chama web_search com algo como {"query": "SQLite latest release changelog"}; o cartão mostra os trechos recebidos e a resposta cita os achados. Exige busca configurada e permitida para a conta.

search_documents — consultar seus arquivos

Envie um PDF ou adicione documentos a uma coleção:

Procure a cláusula de rescisão nos meus documentos e cite-a exatamente.

O modelo chama search_documents com {"query": "termination clause"} e recebe passagens com o documento de origem.

load_skill — aplicar uma habilidade salva

Crie uma habilidade em Configurações → Habilidades (por exemplo $release-notes, com seu estilo). Depois:

Elabore notas desta diferença usando $release-notes.

O modelo vê o manifesto, chama load_skill {"slug": "release-notes"} e segue as instruções. Digitar $ autocompleta slugs.

Servidor OpenAPI — exemplo de clima

1. Configurações → Ferramentas → Registrar servidor: nome Weather, tipo OpenAPI, URL base https://api.example-weather.dev, URL da especificação https://api.example-weather.dev/openapi.json, autenticação bearer.

2. As operações aparecem como ferramentas, como getForecast (GET, leitura) e createAlert (POST, efeito colateral).

3. Cada usuário salva sua própria chave.

4. No chat:

   Qual é a previsão para Montreal neste fim de semana?

   O modelo chama weather__getForecast {"city": "Montreal"} imediatamente.

   Avise-me se cair abaixo de -20 esta noite.

   weather__createAlert pausa com um cartão: Permitir uma vez, Permitir neste chat, Sempre permitir ou Negar. Nada é enviado antes da escolha.

Servidor MCP — exemplo de rastreador de issues

1. Configurações → Ferramentas → Registrar servidor: nome Issues, tipo MCP, URL https://mcp.example-tracker.dev/mcp, autenticação header com X-Api-Key.

2. A lista é fixada; search_issues marcado como leitura executa livremente, enquanto create_issue pede aprovação.

3. No chat:

   Encontre issues abertas com "database lock" e registre uma nova resumindo o padrão.

   issues__search_issues executa; issues__create_issue mostra os argumentos exatos para revisão.

Variáveis de ambiente

Variável	Efeito
TOOLS_ACCESS_MODE	Fixa o recurso em admins ou all-users e bloqueia a chave administrativa.
TOOLS_PRIVATE_NETWORK_ALLOWLIST	Hosts exatos que podem resolver para endereços privados (lista por vírgulas).

Limites

• Chamadas rodam no caminho WebSocket (o transporte de sessão privada é excluído) e no caminho durável dos chats persistidos. O endpoint REST legado de streaming não executa o loop.
• Agentes do Work chamam os mesmos servidores pelo mesmo gateway: apenas execuções com rede, servidores sem credencial armazenada filtrados no momento da oferta e ferramentas com efeito colateral sujeitas às aprovações do Work.
• Modelos Gemini e agent CLI não recebem ferramentas; Ollama, OpenAI compatível, Responses-API e Anthropic recebem.
• Servidores MCP usam credenciais estáticas por usuário; um servidor apenas com OAuth interativo ainda não pode ser registrado.