::::card-grid
:::card{title="Assistant quickstart" href="/guides/get-started-assistant-quickstart-sdk-quickstart" icon="comments"}
Create an AI assistant that answers complex questions about your proprietary data
:::

:::card{title="Database quickstart" href="/guides/get-started-quickstart" icon="database"}
Set up a fully managed vector database for high-performance semantic search
:::
::::

## Use cases

Pinecone Assistant is useful for a variety of tasks, especially for the following:

- Prototyping and deploying an AI assistant quickly.
- Providing context-aware answers about your proprietary data without training an LLM.
- Retrieving answers grounded in your data, with references.

## SDK support

You can use the [Assistant API](/guides/apis-assistant-introduction) directly, through the [Pinecone Python SDK](/guides/sdks-python-overview), or through the [Pinecone Node.js SDK](/guides/sdks-node-overview).

## Workflow

You can use the Pinecone Assistant through the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/assistant) or [Pinecone API](/guides/apis-assistant-introduction).

::::::tabs
:::::tab{title="Overview"}
The following steps outline the general Pinecone Assistant workflow:

::::steps
:::step{title="Create an assistant"}
[Create an assistant](/guides/build-an-assistant-create-assistant) to answer questions about your documents.
:::

:::step{title="Upload documents"}
[Upload documents](/guides/upload-your-data-upload-files) to your assistant. Your assistant manages chunking, embedding, and storage for you.
:::

:::step{title="Chat with an assistant"}
[Chat with your assistant](/guides/chat-with-an-assistant-chat-with-assistant) and receive responses as a JSON object or as a text stream. For each chat, your assistant queries a large language model (LLM) with context from your documents to ensure the LLM provides grounded responses.
:::

