Copilot connectors e grounding: como o Copilot passa a enxergar dados fora do Microsoft 365

O helpdesk de uma empresa de energia com 3.000 usuários mantinha 1.200 artigos de base de conhecimento em um sistema de chamados fora do Microsoft 365. Quem precisava redefinir o token da VPN perguntava ao Copilot, recebia uma resposta genérica da web e abria chamado. O artigo certo existia, em um sistema que o Copilot não via. Depois de um conector sincronizado, a mesma pergunta passou a devolver o passo a passo do artigo, com link para a origem, e só para quem tinha permissão de ler aquele artigo no sistema de chamados.

Este post explica como isso funciona: o que o conector faz, como a permissão chega ao Copilot, como registrar uma conexão pela Graph API e quando um conector é a escolha errada.

O que é grounding e o que fica fora dele

Grounding é o passo em que o Microsoft 365 Copilot (a documentação mais recente o chama de Microsoft Copilot) busca conteúdo relevante antes de mandar o prompt ao modelo. Com a licença, ele busca no Microsoft Graph: e-mails, reuniões, chats e arquivos do SharePoint e do OneDrive aos quais o usuário já tem acesso, organizados pelo semantic index. O que mora em outro sistema fica fora dessa busca, e o modelo responde com conhecimento geral ou com a web.

Um Copilot connector registra uma fonte externa no Graph. Cada conteúdo vira um item externo, com propriedades (título, link, data, autor), um texto para busca e uma lista de controle de acesso. A partir daí, o item entra nos mesmos lugares em que um arquivo do SharePoint entra: Copilot Chat, Copilot nos apps, Copilot Search e agentes declarativos que usem a conexão como conhecimento.

Sincronizado ou federado

A documentação separa dois tipos. O conector sincronizado rastreia a origem, copia o conteúdo para o índice e o atualiza por rastreamentos completos e incrementais. É o caso da base de conhecimento do helpdesk: os artigos mudam pouco, e vale tê-los no índice, pesquisáveis a qualquer hora. O conector federado consulta a origem no momento da pergunta, sem cópia, usando o Model Context Protocol (MCP), e serve para dado que muda a toda hora.

A licença segue o tipo. Segundo a página de licenciamento de junho de 2026, conectores sincronizados indexam sem custo extra para tenants com licenças do Microsoft 365. Conectores federados exigem licença Microsoft 365 Copilot (ou Microsoft 365 E7) para cada usuário que faz a consulta. O limite de itens incluído por tenant não aparece na página atual, e a FAQ do Copilot Search diz apenas que conectores podem gerar custos adicionais. Antes de indexar milhões de registros, confira a tabela oficial, nas fontes.

Conectores prontos e conector personalizado

A galeria da Microsoft lista mais de 100 conectores prontos, da própria Microsoft e de parceiros, configurados no centro de administração do Microsoft 365, sem código: ServiceNow, Salesforce, Jira, Azure DevOps, Confluence, compartilhamentos de arquivos, sites corporativos e bancos SQL, entre outros. Você informa a credencial, escolhe as tabelas ou objetos, mapeia as propriedades e define como a permissão da origem vira ACL.

Quando a fonte é um sistema interno sem conector pronto, ou quando você precisa de controle total sobre o que entra, o caminho é o conector personalizado pela Graph API. São três chamadas: criar a conexão, registrar o schema e enviar os itens. O código abaixo é o esqueleto do caso do helpdesk, sem segredos e com comentários em português. Ele exige um app registrado no Entra, com as permissões de aplicativo indicadas em cada bloco e consentimento de administrador.

1. Criar a conexão

// POST https://graph.microsoft.com/v1.0/external/connections
// Permissão de aplicativo: ExternalConnection.ReadWrite.OwnedBy
{
  // 3 a 32 caracteres, só letras e números, único no tenant
  "id": "helpdeskkb",
  "name": "Base de conhecimento do helpdesk",
  "description": "Artigos internos do helpdesk, sincronizados a cada hora"
}

A conexão é o contêiner dos itens. O id precisa ter de 3 a 32 caracteres alfanuméricos, ser único no tenant e não pode começar com "Microsoft" nem usar nomes reservados como SharePoint ou Teams. O nome de exibição aceita até 128 caracteres e é o que o usuário vê como fonte na citação.

2. Registrar o schema

// PATCH https://graph.microsoft.com/v1.0/external/connections/helpdeskkb/schema
// Responde 202 Accepted com um cabeçalho Location para acompanhar a operação.
// A documentação fala em 5 a 15 minutos até o schema ficar pronto.
{
  "baseType": "microsoft.graph.externalItem",
  "properties": [
    // Labels semânticos dizem ao Copilot o que é título, link, ícone e data.
    // Toda propriedade com label precisa ser retrievable.
    { "name": "title", "type": "string", "isSearchable": true, "isRetrievable": true, "labels": ["title"] },
    { "name": "url", "type": "string", "isRetrievable": true, "labels": ["url"] },
    { "name": "iconUrl", "type": "string", "isRetrievable": true, "labels": ["iconUrl"] },
    { "name": "lastModified", "type": "dateTime", "isRetrievable": true, "labels": ["lastModifiedDateTime"] },
    { "name": "autor", "type": "string", "isRetrievable": true, "isQueryable": true, "labels": ["createdBy"] },
    // Propriedade própria, sem label. Refinável e pesquisável são excludentes:
    // esta serve de filtro, e o texto do artigo fica em content.
    { "name": "categoria", "type": "string", "isQueryable": true, "isRefinable": true, "isRetrievable": true }
  ]
}

