Como conectar Copilot Studio ao ServiceNow via OAuth2

Por que ligar o Copilot Studio a uma base de conhecimento do ServiceNow

Times de suporte que já usam ServiceNow como sistema de registro têm um problema recorrente: o conhecimento técnico fica preso em artigos que só quem já sabe procurar encontra. Um agente do Copilot Studio conectado diretamente à base de conhecimento do ServiceNow resolve isso de um jeito específico, o agente responde citando o artigo oficial, não inventa procedimento e não depende de alguém ter copiado o conteúdo para um SharePoint paralelo que ninguém atualiza.

A mesma conexão OAuth2 que dá acesso de leitura à base de conhecimento também abre a porta para consultar tabelas estruturadas do ServiceNow, como a tabela de Incidents. Isso significa que o mesmo agente pode responder “como configuro resposta automática no Outlook” citando o artigo certo e, na sequência, mostrar ao usuário os cinco chamados mais recentes que ele abriu, sem que o usuário precise abrir o portal do ServiceNow para isso.

O ganho prático é reduzir o número de interações que hoje passam por um analista humano só para responder perguntas que já estão documentadas ou para consultar status de um chamado. O risco prático, que a maioria dos tutoriais não menciona, está em como a autenticação é configurada, porque isso determina se o agente respeita as permissões de cada usuário ou se acaba expondo dados de um jeito que ninguém pretendia. Vamos chegar nisso.

Como funciona a integração por trás dos panos

O Copilot Studio não acessa o ServiceNow com uma chave genérica solta no ar. A conexão é feita via OAuth2, com um registro de aplicação (application registry) criado dentro do próprio ServiceNow. Esse registro gera um client ID e um client secret, que o Copilot Studio usa para se autenticar como uma aplicação confiável perante a instância.

Depois de autenticado, o Copilot Studio pode fazer duas coisas com essa conexão: indexar a tabela Knowledge como fonte de conhecimento para respostas em linguagem natural, e executar operações de leitura ou escrita em tabelas estruturadas via conector nativo do ServiceNow, como List Records, Get Record, Create Record e Update Record. A tabela de Incidents é só um exemplo, o mesmo mecanismo serve para Change Requests, Problems ou qualquer tabela customizada exposta no instance.

Passo 1: criar o application registry no ServiceNow

Confirmar que sua conta tem papel de administrador

Configurar OAuth2 no ServiceNow exige papel de admin. Se você estiver testando em uma instância de desenvolvimento pessoal (developer.servicenow.com), clique no avatar no canto superior direito e selecione Change User Role. Defina o papel como Admin caso ainda não esteja. Em instância de produção corporativa, essa etapa normalmente já foi feita pelo time de plataforma e você só precisa confirmar que tem acesso ao módulo Application Registry.

Criar o registro OAuth2

Dentro do ServiceNow, abra o Creator Studio e vá até Application Registry, na aba All da navegação superior. Crie um novo registro escolhendo a opção Create an OAuth API endpoint for external clients, que é o tipo correto para uma aplicação externa como o Copilot Studio consumir a API do ServiceNow. Nomeie o registro de forma que qualquer pessoa da equipe de plataforma reconheça depois, algo como CopilotStudioSPN, e salve.

Coletar client ID, client secret e nome da instância

Na página de detalhes do registro recém-criado você encontra o Client ID e o Client Secret. Guarde os dois, você vai colar exatamente esses valores no Copilot Studio. O nome da instância não aparece nessa tela, ele é o subdomínio da URL do seu ServiceNow no navegador. Se sua instância é https://dev348343.service-now.com, o nome da instância para efeitos de conexão é dev348343.

Passo 2: o erro invalid redirect_uri (e como resolver de verdade)

Esse é o ponto onde a maioria das tentativas trava na primeira vez. O registro de aplicação no ServiceNow precisa de uma Redirect URL configurada manualmente, ela não vem preenchida por padrão. Para a maioria dos tenants americanos, o valor esperado é:

https://global.consent.azure-apim.net/redirect

O problema é que esse endereço com o subdomínio global só funciona para determinadas regiões do Azure. Se o seu tenant do Microsoft 365 está hospedado em outra região, geograficamente fora dos Estados Unidos, você vai receber o erro Invalid redirect_uri na hora de conceder consentimento OAuth2, mesmo com client ID e secret corretos.

