Pinecone

Access fast, accurate, and multi-faceted search for your agents. This tool allows you to perform semantic, lexical, and hybrid queries against your Pinecone vector indexes.

This guide will walk you through the core concepts, configuration (from simple to advanced), and practical recipes to get you started.

💡 Core Concepts

To configure this tool, you must first answer three key questions about your Pinecone setup. Your answers will determine which parameters you need.

1. What is your search_type?

This is the most important setting. It tells the tool how to query your data.

• semantic: (Default) The best choice for "meaning-based" or "concept" search. It uses dense vectors.
• lexical: The best choice for "keyword" or "exact-match" search. It uses sparse vectors.
• single_index_hybrid: The best of both worlds. It queries a single index that contains both dense and sparse vectors, then reranks the results.
• seperate_index_hybrid: Queries two different indexes (one dense, one sparse) and merges the results.

Note on Sparse Vectors: For lexical and hybrid searches, the tool automatically uses the pinecone-sparse-english-v0 model to generate sparse vectors for your query text.

2. What is your Index Setup?

Your search_type dictates which index parameters to use.

Important: You will use EITHER the "Single Index" group OR the "Separate Index" group. Never both.

If your search_type is...	You MUST provide these parameters:
semantic	index_host and namespace
lexical	index_host and namespace
single_index_hybrid	index_host and namespace
seperate_index_hybrid	dense_index, dense_index_namespace, sparse_index, and sparse_index_namespace

3. What is your Embedding Setup?

This only applies to semantic and hybrid searches.

• Scenario A: Server-Side Embeddings (Modern)

  • If your Pinecone index was created recently and configured with a model, Pinecone handles embeddings automatically.
  • In this case, you OMIT the embedding_model and openai_api_key fields. The tool sends raw text, and Pinecone does the work.

• Scenario B: Client-Side Embeddings (Manual)

  • If your index is older or you manage embeddings manually, the tool must generate them before sending them to Pinecone.
  • In this case, you MUST provide the embedding_model and any required API keys.

---

⚙️ Configuration Reference

Here are all the available parameters, broken down by necessity.

🔑 Universal Parameters (Always Required)

These parameters are required for all search types.

Field	Type	Default	Description
api_key	string	required	Your Pinecone API key. This is always needed.
search_type	string	"semantic"	semantic, lexical, single_index_hybrid, or seperate_index_hybrid.
top_k	int	3	The number of search results to return.

---

🗂️ Group 1: Single-Index Parameters

Provide these only if search_type is semantic, lexical, or single_index_hybrid.

Field	Type	Description
index_host	string	Required. The full hostname of your index (e.g., my-index-123.svc.region.pinecone.io).
namespace	string	Required. The namespace within the index you want to search.

---

🧬 Group 2: Separate-Index Hybrid Parameters

Provide these only if search_type is seperate_index_hybrid.

Note: When using this group, DO NOT provide index_host or namespace.

Field	Type	Description
dense_index	string	Required. The full hostname of your dense (semantic) index.
dense_index_namespace	string	Required. The namespace within your dense index.
sparse_index	string	Required. The full hostname of your sparse (lexical) index.
sparse_index_namespace	string	Required. The namespace within your sparse index.

---

🤖 Group 3: Embedding & Filter Parameters (Optional)

Note on Sparse Vectors: For lexical and hybrid searches, the tool automatically uses the pinecone-sparse-english-v0 model to generate sparse vectors for your query text. These parameters control client-side embeddings and metadata filtering.

