Manage assistants

List, describe, update, and delete Pinecone assistants and check assistant status using the API, Python SDK, Node.js SDK, or Pinecone console.

List assistants for a project

You can get the name, status, and metadata for each assistant in your project as in the following example:

Python

# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant

from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

assistants = pc.assistant.list_assistants()

JavaScript

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

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

const assistants = await pc.listAssistants();
console.log(assistants);

curl

PINECONE_API_KEY="YOUR_API_KEY"

curl -X GET "https://api.pinecone.io/assistant/assistants" \
  -H "Api-Key: $PINECONE_API_KEY"

This operation returns a response like the following:

JSON

{
  "assistants": [
    {
      "name": "example-assistant",
      "instructions": "Use American English for spelling and grammar.",
      "metadata": {"team": "customer-support", "version": "1.0"},
      "status": "Initializing",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ]
}

You can use the name value to check the status of an assistant.

Get the status of an assistant

You can get the status and metadata for your assistant as in the following example:

Python

# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant

from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

assistant = pc.assistant.describe_assistant(
    assistant_name="example-assistant", 
)

JavaScript

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

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

const assistant = await pc.describeAssistant('example-assistant');
console.log(assistant);

curl

PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl -X GET "https://api.pinecone.io/assistant/assistants/$ASSISTANT_NAME" \
  -H "Api-Key: $PINECONE_API_KEY"

This operation returns a response like the following:

JSON

{
  "name": "example-assistant",
  "instructions": "Use American English for spelling and grammar.",
  "metadata": {"team": "customer-support", "version": "1.0"},
  "status": "Initializing",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

The status field has the following possible values:

Initializing
Failed
Ready
Terminating

Change an assistant's chat model

The chat model is the underlying large language model (LLM) that powers the assistant's responses. You can change the chat model for an existing assistant through the Pinecone console:

On the Assistants page, select the assistant you want to update.
In the sidebar on the right, select Settings (gear icon).
Select the Chat model.

Add instructions to an assistant

You can add or update the instructions for an existing assistant. Instructions are a short description or directive for the assistant to apply to all of its responses. For example, you can update the instructions to reflect the assistant's role or purpose.

For example:

Python

# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant

from pinecone import Pinecone

pc = Pinecone(api_key=YOUR_API_KEY)

assistant = pc.assistant.update_assistant(
    assistant_name="example-assistant", 
    instructions="Use American English for spelling and grammar.",
    metadata={"team": "customer-support", "version": "1.1"} # Optional metadata (max 16KB) for organizing assistants.
)

JavaScript

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

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

await pc.updateAssistant('example-assistant', {
  instructions: 'Use American English for spelling and grammar.',
  metadata: { team: 'customer-support', version: '1.1' }, // Optional metadata (max 16KB) for organizing assistants.
});

curl

PINECONE_API_KEY="YOUR_API_KEY"

curl -X PATCH "https://api.pinecone.io/assistant/assistants/example-assistant" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "instructions": "Use American English for spelling and grammar.",
  "metadata": {"team": "customer-support", "version": "1.1"}
}'

The example above returns a result like the following:

JSON

{
    "name":"example-assistant",
    "instructions":"Use American English for spelling and grammar.",
    "metadata":{"team": "customer-support", "version": "1.1"},
    "status":"Ready",
    "created_at":"2024-06-14T14:58:06.573004549Z",
    "updated_at":"2024-10-01T19:44:32.813235817Z"
}

Delete an assistant

You can delete an assistant as in the following example:

Python

# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant

from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")

pc.assistant.delete_assistant(
    assistant_name="example-assistant", 
)

JavaScript

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

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

await pc.deleteAssistant('example-assistant');

curl

PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl -X DELETE "https://api.pinecone.io/assistant/assistants/$ASSISTANT_NAME" \
  -H "Api-Key: $PINECONE_API_KEY"