Módulo IA

Nesta funcionalidade é possível conhecer os recursos de inteligência artificial do CITSmart X: o assistente de autoria no Studio, os passos de IA dentro do Robô, o diagnóstico de falhas, o servidor e o cliente MCP e o agente de operação.

A configuração central da IA é feita no Orquestrador, pelo menu de navegação: Configurar > Modelos de IA. Ela é descrita em Modelos de IA.

O CITSmart X não depende de um fornecedor de IA específico. O provedor é um cadastro, não uma configuração fixa do produto:

Os tipos de provedor aceitos no cadastro são anthropic, openai, azure-openai, google, deepseek, vllm, ollama, openai-compat e custom. Provedores acessíveis por interface compatível com OpenAI (gateways, vLLM, LM Studio e similares) usam o tipo openai-compat.

As chaves de API dos provedores ficam no cofre do Orquestrador. O cadastro do modelo guarda apenas o nome do ativo do cofre, e a chave não é exibida de volta em nenhuma tela. Detalhes em Segurança e privacidade da IA.

Para o restante do produto, consulte a documentação do Orquestrador e do Studio.

Nesta funcionalidade é possível cadastrar os provedores e modelos de IA usados pelo CITSmart X, definir qual modelo atende os assistentes, testar se cada modelo responde e acompanhar o gasto do dia.

A funcionalidade pode ser acessada através do menu de navegação: Configurar > Modelos de IA.

Tela Modelos de IA do Orquestrador

A imagem mostra a tela de uma instalação ainda sem modelo cadastrado. A tela é organizada em três blocos, de cima para baixo: Modelo padrão dos assistentes, Modelos cadastrados e Outras finalidades.

Para cadastrar um modelo é necessário:

Nota: Nos tipos ollama e vllm a chave é opcional. Um Ollama atrás de gateway autenticado exige a chave, que é enviada como Bearer.

Importante: Não sai da rede é uma declaração de governança. O cadastro recusa a marcação quando o endereço é remoto (são aceitos localhost, faixas de rede privada, .local e .internal).

Nota: A chave é gravada no cofre e o cadastro guarda apenas o nome do ativo, exibido no cartão como chave: <nome do ativo>. Remover um provedor mantém a credencial no cofre.

O bloco Modelo padrão dos assistentes mostra Hoje responde: / , se o modelo não sai da rede, quantas reservas existem e o gasto de hoje. Esse modelo atende o assistente do Studio e a coautoria pela API.

Para trocar o modelo é necessário:

Nota: Enquanto nenhum modelo estiver definido, a tela exibe Nenhum modelo definido e o pedido de ajuda no Studio é recusado por falta de rota.

Para limitar o gasto do assistente é necessário:

Quando o teto é atingido, o assistente é recusado com a razão e volta a atender no dia seguinte.

Nota: O gasto é estimado a partir dos preços cadastrados para cada modelo e serve como referência de grandeza, não como fatura do provedor. O contador diário fica em memória e é zerado se o Orquestrador for reiniciado.

Cada cartão em Modelos cadastrados exibe o nome, o tipo, o endereço, os modelos e as ações editar, provar e desligar (ou ligar, quando desligado).

Nota: Ao editar a lista de modelos, os que já existiam mantêm preço e ajustes.

A tabela Outras finalidades lista as rotas que ligam uma finalidade (extrair-documento, classificar, diagnostico, resumir, agente, embeddings) a um provedor e modelo, com a pasta e o gasto de hoje. Finalidades que nenhuma parte do produto chama ainda são sinalizadas na tela com o aviso de que a escolha fica gravada e não é usada.

Nota: Rotas, tetos por chamada, reservas e a exigência de IA local por pasta (aiLocalOnly, definida na criação da pasta) são configurados pela API do Orquestrador (/api/ai/routes, /api/folders); a tela cobre o modelo dos assistentes, o teto diário e o cadastro dos provedores.

