Pinecone (external store)

Connect your existing Pinecone index — REST-based, works for serverless and pod-based indexes alike.

Pinecone

Agentheya calls Pinecone’s REST API directly (no SDK). For every chat turn the runtime:

1. Embeds the user query with the embedding provider you configured.
2. Sends POST https://<your-host>/query with the vector + your topK + optional filter.
3. Maps the resulting matches into the agent’s retrieval context to ground its answer.

Connection settings

Field	Required	Notes
pinecone_host	yes	Per-index host from the Pinecone console. Looks like my-index-abc.svc.aped-us-east-1-fkj4.pinecone.io. Works for both serverless and pod-based indexes. Copy without https://.
pinecone_index	yes	Logical index name (e.g. docs). Pinecone resolves the same data as the host header, but the field is required so the trace stays readable.
pinecone_namespace	no	Optional namespace inside the index. Empty = default namespace.
pinecone_api_key	yes	Pinecone API key. Encrypted at rest.
text_field	yes	Name of the metadata field on each vector that holds the original chunk text. Defaults to text — change to match your indexing convention.
title_field	no	Optional metadata field used as the citation title. Falls back to the vector’s id.
source_field	no	Optional metadata field with a URL / origin path for citations.
top_k	no	Hits to request per query (1–50, default 8).
filter	no	Native Pinecone metadata filter object. Passed verbatim. Example: {"tenant": "acme"}.

Embedding settings

Pinecone does not embed on its own — you supply a query vector with each POST /query. Agentheya needs the same embedding provider + model your data was indexed with, plus an API key.

Field	Notes
embedding_provider	One of openai, voyage, cohere.
embedding_model	Model id (e.g. text-embedding-3-small, voyage-3.5, embed-english-v3.0). Must match what your data was indexed with — query and index vectors share the same vector space.
embedding_api_key	API key for the embedding provider. Encrypted at rest. The owner pays this provider directly; Agentheya does not bill for these calls.
embedding_dimensions	Optional sanity check. When set, vectors with the wrong dimension count are rejected before reaching Pinecone (e.g. catches a text-embedding-3-large model being used against a 1536-D index).

Common shapes

Standard 1536-D OpenAI setup:

{
  "kind": "pinecone",
  "name": "Acme docs",
  "pinecone_host": "acme-docs-abc.svc.aped-us-east-1-fkj4.pinecone.io",
  "pinecone_index": "acme-docs",
  "pinecone_api_key": "pcsk_...",
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "embedding_api_key": "sk-...",
  "embedding_dimensions": 1536,
  "text_field": "text",
  "title_field": "title",
  "source_field": "url",
  "top_k": 8
}

Multi-tenant namespace + filter:

{
  "kind": "pinecone",
  "name": "Acme knowledge (tenant=acme)",
  "pinecone_host": "shared-knowledge-abc.svc.aped-us-east-1-fkj4.pinecone.io",
  "pinecone_index": "shared-knowledge",
  "pinecone_namespace": "acme",
  "pinecone_api_key": "pcsk_...",
  "embedding_provider": "voyage",
  "embedding_model": "voyage-3.5",
  "embedding_api_key": "pa-...",
  "filter": { "$or": [ { "category": "public" }, { "owner": "acme" } ] },
  "text_field": "text",
  "top_k": 12
}

“Test connection” button

Hits POST https://<host>/describe_index_stats first. If credentials work, the editor runs a one-shot embedding round-trip (when embedding fields are filled in) so a dimension mismatch is caught immediately. Both halves of the result are surfaced inline; either passing is enough to write the connection, but you usually want both.

Gotchas

• Wrong host: Pinecone returns 404 if the host is right but the index name is wrong, and ENOTFOUND / connection refused if the host itself is wrong. The “Test connection” button surfaces the raw error.
• Dimension mismatch: querying a 1536-D index with text-embedding-3-large (3072-D) returns a 400 from Pinecone. Setting embedding_dimensions makes Agentheya fail-fast before the request, with a clearer error.
• Filter syntax: Pinecone uses MongoDB-flavored filter language ($and, $or, $eq, $in, …). Mistakes here surface at chat time, not save time — test with the dashboard editor’s connection check.
• Subscriber scoping: if you store per-tenant content in one index, use filter to scope. Agentheya does not automatically inject power_user_id into Pinecone queries today.