:::step{title="Evaluate answers"}
[Evaluate the assistant's responses](/guides/evaluate-answers-evaluation-overview) for correctness and completeness.
:::

:::step{title="Optimize performance"}
[Use custom instructions](https://www.pinecone.io/learn/assistant-api-deep-dive/#Custom-Instructions) to tailor your assistant's behavior and responses to specific use cases or requirements. [Filter by metadata associated with files](https://www.pinecone.io/learn/assistant-api-deep-dive/#Using-Metadata) to reduce latency and improve the accuracy of responses.
:::

:::step{title="Retrieve context snippets"}
[Retrieve context snippets](/guides/retrieve-context-snippets-retrieve-context-snippets) to understand what relevant data snippets Pinecone Assistant is using to generate responses. You can use the retrieved snippets with your own LLM, RAG application, or agentic workflow.
:::
::::

:::callout{intent="note"}
For information on how the Pinecone Assistant works, see [Assistant architecture](/guides/architecture-assistant-architecture).
:::
:::::

::::tab{title="Code sample"}
The following code samples outline the Pinecone Assistant workflow using either the [Pinecone Python SDK](/guides/sdks-python-overview) and [Pinecone Assistant plugin](/guides/sdks-python-overview#install-the-pinecone-assistant-python-plugin) or the [Pinecone Node.js SDK](/guides/sdks-node-overview).

:::code-group
```python Python theme={null}
# pip install pinecone
# pip install pinecone-plugin-assistant

from pinecone import Pinecone
import requests
from pinecone_plugins.assistant.models.chat import Message

pc = Pinecone(api_key="YOUR_API_KEY")

# Create an assistant.
assistant = pc.assistant.create_assistant(
    assistant_name="example-assistant", 
    instructions="Use American English for spelling and grammar.", # Description or directive for the assistant to apply to all responses.
    region="us", # Region to deploy assistant. Options: "us" (default) or "eu".    
    timeout=30 # Maximum seconds to wait for assistant status to become "Ready" before timing out.
)

# Upload a file to your assistant.
response = assistant.upload_file(
    file_path="/Users/jdoe/Downloads/Netflix-10-K-01262024.pdf",
    metadata={"company": "netflix", "document_type": "form 10k"},
    timeout=None
)

# Set up for evaluation later.
payload = {
    "question": "Who is the CFO of Netflix?", # Question to ask the assistant.
    "ground_truth_answer": "Spencer Neumann" # Expected answer to evaluate the assistant's response.
}

# Chat with the assistant.
msg = Message(role="user", content=payload["question"])
resp = assistant.chat(messages=[msg], model="gpt-4o")
print(resp)

# {
#    'id': '0000000000000000163008a05b317b7b', 
#    'model': 'gpt-4o-2024-05-13', 
#    'usage': {
#        'prompt_tokens': 9259, 
#        'completion_tokens': 30, 
#        'total_tokens': 9289
#        }, 
#        'message': {
#            'content': 'The Chief Financial Officer (CFO) of Netflix is Spencer Neumann.', 
#            'role': '"assistant"'
#            }, 
#            'finish_reason': 'stop', 
#            'citations': [
#                {
#                    'position': 63, 
#                    'references': [
#                        {
#                            'pages': [78, 72, 79], 
#                            'file': {
#                                'name': 'Netflix-10-K-01262024.pdf', 
#                                'id': '76a11dd1...', 
#                                'metadata': {
#                                    'company': 'netflix', 
#                                    'document_type': 'form 10k'
#                                    }, 
#                                    'created_on': '2024-12-06T01:29:07.369208590Z', 
#                                    'updated_on': '2024-12-06T01:29:50.923493799Z', 
#                                    'status': 'Available', 
#                                    'signed_url': 'https://storage.googleapis.com/...',
#                                    'size': 1073470.0
#                                }
#                            }
#                        ]
#                    }
#                ]
#            }

# Evaluate the assistant's response.
payload["answer"] = resp.message.content

headers = {
    "Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

url = "https://prod-1-data.ke.pinecone.io/assistant/evaluation/metrics/alignment"

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

# {
#    "metrics":
#    {
#        "correctness":1.0,
#        "completeness":1.0,
#        "alignment":1.0
#    },
#    "reasoning":
#    {
#        "evaluated_facts":
#        [
#            {
#                "fact":
#                {
#                    "content":"Spencer Neumann is the CFO of Netflix."
#                    },
#                    "entailment":"entailed"
#                }
#            ]
#        },
#        "usage":
#        {
#            "prompt_tokens":1221,
#            "completion_tokens":24,
#            "total_tokens":1245
#            }
#        }
```

```javascript JavaScript theme={null}
import { Pinecone } from "@pinecone-database/pinecone";

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function testPinecone() {
  try {
    console.log("Initializing Pinecone client...");

    const pc = new Pinecone({
      apiKey: "YOUR_API_KEY",
    });

    console.log("Pinecone client initialized successfully.");

    const assistantName = "test-assistant";

    // Create a new assistant.
    console.log(`Creating new assistant: ${assistantName}...`);
    await pc.createAssistant({
      name: assistantName,
      region: "us",
      metadata: { 'test-key': 'test-value' },
    });

    // Validate Assistant was created through describe.
    const asstDesc = await pc.describeAssistant(assistantName);
    console.log(`Described Assistant: ${JSON.stringify(asstDesc)}`);

    // Delay to ensure the Assistant is ready.
    await sleep(4000);

    // Upload file
    const assistant = pc.Assistant(assistantName);
    await assistant.uploadFile({
      path: '/Users/jdoe/Downloads/Netflix-10-K-01262024.pdf',
      metadata: { 'test-key': 'test-value' },
    });
    console.log("File uploaded. Processsing...");

    // Delay to ensure file is available.
    await sleep(45000);

    // Chat
    const chatResp = await assistant.chat({
      messages: [{ role: 'user', content: 'Who is the CFO of Netflix?' }]
    });
    console.log(chatResp);

  // Error handling
  } catch (error) {
    console.error("Error:", error);
  }
}

// Run the sample code
testAssistant();
```
:::
::::
::::::

## Learn more

::::card-grid
:::card{title="API Reference" href="/guides/apis-introduction" icon="code-simple"}
Comprehensive details about the Pinecone APIs, SDKs, utilities, and architecture.
:::

:::card{title="Blog" href="https://www.pinecone.io/learn/assistant-api-deep-dive/" icon="blog"}
Four features of the Assistant API you aren't using - but should
:::

:::card{title="Changelog" href="/guides/changelog-2026" icon="party-horn"}
News about features and changes in Pinecone and related tools.
:::
::::

## Related pages

- [Account management](./account-management-index.md)
- [Admin](./admin-2-index.md)
- [Admin](./admin-index.md)
- [APIs](./apis-index.md)
- [Architecture](./architecture-index.md)
- [Assistants](./assistants-index.md)
- [Bring Your Own Cloud](./bring-your-own-cloud-index.md)
- [Build an assistant](./build-an-assistant-index.md)
- [Build an integration](./build-an-integration-index.md)
- [Changelog](./changelog-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.