O schema define as propriedades de cada item (até 128) e o que o índice faz com elas: searchable entra na busca por texto, queryable permite filtro por valor, refinable permite refinar resultados e retrievable devolve o valor na resposta. Duas regras costumam surpreender quem está começando. Uma propriedade não pode ser refinável e pesquisável ao mesmo tempo. E só propriedades retrievable recebem label.

Os labels semânticos (title, url, iconUrl, lastModifiedDateTime, createdBy e outros) dizem ao Copilot qual propriedade é o título, qual é o link para citar e qual é a data. A documentação recomenda aplicar todos os que o schema permitir, e trata title como o mais importante. Sem eles, o item pode até ser encontrado, mas a resposta sai sem o link para a origem ou com o título errado. Depois de registrado, o schema aceita propriedades novas; tornar uma propriedade refinável depois ou mudar a capacidade de busca exige nova ingestão dos itens.

3. Enviar um item

// PUT https://graph.microsoft.com/v1.0/external/connections/helpdeskkb/items/kb00123
// Permissão de aplicativo: ExternalItem.ReadWrite.OwnedBy
// id do item: só letras e números, até 128 caracteres. Payload de até 30 MB.
{
  "acl": [
    // Só quem está aqui vê o item no Copilot. Replique a permissão da origem.
    // Tipos: user, group, everyone, everyoneExceptGuests, externalGroup. deny vence grant.
    { "type": "group", "value": "f1a2b3c4-5d6e-4f70-8a9b-0c1d2e3f4a5b", "accessType": "grant" },
    { "type": "user", "value": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "accessType": "deny" }
  ],
  "properties": {
    "title": "Como redefinir o token da VPN",
    "url": "https://helpdesk.exemplo.com.br/kb/kb00123",
    "iconUrl": "https://helpdesk.exemplo.com.br/favicon.png",
    "lastModified": "2026-10-28T14:00:00Z",
    "autor": "Equipe de Suporte N1",
    "categoria": "Acesso remoto"
  },
  "content": {
    // text ou html. É este texto que o índice pesquisa e o Copilot lê para responder.
    "type": "text",
    "value": "1. Abra o portal de autoatendimento. 2. Em Dispositivos, escolha Redefinir token. 3. Confirme no app autenticador..."
  }
}

Cada item vai por PUT com o próprio id. A ACL é uma lista de entradas com tipo (user, group, everyone, everyoneExceptGuests ou externalGroup), valor (o id do objeto no Entra) e accessType grant ou deny, com deny prevalecendo. É aqui que a permissão da origem precisa ser traduzida. No helpdesk, cada artigo tinha um grupo de leitores no sistema de chamados; o conector mapeou esses grupos para grupos do Entra e mandou a ACL correspondente. Quando a origem usa grupos que não existem no Entra, o tipo externalGroup permite declarar o grupo no Graph e listar os membros.

O campo content recebe o texto que o índice pesquisa e que o Copilot lê para montar a resposta, como texto puro ou HTML. Para artigos longos, mande o texto inteiro, sem truncar: é dele que sai a citação.

Connector ou agente com ação

Connector resolve "onde está a informação". Ele leva conteúdo pesquisável ao índice e deixa o Copilot citá-lo em qualquer pergunta. Agente com ação, construído no Copilot Studio ou no Agent Builder, resolve "faça isso agora": consulta um sistema em tempo real ou executa uma operação com a credencial do usuário. O saldo do pedido, o status do chamado de hoje e a abertura de um chamado novo são ações. O artigo que explica como abrir o chamado é connector.

Os dois caminhos se combinam. No helpdesk, o agente de suporte interno usa a conexão do conector como conhecimento (o Agent Builder aceita Copilot connectors como fonte) e uma ação para abrir o chamado quando o artigo não resolve. O usuário faz a pergunta e recebe o passo a passo com citação; se responder "não funcionou", o agente abre o chamado já com o artigo tentado no histórico.

O próximo passo prático é escolher uma fonte pequena e valiosa: uma base de conhecimento, um catálogo de produtos, um conjunto de políticas. Veja se existe conector pronto na galeria; se existir, configure no centro de administração e observe o que o Copilot passa a responder. Se for personalizado, comece com 100 itens e a ACL real, confira quem vê o quê com dois usuários de permissões diferentes e só então ligue a sincronização completa. Se quiser ajuda para desenhar isso com os sistemas da sua empresa, a consultoria em Copilot Studio cobre conectores e agentes, e o curso de Copilot Studio tem o módulo de conhecimento e ações.