A causa raiz é simples: o Copilot Studio tenta redirecionar o fluxo de consentimento para um subdomínio regional do serviço de API management da Microsoft (azure-apim.net), e esse subdomínio precisa bater exatamente com o que está cadastrado no ServiceNow. Quando aparece o erro, olhe a barra de endereço do navegador no momento da falha, ela vai mostrar qual subdomínio o Copilot Studio realmente tentou usar. Copie esse subdomínio e substitua no registro do ServiceNow. Um exemplo real: para um tenant no Canadá, o valor correto passou a ser https://canada-001.consent.azure-apim.net/redirect em vez de global. Depois dessa correção, o consentimento é concedido normalmente.

Vale registrar isso como um item de runbook para quem for replicar em outro tenant, porque o erro se repete toda vez que alguém segue a documentação genérica sem ajustar para a região correta do Azure.

Passo 3: criar o agente no Copilot Studio e conectar a base de conhecimento

Com o application registry pronto no ServiceNow, abra o Copilot Studio e crie um novo agente, por exemplo ServiceNow Agent. Vá até a aba Knowledge e adicione uma fonte de conhecimento do tipo ServiceNow.

Autorizando a conexão OAuth2

Escolha o tipo de autenticação Use OAuth2 e informe os três dados coletados no passo anterior:

• Nome da instância, por exemplo dev348343
• Client ID gerado pelo application registry
• Client Secret gerado pelo application registry

Ao confirmar, o ServiceNow exibe uma tela de consentimento, clique em Allow. Se aparecer o erro de redirect_uri descrito acima, resolva no ServiceNow antes de continuar, não adianta tentar de novo sem ajustar o registro.

Selecionando a tabela Knowledge

Após o consentimento bem-sucedido, o Copilot Studio lista as tabelas disponíveis na instância. Selecione a tabela Knowledge e clique em Add To Agent. Essa tabela armazena os artigos de conhecimento que existem no ServiceNow. Depois de adicionada, aguarde o status mudar para Ready, o Copilot Studio precisa indexar o conteúdo, e em bases de conhecimento grandes isso pode levar tempo considerável. Não tente testar o agente antes disso, as respostas virão incompletas ou vazias.

Testando a base de conhecimento

Antes de testar o agente, confira no próprio ServiceNow, na página Knowledge, quais artigos existem na instância, para saber o que esperar como resposta. Depois, no agente do Copilot Studio, faça uma pergunta que corresponda a um artigo real, por exemplo “como configuro resposta automática de ausência no Outlook”. O agente deve responder com base no conteúdo oficial e trazer a citação apontando para o artigo de origem no ServiceNow. Essa citação é o que diferencia uma resposta confiável de uma alucinação, e é o motivo de conectar a base de conhecimento em vez de simplesmente colar o texto dos artigos num prompt.

Passo 4: um tópico para listar os incidents recentes do usuário

Responder dúvidas técnicas é só metade do valor. A outra metade é deixar o usuário consultar o status dos próprios chamados sem sair da conversa. Para isso, vá até a aba Topics no Copilot Studio e crie um novo tópico chamado, por exemplo, Get My Recent ServiceNow Tickets. Use o gatilho Agent chooses e escreva uma descrição clara do que o tópico faz, algo como “este tópico retorna a lista dos chamados mais recentes que o usuário abriu no ServiceNow”. O Copilot Studio usa essa descrição para decidir quando acionar o tópico, então quanto mais específica, menor a chance de o agente confundir esse pedido com outra intenção.

Filtrando incidents pelo e-mail do usuário logado

Dentro do tópico, adicione um nó Add A Tool > Connector > List Records (ServiceNow), usando a mesma conexão OAuth2 já configurada para a base de conhecimento. Selecione a opção de credenciais do maker, para que o usuário final não precise autenticar manualmente toda vez que abrir uma conversa.

Na aba Input, defina o Record Type como Incident. O ponto importante aqui é o filtro: a tabela de Incidents guarda o solicitante no campo caller_id, que é uma referência à tabela User do ServiceNow, e é essa tabela User que tem o campo de e-mail. Para trazer só os chamados do usuário que está conversando com o agente, use uma query encadeada que filtra pelo e-mail e ordena do mais recente para o mais antigo:

"caller_id.email=" & System.User.Email & "^ORDERBYDESCopened_at"

Defina o limite de registros como 5, para não sobrecarregar a resposta com um histórico inteiro. Essa query é o coração de todo o tópico, se o filtro de e-mail estiver incorreto ou o campo caller_id.email não corresponder ao formato usado na sua instância, o agente vai retornar os últimos chamados abertos por qualquer pessoa, não os do usuário logado, que é exatamente o comportamento incorreto que alguns times relatam ao replicar essa configuração sem ajustar o nome do campo para o schema real do próprio ServiceNow.

Exibindo o resultado como lista

