Adicionar experiências de agente e Microsoft 365 Copilot

Aplica-se a: Desenvolvedor

As experiências de agente do SharePoint Embedded permitem que seu aplicativo responda a perguntas sobre arquivos armazenados em contêineres do SharePoint Embedded. Dois produtos separados fundamentam essas experiências no conteúdo do contêiner:

• Microsoft Foundry Agent Service com uma fonte de conhecimento do SharePoint — para agentes que você constrói no Foundry. Foundry executa a recuperação para você como parte do agente. Para obter as etapas de configuração, consulte Configurar o SharePoint Embedded como uma fonte de conhecimento do Foundry.
• API de recuperação do Microsoft 365 Copilot — para agentes personalizados e aplicativos que executam suas próprias etapas de aterramento. Chame-o de qualquer aplicativo, incluindo um agente do Foundry que não usa a fonte de conhecimento do SharePoint.

Escolha a fonte de conhecimento quando quiser que o Foundry gerencie a recuperação e a orquestração do agente. Escolha a API de recuperação quando quiser controlar a etapa de aterramento, o prompt e o modelo por conta própria.

Como o SharePoint Embedded fundamenta os agentes

O SharePoint Embedded fundamenta os agentes de IA no conteúdo corporativo, mantendo esse conteúdo e seus controles de conformidade dentro do locatário do Microsoft 365 do cliente. Você não copia conteúdo para um banco de dados vetorial externo. Fatos importantes:

• A descoberta de conteúdo é uma configuração no tipo de contêiner que determina se o Microsoft 365 Copilot pode exibir o conteúdo. A governança de locatário controla essa configuração, portanto, um aplicativo não pode expor o conteúdo alterando sua própria configuração.
• Recupere conteúdo com a API de Pesquisa da Microsoft, com escopo pela ID de tipo de contêiner (ContainerTypeId) ou com uma fonte de conhecimento do Foundry SharePoint.
• O conteúdo permanece no locatário do Microsoft 365 do cliente, portanto, a DLP (prevenção contra perda de dados), a retenção e a Descoberta Eletrônica do Microsoft Purview se aplicam.
• Nada é exposto automaticamente. O conteúdo inserido do SharePoint não está disponível para o Copilot até que a detectabilidade esteja habilitada no tipo de contêiner.

Para o contexto de decisão, consulte IA terrestre sem um banco de dados de vetor externo.

Usar a API de recuperação

A API de recuperação do Microsoft 365 Copilot retorna trechos de texto relevantes que seu aplicativo passa para seu próprio modelo como dados de base. Defina dataSource como sharePointEmbedded para recuperar do conteúdo inserido do SharePoint.

Pré-requisitos da API de recuperação

• Um aplicativo incorporado do SharePoint com pelo menos um contêiner, além da ID do tipo de contêiner.
• Cobrança paga conforme o uso configurada para o tipo de contêiner.
• Pelo menos um usuário no locatário com uma licença do Microsoft 365 Copilot, portanto, o índice semântico é inicializado. Para obter mais informações, consulte Índice semântico do Microsoft 365 Copilot.

A sharePointEmbedded fonte de dados cobra o pagamento conforme o uso, portanto, cada usuário que consulta a API de recuperação não precisa de uma licença individual do Microsoft 365 Copilot.

Recuperar conteúdo de um tipo de contêiner

Chamada POST /copilot/retrieval com um token delegado. Defina dataSource como e passe a sharePointEmbedded ID do tipo de contêiner em dataSourceConfiguration. A solicitação precisa da FileStorageContainer.Selected permissão delegada e o serviço corta os resultados para o conteúdo que o usuário conectado pode acessar.

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "What are the terms of the Contoso agreement?",
  "dataSource": "sharePointEmbedded",
  "dataSourceConfiguration": {
    "sharePointEmbedded": {
      "containerTypeId": "{containerTypeId}"
    }
  }
}

Substitua {containerTypeId} pela ID do tipo de contêiner.

A resposta retorna uma retrievalHits coleção. Cada ocorrência identifica um arquivo webUrl de origem e carrega um ou mais extracts, ordenado por relevanceScore.

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.com/spe/file",
      "extracts": [
        {
          "text": "The agreement renews annually unless either party gives 30 days' notice.",
          "relevanceScore": 0.8421
        }
      ]
    }
  ]
}

A forma de webUrl depende da configuração do tipo de urlTemplate contêiner, portanto, trate-o como um link opaco em vez de analisá-lo. Para resolver detalhes do arquivo, chame Get a driveItem. Para obter mais informações sobre urlTemplate, consulte Criar e configurar um tipo de contêiner.

