🌐 此页面尚未翻译为中文。显示葡萄牙语（BR）参考。帮助翻译。
Agentes Server Mode
O Agentes é o registro central de agentes de IA do RoqueOS, no espírito do Copilot Studio. Você define um agente uma vez (identidade, modelo de IA, instruções, skills e as ferramentas que ele pode usar) e o reutiliza em qualquer lugar. Cada agente é testável ao vivo enquanto você o desenvolve.
Por que isso é útil
Em vez de repetir a configuração do agente em cada lugar, você monta um agente rico num só lugar, com regras, conhecimento em pacotes (skills) e uma lista controlada de ferramentas, e o teste na hora. É a base para automações e fluxos agênticos mais avançados.
Requer Server Mode
O Agentes precisa de um RoqueOS Server conectado (é onde os agentes ficam salvos, com os segredos criptografados, e onde o executor roda). Veja Primeiros Passos para conectar um servidor, ou use o servidor DEMO pré-configurado para experimentar.
Criando um agente
Clique em + Novo e preencha:
- Nome, como o agente aparece na lista (ex.: "Pesquisador de Mercado", "Suporte Nível 1").
- Descrição (opcional), uma frase curta do que o agente faz, mostrada no card para você reconhecer e reutilizar o agente certo rapidamente. O "Gerar com IA" preenche isso pra você.
- Pasta (opcional), um rótulo para organizar o catálogo (ex.: "Vendas", "Suporte"). Agentes com o mesmo rótulo aparecem juntos sob um cabeçalho de pasta na lista, e uma pasta é criada só de dar um nome a ela. Sem rótulo, o agente fica na área sem pasta, no topo.
- Cor, um destaque para identificar o agente rapidamente.
- Modelo de IA, escolha entre os provedores de nuvem configurados (OpenAI, Anthropic, Google e outros) ou um LLM local. O modelo é obrigatório: um agente sem modelo não pode rodar, então o botão Salvar só habilita depois de escolher um. A chave usada é a do seu hub central de IA, a menos que você informe uma chave própria só para este agente.
- Instruções (regras), a persona e as regras que o agente deve sempre seguir (o "system prompt" dele).
- Skills, pacotes de instrução reutilizáveis anexados às regras. Cada skill tem um nome e um bloco de instruções; use-as para encapsular comportamentos ("Resumo executivo", "Tom formal") sem reescrever tudo. Você pode escrever a sua ou pegar uma pronta na biblioteca de skills (botão "Da biblioteca"): um painel que sobe de baixo com skills prontas agrupadas por categoria (Documentos: Word, apresentações, planilhas, PDF; Desenvolvimento: design de frontend, artefato web, servidor MCP; Criativo: guia de marca, arte generativa; Escrita e comunicação: resumir, revisar, traduzir, pesquisar, comunicação interna, atendimento), no espírito das Agent Skills da Anthropic. Toque numa para adicioná-la; ela entra como skill editável, no seu idioma.
Duplicando um agente
No menu ⋮ de um agente, Duplicar abre uma cópia no editor para você ajustar e salvar. A cópia só existe depois que você salvar. Duas coisas ficam com o original de propósito: a base de conhecimento (os trechos pertencem ao agente que os indexou) e uma chave de IA própria (o servidor nunca devolve uma chave salva). Se a cópia precisar delas, configure na cópia.
Ferramentas (allow-list)
Por padrão, um agente pode usar todas as ferramentas disponíveis. Ative Restringir ferramentas para escolher exatamente quais ele pode chamar, uma lista com dois grupos:
- Ferramentas do servidor (
roqueos_*), busca na web (o agente pesquisa na internet e cita as fontes); saúde do servidor; arquivos (listar, ler, escrever, criar pasta, renomear, mover, apagar e inspecionar); apps/containers (buscar no catálogo, listar, ver logs, iniciar, parar, reiniciar, instalar e desinstalar); e um terminal que roda um comando one-shot no seu container isolado. Cada uma indica a permissão que exige (ex.:filesystem:read,apps:write,terminal), e ações destrutivas (apagar, desinstalar, comando de shell) vêm sinalizadas. A busca na web precisa de uma chave (TAVILY_API_KEY) configurada no servidor; sem ela, a ferramenta avisa que não está configurada em vez de falhar. - Ferramentas do cliente (
desktop_*), abrir a janela de um app nativo, mostrar uma notificação na tela, etc.
Marcar só um subconjunto dá ao agente exatamente o alcance que você quer, nem mais, nem menos.
Conhecimento (memória do agente)
No editor de um agente já salvo aparece a seção Conhecimento: dê ao agente uma base própria de material para ele responder a partir dos seus documentos (RAG). Você pode:
- Enviar arquivos (clicando ou arrastando): PDFs, Word (.docx) e arquivos de texto (txt, md, csv, json, código…), vários de uma vez. O texto é extraído no seu navegador (PDFs pela mesma engine do Roque PDF, .docx via mammoth), então cada arquivo vira uma fonte de conhecimento indexada. Você vê o progresso de cada arquivo (adicionado, formato não suportado, sem texto, ou cortado no limite de 200 mil caracteres por fonte).
- Indexar um endereço da web: cole a URL de uma página (o domínio pelado já basta,
exemplo.comvirahttps://exemplo.com) e clique em Indexar. O servidor busca a página, descarta menu, rodapé e scripts, e guarda só o texto legível, com o título da página virando o nome da fonte. - Colar texto direto, com um título opcional.
Duas coisas o endereço da web recusa, e diz o porquê: uma página que só se monta por JavaScript (ou um muro de login, ou um erro) devolve quase nada e não vira fonte vazia, e endereços da rede interna são barrados, porque quem busca a página é o servidor, não o seu navegador.
Cada fonte é dividida em trechos e transformada em embeddings (precisa de uma chave OpenAI no seu hub de Provedores de IA). Na hora de rodar, o agente busca os trechos mais relevantes para a pergunta e os injeta no contexto, então ele responde com base no seu material. Remova uma fonte a qualquer momento.
Servidores MCP (ferramentas que não são nossas)
Um agente já sabe usar as ferramentas do RoqueOS (roqueos_*) e as do seu desktop (desktop_*). A seção Servidores MCP, no editor de um agente já salvo, dá a ele um terceiro conjunto: as ferramentas de um servidor MCP de terceiros.
MCP (Model Context Protocol) é o padrão que Notion, Linear, GitHub, Sentry e vários outros usam para expor as próprias funções a uma IA. Cole o endereço do servidor, o token dele, e as ferramentas aparecem na caixa do agente ao lado das nossas.
Como adicionar
- Dê um nome (é ele que vira o prefixo das ferramentas).
- Cole a URL do servidor (costuma terminar em
/mcp). - Cole os cabeçalhos de autenticação, um por linha (
Authorization: Bearer seu-token) ou como objeto JSON. - Conectar. O RoqueOS conecta na hora e diz quantas ferramentas encontrou. Se o endereço estiver errado ou o token recusado, você descobre ali, não depois.
O que esperar
- As ferramentas entram com o nome
mcp_<servidor>_<ferramenta>. O prefixo não é enfeite: sem ele, um servidor de terceiros poderia publicar uma ferramenta com o nome de uma nossa e responder no lugar dela. - No menu ⋮ de cada servidor: Reconectar (atualiza a lista de ferramentas), Desativar (mantém a configuração sem dar as ferramentas ao agente) e Remover.
- Um servidor fora do ar não derruba o agente. Ele é pulado e o agente responde com as ferramentas que sobraram, com o erro anotado na linha do servidor.
- O token fica criptografado no seu servidor e nunca é devolvido pela API; a tela mostra apenas que existe.
Limites atuais
- Só servidores remotos (Streamable HTTP). Servidores
stdio(que rodam como um comando local) não são suportados de propósito: seria o mesmo que executar um comando arbitrário dentro do seu servidor. - Endereços da rede interna são recusados, porque quem conecta é o seu servidor, não o seu navegador.
- As ferramentas de um servidor MCP não passam pela lista de ferramentas permitidas do agente: conectar o servidor é a permissão, e desativar ou remover é como você a retira.
Testando ao vivo
No editor de um agente salvo há o painel Testar agente: escreva uma mensagem, clique em Rodar, e o agente executa de verdade, com as instruções, skills e ferramentas configuradas, devolvendo a resposta e as ferramentas que ele acionou. Assim você itera na configuração vendo o efeito na hora.
Avançado
A seção Avançado permite associar credenciais de servidor específicas para o agente usar ao chamar as ferramentas roqueos_* (por padrão ele usa as do servidor conectado). Todos os segredos, chave de IA e credenciais de servidor, são criptografados em repouso e nunca retornados pela API.
Onde os agentes são usados
O registro de Agentes é a base do RoqueOS para IA agêntica. A ideia é definir o agente aqui e reutilizá-lo nas demais superfícies (Chat, Automações, Fluxos), com autoria por linguagem natural, voz, e reutilização em qualquer app de texto (Notas, Editor, Roque Code). Cada agente também pode virar um "modelo" usável em ferramentas externas via o gateway compatível com OpenAI.
Compartilhando um agente
Um agente que você cria é seu. Ninguém mais vê, usa ou edita até você compartilhar, o mesmo modelo do compartilhamento de arquivos do Finder.
Para compartilhar, abra o menu ⋮ do agente na lista e escolha Compartilhar. Informe com quem (o ID de usuário RoqueOS da pessoa) e escolha o nível de acesso:
| Nível | O que a pessoa pode fazer |
|---|---|
| Usar | Chamar o agente, sem ver as instruções, o modelo, o conhecimento nem qualquer chave |
| Ver | Usar e também ver como o agente foi configurado (as chaves continuam ocultas) |
| Editar | Usar, ver e alterar a configuração |
Apagar e recompartilhar continuam só com você, em qualquer nível. Nem quem tem "Editar" consegue excluir o seu agente ou repassá-lo para outra pessoa.
O que os outros compartilharam com você aparece na própria lista de Agentes, na faixa Compartilhados comigo, marcado com o nível de acesso recebido.
Removendo o acesso
No mesmo modal de compartilhamento você vê quem tem acesso e pode remover a qualquer momento. A remoção vale na hora: a próxima chamada da pessoa já é recusada. O registro fica guardado, então você continua sabendo quem teve acesso e quando foi retirado.
Se você excluir o agente, todos os compartilhamentos dele somem junto.
Perguntas frequentes
Preciso de chave de IA para criar um agente?
Para salvar um agente você escolhe um modelo do seu hub de IA; para o agente rodar (testar/usar), o modelo escolhido precisa ter uma chave configurada (de nuvem) ou um LLM local acessível. Configure seus provedores no hub de IA do RoqueOS.
Os segredos ficam expostos?
Não. Chave de IA e credenciais de servidor são criptografadas no servidor e a API só devolve uma indicação de que existem (nunca o valor).
Posso restringir o que o agente faz?
Sim, a allow-list de ferramentas define exatamente quais capacidades o agente pode usar. Sem restrição, ele pode usar todas.