Nota: Na primeira inicialização, se existirem variáveis de ambiente NEXO_AI_* e nenhum provedor cadastrado, a configuração é migrada para um provedor, e a chave vai para o cofre.

Nesta funcionalidade é possível descrever em português o que se deseja em um Robô ou em uma Orquestração e receber do assistente uma proposta de documento, com o resumo do que muda e os problemas encontrados pelo validador. A pessoa lê a proposta e decide se aplica no editor.

A funcionalidade pode ser acessada através do menu de navegação: Studio > painel direito > aba Assistente. A aba existe no editor de Robô e no editor de Orquestração.

Aba Assistente do Studio

Há um modelo cadastrado e definido como modelo dos assistentes em Configurar > Modelos de IA (veja Modelos de IA). O cabeçalho da aba mostra o provedor e o modelo que responde; sem modelo definido, ele exibe "modelo definido no cadastro de LLMs".

O cabeçalho da aba exibe o campo sobre, que indica o alvo do pedido: o robô inteiro (ou a orquestração inteira) quando nenhum passo está selecionado, ou o nome do passo selecionado no canvas.

Para pedir uma alteração é necessário:

Nota: O assistente trabalha sobre o documento que está na tela, inclusive com alterações ainda não salvas. Não há memória de conversas anteriores.

A Proposta exibe o modelo que respondeu, o tempo, o resumo das mudanças (o diff), avisos e, se houver, o bloco O validador recusaria: com os problemas encontrados.

Para aplicar a proposta é necessário:

Importante: Aplicar no editor apenas carrega o documento no editor e o marca como não salvo. O assistente nunca publica. A publicação continua sendo um passo separado, com validação, assinatura e trilha de auditoria.

Nota: Se o documento for alterado depois do pedido, o Studio recusa aplicar a proposta e exibe a mensagem de que o documento mudou. Nesse caso, faça um novo pedido.

Nota: É possível aplicar uma proposta que o validador recusaria, por exemplo, para corrigir um campo diretamente no editor. Os problemas são exibidos acima do botão para que a decisão seja consciente.

O mesmo recurso é oferecido pela API do Orquestrador (POST /api/ai/coauthor/process e POST /api/ai/coauthor/plan), que gera rascunhos listados em GET /api/ai/drafts e aceitos ou descartados em POST /api/ai/drafts/:id/accept e POST /api/ai/drafts/:id/discard. Aceitar um rascunho usa a publicação normal e exige a permissão process:publish; rascunho inválido não pode ser aceito.

Nota: O custo do assistente é contabilizado na finalidade coautoria. Veja Trilha de prompt e conjunto de referência e Segurança e privacidade da IA.

Nesta funcionalidade é possível usar modelos de linguagem e servidores MCP como passos de um Robô, para classificar, resumir, extrair campos de texto solto, interpretar imagens ou chamar ferramentas de sistemas externos.

A funcionalidade pode ser acessada através do menu de navegação: Studio > paleta de atividades > categoria IA.

Paleta de atividades do Studio com a categoria IA

A categoria IA reúne quatro atividades: Perguntar a uma IA, Ver imagem com IA, Listar ferramentas MCP e Chamar ferramenta MCP. A extração de campos com IA fica na categoria Documentos.

Importante: Os passos de IA não são agentes. Eles recebem um pedido e devolvem uma resposta, e o que se faz com ela é o passo seguinte do Robô. O modelo responde sempre, inclusive quando não sabe: confira a resposta no passo seguinte.

Envia um pedido em português para um modelo e grava a resposta em uma variável.

Para usar a atividade é necessário:

Nota: Mantenha Criatividade em 0 para que a mesma entrada produza a mesma resposta. No formato JSON, descreva no comando quais campos deseja. Um tamanho máximo curto demais corta a resposta e quebra o objeto JSON.

Envia uma ou mais imagens a um modelo que enxerga e faz uma pergunta sobre elas. Diferente do OCR, que apenas transcreve, aqui o modelo interpreta a imagem.

