Connecting to a Milvus content repository

Edit online

Connect a Milvus content repository to enable high‑performance vector search for your agents. At runtime, your agent submits queries to Milvus to retrieve contextually relevant content, improving search accuracy for long or complex documents.

Vector search helps you to retrieve semantically relevant results instead of relying only on keyword matching. You use Milvus when you want your agent to return richer, context‑based answers.

Use the following products and tools to connect to a Milvus repository:

IBM® watsonx.data (SaaS): Used to provision and manage the Milvus instance.
watsonx.ai (optional): Used only if you want to create Milvus collections or load data.
agent builder: Used to configure the connection between an agent and your Milvus instance.

Before you begin, ensure that you complete all Prerequisites.

To use a custom server certificate for Milvus when you connect through ADK, see Milvus.

To enable access control for Milvus in watsonx Orchestrate, see Enabling access control for Milvus.

Before you connect to Milvus

Before you connect your agent to Milvus:

Have an active IBM® watsonx.data SaaS account: To create an account, go to the IBM® watsonx.data home page.
Provision a Milvus instance in IBM® watsonx.data: For more information, see Adding Milvus service in IBM® watsonx.data. For more information on creating an API key, see API keys.
(Optional) Have a watsonx.ai account: If you want to create Milvus collections or load data, create an account in watsonx.ai home page.
(Optional) Configure Milvus in watsonx.ai: Connect Milvus to IBM watsonx.ai and Create a vector index. For more information about creating collections, see Creating collections.

Connect your agent to Milvus

Use your Milvus instance in IBM® watsonx.data to supply knowledge content to your agent.

Note:

The Choose knowledge + option does not appear if another knowledge source is already connected. To switch sources, click Replace source, select your new source, and confirm. Replacing a source permanently deletes the previous connection and its uploaded files.

Step 1: Select source

In the agent builder, open the Knowledge section and initiate the action to add a knowledge source. The Choose knowledge source dialog opens with the Select source step active in the left sidebar.
From the list of available knowledge sources, select Milvus — "Connect to an existing Milvus instance." A checkmark confirms your selection. The left sidebar updates to show the following sub-steps:
- Connect
- Select index
- Provide description
Click Next.

Step 2: Connect

The Connections panel lists all existing knowledge connections for Milvus. Each row shows the connection name, ID, authentication type (for example, Basic Auth), and credential scope (Draft / Live).

If an existing connection is already configured, select it and click Next to proceed to the Select index step.
To create a new connection, click Add knowledge connection.

If you clicked Add knowledge connection, the Add a knowledge connection dialog opens. Complete the following steps:

On the Define connection details step, provide the following information:

Table 1. Define connection details fields
Field	Description
Connection ID (required)	A unique identifier for this connection. The ID can include letters, numbers, underscores (`_`), and hyphens (`-`). Special characters are not allowed. For example, `Sample123`.
Display name (optional)	A human-readable name that appears in the catalog and agent builder. If left blank, the Connection ID is used.

Click Next.

On the Configure connection step, complete the following fields:

Table 2. Configure connection fields
Field	Description
Authentication type (required)	Select `Basic auth` (username and password) or `None` from the dropdown. The default is `Basic auth`.
Server URL (required)	The full URL of your Milvus server, for example, `https://test.com`. Click Reset to clear the field.
TLS/SSL certificate (optional)	Paste the TLS/SSL certificate content to verify the server's identity and encrypt data in transit. The field has a limit of 100 characters.
Credential type	Select `Team credential` so that all users share the credentials you provide, or `Member credential` for per-user credentials.
Username	The Milvus username. Required when the authentication type is `Basic auth`.
Password	The corresponding password. Use the visibility toggle to show or hide the value.

Note:

An SSL certificate verifies a website's identity and encrypts data sent to the server, keeping your information secure.

Click Finish to save the connection. The system displays a Saving… indicator while the connection is being created.

The new connection is saved and appears in the connections list. Select it and click Next to continue.

Step 3: Select index

After the connection is established, select the Milvus index (collection) that your agent will query, and click Next.

Step 4: Provide description

