Vector Database Integration — Client Developer Documentation

Introduction

The Vector Database add-on gives agents a unified, pluggable way to store and search high-dimensional vectors (embeddings) for semantic search, recommendation, clustering, and retrieval-augmented generation (RAG).

It supports:

• Local, in-memory engines for prototyping (e.g., FAISS)
• Distributed, production-grade DBs (e.g., Milvus, Qdrant, Weaviate)
• Local file-backed stores (e.g., LanceDB)
• A common abstract interface for custom backends

Agents declare vector DB capabilities via an Add-On entry in the Subject Specification (similar to how MemoryItem declares memories).

Typical workflow:

1. Declare an AddonItem with addon_type="vector_db" and your chosen backend.
2. Initialize a vector DB client from agent_sdk.embeddings.db based on that backend.
3. Insert vectors with optional metadata.
4. Perform filtered similarity search.
5. Retrieve, update, or delete as needed.

---

Registering Vector DB in Subject Specification

Vector DBs are registered using AddonItem.

Data Class Reference

from dataclasses import dataclass, field
from typing import Dict, Any

@dataclass
class AddonItem:
    addon_id: str
    addon_type: str
    addon_backend: str
    addon_config: Dict[str, Any] = field(default_factory=dict)

For vectors: set addon_type="vector_db". addon_backend can be "faiss", "milvus", "weaviate", "lancedb", "qdrant", "custom", etc.

---

Minimal Required Configuration

{
  "addon_id": "vector-primary",
  "addon_type": "vector_db",
  "addon_backend": "qdrant",
  "addon_config": {
    "collection_name": "knowledge_base",
    "url": "http://qdrant.default.svc.cluster.local:6333",
    "api_key": "",
    "options": {}
  }
}

---

Field Descriptions

Field	Location	Type	Description
addon_id	root	str	Unique identifier for this add-on.
addon_type	root	str	Must be "vector_db" to enable the vector DB module.
addon_backend	root	str	"faiss" | "milvus" | "weaviate" | "lancedb" | "qdrant" | "custom".
addon_config.collection_name	config	str	Name of the vector collection/index.
addon_config.url / host / port	config	str/int	Remote endpoint or local path depending on backend.
addon_config.options	config	dict	Extra backend-specific options (dimension, metric type, credentials, etc.).

---

Import and Setup

Choosing a backend at runtime

from agent_sdk.embeddings.db import (
    FaissEmbeddings, MilvusEmbeddings,
    WeaviateDB, LanceDB, QdrantDB
)

def build_vector_client(addon: dict):
    backend = addon["addon_backend"]
    cfg = addon.get("addon_config", {})

    if backend == "faiss":
        return FaissEmbeddings(dimension=cfg.get("dimension", 768))
    elif backend == "milvus":
        return MilvusEmbeddings(
            host=cfg.get("host", "localhost"),
            port=cfg.get("port", "19530"),
            collection_name=cfg.get("collection_name", "default")
        )
    elif backend == "weaviate":
        return WeaviateDB(config=cfg)
    elif backend == "lancedb":
        return LanceDB(config=cfg)
    elif backend == "qdrant":
        return QdrantDB(config=cfg)
    else:
        raise NotImplementedError(f"Unsupported backend: {backend}")

---

Usage Guide

A. FAISS (In-Memory)

from agent_sdk.embeddings.db import FaissEmbeddings

db = FaissEmbeddings(dimension=128)
db.add_embeddings([[0.1]*128, [0.2]*128], ids=[1, 2])
results = db.search([0.1]*128, top_k=2)

• Lightweight, in-memory, no persistence
• Best for prototyping or short-lived apps

---

B. Milvus (Distributed)

from agent_sdk.embeddings.db import MilvusEmbeddings

db = MilvusEmbeddings(host="localhost", port="19530", collection_name="my_collection")
db.create_index(dimension=128)
db.add_embeddings([[0.1]*128], ids=[101])
results = db.search([0.1]*128, top_k=2)
db.delete_embeddings([101])

• Persistent, scalable, filtering support
• Best for production-grade deployments

---

C. Weaviate (GraphQL)

from agent_sdk.embeddings.db import WeaviateDB

db = WeaviateDB(config={"url": "http://localhost:8080"})
db.set_embedder(my_embedder)
db._initialize()
db.add(documents, metadatas, ids)
results = db.query(input_query="example", n_results=3, where={"doc_id": "123"})

• Schema-aware, GraphQL filtering
• Best for rich metadata queries

---

D. LanceDB (Local File-Backed)

from agent_sdk.embeddings.db import LanceDB

db = LanceDB(config={"uri": "./lancedb"})
db.set_embedder(my_embedder)
db._initialize()
db.add(documents, metadatas, ids)
results = db.query("semantic search", n_results=3)

• Local file storage, lightweight
• Best for desktop or edge deployments

---

E. Qdrant (High-Performance)

from agent_sdk.embeddings.db import QdrantDB

db = QdrantDB(config={"collection_name": "kb"})
db.set_embedder(my_embedder)
db._initialize()
db.add(documents, metadatas, ids)
results = db.query("query text", n_results=3, where={"topic": "ai"})

• Disk-backed or in-memory, filtering, batch ops
• Best for fast RAG pipelines with metadata filtering

---

Custom Backends

All custom vector DBs must implement:

class BaseVectorDB(ABC):
    @abstractmethod
    def add_embeddings(self, vectors, ids, metadatas=None): ...
    @abstractmethod
    def search(self, query_vector, top_k=5, filters=None): ...
    @abstractmethod
    def delete_embeddings(self, ids): ...
    @abstractmethod
    def get_embedding(self, id): ...
    @abstractmethod
    def reset(self): ...

---

Quick Subject Spec Example (two add-ons)

{
  "subject_id": "agent-searcher",
  "subject_type": "agent",
  "addons": [
    {
      "addon_id": "vectors-local",
      "addon_type": "vector_db",
      "addon_backend": "faiss",
      "addon_config": { "dimension": 768 }
    },
    {
      "addon_id": "vectors-prod",
      "addon_type": "vector_db",
      "addon_backend": "qdrant",
      "addon_config": {
        "collection_name": "knowledge_base",
        "url": "http://qdrant.default.svc.cluster.local:6333",
        "options": { "prefer_disk": true }
      }
    }
  ]
}