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.

Cuidado

O SDK do agente incorporado do SharePoint anterior (o controle ReactChatEmbedded) foi preterido em março de 2026 e substituído pelo Microsoft Foundry Agent Service com uma fonte de conhecimento do SharePoint (versão prévia) configurada para o SharePoint Embedded. Use uma das duas opções neste artigo para um novo trabalho.

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.

Observação

O suporte à API de recuperação para a sharePointEmbedded fonte de dados está em versão prévia.

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.

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

Last updated on 2026-08-13