Custom service integration setup

Selecting Custom service

To select a Custom service as the search integration, use one of the following procedures:

• Selecting Custom service search integration from the Integrations page

  1. After you create a watsonx Assistant instance, go to Home > Integrations.
  2. Click Open inside the Search tile to view the "Open Search" window.
  3. In the "Open Search" window, select the Draft option in the dropdown if you want to set up Custom service in your assistant’s draft environment. If you want to set up Custom service in your assistant’s live environment, select the Live option in the dropdown.
  4. In the following "Edit an existing new search integration" window, select the Custom service tile.

• Selecting Custom service search integration from the Environments page

  1. After you create a watsonx Assistant instance, go to Home > Environments.

  2. Select the Draft tab if you want to set up Custom service in the draft environment. If you want to set up Custom service in the live environment, select the Live tab.

  3. In the Resolution methods section, click Add inside the Search tile under Extensions if you want to add a Custom service search integration.

     If you already added the Custom service search integration, you see the Open button instead of Add inside the Search tile under Extensions.

  4. In the Set up a new search extension window, select the Custom service tile to see the Search integration dialog.

  

Your assistant has limitations in passing the search parameters directly to your Custom service or retrieving the search results directly from it. Hence, your Custom service search integration must host an accessible web server that implements the search API interface provided by the assistant or a client that is configured to call your assistant to provide search results. For more information, see Setting up retrieval systems for a Custom service.

Setting up a Custom service with server credentials

To set up Custom service on your assistant with server credentials, use the following procedure:

1. In the Connect your search provider section of the Custom service window, select By providing credentials. By default, this option is selected.

2. Provide the following fields to enable your assistant to connect to your Custom service instance:

   • URL
   • Choose an authentication type
     • if you select Basic authentication, you must provide Username and Password.
     • if you select API key, you must provide an API key.
     • if you select None, you cannot provide any other authentication details.

3. Click Next to go to Conversational search (optional).

4. If you want to activate conversational search, switch the Conversational Search toggle to on. For more information about conversational search, see conversational search.

5. Filling Default filter and Metadata is optional. You can place the information in these fields for your server to perform search requests. The metadata must be a JSON object and the default filter can be a text string. You can override the default filter in an action step or dialog node that starts the search. You cannot override the metadata through other options and the metadata you provide applies to all uses of this integration. For more information, see filling default filter and metadata for server.

6. Use the No results found and Connectivity issue tabs to customize different messages to share with users based on the success of the search.

   Custom service search result messages

   Tab	Scenario	Example message
   No results found	No search results are found	I searched my knowledge base for information that might address your query, but did not find anything useful to share.
   Connectivity issue	I was unable to complete the search for some reason	I might have information that could help address your query, but am unable to search my knowledge base at the moment.

7. Click Save and then Close to end the custom service set up with server credentials.

   

Setting up a Custom service through your client

To set up Custom service on your assistant through your client, use the following procedure:

1. In the Connect your search provider section of the Custom service window, select “Through your client”.

2. Click Next to go to Conversational search (optional).

3. If you want to activate conversational search, switch the Conversational Search toggle to on. For more information about conversational search, see conversational search.

4. Filling Default filter and Metadata is optional. You can place the information in these fields for your server to perform search requests. The metadata must be a JSON object and the default filter can be a text string. You can override the default filter in an action step or dialog node that starts the search. You cannot override the metadata through other options and the metadata you provide applies to all uses of this integration. For more information, see filling default filter and metadata for client.

5. Use the No results found and Connectivity issue tabs to customize different messages to share with users based on the success of the search.

   Custom service search result messages

   Tab	Scenario	Example message
   No results found	No search results are found	I searched my knowledge base for information that might address your query, but did not find anything useful to share.
   Connectivity issue	I was unable to complete the search for some reason	I might have information that could help address your query, but am unable to search my knowledge base at the moment.

6. Click Save and then Close to end the Custom service set up in the client-side.

Setting up Milvus for Custom service

Milvus is a full-text search engine that you can use for handling large-scale datasets. For applications requiring real-time search capabilities and numerous concurrent users, you can use Milvus, that has a distributed architecture, high performance, flexible data model, and real-time analytics capabilities.

Setting up retrieval systems for a Custom service

To use a Custom service with your search integration, you must integrate your search capability by providing a server or by having the client that calls your assistant to provide search results. You can use your own retrieval if the retrieval schema matches with the schema that is provided by your assistant. If your retrieval schema does not match with the assistant’s schema, you must provide a wrapper that does the schema mapping. You can deploy the wrapper as a service or your chat client can start it. Building a wrapper is useful when you want to combine a different source or invoking libraries or services that do not comply with the schema for assistant search results.

{
    "query": "<QUERY>",
    "filter": "<FILTER>", // optional
    "metadata": {
        // optional, you can fill any information here
    }
}

{
    
  "search_results": [
    {
      "result_metadata": { // optional
        "score": <SCORE as a number>
      },
      "title": "<TITLE>",
      "body": "<BODY>",
      "url": "<URL>", // optional
      "highlight": { // optional, will be used instead of "body" for Conversational Search if provided
        "body": [
          "<HIGHLIGHT1>",
          "<HIGHLIGHT2>",
           ...
        ]
      }
    }
  ]

}

{
    "output": {
        "intents": [ ... ],
        "actions": [
            {
                "type": "search",
                "query": "<QUERY>",
                "filter": "<FILTER>",
                "metadata": { // optional
                    /* you can use any JSON object here */
                }
            }
        ]
    }
}

{
    "input": {
        "message_type": "search_results",
         "search_results": [
          {
            "result_metadata": { // optional
                "score": <SCORE as a number>
            },
            "title": "<TITLE>",
            "body": "<BODY>",
            "url": "<URL>", // optional
            "highlight": { // optional, will be used instead of "body" for Conversational Search if provided
                "body": [
                "<HIGHLIGHT1>",
                "<HIGHLIGHT2>",
                ...
                ]
            }
         }
     ]
  }
}