Para retornar campos extras, como title ou author com cada ocorrência, adicione uma resourceMetadata coleção à solicitação. Solicite apenas os campos que seu aplicativo usa, pois cada campo é adicionado ao conteúdo de resposta.

Recuperação de filtro por metadados personalizados

Use filterExpression para limitar a recuperação a arquivos com metadados personalizados específicos. Primeiro, crie uma coluna personalizada indexada, defina os valores do arquivo e aguarde a conclusão da indexação da pesquisa. Para obter instruções, consulte Armazenar e consultar metadados de contêiner.

O SharePoint Embedded armazena os valores de coluna personalizados de um arquivo em seu recurso associado listItem/fields . Filtros de recuperação na propriedade gerenciada do SharePoint indexada da coluna, não no nome do campo armazenado.

Por exemplo, uma coluna de texto de linha única chamada ClientMatterCode normalmente tem esta propriedade gerenciada:

ClientMatterCodeOWSTEXT

As propriedades gerenciadas criadas automaticamente são propriedades de texto, mesmo quando suas colunas de origem usam outro tipo de dados. O sufixo e o formato do valor indexado dependem do tipo da coluna. Confirme o nome da propriedade gerada e o formato do valor no locatário de destino. Para obter detalhes de nomenclatura, consulte Propriedades gerenciadas criadas automaticamente no Servidor do SharePoint.

Essa solicitação limita os candidatos a arquivos com um valor exato de metadados indexados. Ele também retorna o valor com cada acerto correspondente:

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json

{
  "queryString": "What obligations are described in the client agreement?",
  "dataSource": "sharePointEmbedded",
  "dataSourceConfiguration": {
    "sharePointEmbedded": {
      "containerTypeId": "{containerTypeId}"
    }
  },
  "filterExpression": "ClientMatterCodeOWSTEXT=\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"",
  "resourceMetadata": [
    "title",
    "containerTypeId",
    "ClientMatterCodeOWSTEXT"
  ],
  "maximumNumberOfResults": 10
}

Use = quando o valor indexado completo deve corresponder:

ClientMatterCodeOWSTEXT="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"

Não use o : operador para um limite exato. O operador de dois pontos executa a correspondência de termos e pode corresponder valores ou prefixos relacionados. Para obter mais informações, consulte Referência de sintaxe da linguagem de consulta QL por palavra-chave.

O filtro limita os arquivos candidatos antes queryString das classificações de extrações semanticamente relevantes. Um arquivo com metadados correspondentes pode não aparecer quando seu conteúdo não está relacionado a queryString.

Passe as extrações para seu próprio modelo ou etapa de geração de resposta como dados de base. Este trecho envia a consulta e lê o extrato principal de cada ocorrência:

const response = await fetch("https://graph.microsoft.com/v1.0/copilot/retrieval", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    queryString: query,
    dataSource: "sharePointEmbedded",
    dataSourceConfiguration: {
      sharePointEmbedded: { containerTypeId: containerTypeId }
    }
  })
});

const data = await response.json();
const grounding = (data.retrievalHits ?? []).map(hit => ({
  url: hit.webUrl,
  text: hit.extracts?.[0]?.text?.trim(),
  score: hit.extracts?.[0]?.relevanceScore
}));

A recuperação abrange todos os contêineres do tipo de contêiner que o usuário conectado pode acessar. Se uma solicitação não retornar resultados, confirme se o índice semântico foi inicializado, se a indexação foi concluída e se o usuário tem acesso ao conteúdo.

Cobrança da API de recuperação

Solicitações de API de recuperação que usam a fatura da sharePointEmbedded fonte de dados no medidor de mensagens do Copilot Studio. Os encargos seguem o modelo de cobrança configurado para o tipo de contêiner. A cobrança Standard cobra a assinatura do Azure do locatário proprietário e a cobrança de passagem cobra a assinatura do locatário consumidor.

Para obter detalhes do medidor, consulte Medidores de faturamento. Para comparar modelos, consulte Escolher um modelo de cobrança.

Testar experiência do usuário

Entre com um usuário que possa acessar o conteúdo do contêiner. Carregue arquivos com suporte em um contêiner, aguarde a indexação, abra o chat e faça perguntas que o conteúdo do arquivo possa responder. Se as respostas omitirem os arquivos esperados, marque:

• Detectabilidade.
• Formatos de arquivo com suporte.
• Acesso ao aplicativo.
• Acesso do usuário.
• Seleção de escopo.
• Atraso de indexação.

Próximas etapas

• Configurar o SharePoint Embedded como uma fonte de conhecimento Foundry
• Contadores de faturação
• Escolha um modelo de cobrança