Field	Type	Description
embedding_model	string	See "Embedding Setup" above. Omit this if your index handles embeddings server-side.
openai_api_key	string	Required only if embedding_model is an OpenAI model (e.g., text-embedding-3-small).
dimensions	int	Required only if embedding_model is a Pinecone model (e.g., llama-text-embed-v2). Check with your admin for the correct value. (OpenAI API key is not required if you're using multilingual-e5-large or llama-text-embed-v2)
filter	mapping	A Pinecone metadata filter. (e.g., { "genre": { "$eq": "documentation" } }).

Summary of Supported Embedding Models (Client-Side)

Model Provider	embedding_model Value	Required Keys	Embedding dimensions
OpenAI	text-embedding-3-small	openai_api_key & embedding_model	1536 (no need to provide dimensions)
	text-embedding-3-large	openai_api_key & embedding_model	3072 (no need to provide dimensions)
	text-embedding-ada-002	openai_api_key & embedding_model	1536 (no need to provide dimensions)
Pinecone	multilingual-e5-large	dimensions & embedding_model	1024 (default) (Optional to provide dimensions)
	llama-text-embed-v2	dimensions & embedding_model	1024 (default), 2048, 768, 512, 384 (need to provide dimensions)

---

📚 Practical Recipes (Examples)

Copy and paste these configurations as a starting point.

Recipe 1: Modern Semantic Search (Server-Side)

Use Case: The most common and recommended setup. Your index handles embeddings automatically.

create_vertical_agent_network:
  agent-1:
    agent_name: Pinecone_agent
    LLM_config:
        params:
          model: gpt-5-nano
    tools:
      tool_assigned:
        - name: PineconeTool
          config:
            api_key: "pc-abc123..."
            search_type: "semantic"
            top_k: 5            
            # Single-Index Params
            index_host: "my-modern-index.svc.region.pinecone.io"
            namespace: "production-docs"
            
            # embedding_model is OMITTED
    agent_function:
      - Analyze the user's intent and immediately call PineconeTool with a distinct search query if external context is needed to answer. Use the retrieved data to ground your answer, citing the source where possible, and only request clarification if the tool returns insufficient results.
    incoming_edge:
      - Start
    outgoing_edge: []

Recipe 2: Manual Semantic Search (Client-Side OpenAI)

Use Case: Your index is older and requires you to provide vectors. You use OpenAI's text-embedding-3-small model.

create_vertical_agent_network:
  agent-1:
    agent_name: Pinecone_agent
    LLM_config:
        params:
          model: gpt-5-nano
    tools:
      tool_assigned:
        - name: PineconeTool
          config:
            api_key: "pc-abc123..."
            search_type: "semantic"
            top_k: 5
            # Single-Index Params
            index_host: "my-legacy-index.svc.region.pinecone.io"
            namespace: "archive"
            
            # Embedding Params
            embedding_model: "text-embedding-3-small"
            openai_api_key: "sk-xyz..." 
    agent_function:
      - Analyze the user's intent and immediately call PineconeTool with a distinct search query if external context is needed to answer. Use the retrieved data to ground your answer, citing the source where possible, and only request clarification if the tool returns insufficient results.
    incoming_edge:
      - Start
    outgoing_edge: []

Recipe 3: Lexical (Keyword) Search

Use Case: You only want to find exact keyword matches.

create_vertical_agent_network:
  agent-1:
    agent_name: Pinecone_agent
    LLM_config:
        params:
          model: gpt-5-nano
    tools:
      tool_assigned:
        - name: PineconeTool
          config:
            api_key: "pc-abc123..."
            search_type: "lexical"
            top_k: 10
            # Single-Index Params
            index_host: "my-sparse-index.svc.region.pinecone.io"
            namespace: "logs"
    agent_function:
      - Analyze the user's intent and immediately call PineconeTool with a distinct search query if external context is needed to answer. Use the retrieved data to ground your answer, citing the source where possible, and only request clarification if the tool returns insufficient results.
    incoming_edge:
      - Start
    outgoing_edge: []

Recipe 4: Single-Index Hybrid Search

Use Case: You have one advanced index that stores both dense and sparse vectors and want a single, reranked list of results.

create_vertical_agent_network:
  agent-1:
    agent_name: Pinecone_agent
    LLM_config:
        params:
          model: gpt-5-nano
    tools:
      tool_assigned:
        - name: PineconeTool
          config:
            api_key: "pc-abc123..."
            search_type: "single_index_hybrid"
            top_k: 5         
            # Single-Index Params
            index_host: "my-hybrid-index.svc.region.pinecone.io"
            namespace: "default"
            
            # Embedding Params (assuming server-side for this example)
            # Omit embedding_model if index handles it
    agent_function:
      - Analyze the user's intent and immediately call PineconeTool with a distinct search query if external context is needed to answer. Use the retrieved data to ground your answer, citing the source where possible, and only request clarification if the tool returns insufficient results.
    incoming_edge:
      - Start
    outgoing_edge: []

Recipe 5: Separate-Index Hybrid Search (Most Complex)

Use Case: You have two separate indexes (one semantic, one lexical) and want to query both and merge the results.

create_vertical_agent_network:
  agent-1:
    agent_name: Pinecone_agent
    LLM_config:
        params:
          model: gpt-5-nano
    tools:
      tool_assigned:
        - name: PineconeTool
          config:
            api_key: "pc-abc123..."
            search_type: "seperate_index_hybrid"
            top_k: 7
            
            # Separate-Index Params
            dense_index: "my-dense-index.svc.region.pinecone.io"
            dense_index_namespace: "main"
            sparse_index: "my-sparse-index.svc.region.pinecone.io"
            sparse_index_namespace: "main"
            
            # Embedding Params for the DENSE index
            embedding_model: "TextEmbeddingADA002"
            openai_api_key: "sk-xyz..."
    agent_function:
      - Analyze the user's intent and immediately call PineconeTool with a distinct search query if external context is needed to answer. Use the retrieved data to ground your answer, citing the source where possible, and only request clarification if the tool returns insufficient results.
    incoming_edge:
      - Start
    outgoing_edge: []

Recipe 6: Semantic Search with a Metadata Filter

Use Case: You want to find documents about "agentic AI" but only those published in or after 2024.

create_vertical_agent_network:
  agent-1:
    agent_name: Pinecone_agent
    LLM_config:
        params:
          model: gpt-5-nano
    tools:
      tool_assigned:
        - name: PineconeTool
          config:
            api_key: "pc-abc123..."
            search_type: "semantic"
            top_k: 5

            index_host: "my-modern-index.svc.region.pinecone.io"
            namespace: "production-docs"
            
            # Filter Param
            filter:
              year:
                $gte: 2024
    agent_function:
      - Analyze the user's intent and immediately call PineconeTool with a distinct search query if external context is needed to answer. Use the retrieved data to ground your answer, citing the source where possible, and only request clarification if the tool returns insufficient results.
    incoming_edge:
      - Start
    outgoing_edge: []

💡 Tip: Converting JSON Filters to YAML

If you have a complex Pinecone filter in JSON format and need to convert it to YAML, you can use this Python snippet:

import json
import yaml

json_string = '''
{
  "genre": { "$in": ["comedy", "documentary", "drama"] },
  "year": { "$eq": 2019 }
}
'''

data = json.loads(json_string)

yaml_str = yaml.safe_dump(data, sort_keys=False)
print(yaml_str)

and the output will be:

genre:
  $in:
    - comedy
    - documentary
    - drama
year:
  $eq: 2019

---

🚑 Troubleshooting & FAQ

• Error: "Parameter 'index_host' not provided"

  • You set search_type to semantic, lexical, or single_index_hybrid, but you forgot to provide the index_host and namespace parameters.

• Error: "Parameter 'dense_index' not provided"

  • You set search_type to seperate_index_hybrid, but you provided index_host instead of the required dense_index, sparse_index, dense_index_namespace, and sparse_index_namespace.

• Error: "OpenAI API key not provided"

  • You specified an embedding_model from OpenAI (like TextEmbedding3Small) but forgot to add the openai_api_key.

• My search results are bad or irrelevant.

  • This is almost always an embedding model mismatch. If you are using client-side embeddings, double-check that the embedding_model you set in the config is the exact same model that was used to create the vectors in your index.

• I get no results.

  • Check your namespace and filter values. An incorrect namespace or a filter that matches nothing are the most common causes.