Para usar a atividade é necessário:

Nota: São aceitas apenas extensões de imagem, com limite de aproximadamente 4,5 MB por imagem. Para PDF, use Ler PDF (texto) seguido de Perguntar a uma IA.

A atividade Extrair campos com IA (categoria Documentos) pede ao modelo campos sem padrão fixo, como partes de um contrato. Os campos informados em Campos, com Instrucoes opcionais, passam pelos mesmos validadores de CPF, CNPJ, chave de NFe, boleto e datas. O campo que não fecha perde confiança e vai para revisão. Use a saída needsReview para desviar para a revisão humana. O limiar padrão é 0,8 e a finalidade usada é extrair-documento.

Consomem servidores MCP que a empresa já possui. Veja MCP: servidor e cliente.

Nota: Se o Robô não alcançar um modelo, a atividade falha com a mensagem de que o Robô não tem como falar com um modelo de linguagem. Confira se o Orquestrador está acessível e se há modelo cadastrado.

Nesta funcionalidade é possível usar o protocolo MCP (Model Context Protocol) nos dois sentidos: permitir que um assistente externo consulte a operação do CITSmart X e permitir que um Robô chame ferramentas de servidores MCP que a empresa já possui.

A funcionalidade de servidor é ligada na política da instalação do Orquestrador. A funcionalidade de cliente pode ser acessada através do menu de navegação: Studio > paleta de atividades > IA > Listar ferramentas MCP / Chamar ferramenta MCP.

O Orquestrador expõe o endpoint POST /mcp (transporte HTTP, JSON-RPC 2.0). Um assistente conectado pode, por exemplo, responder "por que o fechamento falhou?" sem que a pessoa copie logs.

O endpoint não é uma porta de trás: usa a mesma autenticação, as mesmas permissões, o mesmo escopo de pastas e a mesma trilha de auditoria das demais rotas. A lista de ferramentas mostra apenas o que o usuário conectado pode usar.

O servidor vem desligado (o endpoint responde 404). Para ligá-lo é necessário:

Importante: Ler a operação e disparar produção são decisões de risco diferentes. Mantenha allowWrites desligado a menos que seja necessário. Ligar o MCP e a escrita fica registrado na trilha de auditoria.

Nota: Não existem ferramentas para responder tarefa humana, forçar sucesso, liberar execução segurada ou publicar processo. Essas decisões ficam com pessoas e com os fluxos próprios.

Nota: As respostas saem mascaradas conforme a política de dados pessoais da instalação. Recursos fora do escopo do usuário respondem como inexistentes. Leituras por MCP não geram linha na trilha de auditoria; as escritas e as recusas de segurança geram.

As atividades de MCP permitem que um Robô use ferramentas de servidores MCP próprios da empresa (ERP, service desk, data lake) sem conector novo.

Para chamar uma ferramenta MCP é necessário:

Importante: Prefira a credencial do cofre a colocar o token em campo do processo, pois os campos ficam no pacote publicado.

Nota: Cada chamada abre a própria conexão, sem sessão persistente entre passos.

Nesta funcionalidade é possível auditar o uso da IA (qual modelo foi chamado, para quê, com que custo e tempo) e comparar modelos usando casos de teste com resposta esperada antes de trocar o modelo de uma finalidade.

Os recursos são oferecidos pela API do Orquestrador, na seção /api/ai, e pela política da instalação. Não há tela dedicada.

Toda chamada de IA feita pelo produto é registrada pelo Orquestrador, inclusive as recusadas (teto estourado, pasta que exige IA local, provedor que recusou), com o provedor nomeado.

Para consultar o consumo é necessário:

Cada registro traz provedor, modelo, finalidade, tokens, custo estimado, duração, erro (quando houve), promptHash e promptChars.

Por padrão o conteúdo do prompt e da resposta não é guardado. Para guardá-lo é necessário alterar o bloco prompt da política (PUT /api/policy):

