Pinecone Vector Index

Overview

Pinecone is a managed vector database — the storage layer behind most 'ask my own documents' AI assistants. Your content gets pre-processed into numeric fingerprints (embeddings) once; this tool lets the agent instantly find the fingerprints most similar to any new question, so it can answer using your data instead of guessing.

How it works

Four operations are exposed. 'query' runs a nearest-neighbor search and returns the most similar vectors with their metadata. 'upsert' writes new vectors (up to 100 per call). 'delete' removes vectors by ID (up to 1000 per call). 'stats' returns the index's total vector count and per-namespace breakdown. Embeddings must be generated elsewhere — this tool only manages stored vectors. Top-K is capped at 100 per query.

Example

When a user asks:

Find the 10 product descriptions most similar to this query embedding.

the agent calls the tool:

pinecone(operation="query", vector=[0.12, -0.34, …], topK=10)

and gets back: the 10 nearest-neighbor matches with IDs, scores, and metadata.

Configuration

Set these before calling the tool. Values marked required must be present or the tool call will fail.

PINECONE_API_KEY required

Pinecone API key from the Pinecone console.

PINECONE_INDEX_HOST required

Full index host URL (shown in the Pinecone console next to the index).

Use it in a workflow

Wire this tool into a SwarmAI crew. Use the YAML DSL for declarative workflows, or the Java builder API when you want full programmatic control.

YAML DSL

# vector-search.yaml
name: vector-search-crew
process: SEQUENTIAL

agents:
  - id: searcher
    role: Vector Searcher
    goal: Retrieve nearest-neighbor matches for an embedded query
    tools:
      - pinecone

tasks:
  - id: vector-search-task
    agent: searcher
    description: Query the index with the supplied query vector and return the top 10 matches.

Java

import ai.intelliswarm.swarmai.agent.Agent;
import ai.intelliswarm.swarmai.task.Task;
import ai.intelliswarm.swarmai.swarm.Swarm;
import ai.intelliswarm.swarmai.swarm.SwarmOutput;
import ai.intelliswarm.swarmai.process.ProcessType;
import ai.intelliswarm.swarmai.tool.vector.PineconeVectorTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired PineconeVectorTool pineconeVectorTool;

Agent searcher = Agent.builder()
    .role("Vector Searcher")
    .goal("Retrieve nearest-neighbor matches for an embedded query")
    .chatClient(chatClient)
    .tool(pineconeVectorTool)
    .build();

Task searcherTask = Task.builder()
    .description("Query the index with the supplied query vector and return the top 10 matches.")
    .agent(searcher)
    .build();

SwarmOutput result = Swarm.builder()
    .agent(searcher)
    .task(searcherTask)
    .process(ProcessType.SEQUENTIAL)
    .build()
    .kickoff();

What it's good for

Real scenarios where agents put this tool to work.

Top-K retrieval for grounded LLM answers (classic RAG)

Ingest batches of freshly embedded knowledge-base chunks

Purge stale vectors when source documents are rotated

Capacity-planning reports from index fullness stats

Source

Implementation lives at swarmai-tools/src/main/java/ai/intelliswarm/swarmai/tool/vector/PineconeVectorTool.java in the swarm-ai repository.

Open pinecone on GitHub →