Skip to main content
A query is a single turn that takes a question and returns a grounded answer, and a multi-turn conversation is a session. To answer, Pinecone Nexus runs an agent loop in which the model writes Python against a retrieval SDK to gather the evidence it needs, then composes an answer with citations. In a query turn, the agent loops, writing code against a retrieval SDK to gather evidence, then composes a cited answer In a query turn, the agent loops, writing code against a retrieval SDK to gather evidence, then composes a cited answer

​
Retrieval as code

Two common ways to answer over a corpus have drawbacks. Agentic retrieval-augmented generation (RAG) issues many retrieval calls and spends tokens stitching the results together. A coding agent that greps and parses raw files is flexible, but it’s slow and expensive, and its results are unreliable. A query turn does the hard retrieval work in one place. The model writes Python that reads artifacts, runs search, walks the graph, and queries structured tables, then answers from only the evidence it surfaced. Raw tool output never enters the model’s context.

​
Query runtime

The Nexus runtime runs each query. It’s a single generic Python image that the orchestrator launches fresh for each turn, with no per-context code. Every context runs the same entrypoint, parameterized by its manifest.
  1. Container: Each query starts one isolated container that runs that turn, then exits. It pulls the scoped contexts’ curated knowledge: artifacts on disk plus their vector index.
  2. Orientation: The runtime reads the manifests and an artifact outline up front, so the model starts knowing what knowledge exists and where.
  3. Agent loop: The model writes Python into a persistent REPL that calls the retrieval SDK to read artifacts, run searches, walk the graph, and query structured tables.
  4. Step events: The runtime posts each step as it happens, which powers the live answer stream. You can replay the full sequence for any query in its query trace.
  5. Synthesis: Once enough evidence is gathered, the runtime composes a grounded answer with inline citations, then finalizes the turn.

​
Agent loop

The model’s primary tool is run_python, a persistent REPL. Variables survive across calls, so the model chains operations together: find an artifact, read it, filter its sources, drill for a verbatim quote, all in one block. It processes results in code and prints only what it needs. If the first pass misses, the model refines its code and searches again, so a hard question gets more steps. The loop stops as soon as the model can answer.
Independent searches run concurrently, and the model reuses lookups it already holds in a variable. The loop has a step cap, so the model aims to gather what it needs and answer in a few steps.

​
Tool output limit

By default, the model sees at most 10,000 characters of each run_python result. A longer result is cut off and ends with a notice, such as [truncated: showing 10,000 of 46,212 chars], so the model knows the result is partial. You can raise the limit to as much as 100,000 characters for a single query. This helps with questions whose answers are long lists, such as “List every company with a change-of-control clause.” A higher limit makes the query slower and more expensive. Every extra 10,000 characters adds about 2,500 input tokens, which are sent again on every later step. To raise it, set max_tool_output_chars to a value from 1 to 100,000 in the POST /query request body. A value outside that range returns a 400 error. This field requires X-Pinecone-Api-Version: unstable, and the unstable API can change without notice.
curl

​
Retrieval SDK

The Composable Retriever loads these primitives into the REPL. The model reads artifacts off disk first because it’s cheapest, falls back to search over the index, and uses SQL for counts and enumerations.

​
Read artifacts

​
Structured tables

​
Synthesis

  • Evidence: The model composes the answer from the evidence its code surfaced, so it reasons over a small, relevant context.
  • Citations: Each inline citation marker maps to a source span, with the file, page, and verbatim text behind the claim.
  • Structured output: When a query includes a shape, synthesis returns a document that conforms to that schema.

​
Session instructions

A session can carry its own instructions, a system prompt layered over the context’s default that shapes every answer in the session. See Set session instructions.