Python: add Milvus vector store (agent-framework-milvus)

.github/workflows/python-merge-tests.yml

@@ -41,6 +41,7 @@ jobs:
       cosmosChanged: ${{ steps.filter.outputs.cosmos }}
       duckdbChanged: ${{ steps.filter.outputs.duckdb }}
       qdrantChanged: ${{ steps.filter.outputs.qdrant }}
+      milvusChanged: ${{ steps.filter.outputs.milvus }}
       mongodbChanged: ${{ steps.filter.outputs.mongodb }}
       redisChanged: ${{ steps.filter.outputs.redis }}
       githubCopilotChanged: ${{ steps.filter.outputs.github_copilot }}
@@ -98,6 +99,9 @@ jobs:
               - 'python/packages/qdrant/**'
               - '.github/workflows/python-merge-tests.yml'
               - '.github/workflows/python-integration-tests.yml'
+            milvus:
+              - 'python/packages/milvus/**'
+              - '.github/workflows/python-merge-tests.yml'
             mongodb:
               - 'python/packages/mongodb/**'
               - '.github/workflows/python-merge-tests.yml'
@@ -144,6 +148,124 @@ jobs:
       - name: Test DuckDB package
         run: uv run poe test -P duckdb
 
+  python-tests-milvus:
+    name: Python Tests - Milvus
+    needs: paths-filter
+    if: >
+      github.event_name == 'pull_request' &&
+      (needs.paths-filter.outputs.milvusChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up python and install the project
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test Milvus package
+        run: uv run poe test -P milvus
+
+  # Milvus integration tests run against a disposable standalone Milvus and need
+  # no cloud credentials, mirroring the Qdrant and MongoDB jobs. Milvus standalone
+  # needs a separate etcd (it rejects embedded etcd in this run mode) but can use
+  # local-disk object storage (COMMON_STORAGETYPE=local), so no MinIO is required.
+  # GitHub service containers cannot override the image command etcd and Milvus
+  # need, so the two containers are brought up with docker compose.
+  python-tests-milvus-integration:
+    name: Python Integration Tests - Milvus
+    needs: paths-filter
+    if: >
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' ||
+       needs.paths-filter.outputs.milvusChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    env:
+      MILVUS_TEST_URI: "http://localhost:19530"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up python and install the project
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Start Milvus standalone
+        run: |
+          cat > docker-compose.milvus.yml <<'EOF'
+          services:
+            etcd:
+              container_name: milvus-etcd
+              image: quay.io/coreos/etcd:v3.5.25
+              environment:
+                - ETCD_AUTO_COMPACTION_MODE=revision
+                - ETCD_AUTO_COMPACTION_RETENTION=1000
+                - ETCD_QUOTA_BACKEND_BYTES=4294967296
+                - ETCD_SNAPSHOT_COUNT=50000
+              command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
+            standalone:
+              container_name: milvus-standalone
+              image: milvusdb/milvus:v2.6.20
+              command: ["milvus", "run", "standalone"]
+              security_opt:
+                - seccomp:unconfined
+              environment:
+                ETCD_ENDPOINTS: etcd:2379
+                # Local-disk object storage; no MinIO/S3. The default standalone message queue
+                # (rocksmq, local disk) pairs with this, matching Milvus's standalone_embed.sh.
+                # Do not force MQ_TYPE=woodpecker here: woodpecker needs remote object storage
+                # for its WAL, so with local storage it never acks writes and data ops hang.
+                COMMON_STORAGETYPE: local
+              ports:
+                - "19530:19530"
+                - "9091:9091"
+              depends_on:
+                - etcd
+          EOF
+          docker compose -f docker-compose.milvus.yml up -d
+      - name: Wait for Milvus
+        run: |
+          for i in {1..90}; do
+            if curl --fail --silent http://localhost:9091/healthz > /dev/null; then
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Milvus did not become ready in time." >&2
+          docker compose -f docker-compose.milvus.yml logs --tail=100 || true
+          exit 1
+      - name: Test with pytest (Milvus integration)
+        run: >
+          uv run --directory packages/milvus poe test-integration
+          --junitxml=${{ github.workspace }}/python/pytest-milvus.xml
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@fdc7f18d9934e38aca411ca9557e6577bd25ca9c # v0.9.0
+        with:
+          path: ./python/pytest-milvus.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Milvus integration test results
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: test-results-milvus
+          path: ./python/pytest-milvus.xml
+          if-no-files-found: ignore
+
   python-tests-qdrant:
     name: Python Integration Tests - Qdrant
     needs: paths-filter
@@ -923,6 +1045,7 @@ jobs:
         python-tests-cosmos,
         python-tests-qdrant,
         python-tests-mongodb,
+        python-tests-milvus-integration,
         python-tests-github-copilot,
         python-tests-postgres,
         python-tests-redis,
@@ -980,6 +1103,7 @@ jobs:
     needs:
       [
         python-tests-duckdb,
+        python-tests-milvus,
         python-tests-unit,
         python-tests-openai,
         python-tests-azure-openai,
@@ -989,6 +1113,7 @@ jobs:
         python-tests-cosmos,
         python-tests-qdrant,
         python-tests-mongodb,
+        python-tests-milvus-integration,
         python-tests-github-copilot,
         python-tests-postgres,
         python-tests-redis,

.github/workflows/python-milvus-dependency-bounds.yml

@@ -0,0 +1,52 @@
+name: Python - Milvus Dependency Bounds
+
+on:
+  pull_request:
+    branches: ["main", "feature*"]
+    paths:
+      - ".github/actions/python-setup/**"
+      - ".github/workflows/python-milvus-dependency-bounds.yml"
+      - "python/packages/milvus/**"
+      - "python/pyproject.toml"
+      - "python/scripts/dependencies/**"
+      - "python/shared_tasks.toml"
+      - "python/tooling/requirements-typing.txt"
+
+permissions:
+  contents: read
+
+env:
+  UV_CACHE_DIR: /tmp/.uv-cache
+  UV_PYTHON: "3.13"
+
+jobs:
+  milvus-dependency-bounds:
+    name: Milvus ${{ matrix.name }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Lowest pymilvus whose AsyncMilvusClient exposes the full collection API
+          # this connector uses; anything below raises AttributeError at runtime.
+          - name: pymilvus 2.6 floor
+            package: milvus
+            module: agent_framework_milvus
+            requirement: pymilvus==2.6.0
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python and install the project
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Install ${{ matrix.name }}
+        run: uv pip install "${{ matrix.requirement }}"
+        working-directory: ./python
+      - name: Test and type-check ${{ matrix.name }}
+        run: |
+          uv run --no-sync python -c "import pymilvus; print(f'pymilvus {pymilvus.__version__}')"
+          uv run --no-sync python -m pytest -m "not integration" --cov=${{ matrix.module }} --cov-report=term-missing:skip-covered tests
+          uv run --no-sync --with-requirements ../../tooling/requirements-typing.txt pyright
+        working-directory: ./python/packages/${{ matrix.package }}

python/PACKAGE_STATUS.md

@@ -52,6 +52,7 @@ column records whether `pip install agent-framework` installs the workspace pack
 | `agent-framework-hyperlight` | `python/packages/hyperlight` | `beta` | `yes` |
 | `agent-framework-lab` | `python/packages/lab` | `beta` | `no` |
 | `agent-framework-mem0` | `python/packages/mem0` | `beta` | `yes` |
+| `agent-framework-milvus` | `python/packages/milvus` | `alpha` | `no` |
 | `agent-framework-mistral` | `python/packages/mistral` | `beta` | `yes` |
 | `agent-framework-mongodb` | `python/packages/mongodb` | `alpha` | `no` |
 | `agent-framework-monty` | `python/packages/monty` | `beta` | `yes` |

python/packages/milvus/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.

python/packages/milvus/README.md

@@ -0,0 +1,69 @@
+# Milvus for Microsoft Agent Framework
+
+`agent-framework-milvus` provides a [Milvus](https://milvus.io/) vector store for the
+Microsoft Agent Framework, implementing the framework's `BaseVectorStore` /
+`BaseVectorCollection` interfaces. It works alongside the Postgres, Qdrant, Redis and
+other vector-store connectors.
+
+## Installation
+
+```bash
+pip install agent-framework-milvus
+```
+
+This connects to a Milvus server. To use a local `.db` file (Milvus Lite) instead, also
+install the Milvus Lite extra, which is published for Linux and macOS only:
+
+```bash
+pip install "pymilvus[milvus_lite]"
+```
+
+## Usage
+
+```python
+from agent_framework import VectorStoreCollectionDefinition, VectorStoreField
+from agent_framework_milvus import MilvusStore
+
+definition = VectorStoreCollectionDefinition([
+    VectorStoreField("key", name="id", type_="int"),
+    VectorStoreField("data", name="text", type_="str"),
+    VectorStoreField("vector", name="embedding", dimensions=3, distance_function="cosine_similarity"),
+])
+
+# Connects to a Milvus server; set the MILVUS_URI env var or pass uri=...
+# For Milvus Lite, pass a local ".db" path as the uri argument, e.g.
+# MilvusStore(uri="milvus.db") (requires the pymilvus[milvus_lite] extra). The
+# MILVUS_URI env var must be a server address, not a file path.
+async with MilvusStore(uri="http://localhost:19530") as store:
+    collection = store.get_collection(dict, definition=definition, collection_name="docs")
+    await collection.ensure_collection_exists()
+    # upsert takes a sequence; pass generate_vectors=False when vectors are supplied.
+    await collection.upsert([{"id": 1, "text": "hello", "embedding": [0.1, 0.2, 0.3]}], generate_vectors=False)
+    results = await collection.search(vector=[0.1, 0.2, 0.3], top=5)
+    async for hit in results:  # each hit is a SearchResponse mapping
+        print(hit["record"], hit["score"])
+```
+
+## Configuration
+
+Settings are resolved from explicit arguments, then an optional `.env` file, then
+environment variables prefixed with `MILVUS_`:
+
+| Setting    | Environment variable | Notes                                              |
+| ---------- | -------------------- | -------------------------------------------------- |
+| `uri`      | `MILVUS_URI`         | Server URI (e.g. `http://localhost:19530`). For Milvus Lite, pass a local `.db` path as the `uri=` argument instead — the `MILVUS_URI` env var must be a server address. |
+| `token`    | `MILVUS_TOKEN`       | Access token (API key or `user:password`).         |
+| `user`     | `MILVUS_USER`        | Username.                                          |
+| `password` | `MILVUS_PASSWORD`    | Password.                                          |
+| `db_name`  | `MILVUS_DB_NAME`     | Database name.                                     |
+
+## Notes
+
+- The key field becomes the Milvus primary key (`INT64` for `int` keys, `VARCHAR`
+  otherwise). Data fields map to typed scalar fields and vector fields to
+  `FLOAT_VECTOR` fields, each with its own index.
+- Distance functions map to Milvus metrics (`cosine_similarity`/`cosine_distance` →
+  `COSINE`, `dot_prod` → `IP`, `euclidean_distance` → `L2`) and index kinds to Milvus
+  index types (`hnsw`, `flat`, `ivf_flat`, `disk_ann`, and `default` → `AUTOINDEX`).
+- Portable filters support `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `in`,
+  `not_in`, and `and`/`or`/`not` groups, translated to Milvus boolean expressions.

python/packages/milvus/agent_framework_milvus/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Milvus vector stores for Microsoft Agent Framework."""
+
+import importlib.metadata
+
+from ._vector_store import MilvusCollection, MilvusSettings, MilvusStore
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["MilvusCollection", "MilvusSettings", "MilvusStore", "__version__"]