Implementar Insights de conversa

Para produzir dados de conversa como Eventos de experiência XDM e garantir que esses eventos de experiência de conversa terminem no Adobe Experience Platform como conjuntos de dados, instrumente seu aplicativo de agente ou serviço para usar Insights de conversa.

Este artigo documenta as etapas de implementação necessárias.

Esquema e conjuntos de dados

Configurar conjuntos de dados para os eventos principais de conversa: prompt, resposta, feedback. Os conjuntos de dados de prompt, resposta e feedback devem estender o esquema base do Evento de Experiência XDM com o grupo de campos Evento de Conversa e podem incluir, opcionalmente, o grupo de campos Informações de Agente e outros grupos de campos adicionais.

Você pode definir conjuntos de dados separados para prompts, respostas e feedback ou combinar dados em conjuntos de dados. Por exemplo, use um conjunto de dados para prompts e respostas e outro conjunto de dados para feedback. Ou use um conjunto de dados separado para cada tipo de evento de conversa, conforme ilustrado em Como funciona.

Para ilustrar, use:

O layout do conjunto de dados e a entrega de eventos de conversa nesses conjuntos de dados são preocupações separadas. Envie cada evento de conversa assim que os dados estiverem disponíveis, para garantir identificadores de conversa estáveis e identificadores de conversão. Identificadores estáveis facilitam a correlação adequada pelo serviço de Misturador de Conversas entre conjuntos de dados.

Grupo de campos de Evento de conversa

O grupo de campos Evento de Conversa é um grupo de campos obrigatório e usa o objeto conversation.

O objeto de conversa captura dados para:

Conversa

Um conversationID exclusivo identifica uma conversa. Por exemplo: conversationID = "conv-001". O conversationID permite que todos os eventos de turnos relacionados sejam agrupados na mesma experiência de conversação.

O esquema também oferece suporte a conversationName. Um nome legível que descreve o contexto geral da conversa, como: France Geography Q&A. O nome da conversa é gerado automaticamente, mas você pode atualizar o nome gerado. O nome da conversa também é preenchido para signals[].name. O Adobe preenche conversationName com o mesmo valor que o sinal signals[].name = “title”. Você pode definir o conversation.conversationName em qualquer conjunto de dados preenchido e substituir o valor fornecido pela Adobe.

Girar

Um turno é um ciclo de interação dentro de uma conversa.

turnID Um único turnID identifica uma vez. Por exemplo:

conversationID = "conv-001"
turnID = "turn-001"

Os mesmos conversationID e turnID são usados para correlacionar o prompt, a resposta e o feedback associados a esse turno. Essa correlação funciona em registros fornecidos separadamente ou que acabam em conjuntos de dados diferentes. Um turnId só precisa ser exclusivo na mesma conversa, mas pode ser reutilizado em conversas. Por exemplo, você pode ter turn-001 como turnID em conversas com conversationID conv-001 e conv-002.

Aviso

Um prompt é a entrada enviada para o agente. Na maioria dos cenários de clientes, essa entrada é a pergunta, a solicitação, a instrução ou a mensagem do usuário.

O prompt usa a seguinte representação: conversation.prompt

Os campos de prompt importantes incluem:

Um prompt pode conter vários segmentos brutos. Por exemplo, um usuário insere texto e inclui um URL.

Resposta

Uma resposta é o conteúdo retornado pelo agente ou por outra parte respondente.

conversation.response Um responseID exclusivo representa a resposta.

Os campos de resposta importantes incluem:

Os tipos de origem documentados incluem:

Feedback

O feedback é a avaliação ou reação explícita do usuário à interação.

A estrutura de comentários inclui: conversation.feedback.

Exemplos:

O intervalo de pontuação de classificação documentado é de -1.0 a 1.0.

Um evento de comentários pode ser representado como um evento somente de comentários usando: eventType = "conversation.feedback".

Quando o feedback se aplicar a um turno específico, preserve os conversationID e turnID apropriados para que o misturador de conversação possa associar o feedback à interação relevante.

Sinal

Um sinal é uma observação analítica estruturada sobre o conteúdo da conversa. O serviço de extração de sinal fornece sinais prontos para uso. Nenhuma ação é necessária para fornecer sinais, mas você pode adicionar sinais como parte da integração do.

Um sinal tem os seguintes campos.

O serviço de extração de sinal preenche o objeto signals para o conjunto de dados de sinais.

O contêiner signals[].attributes.{subjects,intents,tones,sentiment} anterior está obsoleto.

Tipo de Source