Importante: O prompt pode conter o documento inteiro, com dados pessoais. Ligar logPrompts é uma decisão de quem responde pela instalação. O texto guardado passa pelo mesmo mascaramento aplicado nas telas e é marcado como mascarado quando houve acerto.

Nota: Mesmo com logPrompts desligado, o hash e o tamanho do prompt são gravados. O prompt nunca entra na trilha de auditoria permanente; esta registra apenas o ato (provedor, modelo, tokens, custo e tempo).

Um conjunto de referência é um grupo de casos, cada um com um prompt e a resposta esperada, ligado a uma finalidade. Ele permite rodar os mesmos casos em modelos diferentes e ver o que piorou antes de trocar o modelo.

Para criar e usar um conjunto é necessário:

A comparação responde quais casos pioraram, melhoraram e ficaram iguais, com o custo e o tempo dos dois lados.

Nota: Falha do provedor conta como caso reprovado. O histórico guarda um resultado por provedor e modelo, o mais recente, com no máximo dez. Rodar o conjunto gera custo, que aparece na trilha.

Nota: Criar, rodar e remover conjuntos exige policy:manage; consultar e comparar exige policy:read.

Nesta funcionalidade é possível ver quais defeitos mais se repetem nas execuções e pedir à IA um diagnóstico de uma falha, com hipótese, evidências citadas, próximo passo, categoria e grau de confiança.

A funcionalidade pode ser acessada através do menu de navegação: Entender > Falhas.

Tela Falhas do Orquestrador

A tela exibe o período selecionado (24h, 7 dias, 30 dias ou 90 dias), a quantidade de falhas, a quantidade de defeitos distintos e, em O que mais quebra, os grupos de falhas.

As falhas são agrupadas por assinatura: números de nota, identificadores, datas, caminhos de arquivo, endereços e valores são normalizados, de modo que mensagens que só diferem por esses dados contam como o mesmo defeito. Cada grupo mostra quantas vezes ocorreu (por exemplo, 12×), a mensagem de exemplo, os processos, os passos, a quantidade de Robôs afetados, a última ocorrência e, quando metade ou mais das ocorrências se concentra em um horário, o padrão de horário.

Esse agrupamento é feito sem IA e não exige modelo cadastrado.

Para diagnosticar um defeito é necessário:

O diagnóstico é feito sobre o job mais recente do grupo. O modelo recebe o erro, o passo que quebrou, a duração em relação ao padrão do processo, a reincidência, os argumentos do job e o fim do log.

Importante: O log e os argumentos são enviados ao provedor de IA já mascarados pela política de dados pessoais. Se a área exige IA local, o diagnóstico usa apenas provedor local.

Nota: A IA propõe uma hipótese. Ela não conserta, não reexecuta e não fecha alertas. Quando o material não permite concluir, a confiança é baixa e a resposta informa qual informação falta.

Nota: Somente jobs com falha (Faulted) são diagnosticados. O resultado fica guardado no job, e um novo clique só gera nova chamada em diagnosticar de novo.

Nota: Se não houver modelo para a finalidade diagnostico, a tela exibe Não foi possível diagnosticar com a orientação para cadastrar um provedor e uma rota. Veja Modelos de IA.

O diagnóstico exige a permissão de leitura de job (job:read), para que o operador de plantão possa usá-lo. O gasto é controlado pelo teto de custo da rota diagnostico e entra na trilha de prompt.

Nesta funcionalidade é possível acompanhar o agente de operação do CITSmart X, que identifica falhas e propõe uma ação de remediação, com a evidência que a sustenta. A pessoa aprova ou recusa, ou o agente executa sozinho apenas o que a política da instalação permite.

A funcionalidade pode ser acessada através do menu de navegação: Entender > Agente.

O agente propõe; a política decide. A escolha da ação é feita por um mapa fixo de sintomas para ações e não por um modelo de IA. O diagnóstico do modelo entra apenas como evidência.

