Agentic quickstart

This quickstart shows you how to use AI coding agents like Claude Code and Cursor to build Pinecone applications with current best practices. Instead of copying code snippets, you’ll work with an agent that understands Pinecone APIs and implements production-ready patterns automatically.

Because this quickstart relies on AI coding agents, the exact implementation may vary each time. If you run into issues, please give us feedback.

1. Choose a use case

Search
RAG/agents
Recommendations

Build a semantic search system that returns ranked results from your knowledge base. This pattern is ideal for search interfaces where users need a list of relevant documents with confidence scores.In production, semantic search typically involves a single large dataset (or small number of datasets) with medium-to-high query throughput. For high-traffic applications, you may need dedicated read nodes to handle the query load efficiently.

2. Set up the Pinecone CLI

The Pinecone CLI handles administrative tasks like creating and managing indexes, while Pinecone SDKs are used for application code and data operations. You’ll use both in this quickstart.

The CLI is in public preview.

Install the Pinecone CLI:

brew tap pinecone-io/tap
brew install pinecone-io/tap/pinecone

3. Set up a coding agent

AI coding agents like Claude Code and Cursor learn from web searches and training data, which can include outdated patterns. To ensure your assistant uses current Pinecone APIs and best practices, you’ll create a CLAUDE.md or AGENTS.md reference file that provides authoritative, up-to-date information about Pinecone’s 2025 APIs and CLI commands.

Claude Code
Cursor

Open a terminal or command prompt.
Create a new project folder for your Pinecone application:
```
mkdir pinecone-app
cd pinecone-app
```
Download the reference file with authoritative Pinecone information and save it as CLAUDE.md in your project root:
```
curl -o CLAUDE.md https://docs.pinecone.io/assets/pinecone-agent-reference-python.md
```
Python-only: The reference file currently features only the Pinecone Python SDK, so all generated code will be in Python. Support for other SDKs (TypeScript, Go, Java, .NET) is coming soon.
Start Claude Code:
```
claude
```
If you don’t have Claude Code installed, see the Claude Code quickstart.

Verify that Claude Code has access to the CLAUDE.md file:

Confirm you can see the CLAUDE.md file and understand the current Pinecone best practices it contains.

Summarize the key points about using Pinecone in 2025.

Just give me a concise summary - don't create any additional files or examples yet.

Ask Claude Code to set up your environment and install the Pinecone SDK:

Create a new Python project for working with Pinecone.

Set up the project structure and install the Pinecone SDK.

Keep this basic: Create the essential directories, virtual environment, and install dependencies. Activate the virtual environment. Don't build any application code yet.

Your coding agent will:

Create the proper directory structure
Set up a virtual environment
Install required dependencies
Create configuration files

Ask Claude Code to configure a Pinecone API key for your application:
```
Create an API key called "agentic-quickstart".

Save the API key as an env variable for the project.
```
Your coding agent will:
- Create an API key using CLI command pc api-key create
- Save the API key as an env variable for the project

4. Create an index

Now that your coding agent has access to up-to-date Pinecone reference information, let’s create your first index:

I want to create a Pinecone index for a knowledge base application. 

Please create an index called "agentic-quickstart-search" with integrated embeddings that can handle text documents. Use the best practices from the CLAUDE.md or AGENTS.md file.

Keep this focused: Create one index that follows CLAUDE.md or AGENTS.md best practices and verify it was created successfully. Don't build management systems or multiple examples.

Your coding agent will:

Create an index using CLI command pc index create
Select llama-text-embed-v2 (recommended embedding model)
Set up proper cloud/region configuration
Verify successful creation with CLI command pc index describe

5. Build a knowledge base

Now ask your coding agent to help you populate your index:

I want to create a knowledge base about AI and machine learning concepts.

Please help me:
1. Create 20 unique sample documents with metadata (following CLAUDE.md or AGENTS.md guidelines)
2. Store them in the Pinecone index using proper namespaces

The documents should cover these topics to answer specific questions:
- How neural networks learn and adapt (include gradient descent, backpropagation, training)
- Differences between supervised and unsupervised learning (with clear comparisons)
- AI fairness and transparency (bias mitigation, explainability, ethical AI)

