Skip to main content

Conversations Tutorial

This tutorial demonstrates how to have multi-turn conversations with Knowledge Discovery agents. Unlike single-shot questions, conversations maintain context across multiple questions and answers, allowing for more natural dialogue.

Prerequisites​

  • Valid access token (see Authentication)
  • At least one configured agent with data sources
  • Discovery User role or higher

Tutorial Overview​

In this tutorial, you'll learn to:

  1. Start a new conversation with an agent
  2. Ask follow-up questions within a conversation
  3. List and retrieve conversation messages
  4. Provide feedback on conversation messages
  5. Manage conversations (list, update metadata)

Part 1: Start a Conversation​

To start a new conversation, send the first question using the conversation endpoint. The response returns both the new conversationId and the first message (question and answer).

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "question": "What is the status of the project?",
  "contextObjectIds": null,
  "dynamicFilter": null
}

Start Conversation Request Parameters​

FieldRequiredDescription
questionYesInitial natural language question for the conversation
dynamicFilterNoRuntime filter expression to narrow search results

Response Structure​

{
  "conversation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "lastModified": "2025-12-02T10:30:00Z"
  },
  "message": {
    "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "answer": "Based on the documents, the project is currently in progress.",
    "documentReferences": [
      {
        "documentId": "doc001",
        "references": [
          {
            "referenceId": "ref001",
            "rankScore": 0.95,
            "rank": 1
          }
        ]
      }
    ],
    "question": "What is the status of the project?",
    "feedback": null,
    "staticFilter": null,
    "dynamicFilter": null,
    "dateCreated": "2025-12-02T10:30:00Z",
    "dateAnswered": "2025-12-02T10:30:05Z",
    "agentVersion": 1
  }
}

Understanding the Response​

FieldTypeDescription
conversation.idUUIDUnique identifier for the conversation
conversation.lastModifieddatetimeTimestamp of the last update
message.idUUIDUnique identifier for this message
message.questionstringThe question text
message.answerstringThe generated answer
message.documentReferencesarraySource documents and chunks used for the answer
message.dateCreateddatetimeWhen the question was submitted
message.dateAnswereddatetimeWhen the answer was generated
message.agentVersionintegerVersion of the agent used

Part 2: Ask Follow-Up Questions​

Once you have a conversationId, you can continue the conversation by sending follow-up questions. The agent will use previous messages in the conversation as context.

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}/messages
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "question": "Can you provide more details about the timeline?",
  "contextObjectIds": null,
  "dynamicFilter": null
}

Response​

The response contains a ConversationMessageDto with the new question and answer, similar to the initial message:

{
  "id": "b2c3d4e5-f6a7-8901-2345-678901abcdef",
  "answer": "The latest update shows the project timeline is on track with an expected completion date of Q2 2026.",
  "documentReferences": [
    {
      "documentId": "doc002",
      "references": [
        {
          "referenceId": "ref002",
          "rankScore": 0.92,
          "rank": 1
        }
      ]
    }
  ],
  "question": "Can you provide more details about the timeline?",
  "feedback": null,
  "staticFilter": null,
  "dynamicFilter": null,
  "dateCreated": "2025-12-02T10:35:00Z",
  "dateAnswered": "2025-12-02T10:35:03Z",
  "agentVersion": 1
}
Context Awareness

The agent understands that "the timeline" refers to the project mentioned in the first question, demonstrating context retention across the conversation.

Part 3: List Conversation Messages​

You can retrieve the history of messages within a conversation using cursor-based pagination.

GET {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}/messages?pageSize=50&maxContentLength=500
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

Query Parameters​

ParameterRequiredDefaultDescription
cursorNonullCursor token for fetching the next page
pageSizeNo100Number of items per page (1-100)
maxContentLengthNonullMaximum length of question/answer content (10-1000)
fieldsNonullComma-separated list of fields to include in response

Response Structure​

