Manage assistants

After you create an assistant, you can list your assistants, check an assistant’s status, change its chat model, update its instructions, and delete assistants you no longer need.

List assistants for a project

To list the assistants in your project, call list:

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

for assistant in pc.assistants.list():
    print(assistant.name, assistant.status)

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

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

const { assistants } = await pc.assistants.list();
console.log(assistants);

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:

Response

{
  "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.

You can list assistants using the Pinecone console.

Get the status of an assistant

To get an assistant’s status and metadata, call describe:

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

assistant = pc.assistants.describe(name="example-assistant")
print(assistant.status)

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

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

const assistant = await pc.assistants.describe('example-assistant');
console.log(assistant.status);

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:

Response

{
  "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
InitializationFailed
Failed
Ready
Terminating

You can check the status of an assistant using the Pinecone console.

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

Instructions are a short directive the assistant applies to all of its responses, for example to reflect its role or purpose.

Instructions (maximum size 16 KB) are included in every chat API call. Longer instructions increase input token costs for each request and consume more of the LLM’s context window, reducing available space for retrieved context and conversation history.

To add or update an assistant’s instructions, call update:

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

assistant = pc.assistants.update(
    name="example-assistant",
    instructions="Use American English for spelling and grammar.",
    metadata={"team": "customer-support", "version": "1.1"},
)

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

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

await pc.assistants.update({
  name: 'example-assistant',
  instructions: 'Use American English for spelling and grammar.',
  metadata: { team: 'customer-support', version: '1.1' },
});

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:

Response

{
    "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"
}

You can add or update instructions for an assistant using the Pinecone console.

Delete an assistant

To delete an assistant, call delete:

Deleting an assistant also deletes all files uploaded to the assistant.

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

pc.assistants.delete(name="example-assistant")

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

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

await pc.assistants.delete('example-assistant');

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"

You can delete an assistant using the Pinecone console.

Get started

Build an assistant

Upload your data

Chat with an assistant

Context snippets

Evaluate answers

Agents

Admin

List assistants for a project

Get the status of an assistant

Change an assistant’s chat model

Add instructions to an assistant

Delete an assistant

​List assistants for a project

​Get the status of an assistant

​Change an assistant’s chat model

​Add instructions to an assistant

​Delete an assistant

List assistants for a project

Get the status of an assistant

Change an assistant’s chat model

Add instructions to an assistant

Delete an assistant