ChromaDB Vector Database

The example uses OpenAI-backed embeddings or models. Set your key before running it:

export OPENAI_API_KEY="your-api-key"

Setup

uv pip install -U chromadb pypdf openai agno

Example

agent_with_knowledge.py

import asyncio

from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.chroma import ChromaDb

# Create Knowledge Instance with ChromaDB
knowledge = Knowledge(
    name="Basic SDK Knowledge Base",
    description="Agno 2.0 Knowledge Implementation with ChromaDB",
    vector_db=ChromaDb(
        collection="vectors", path="tmp/chromadb", persistent_client=True
    ),
)

asyncio.run(
    knowledge.ainsert(
        name="Recipes",
        url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
        metadata={"doc_type": "recipe_book"},
    )
)

# Create and use the agent
agent = Agent(knowledge=knowledge)
agent.print_response("List down the ingredients to make Massaman Gai", markdown=True)

# Delete operations examples
vector_db = knowledge.vector_db
vector_db.delete_by_name("Recipes")
# or
vector_db.delete_by_metadata({"doc_type": "recipe_book"})

For hosted ChromaDB (Chroma Cloud)

from chromadb.config import Settings

vector_db = ChromaDb(
    collection="vectors",
    tenant="your-tenant",
    database="your-database",
    settings=Settings(
        chroma_api_impl="chromadb.api.fastapi.FastAPI",
        chroma_server_host="api.trychroma.com",
        chroma_server_http_port=443,
        chroma_server_ssl_enabled=True,
        chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider",
        chroma_client_auth_credentials="your-api-key",
        chroma_auth_token_transport_header="X-Chroma-Token",
    ),
)

The tenant, database, and settings arguments are forwarded to the ChromaDB client.

Async Support ⚡

ChromaDB also supports asynchronous operations, enabling concurrency and leading to better performance.

import asyncio

from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.chroma import ChromaDb

# Initialize ChromaDB
vector_db = ChromaDb(collection="recipes", path="tmp/chromadb", persistent_client=True)

# Create knowledge base
knowledge = Knowledge(
    vector_db=vector_db,
)

# Create and use the agent
agent = Agent(knowledge=knowledge)

if __name__ == "__main__":
    # Comment out after first run
    asyncio.run(
        knowledge.ainsert(url="https://docs.agno.com/agents/overview.md")
    )

    # Create and use the agent
    asyncio.run(
        agent.aprint_response("What is the purpose of an Agno Agent?", markdown=True)
    )

Use ainsert() and aprint_response() methods with asyncio.run() for non-blocking operations in high-throughput applications.

ChromaDB has a batch size limit due to SQLite constraints. When inserting documents that exceed this limit, Agno automatically splits them into smaller batches. The batch size is auto-detected from ChromaDB's server configuration.

You can also set batch_size to override the auto-detected value.

ChromaDb Params

Parameter	Type	Default	Description
`collection`	`str`	None	The name of the collection to use. Derived from `name` if not provided.
`name`	`str`	None	Name of the vector database. Used as the collection name if `collection` is not set.
`embedder`	`Embedder`	OpenAIEmbedder()	The embedder to use for embedding document contents.
`distance`	`Distance`	cosine	The distance metric to use.
`path`	`str`	"tmp/chromadb"	The path where ChromaDB data will be stored.
`persistent_client`	`bool`	False	Whether to use a persistent ChromaDB client.
`search_type`	`SearchType`	SearchType.vector	Search type: `SearchType.vector`, `SearchType.keyword`, or `SearchType.hybrid` (vector + first-word substring candidates ranked by term overlap, with RRF fusion).
`hybrid_rrf_k`	`int`	60	RRF constant for hybrid search. Higher values give more weight to lower-ranked results.
`batch_size`	`int`	None	Maximum number of documents per batch operation. Auto-detected from ChromaDB's server limit if not set, falls back to `100` if auto-detect fails.
`reranker`	`Reranker`	None	The reranker to use when reranking documents.