A faixa Autonomia mostra o nível vigente e o que ele permite. Abaixo, Esperando você lista as propostas que exigem decisão, O que o agente fez lista o histórico e O que ele PODE fazer apresenta o catálogo de ações.

Cada proposta mostra a ação, o nível de risco, o sintoma, os motivos (incluindo, quando houver, quantas vezes a ação resolveu o mesmo caso antes) e o motivo de estar esperando.

Para decidir uma proposta é necessário:

Nota: Aprovar e recusar exigem a permissão job:run.

O catálogo é fechado e o risco de cada ação é declarado.

A autonomia é definida na política da instalação (PUT /api/policy, bloco remediacao, com autonomia, maxPorHora e bloqueadas) e pode ser definida por pasta (remediacaoPorPasta). Alterar a política exige a permissão policy:manage.

Importante: Ação irreversível nunca roda sozinha, em nenhuma configuração. Ligar a autonomia é a mudança de política de maior efeito e fica registrada na trilha de auditoria. Ative-a somente depois de revisar algumas propostas.

Nota: Há limites contra excesso de propostas: uma proposta por combinação de sintoma, alvo e ação, um teto por hora por pasta e um teto por ciclo. Estourar o teto não silencia o agente. O agente considera execuções das últimas seis horas, inclusive as já terminadas em falha.

Nota: O aviso ao plantão sai pelo webhook de eventos, com o evento agente.proposta. O catálogo e a política estão em GET /api/remediation/catalog.

Nesta funcionalidade é possível transformar imagens e PDFs digitalizados em texto, que pode então ser classificado, extraído por regras ou enviado a um modelo de IA.

A funcionalidade pode ser acessada através do menu de navegação: Studio > paleta de atividades > Documentos.

O OCR é feito localmente pelo Tesseract. A imagem não é enviada a provedor de IA nessas atividades.

Para usar OCR é necessário:

Nota: O texto reconhecido é um palpite do reconhecedor. Confira o que for crítico antes de gravar em um sistema. Um número muito baixo de caracteres costuma indicar imagem ruim.

Nota: Se o PDF tem camada de texto, use Ler PDF (texto), que é exato e não exige Tesseract. Jobs que exigem a capacidade ocr só são atribuídos a máquinas onde o Tesseract foi detectado.

Cada campo extraído sai com uma confiança. Campos abaixo do limiar (padrão 0,8) ficam marcados e a saída needsReview indica a necessidade de revisão. A atividade Revisar extracao transforma os campos duvidosos em uma tarefa humana com o formulário já preenchido. Para a extração por IA, o validador tem a última palavra: campo que não fecha o dígito verificador perde confiança, por mais segura que seja a resposta do modelo.

Importante: Na extração com IA, o texto do documento (até 24000 caracteres) é enviado ao provedor configurado para a finalidade extrair-documento. Para dados que não podem sair da rede, use um provedor marcado como Não sai da rede. Veja Segurança e privacidade da IA.

Nesta funcionalidade é possível entender como o CITSmart X protege as chaves de API dos provedores, o que é enviado ao provedor de IA, como manter dados dentro da rede, como limitar o gasto e o que fica registrado para auditoria.

As configurações descritas aqui estão em Configurar > Modelos de IA, na política da instalação do Orquestrador e no cadastro de pastas. Veja também Modelos de IA.

Ao usar um provedor em nuvem, o conteúdo enviado em cada recurso é:

Importante: Não coloque segredos em campos de Robôs ou em pedidos ao assistente. O assistente não lê valores de ativos do cofre, mas o conteúdo do documento em edição é enviado ao modelo.

O diagnóstico de falha, as respostas do servidor MCP e o conteúdo guardado na trilha de prompt passam pelo mesmo mascaramento de dados pessoais usado nas telas, definido na política da instalação. Os demais pedidos seguem como foram montados pelo Robô ou pela pessoa.

Nota: Recursos de IA recusados por configuração ausente, teto atingido ou falha do provedor retornam, respectivamente, os códigos 409, 429 e 502.