Skip to content

Latest commit

 

History

History
157 lines (107 loc) · 6.78 KB

AGENTS.md

File metadata and controls

157 lines (107 loc) · 6.78 KB

Weaviate Agent Skills - Setup Instructions

This document provides setup instructions for AI agents using the Weaviate skill and plugin.

Prerequisites

1. Weaviate Cloud Instance

If the user does not have an instance yet, direct them to the cloud console to register and create a free sandbox. Create a Weaviate instance via Weaviate Cloud.

2. Environment Variables

Required:

WEAVIATE_URL="https://your-cluster.weaviate.cloud"
WEAVIATE_API_KEY="your-api-key"

External Provider Keys (auto-detected):

Set only the keys your collections use:

  • OPENAI_API_KEY
  • COHERE_API_KEY
  • HUGGINGFACE_API_KEY
  • JINAAI_API_KEY
  • VOYAGE_API_KEY
  • MISTRAL_API_KEY
  • NVIDIA_API_KEY
  • VERTEX_API_KEY
  • STUDIO_API_KEY
  • AZURE_API_KEY
  • ANTHROPIC_API_KEY
  • ANYSCALE_API_KEY
  • DATABRICKS_TOKEN
  • FRIENDLI_TOKEN
  • XAI_API_KEY
  • AWS_ACCESS_KEY
  • AWS_SECRET_KEY

Check if variables are set:

[ -z "$WEAVIATE_URL" ] && echo "WEAVIATE_URL is NOT set" || echo "WEAVIATE_URL is set"
[ -z "$WEAVIATE_API_KEY" ] && echo "WEAVIATE_API_KEY is NOT set" || echo "WEAVIATE_API_KEY is set"

3. Python Runtime

All scripts require Python 3.11+.

python3 --version

4. uv Package Manager (Recommended)

Scripts use uv for dependency management.

Check if uv is installed:

uv --version

Install uv if needed:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

# Or with Homebrew
brew install uv

Project Structure

Skill Path Description
weaviate skills/weaviate/ Scripts and references for searching, querying, and managing Weaviate collections
weaviate-cookbooks skills/weaviate-cookbooks/ Implementation guides for building full-stack AI applications with Weaviate

Running Scripts

All scripts are in skills/weaviate/scripts/. Run from that directory.

Available Scripts

For full parameter details, examples, and usage guidance, see the linked references.

Search & Query

  • Query Agent - Ask Mode: Generate AI-powered answers with source citations across multiple collections.
  • Query Agent - Search Mode: Retrieve raw objects using natural language queries across multiple collections.
  • Hybrid Search: Combine vector similarity and keyword matching — the default choice for most searches.
  • Semantic Search: Pure vector similarity search for finding conceptually similar content.
  • Keyword Search: BM25 keyword matching for exact terms, IDs, or specific text patterns.

Collection Management

  • List Collections: Show all available collections with their properties.
  • Get Collection Details: Get detailed configuration of a specific collection including vectorizer, properties, and multi-tenancy settings.
  • Explore Collection: Get statistical insights, aggregation metrics, and sample data from a collection.
  • Create Collection: Create a new collection with custom schema, optional vectorizer, and multi-tenancy support.

Data Operations

  • Fetch and Filter: Fetch objects by UUID or with complex nested filters (AND, OR logic).
  • Import Data: Import data from CSV, JSON, or JSONL files with automatic type conversion and column mapping.

Dependencies

All scripts use inline dependency declarations (auto-installed via uv run):

Package Version Used By
weaviate-client >=4.19.2 All scripts
weaviate-agents >=1.2.0 ask.py, query_search.py
typer >=0.21.0 All scripts

Weaviate Cookbooks

Weaviate cookbooks are implementation guides for building full-stack AI applications with Weaviate. All cookbooks are in the skills/weaviate-cookbooks/ skill. For full details and best practices, see the linked references.

  • Query Agent Chatbot: Build a full-stack chatbot using Weaviate Query Agent with streaming and chat history support.
  • Data Explorer: Build a full-stack data explorer app with sorting, keyword search, and tabular data view.
  • Basic RAG: Implement basic retrieval and generation with Weaviate — covers vector, keyword, hybrid, and image search.
  • Advanced RAG: Extend basic RAG with query rewriting, decomposition, LLM-created filters, and re-ranking.
  • Multimodal RAG (PDF): Build a multimodal RAG system for PDF documents using Weaviate Embeddings (ModernVBERT/colmodernvbert) and Ollama with Qwen3-VL for generation.
  • Basic Agent: Build tool-calling AI agents with structured outputs using DSPy.
  • Agentic RAG: Build RAG-powered AI agents combining retrieval with agent logic — covers naive RAG tools, hierarchical RAG, vector DB memory, and Weaviate Query Agent.

Optional Frontend Guide

  • Frontend Interface: Build a Next.js frontend (App Router, Tailwind v4, shadcn/ui) to interact with Weaviate backends.

Contributing

For full guidelines, see CONTRIBUTING.md.

Adding a Reference

  1. Create a new .md file in skills/<skill-name>/references/.
  2. Include usage, parameters, examples, and prerequisites.
  3. Link the new reference from the skill's SKILL.md.

Creating a New Skill

  1. Create directory: mkdir -p skills/my-skill/references
  2. Add a SKILL.md with YAML frontmatter (name, description) and reference links.
  3. Add reference markdown files in references/.

Skills follow the Agent Skills Open Standard.