Conectar-se a fontes de conhecimento personalizadas

O Copilot Studio inclui fontes de conhecimento integradas, como o SharePoint e o Dataverse. Muitas organizações também utilizam seus próprios pontos de extremidade de pesquisa, como APIs personalizadas, sistemas de busca empresarial existentes ou Pesquisa de IA do Azure , mantendo controle total sobre a consulta que é executada.

O Copilot Studio oferece suporte a esse cenário com o gatilho OnKnowledgeRequested. Qualquer tópico que utilize esse gatilho atua como uma fonte de conhecimento personalizada e contribui com resultados para respostas generativas.

Este artigo explica como criar e integrar fontes de conhecimento personalizadas no Copilot Studio utilizando o gatilho OnKnowledgeRequested. Você aprende como o Copilot Studio reescreve consultas, como conectar à sua própria API de busca, como formatar resultados para respostas generativas e melhores práticas ao trabalhar com conhecimento personalizado.

O gatilho OnKnowledgeRequested

Use o gatilho OnKnowledgeRequested nessas duas situações:

  • Quando o orquestrador determina que a recuperação de conhecimento é necessária para responder a uma consulta do usuário.
  • Quando um nó de resposta generativa é explicitamente acionado na conversa.

Importante

Você só pode configurar esse gatilho na exibição de código usando YAML. Não há suporte para designer visual.

Os tópicos que utilizam OnKnowledgeRequested têm acesso a variáveis do sistema que não estão disponíveis em tópicos regulares:

  • System.SearchQuery: uma versão reescrita sensível ao contexto da consulta do usuário, otimizada para pesquisa semântica.
  • System.KeywordSearchQuery: uma consulta reescrita otimizada para mecanismos de busca por palavras-chave.
  • System.SearchResults: onde o tópico armazena trechos de conhecimento formatados.

O Copilot Studio reescreve as consultas de forma inteligente usando o histórico de conversas, garantindo que ele preserve o contexto de várias rodadas.

Criando uma fonte de conhecimento personalizada

Para criar uma fonte de conhecimento personalizada, você cria um tópico com o gatilho OnKnowledgeRequested que chama sua API de busca e adapta os resultados ao formato exigido pelo Copilot Studio.

Etapa 1: criar o gatilho

Criar o novo tópico no Copilot Studio, alterne para exibição do código e defina o gatilho OnKnowledgeRequested.

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  intent: {}
  actions:
    # Actions go here
inputType: {}
outputType: {}

Essa estrutura informa ao Copilot Studio que este tópico é responsável por atender solicitações de conhecimento.

Etapa 2: adicionar uma solicitação HTTP

Adicione uma ação HTTP que chame seu ponto de extremidade de pesquisa.

Exemplo:

- kind: HttpRequestAction
  id: searchRequest
  url: = "https://search-api.contoso.com/search?q=" & System.KeywordSearchQuery
  response: Topic.searchResults
  responseSchema:
    kind: Record
    properties:
      query: String
      results:
        type:
          kind: Table
          properties:
            snippet: String
            title: String
            url: String

Concatene System.KeywordSearchQuery à sua URL base porque o Copilot Studio reescreve automaticamente a consulta do usuário com o contexto da conversa antes de fazer a solicitação de pesquisa. Essa etapa é importante para manter o contexto em conversas com várias rodadas.

Dica

Em vez de uma solicitação HTTP bruta, você pode usar qualquer método que obtenha resultados de um ponto de extremidade de pesquisa, incluindo conectores personalizados, conectores integrados como a Pesquisa de IA do Azure ou fluxos de agente.

Exemplo de reescrita de consultas

  • Consulta do usuário 1: “Qual é o nosso período de retenção de dados oficial para registros de clientes?”
  • Consulta de acompanhamento: “Isso muda para informações financeiras?”
  • Consulta de acompanhamento: “E há exceções?”

A consulta reescrita se torna: “exceções à política de retenção de dados, exceções de retenção de dados de clientes e de informações financeiras, isenções regulatórias, tratamento de exceções, diretrizes de conformidade”

Observe que a consulta reescrita:

  • Resolve "lá" a política de retenção de dados
  • Extrai o contexto das interações anteriores: dados do cliente + dados financeiros
  • Inclui termos de política empresarial: exceções, isenções, aspectos regulatórios, diretrizes

Etapa 3: transformar resultados

Uma fonte de conhecimento personalizada deve fornecer resultados no formato esperado pelo Copilot Studio. Este formato usa:

  • Conteúdo: trecho ou fragmento.
  • ContentLocation (opcional): URL.
  • Título (opcional): Título do resultado.

Para definir a estrutura da resposta HTTP, configure o esquema de resposta na interface do usuário do Copilot Studio.

  • Selecione Dados de exemplo - De para o tipo de dados de resposta.
  • Selecione Obter esquema de um JSON de exemplo.
  • Cole o conteúdo JSON de exemplo para gerar automaticamente o esquema.

Esse processo gera o esquema de resposta no seu arquivo YAML.

responseSchema:
  kind: Record
  properties:
    query: String
    results:
      type:
        kind: Table
        properties:
          snippet: String
          title: String
          url: String

Em seguida, adapte a resposta da sua API para este formato. Atribua os dados transformados a System.SearchResults.

Transformação de exemplo

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  intent: {}
  actions:
    - kind: HttpRequestAction
      id: searchRequest
      url: ="https://search-api.contoso.com/search?q=" & System.KeywordSearchQuery
      response: Topic.searchResults
      responseSchema:
        kind: Record
        properties:
          query: String
          results:
            type:
              kind: Table
              properties:
                snippet: String
                title: String
                url: String
    
    - kind: SetVariable
      id: setSearchResults
      variable: System.SearchResults
      value: |-
        =ForAll(Topic.searchResults.results,
        {
          Content: snippet,
          ContentLocation: url,
          Title: title
        })

inputType: {}
outputType: {}

A ação SetVariable realiza ambas as operações:

  • A função ForAll transforma cada resultado de pesquisa, mapeando snippet para Content, url para ContentLocation e title para Title.
  • A tabela transformada é atribuída a System.SearchResults, que é a variável que o Copilot Studio usa para gerar respostas.

Considerações

Tenha estas principais considerações em mente ao criar fontes de conhecimento personalizadas.

Limite de resultados

O Copilot Studio utiliza até 15 trechos de System.SearchResults para gerar uma resposta. Se sua API retornar mais resultados, considere:

  • Implementar pontuação de relevância para devolver os melhores resultados primeiro.
  • Limitando a resposta da sua API a 15 resultados.
  • Ordenando os resultados por relevância antes da transformação.

Vários tópicos de conhecimento personalizado

Você pode criar vários tópicos usando OnKnowledgeRequested, e cada tópico pode consultar diferentes sistemas de back-end. O Copilot Studio invoca todos eles simultaneamente quando precisa de conhecimento. Essa abordagem permite consultar diferentes pontos de extremidade de pesquisa ou implementar estratégias de fallback.

Aviso

O limite de resultados se aplica ao conjunto de todos os tópicos de conhecimento. Se o Tópico A retornar 10 resultados e o Tópico B retornar 8, apenas os 15 melhores resultados combinados serão usados.

Recomendações

  • Ordene ou pontue os resultados antes de retorná-los.
  • Mantenha os esquemas de resposta consistentes.
  • Use nomes e descrições claras para os tópicos. Essa prática é útil quando grandes conjuntos de resultados exigem filtragem de relevância.
  • Last updated on