Você precisa definir um valor para source para cada objeto prompt, response ou feedback em um evento. Qualquer valor é aceitável. Use valores que ajudam a entender de onde os dados se originam. Por exemplo:

Tipo de finalidade (texto bruto)

Você precisa definir um valor para o atributo purpose em qualquer elemento do objeto raw em um objeto prompt, response ou feedback. Qualquer valor de string é aceitável. Esse campo é usado para diferenciar o que é armazenado no texto bruto. Valores úteis estão abaixo, outros valores são igualmente válidos:

Conversa

Consulte abaixo para obter os detalhes completos de um objeto de conversa.

Grupo de campos Informações do Agente

O grupo de campos Informações da Agência é um grupo de campos opcional e usa o objeto agenticExperience. Considere usar esse grupo de campos se desejar rastrear informações de agente.

Para implementar eventos que propagam o grupo de campos Informações sobre Agentes com dados, você deve garantir:

{
  "_id":"a33e1068-3966-468b-8682-e5e493827ffe",
  "timestamp":"2026-09-11T00:03:15Z",
  "eventType":"agent.interaction",
  "identityMap":{
    "ECID":[
      {
        "id": "12345678901234567890123456789012345678",
        "primary": true
      }
    ]
  },
  "agenticExperience":{
    "conciergeID":"concierge-abc123",
    "name":"Customer Support Experience",
    "version":"1.0.0",
    "environment":"dev",
    "mode":"preview",
    "agents":[
      {
        "agentID":"agent-001",
        "name":"Chatbot Assistant",
        "version":"2.1.3",
        "score":0.92
      },
      {
        "agentID":"agent-002",
        "name":"Voice Assistant",
        "version":"3.0.0",
        "score":0.88
      }
    ],
    "skills":[
      {
        "skillID":"skill-intent-recognition",
        "skillInvocationID":"inv-9f2a-001",
        "name":"Intent Recognition",
        "version":"1.0.0",
        "agentID":"agent-001",
        "invocationSource":"main",
        "score":0.95,
        "failed":false,
        "sequenceNumber":1,
        "timestamp":"2026-09-11T00:03:14Z",
        "skillSource":"inline",
        "executionContext":"inline",
        "reasoning":{
          "narration":"Recognized an intent to verify a geography fact"
        },
        "parameters":[
          { "key":"language", "value":"en-US" },
          { "key":"confidenceThreshold", "value":"0.8" }
        ]
      },
      {
        "skillID":"skill-faq-retrieval",
        "skillInvocationID":"inv-9f2a-002",
        "name":"FAQ Retrieval",
        "version":"1.2.0",
        "agentID":"agent-001",
        "invocationSource":"main",
        "score":0.89,
        "failed":false,
        "sequenceNumber":2,
        "timestamp":"2026-09-11T00:03:15Z",
        "skillSource":"inline",
        "executionContext":"forked",
        "parameters":[
          { "key":"maxResults", "value":"5" }
        ]
      },
      {
        "skillID":"skill-speech-recognition",
        "skillInvocationID":"inv-9f2a-003",
        "name":"Speech Recognition",
        "version":"2.0.1",
        "agentID":"agent-002",
        "invocationSource":"main",
        "score":0.91,
        "failed":false,
        "sequenceNumber":1,
        "timestamp":"2026-09-11T00:03:15Z",
        "skillSource":"deferred",
        "executionContext":"inline",
        "parameters":[
          { "key":"languageModel", "value":"general" },
          { "key":"noiseSuppression", "value":"true" }
        ]
      }
    ]
  }
}

Grupos de campos adicionais

Você pode adicionar grupos de campos opcionais ao esquema usado para conjuntos de dados de prompt, resposta e feedback. Por exemplo:

O cliente é responsável por produzir os eventos de conversação de origem. O Adobe realiza extração de sinal e mistura de dados. O cliente não precisa implementar os serviços de extração de sinal ou mistura.

Tipo de evento

Você precisa definir um dos seguintes valores para eventType (String) para cada evento de conversa:

Exemplo

Veja abaixo um exemplo do uso do grupo de campos Evento de conversa em vários cenários.

