Getting Started with Pinecone Assistant

The Pinecone Assistant API enables you to create and manage AI assistants powered by Pinecone's vector database capabilities. These Assistants can be customized with specific instructions and metadata, and can interact with files and engage in chat conversations.

Create an Assistant

Create a new Assistant with specified configurations. You can define the Assistant's name, provide instructions that guide its behavior, and attach metadata for organization and tracking purposes.

import { Pinecone } from '@pinecone-database/pinecone';

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

const assistant = await pc.assistants.create({
  name: 'product-assistant',
  instructions: 'You are a helpful product recommendation assistant.',
  metadata: {
    team: 'product',
    version: '1.0',
  },
});

console.log(assistant);
// {
//   name: 'product-assistant',
//   instructions: 'You are a helpful product recommendation assistant.',
//   metadata: { team: 'product', version: '1.0' },
//   status: 'Ready',
//   host: 'https://prod-1-data.ke.pinecone.io',
//   createdAt: '2025-01-08T22:24:50.525Z',
//   updatedAt: '2025-01-08T22:24:52.303Z'
// }
Copy

Upload a file

You must upload at least one file in order to chat with an Assistant. Files provide the knowledge base for the assistant to answer questions.

import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
const assistant = pc.assistant({ name: 'product-assistant' });

await assistant.uploadFile({
  path: 'product-catalog.txt',
  metadata: { source: 'catalog', version: '2025-01' },
});

// {
//   name: 'product-catalog.txt',
//   id: '921ad74c-2421-413a-8c86-fca81ceabc5c',
//   metadata: { source: 'catalog', version: '2025-01' },
//   createdOn: '2025-01-06T19:14:21.969Z',
//   updatedOn: '2025-01-06T19:14:21.969Z',
//   status: 'Processing',
//   percentDone: null
// }
Copy

Chat with an Assistant

Once you have created an assistant and uploaded at least one file, you can start chatting:

import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
const assistant = pc.assistant({ name: 'product-assistant' });

const response = await assistant.chat({
  messages: [
    {
      role: 'user',
      content: 'What products do you recommend for outdoor activities?',
    },
  ],
  model: 'gpt-4o', // Optional: specify the model (default: 'gpt-4o')
  temperature: 0.2, // Optional: control response randomness (0.0-1.0)
});

console.log(response);
// {
//   id: '000000000000000023e7fb015be9d0ad',
//   finishReason: 'stop',
//   message: {
//     role: 'assistant',
//     content: 'Based on your catalog, I recommend...'
//   },
//   model: 'gpt-4o',
//   citations: [ { position: 209, references: [Array] } ],
//   usage: { promptTokens: 493, completionTokens: 38, totalTokens: 531 }
// }
Copy

List Assistants

Retrieve a list of all Assistants in your account:

import { Pinecone } from '@pinecone-database/pinecone';

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

const assistants = await pc.assistants.list();
console.log(assistants);
// {
//   assistants: [
//     {
//       name: 'product-assistant',
//       instructions: 'You are a helpful product recommendation assistant.',
//       metadata: { team: 'product', version: '1.0' },
//       status: 'Ready',
//       host: 'product-assistant-abc123.svc.pinecone.io'
//     }
//   ]
// }
Copy

Update an Assistant

Update an Assistant's instructions or metadata:

import { Pinecone } from '@pinecone-database/pinecone';

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

await pc.assistants.update({
  name: 'product-assistant',
  instructions:
    'You are a helpful product recommendation assistant. Be concise and friendly.',
  metadata: { version: '2.0' },
});
Copy

Get information about an Assistant

Retrieve information about a specific Assistant:

import { Pinecone } from '@pinecone-database/pinecone';

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

const info = await pc.assistants.describe('product-assistant');
console.log(info);
// {
//   name: 'product-assistant',
//   instructions: 'You are a helpful product recommendation assistant.',
//   metadata: { team: 'product', version: '2.0' },
//   status: 'Ready',
//   host: 'https://prod-1-data.ke.pinecone.io',
//   createdAt: '2025-01-08T22:24:50.525Z',
//   updatedAt: '2025-01-09T10:15:30.123Z'
// }
Copy

Delete an Assistant

Delete an Assistant by name. Note that deleting an Assistant also deletes all associated files.

import { Pinecone } from '@pinecone-database/pinecone';

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

await pc.assistants.delete('product-assistant');
Copy

Complete quickstart example

import { Pinecone } from '@pinecone-database/pinecone';

async function assistantQuickstart() {
  const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

  // 1. Create an assistant
  await pc.assistants.create({
    name: 'my-assistant',
    instructions: 'You are a helpful assistant.',
  });

  // 2. Target the assistant
  const assistant = pc.assistant({ name: 'my-assistant' });

  // 3. Upload a file
  const operation = await assistant.uploadFile({
    path: 'knowledge-base.txt',
  });

  // 4. Wait for file to be processed (check status)
  let op = operation;
  while (op.status === 'Processing') {
    await new Promise((r) => setTimeout(r, 2000));
    op = await assistant.describeOperation(operation.id);
  }
  if (op.status !== 'Completed') {
    throw new Error(`Upload failed: ${op.errorMessage}`);
  }

  // 5. Chat with the assistant
  const response = await assistant.chat({
    messages: [
      {
        role: 'user',
        content: 'What can you tell me about the information in the file?',
      },
    ],
  });

  if (response.message?.content) {
    console.log(response.message.content);
  }
}

assistantQuickstart();
Copy

For more details on chat operations and streaming, see Chat Operations.

For file management operations, see File Management.