Adicione um nó de mensagem com o texto introdutório, por exemplo “Aqui está a lista dos seus chamados mais recentes:”. Em seguida, use uma fórmula Concat para montar a lista a partir do resultado do nó anterior:

Concat(Topic.IncidentGetRecords.result, number & ": " & short_description, "<br />")

Essa fórmula percorre cada registro retornado e monta uma linha com o número do chamado e a descrição curta, separando as linhas com quebra de linha HTML. O resultado é uma lista legível dentro do próprio chat, sem o usuário precisar abrir o portal do ServiceNow.

Preparando dados de teste no ServiceNow

Antes de testar, confirme que o usuário logado tem chamados registrados no ServiceNow com o mesmo e-mail da conta Microsoft 365 usada no teste. Em ambiente de desenvolvimento isso raramente é verdade de cara. Uma forma prática de testar é editar alguns registros na tabela Incidents, atribuindo o campo caller a um usuário fictício (por exemplo, “Joe Employee”), e depois editar o registro desse usuário na tabela Users para que o e-mail dele seja idêntico ao e-mail da conta Microsoft 365 que está testando o agente. Sem essa correspondência exata de e-mail, o filtro da query não vai retornar nada, e é fácil confundir isso com um bug na configuração quando na verdade é só ausência de dados de teste compatíveis.

Com o e-mail ajustado, salve o tópico e pergunte ao agente algo como “quais são meus chamados mais recentes de suporte”. A resposta esperada é uma lista com os cinco incidents mais recentes, do mais novo para o mais antigo, associados àquele e-mail.

Riscos e decisões de arquitetura que a documentação oficial não deixa claras

Credenciais de maker versus credenciais do usuário final

Essa é a decisão mais importante de toda a configuração e a que mais gera comportamento inesperado em produção. Usar credenciais do maker significa que todas as chamadas ao ServiceNow são feitas com a identidade de quem criou a conexão, não com a identidade de cada usuário que conversa com o agente. Isso simplifica o setup, o usuário final não precisa autenticar nada, mas coloca todo o controle de acesso na query do Power Fx, como a que filtra por caller_id.email. Se essa query tiver qualquer falha de lógica, um usuário pode acabar vendo chamados de outra pessoa.

Usar credenciais do usuário final resolve esse risco de segurança, porque cada chamada respeita as permissões nativas do ServiceNow para aquele usuário específico, mas exige que a pessoa tenha um papel com acesso via API no ServiceNow, além de autenticar dentro da própria conversa. Times que tentam essa abordagem sem atribuir o papel correto de API ao usuário costumam esbarrar em erro 401 (usuário não autenticado), e a tentação de resolver isso concedendo papel de API para toda a organização é um atalho perigoso, porque amplia a superfície de acesso direto à API do ServiceNow para muito além do que o agente realmente precisa. A decisão correta depende do apetite de risco da organização e de quão sensível é o conteúdo da tabela Incidents naquele ambiente específico, não existe resposta única.

User criteria do ServiceNow e vazamento de conteúdo restrito

A base de conhecimento do ServiceNow pode ter artigos restritos por user criteria, uma camada de controle de acesso nativa da plataforma que limita quem enxerga determinado artigo dentro do próprio portal. A conexão de knowledge base do Copilot Studio nem sempre respeita essa camada da mesma forma que o portal nativo respeitaria, porque a indexação passa pela conta usada na autenticação OAuth2, não necessariamente pela identidade de cada usuário que faz a pergunta no chat. Antes de liberar esse agente para produção, vale auditar se existem artigos com informação sensível protegidos por user criteria e confirmar, com um teste real, se um usuário sem permissão para aquele artigo consegue ou não recebê-lo como resposta do agente.

sys_id como pré-requisito para ações de escrita

Se a evolução natural do agente for permitir que o usuário atualize um chamado, por exemplo mudando o status ou adicionando um comentário, a ação Update Record do conector ServiceNow exige o sys_id do registro, não o número visível do incident. O nó List Records retorna esse campo internamente mesmo quando ele não aparece na mensagem exibida ao usuário, então planeje capturar o sys_id do registro certo em uma variável durante o fluxo de consulta, antes de tentar qualquer ação de escrita subsequente.

Ligar um agente do Copilot Studio ao ServiceNow parece, à primeira vista, uma questão de preencher três campos de conexão. Na prática, as decisões que determinam se essa integração é segura e confiável ficam nos detalhes de autenticação e nas queries de filtro, exatamente os pontos que costumam faltar em tutoriais genéricos. Se sua equipe está avaliando essa conexão para o helpdesk interno, vale desenhar esse fluxo de autenticação com calma antes de colocá-lo na frente dos usuários finais.