{
  "_id":"a33e1068-3966-468b-8682-e5e493827fff",
  "timestamp":"2026-09-11T00:03:15Z",
  "eventType":"conversation.turn",
  "identityMap":{
    "ECID":[
      { "id": "12345678901234567890123456789012345678", "primary": true }
    ]
  },
  "web": {
    "webPageDetails": { "URL": "https://www.adobe.com", "name": "Home Page" }
  },
  "agenticExperience":{
    "conciergeID":"concierge-abc123",
    "name":"Customer Support Experience",
    "version":"1.0.0",
    "environment":"dev",
    "mode":"preview",
    "agents":[
      { "agentID":"agent-001", "name":"Chatbot Assistant", "version":"2.1.3", "score":0.92 }
    ]
  },
  "conversation": {
    "conversationID": "conv-001",
    "conversationName": "France Geography Q&A",
    "turnID": "int-001",
    "prompt": {
      "source": "end-user",
      "raw": [
        { "text": "What is the capital of France? This link says it is Lyon.", "purpose": "User Input" },
        { "text": "https://wrong.geography.com/france", "purpose": "link" }
      ]
    }
  }
}

{
  "_id":"a33e1068-3966-468b-8682-e5e493827ffd",
  "timestamp":"2026-09-11T00:03:16Z",
  "eventType":"conversation.turn",
  "identityMap":{
    "ECID":[
      { "id": "12345678901234567890123456789012345678", "primary": true }
    ]
  },
  "web": {
    "webPageDetails": { "URL": "https://www.adobe.com", "name": "Home Page" }
  },
  "agenticExperience":{
    "conciergeID":"concierge-abc123",
    "name":"Customer Support Experience",
    "version":"1.0.0",
    "environment":"dev",
    "mode":"preview",
    "agents":[
      { "agentID":"agent-001", "name":"Chatbot Assistant", "version":"2.1.3", "score":0.92 }
    ]
  },
  "conversation": {
    "conversationID": "conv-001",
    "conversationName": "France Geography Q&A",
    "turnID": "int-001",
    "response": {
      "source": "concierge",
      "raw": [
        { "text": "The capital of France is Paris.", "purpose": "main" },
        { "text": "Would you like to plan a trip to Paris?", "purpose": "advertisement" },
        { "text": "https://en.wikipedia.org/wiki/France", "purpose": "citation" }
      ]
    }
  }
}

{
  "_id":"a33e1068-3966-468b-8682-e5e493827ffb",
  "timestamp":"2026-09-12T00:03:15Z",
  "eventType":"conversation.feedback",
  "identityMap":{
    "ECID":[
      { "id": "12345678901234567890123456789012345678", "primary": true }
    ]
  },
  "web": {
    "webPageDetails": { "URL": "https://www.adobe.com", "name": "Home Page" }
  },
  "conversation": {
    "conversationID": "conv-001",
    "conversationName": "France Geography Q&A",
    "feedback": {
      "source": "end-user",
      "raw": [
        { "text": "Great help", "purpose": "text box" }
      ],
      "rating": {
        "score": 1,
        "classification": "Thumbs Up",
        "reasons": ["Accurate", "Quick response"]
      }
    }
  }
}

{
  "_id":"a33e1068-3966-468b-8682-e5e493827ffa",
  "timestamp":"2026-09-11T00:03:15Z",
  "eventType":"conversation.recommendation",
  "identityMap":{
    "ECID":[
      { "id": "12345678901234567890123456789012345678", "primary": true }
    ]
  },
  "web": {
    "webPageDetails": { "URL": "https://www.adobe.com", "name": "Home Page" }
  },
  "agenticExperience":{
    "conciergeID":"concierge-xyz789",
    "name":"Product Concierge",
    "version":"1.0.0",
    "environment":"prod",
    "mode":"release",
    "agents":[
      { "agentID":"agent-010", "name":"Product Advisor", "version":"1.0.0", "score":0.92 }
    ]
  },
  "conversation": {
    "conversationID": "conv-001",
    "turnID": "int-099",
    "prompt": {
      "source": "end-user",
      "raw": [
        { "text": "What product do you recommend for a new user trying to create a poster?", "purpose": "User Input" }
      ]
    },
    "response": {
      "source": "concierge",
      "raw": [
        { "text": "To create a poster, we would recommend Adobe Express - https://express.adobe.com.", "purpose": "main" },
        { "text": "https://express.adobe.com", "purpose": "link" }
      ]
    }
  },
  "productListItems": [
    { "SKU": "express" }
  ]
}

Coleção de dados

Use a seguinte estratégia de coleta de dados para Insights de conversa.

Tipos de evento

O aplicativo ou serviço do agente envia um evento o mais rápido possível. Certifique-se de que o aplicativo ou serviço não espere uma resposta antes de enviar o prompt com as informações disponíveis no momento do evento.

Esta recomendação implica que:

Correlação de eventos

O aplicativo ou serviço do agente deve preservar identificadores estáveis em todos os eventos relacionados.