Provide a description so the agent understands the content and context of this Milvus knowledge source. This helps the agent respond accurately. Click Next to complete the setup.

The Milvus knowledge source is now connected to your agent. It appears in the agent's knowledge configuration and can be used to answer queries based on the indexed content.

Update Milvus settings

To edit Milvus configuration details:

Open the Knowledge section.
Click the options next to the Milvus source.
Select Edit details and update the configuration.
Save your settings.

Delete a Milvus repository

To remove a Milvus knowledge source:

Go to the Knowledge section.
Click the options next to the Milvus source.
Click Remove.

Update Milvus authentication credentials

IBM watsonx.data Version 2.3 removes the default Milvus username ibmlhapikey. Update your Milvus credentials to avoid service interruption.

Step 1: Find your new Milvus username

Your new username format is:

ibmlhapikey_<your watsonx.data username>

Table 3. Milvus username examples
watsonx.data username	Milvus username
`abc@ibm.com`	`ibmlhapikey_abc@ibm.com`
`serviceid-abcdef-123456`	`ibmlhapikey_serviceid-abcdef-123456`

To find your username:

Open Infrastructure manager in the watsonx.data console.
Select your Milvus service to open the Details page.
Click the Access control tab. Your usernames appear in the first column.

Step 2: Update your Milvus connection

Follow the steps to update your Milvus credentials for each agent that uses a Milvus knowledge source:

In the agent configuration, open Knowledge.
Click Settings next to the Milvus entry.
Record your existing connection details.
Open the Instance tab and click Update details.
Enter the following details:
- GRPC host
- GRPC port
- Username: Use your new Milvus username from Step 1: Find your new Milvus username.
- Password: Use the same password or API key that you used earlier.
Click Next, and reenter your collection, alias, and index information.
- If the connection works, your new credentials are valid.
- If you see an error, review Step 1: Find your new Milvus username to confirm your username and password.
Test the agent by running a search in the chat window.

Tip:

If you are authenticated with a watsonx.data API key, that same key now acts as your password.

Define filter expressions

You can define filter expressions to refine Milvus search results. In the Advanced Milvus settings section, configure a custom filter to query results from Milvus.

Contains

Returns only the search results with a title that contains the word action.

title like "%action%"

Doesn't contain

Returns only the search results with a title that does not contain the word action.

not (title like "%action%")

Nested filter expression

Returns only the search results whose title contains the word action and whose URL is in the specified list.

(title like "%action%") and (url in ["www.url1.com", "www.url2.com"])

Pass context variables

You can make filters dynamic by referencing context variables. When the agent runs, the runtime replaces variable placeholders with actual context values.

How it works

In your content repository, set up filters and reference context variables in the format: {context_var}.
When the agent runs, it fetches context from either of the following:
- The run endpoint payload.
- The JWT token associated with the session.
The knowledge runtime replaces the context variables in your filter template with actual values from the context.

Example: Milvus filter substitution

Table 4. Filter substitution variables
Variable	Description
`filter`	A template with references to context variables entered in the filter field for dynamic substitution.
`final_filter`	The template after context variables are replaced with actual values. This is the query sent to Milvus for data retrieval.
`context_variable`	A set of key-value pairs that define the context variables used in substitution.

filter = "(title like \"%{action}%\") and (url in {url})"
context_variable = {"action": "send-email", "url": ["a.com", "b.com"]}
final_filter = "(title like \"%send-email%\") and (url in [\"a.com\", \"b.com\"])"

Manage collections with aliases

Use aliases to separate your application from specific collection names. Aliases help you to update collections without downtime.

For example, if your application queries a collection called prod_data, you can update the underlying data without interrupting the service by completing the following steps:

Create a new collection: Create a new collection such as prod_data_v2.
Prepare the data: Load and index your data in prod_data_v2.
Switch the alias: When the collection is ready, reassign the alias prod_data from the old collection to the new one.

Your application continues to query prod_data without needing to know the physical collection name. This method supports seamless updates and simplifies tasks such as blue-green deployments. For more information, see Why Use an Alias?

What to do next

After you connect your agent to Milvus, you can update repository settings and refine how search results appear. For more control over result formatting, see Editing the settings of the search results.