Plus other foundational AI/ML concepts.

Keep this simple: Create sample data and store it properly. Don't verify search functionality yet.

Claude Code will demonstrate:

Proper namespace isolation
Flat metadata only (no nested objects)
Batch size of 96 (text records limit)
Integrated embeddings (Pinecone handles vectorization)

6. Implement semantic search

Ask your coding agent to build a search system:

Now I want to search my knowledge base. 

Please create a search function that:
1. Uses semantic search to find relevant documents
2. Includes reranking with bge-reranker-v2-m3 (as specified in CLAUDE.md or AGENTS.md)
3. Allows filtering by metadata
4. Returns well-formatted results

Create one focused search function that demonstrates these capabilities. Don't build search classes, interactive interfaces, or learning path systems.

Your coding agent will implement:

The proper search pattern (fetch 2x candidates for reranking, return top_k)
The bge-reranker-v2-m3 reranking model
Correct metadata filtering with supported operators
Proper namespace handling

Your coding agent will probably also run some test queries. Test it further:

Search my knowledge base for answers to these questions: 
- What is overfitting and how can I prevent it?
- How does transfer learning work?
- What is reinforcement learning and where is it used?

7. Add error handling

Now harden your search implementation with production-ready error handling:

I want to make my search function production-ready using the error handling patterns from CLAUDE.md or AGENTS.md.

Please update my search implementation to include:
1. Proper error classification - distinguish between retryable (5xx, 429) and non-retryable (4xx) errors
2. Exponential backoff with jitter for transient failures
3. Rate limit handling (429 errors) with appropriate backoff
4. Operation monitoring and logging to track performance and errors
5. Graceful degradation when searches fail

Use the specific error handling patterns from CLAUDE.md or AGENTS.md.

Show me the production-ready search function with full error handling. Don't run any tests yet.

Your coding agent will demonstrate:

Wrapping search operations with exponential_backoff_retry
Using PineconeException with status code checking
Implementing the monitored_operation pattern for logging
Proper handling of rate limits (429) vs server errors (5xx) vs client errors (4xx)
How retry logic recovers from transient failures automatically
Tracking and logging failed operations

As your coding agent to run some error handling tests:

Show me examples of how this handles:
- A temporary service unavailability (503 error)
- Rate limiting (429 error)
- An invalid filter parameter (400 error)

For each scenario, explain why the error handling behaves differently.

This transforms your development code into production-ready code by adding resilience and observability.

8. Clean up

When you’re done, ask your coding agent to clean up your resources:

Help me safely delete my Pinecone index and clean up the Python project.

9. Give us feedback

We’d love to hear your feedback on this quickstart. Please fill out this short survey.

Next steps

Index data

Learn more about storing data in Pinecone

Search

Explore different forms of vector search.

Optimize

Find out how to improve performance

Continue with a coding agent: For your next Pinecone projects, start by asking your coding agent to help you plan and implement your specific requirements. Be sure to use the Pinecone reference information in CLAUDE.md or AGENTS.md and the Pinecone documentation to ensure you’re using current best practices.

Get started

Index data

Search

Optimize

Manage data

Manage cost

Move to production

Admin

Operations

Using pods

1. Choose a use case

2. Set up the Pinecone CLI

3. Set up a coding agent

4. Create an index

5. Build a knowledge base

6. Implement semantic search

7. Add error handling

8. Clean up

9. Give us feedback

Next steps

Index data

Search

Optimize

Get started

Index data

Search

Optimize

Manage data

Manage cost

Move to production

Admin

Operations

Using pods

​1. Choose a use case

​2. Set up the Pinecone CLI

​3. Set up a coding agent

​4. Create an index

​5. Build a knowledge base

​6. Implement semantic search

​7. Add error handling

​8. Clean up

​9. Give us feedback

​Next steps

Index data

Search

Optimize

1. Choose a use case

2. Set up the Pinecone CLI

3. Set up a coding agent

4. Create an index

5. Build a knowledge base

6. Implement semantic search

7. Add error handling

8. Clean up

9. Give us feedback

Next steps