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 → Acesso e políticas → Acesso a ferramentas (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.

O interruptor Acesso a ferramentas salva imediatamente. Clique nele ou use Tab para focá-lo e Space para alterná-lo. Mudar o acesso mantém a janela de Configurações e sua posição de rolagem no lugar.

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.

OAuth interativo (MCP)

Um servidor MCP também pode autenticar cada pessoa individualmente. Registre-o com o modo de autenticação OAuth interativo e o Libre WebUI lê o desafio WWW-Authenticate que o servidor devolve, segue até os metadados do recurso protegido, depois até os metadados do servidor de autorização, e registra um cliente dinamicamente (RFC 7591) quando o servidor de autorização oferece registro. Provedores que não registram clientes automaticamente recebem um ID de cliente fornecido pelo administrador, e um segredo opcional, no formulário de registro; o segredo é criptografado junto com os endpoints descobertos.

Cada pessoa então clica em Conectar no cartão do servidor e é redirecionada ao provedor. O fluxo usa PKCE (S256) com estado CSRF, e o verificador PKCE fica em um cookie HttpOnly restrito a esse servidor. O callback troca o código no servidor, armazena os tokens criptografados com o mesmo vínculo de usuário e servidor usado para um segredo estático, e devolve o navegador ao app com um sinalizador de status — os tokens de acesso e atualização nunca chegam à página. Os tokens de acesso são renovados automaticamente um minuto antes de expirar, uma vez por pessoa e servidor mesmo quando várias chamadas de ferramenta competem entre si. Quando a renovação não é possível, a chamada de ferramenta retorna pedindo para reconectar em vez de falhar silenciosamente. Desconectar remove os tokens dessa pessoa e mantém o registro; excluir o servidor também esquece a configuração descoberta.

Um servidor que recusa listar ferramentas sem autenticação ainda assim é registrado: seu inventário é fixado na primeira conexão bem-sucedida (e em qualquer atualização feita pelo administrador), então nada é oferecido a um modelo antes de ser conhecido.

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.

Exa MCP — pesquisar e buscar na web

Em Configurações → Ferramentas → Comece com um modelo, escolha Exa para preencher um registro MCP com:

https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa

A URL seleciona web_search_exa e web_fetch_exa pelo parâmetro de seleção de ferramentas da Exa. O modelo não usa autenticação e limita o acesso a administradores por padrão. Revise o formulário e selecione Salvar para conectar e fixar o inventário de ferramentas. Abrir ou cancelar o modelo não contata a Exa. As consultas de pesquisa e as URLs solicitadas são enviadas à Exa quando essas ferramentas são executadas.

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.
• Menções de @model em canais executam o mesmo loop contra o catálogo do membro que mencionou, com uma diferença: não há ninguém para perguntar, então uma ferramenta com efeito colateral sem uma aprovação permanente é recusada de imediato, em vez de esperar. Ferramentas de leitura executam normalmente.
• 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.
• O OAuth interativo é exclusivo do MCP: um servidor OpenAPI continua usando uma credencial estática por usuário. O fluxo é o de concessão por código de autorização com PKCE; os fluxos de código de dispositivo e de credenciais do cliente não são oferecidos, e um servidor de autorização que não publica metadados (ou não tem endpoint de registro nem ID de cliente fornecido pelo administrador) não pode ser conectado.
• Os endpoints de OAuth descobertos precisam ser https; http simples só é aceito para loopback, para um provedor rodando na mesma máquina durante o desenvolvimento.
• O URI de redirecionamento é derivado de BASE_URL (ou do primeiro CORS_ORIGIN), então esse valor precisa ser o endereço que o navegador realmente alcança e precisa estar registrado junto a provedores que fixam URIs de redirecionamento.