Skip to content

Getting started

Hub: documentation home.

This walkthrough uses the invoice example. Copy .env.example and set QDRANT_URL to your Qdrant cluster (the committed default is http://localhost:6333).

You need Python 3.11+ and uv (or pip).

1. Install from a clone

git clone https://github.com/kjgpta/vectorsmith.git
cd vectorsmith
uv sync

From PyPI (when published), install the extra for your store — which stores ship:

pip install "vectorsmith[qdrant]"      # or pgvector, chroma, pinecone, weaviate, milvus

2. Look at a tools.yaml

Open examples/qdrant_invoices/tools.invoices.yaml. You will see:

  • A connection (backend: qdrant, URL as ${QDRANT_URL}) — six backends ship; see vector stores
  • Tools with kinds (search, lookup, count)
  • static_filters the model never sees (tenant: acme)
  • Parameters the model may pass (client, status, min_amount)

Full contract: tools.yaml reference.

Or generate a starter:

uv run vectorsmith init ./demo

3. Validate

The CLI interpolates only --env-file (not the process environment):

uv run vectorsmith validate examples/qdrant_invoices/tools.invoices.yaml \
  --env-file examples/qdrant_invoices/.env.example

--live also pings the store (dims, hybrid/sparse). --strict treats warnings as failure (exit 1). Errors are exit 2.

4. Call one tool without an agent

uv run vectorsmith test examples/qdrant_invoices/tools.invoices.yaml search_invoices \
  --args '{"query":"Globex invoice","limit":3}' \
  --env-file examples/qdrant_invoices/.env.example

You should get JSON with rows, count, search_mode. This is for authoring. Apps use Python or MCP, not test.

5. Pick a door

A — Claude / Codex / Cursor (MCP)

uv run vectorsmith serve examples/qdrant_invoices/tools.invoices.yaml --name invoices \
  --env-file examples/qdrant_invoices/.env.example

Then paste a config from examples/mcp_hosts/. Host guides: Claude Desktop, Claude Code, Codex, Cursor.

Ask: “Which Globex invoices are overdue?”

B — Python agent

pip install "vectorsmith[qdrant,langchain]"

from vectorsmith import load_tools
from langchain.agents import create_agent

tools = load_tools(
    "examples/qdrant_invoices/tools.invoices.yaml",
    env_file="examples/qdrant_invoices/.env.example",
)
agent = create_agent("openai:gpt-4.1", tools)

Worked apps: examples/langchain_agent, LangGraph, OpenAI Agents, Anthropic. API: python-api.md.

6. Tickets (second connector)

Same cluster, second YAML → second MCP name:

uv run vectorsmith serve examples/qdrant_invoices/tools.tickets.yaml --name tickets \
  --env-file examples/qdrant_invoices/.env.example

Two processes, two Connectors. One Python process can load_tools both files.

Next

  • FAQ if something fails (Desktop Server disconnected, missing ${VAR}, HTTP auth)
  • CLI reference for every flag
  • Architecture for what compiles where