{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "answer": "Based on the documents, the project is currently in progress.",
      "documentReferences": [
        {
          "documentId": "doc001",
          "references": [
            {
              "referenceId": "ref001",
              "rankScore": 0.95,
              "rank": 1
            }
          ]
        }
      ],
      "question": "What is the status of the project?",
      "feedback": "Good",
      "staticFilter": null,
      "dynamicFilter": null,
      "dateCreated": "2025-12-02T10:30:00Z",
      "dateAnswered": "2025-12-02T10:30:05Z",
      "agentVersion": 1
    },
    {
      "id": "b2c3d4e5-f6a7-8901-2345-678901abcdef",
      "answer": "The latest update shows the project timeline is on track...",
      "documentReferences": [
        {
          "documentId": "doc002",
          "references": [
            {
              "referenceId": "ref002",
              "rankScore": 0.92,
              "rank": 1
            }
          ]
        }
      ],
      "question": "Can you provide more details about the timeline?",
      "feedback": null,
      "staticFilter": null,
      "dynamicFilter": null,
      "dateCreated": "2025-12-02T10:35:00Z",
      "dateAnswered": "2025-12-02T10:35:03Z",
      "agentVersion": 1
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  }
}

Understanding Cursor Pagination​

Unlike page-based pagination (used in single-shot question history), conversation messages use cursor-based pagination:

FieldTypeDescription
pagination.nextCursorstring (nullable)Token to fetch the next page; null if no more pages
pagination.hasMorebooleanIndicates whether more messages are available

To fetch the next page, pass the nextCursor value as the cursor query parameter.

Part 4: Get a Single Message​

To retrieve a specific message (for example, when a user opens a detailed view), use the message ID.

GET {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}/messages/{{messageId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

The response is a single ConversationMessageDto object with full details about the message.

Part 5: Provide Feedback on Messages​

Feedback on conversation answers is recorded per message, similar to single-shot questions.

POST {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}/messages/{{messageId}}/feedback
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "feedback": "Good"
}

Feedback Values​

ValueMeaning
"Good"Answer was helpful and accurate
"Bad"Answer was not helpful or contained errors
"Retry"Request to regenerate the answer

Part 6: Manage Conversations​

List All Conversations for an Agent​

Retrieve all conversations associated with an agent.

GET {{baseUrl}}/qna/agents/{{agentId}}/conversations?pageSize=20
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

Query Parameters​

ParameterRequiredDefaultDescription
cursorNonullCursor token for fetching the next page
pageSizeNo20Number of items per page (1-100)

Response​

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Project Status Discussion",
      "description": "Conversation about current project status",
      "lastModified": "2025-12-02T10:35:00Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": null,
      "description": null,
      "lastModified": "2025-12-01T15:20:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJsYXN0SWQiOiJiMmMzZDRlNS1mNmE3LTg5MDEtYmNkZS1mMTIzNDU2Nzg5MDEiLCJsYXN0TW9kaWZpZWQiOiIyMDI1LTEyLTAxVDE1OjIwOjAwWiJ9",
    "hasMore": true
  }
}

Get Conversation Details​

Retrieve metadata for a specific conversation.

GET {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}

Update Conversation Metadata​

Update the name and description of a conversation for better organization.

PUT {{baseUrl}}/qna/agents/{{agentId}}/conversations/{{conversationId}}
Authorization: Bearer {{accessToken}}
Hxp-Environment: {{environmentKey}}
Hxp-App: {{appKey}}
Content-Type: application/json

{
  "name": "Project Status Q2 2025",
  "description": "Discussion about project timeline and deliverables for Q2"
}

Update Request Parameters​

FieldRequiredDescription
nameYesConversation name (for display/organization)
descriptionNoOptional longer description of the conversation purpose

Summary​

In this tutorial, you learned how to:

✅ Start multi-turn conversations with agents
✅ Ask follow-up questions that use previous context
✅ List and retrieve conversation messages
✅ Provide feedback on conversation messages
✅ Manage conversation metadata (list, view, update)

Next Steps​