Ferramentas da Organização

A página Ferramentas (/admin/tools) reúne as capacidades externas que a organização pode oferecer aos agentes. Ela administra integrações do catálogo da Composio, ferramentas HTTP/API que chamam um endpoint próprio e servidores MCP que publicam um conjunto de ferramentas.

Ativar uma ferramenta na organização não a adiciona automaticamente aos agentes. A ativação define o que pode ser usado; cada agente recebe apenas as ferramentas, contas e ações escolhidas na sua própria configuração.

Acesso e permissões

A rota exige Visualizar ferramentas. O contrato de permissões é:

• Visualizar ferramentas: consultar integrações, contas e configurações;
• Criar e editar ferramentas: ativar e conectar integrações, editar ações e criar ou alterar ferramentas HTTP/API e servidores MCP;
• Excluir ferramentas: remover integrações e ferramentas customizadas.

Limitação atual de permissões

Algumas ações de conta e seleção ainda aparecem — e podem ser aceitas — para membros que têm apenas Visualizar ferramentas. Até a correção do produto, conceda essa permissão somente a pessoas autorizadas a gerenciar integrações. Um usuário somente leitura também deve evitar os checkboxes da aba Disponíveis, que podem causar um erro na interface.

Abas Ativas e Disponíveis

A página tem duas abas com contadores:

• Ativas: integrações já ativadas para a organização, conectadas ou aguardando autenticação, além das ferramentas customizadas;
• Disponíveis: catálogo de integrações da Composio ainda não ativadas.

Use a busca para filtrar pelo nome. A aba Disponíveis também tem paginação; a interface atual não oferece um seletor de ordenação.

Na aba Ativas, as integrações da Composio aparecem em grupos de Conectadas e Desconectadas. Uma ferramenta recém-ativada que ainda precisa de credenciais mostra Aguardando autenticação.

Ativar e conectar uma integração da Composio

Ativação e autenticação são etapas separadas:

1. Abra Disponíveis e procure a integração.
2. Selecione o card para abrir Configurar ferramenta.
3. Se houver mais de um método de autenticação, escolha o método exibido.
4. Clique em Ativar. A integração passa para Ativas.
5. Abra a integração ativa e clique em Conectar agora.
6. Quando a ferramenta exigir credenciais, conclua a autorização ou o preenchimento na página segura hospedada pela Composio. Ao finalizar, o navegador retorna ao SquadOS e a conta aparece em Contas.

Ferramentas sem autenticação são conectadas diretamente, sem página externa. Se o fluxo externo for abandonado antes de terminar, nenhuma nova conta conectada é criada.

Se uma integração estiver marcada como Aguardando configuração, a configuração de autenticação da plataforma ainda precisa ser concluída por um superadministrador antes que a organização possa conectá-la.

Gerenciar contas

Uma integração pode ter várias contas, como dois endereços do Gmail ou dois workspaces do Slack. Abra uma ferramenta ativa e consulte Contas. Cada linha mostra o nome da conta e seu estado, que pode ser ativo, pendente ou com erro.

No menu de ações de uma conta você pode:

• Renomear para deixar claro qual agente ou equipe deve usá-la;
• Reconectar para substituir a credencial daquela mesma conta;
• Desconectar para revogar a conexão sem remover a integração da organização;
• Remover para excluir a conta e retirar seu vínculo dos agentes;
• usar Adicionar conta para conectar outra conta do mesmo serviço.

Reconecte pela conta correta

Use Contas → Ações → Reconectar na linha da conta. Esse fluxo preserva a identidade da conta e suas atribuições aos agentes. O botão geral Reconectar no topo da ferramenta tem uma limitação conhecida e pode criar uma conta paralela.

Remover a integração inteira também remove seus vínculos com os agentes. Revise o impacto antes de confirmar.

Limitar ações disponíveis

Uma integração pode expor muitas ações. Na ferramenta ativa, use Editar ações para definir quais ficam disponíveis para a organização:

1. abra a integração na aba Ativas;
2. clique em Editar ações;
3. selecione pelo menos uma ação e salve.

Essa seleção é o limite máximo da organização. Depois, na configuração de cada agente, você escolhe somente as ações que aquele agente deve usar. Quando a organização não define uma lista, todas as ações publicadas pela integração ficam disponíveis para seleção no agente.

Adicionar a ferramenta a um agente

Depois de preparar a ferramenta no nível da organização:

1. abra o agente e entre na seção Ferramentas;
2. escolha Adicionar ferramenta;
3. selecione a integração, ferramenta HTTP/API ou servidor MCP;
4. para Composio, escolha a conta e as ações permitidas para o agente;
5. para MCP, escolha quais ferramentas descobertas o agente pode usar;
6. salve o agente e teste uma solicitação que exija a ferramenta.

O agente nunca recebe automaticamente todas as capacidades ativadas. Prefira o menor conjunto de ações necessário para a função dele.

Ferramentas HTTP/API customizadas

Na seção Ferramentas Customizadas da aba Ativas, clique em Nova Ferramenta e escolha Ferramenta HTTP / API. O formulário permite definir:

• nome de exibição, nome interno e descrição de uso;
• URL e método GET, POST, PUT, PATCH ou DELETE;
• autenticação sem credencial, bearer token, chave de API ou header customizado;
• parâmetros pelo editor visual ou por JSON Schema;
• corpo JSON, headers e valores fixos ou fornecidos pela IA no path e na query;
• timeout entre 1 e 300 segundos;
• envio opcional de metadados da conversa e da identidade do lead.

Credenciais são armazenadas no servidor e não devem ser escritas na descrição, no schema ou em valores públicos. Use o painel de teste antes de salvar.

Editar uma ferramenta já usada por agentes exibe um aviso. A remoção pode ser bloqueada enquanto houver agentes vinculados; retire primeiro esses vínculos.

Servidores MCP

Em Nova Ferramenta, escolha Servidor MCP. Informe nome, descrição, instruções de uso, URL terminada em /mcp, autenticação quando necessária e se a identidade do lead pode ser enviada ao servidor.

Clique em Conectar e descobrir. O SquadOS testa a conexão e lista as ferramentas publicadas pelo servidor. Ao adicionar o MCP a um agente, selecione somente o subconjunto descoberto que ele precisa usar.

Ações em lote

Os checkboxes permitem Ativar várias integrações em Disponíveis ou Desconectar e Remover em Ativas. A barra acompanha o processamento item a item. Essas ações alteram integrações da organização e devem ser usadas apenas por quem tem a permissão correspondente.

Diagnóstico rápido

• Aguardando configuração: um superadministrador precisa configurar a autenticação da integração na plataforma.
• Aguardando autenticação: abra a ferramenta e use Conectar agora.
• Conta com erro: reconecte pelo menu da própria conta, não pelo botão geral.
• Ferramenta ausente no agente: confirme que ela está ativa na organização, que a conta está conectada e que a ferramenta ou ação foi adicionada ao agente.
• MCP sem ferramentas: execute Conectar e descobrir novamente e confirme a URL, a autenticação e a disponibilidade do servidor.
• HTTP/API falhando: teste URL, método, autenticação, parâmetros, corpo e timeout no formulário da ferramenta antes de testar pelo agente.