O aplicativo ou serviço do agente gera IDs que permanecem estáveis durante novas tentativas ou novos deliveries. Isso permite que o processamento de downstream associe eventos corretamente e evite eventos duplicados não intencionais.

Extração de sinal

A extração de sinal ocorre após a coleta de dados. O aplicativo ou serviço do agente pode preencher sinais adicionais.

Nome do sinal

É necessário definir um valor para signals[].name. Qualquer valor de string é aceitável; no entanto, o Adobe preenche os seguintes nomes durante o processo de extração de sinal. Evite usar esses valores para name para qualquer sinal enviado, pois esses valores serão substituídos.

Escopo do sinal

Qualquer valor de string é aceitável; no entanto, o Adobe preenche os seguintes escopos durante o processo de extração de sinal. Evite usar esses valores para scope para qualquer sinal enviado, pois esses valores serão substituídos.

{
  "_id":"a33e1068-3966-468b-8682-e5e493827fff",
  "timestamp":"2026-09-11T00:03:15Z",
  "eventType":"conversation.turn",
  "identityMap":{
    "ECID":[
      { "id":"12345678901234567890123456789012345678", "primary":true }
    ]
  },
  "web":{
    "webPageDetails":{ "URL":"https://www.adobe.com", "name":"Home Page" }
  },
  "agenticExperience":{
    "conciergeID":"concierge-abc123",
    "name":"Customer Support Experience",
    "version":"1.0.0",
    "environment":"dev",
    "mode":"preview",
    "agents":[
      { "agentID":"agent-001", "name":"Chatbot Assistant", "version":"2.1.3", "score":0.92 }
    ],
    "skills":[
      {
        "skillID":"skill-intent-recognition",
        "skillInvocationID":"inv-9f2a-001",
        "name":"Intent Recognition",
        "version":"1.0.0",
        "agentID":"agent-001",
        "invocationSource":"main",
        "score":0.95,
        "sequenceNumber":1,
        "timestamp":"2026-09-11T00:03:14Z",
        "skillSource":"inline",
        "executionContext":"inline"
      }
    ]
  },
  "conversation":{
    "conversationID":"conv-001",
    "conversationName":"France Geography Q&A",
    "turnID":"int-001",
    "signals":[
      {
        "scope":"turn",
        "name":"subjects",
        "type":"string",
        "values":[
          { "stringValue":"capital of France", "confidence":0.93, "qualifiers":["geographical","factual-question"] },
          { "stringValue":"Lyon", "confidence":0.87, "qualifiers":["incorrect","misinformation"] }
        ]
      },
      {
        "scope":"turn",
        "name":"intents",
        "type":"string",
        "values":[
          { "stringValue":"seek-information" },
          { "stringValue":"verify-facts" }
        ]
      },
      {
        "scope":"turn",
        "name":"tones",
        "type":"string",
        "values":[
          { "stringValue":"curious" },
          { "stringValue":"uncertain" }
        ]
      },
      {
        "scope":"turn",
        "name":"sentiment",
        "type":"number",
        "values":[
          { "numberValue":0.1 }
        ]
      },
      {
        "scope":"conversation-to-date",
        "name":"subjects",
        "type":"string",
        "values":[
          { "stringValue":"unreliable source", "qualifiers":["external-link","potentially-misleading"] },
          { "stringValue":"geography knowledge", "qualifiers":["educational","basic-facts"] }
        ]
      },
      {
        "scope":"conversation-to-date",
        "name":"intents",
        "type":"string",
        "values":[
          { "stringValue":"fact-checking" },
          { "stringValue":"learn-correct-information" }
        ]
      },
      {
        "scope":"conversation-to-date",
        "name":"tones",
        "type":"string",
        "values":[
          { "stringValue":"questioning" },
          { "stringValue":"seeking-clarification" }
        ]
      },
      {
        "scope":"conversation-to-date",
        "name":"sentiment",
        "type":"number",
        "values":[
          { "numberValue":0.3 }
        ]
      }
    ],
    "prompt":{
      "source":"end-user",
      "raw":[
        { "text":"What is the capital of France? This link says it is Lyon.", "purpose":"User Input" },
        { "text":"https://wrong.geography.com/france", "purpose":"link" }
      ]
    }
  }
}

Mesclagem de dados

O serviço de mesclagem de conversações mescla eventos de eventos de prompt, resposta, feedback e sinal em um conjunto de dados de eventos de conversação mesclados dedicados. Esse conjunto de dados é usado no Customer Journey Analytics como parte de uma conexão. Os componentes nesse conjunto de dados são adicionados às visualizações de dados especificadas para uma configuração do Conversation Insights.