Astra Assistants

Common errors

• ModuleNotFoundError: No module named 'astra-assistants'

  cause The 'astra-assistants' package is not installed in the Python environment.
  fix Install the package using pip: 'pip install astra-assistants'.

• ImportError: cannot import name 'Chroma' from 'astra-assistants'

  cause The 'Chroma' module is not part of the 'astra-assistants' package.
  fix Ensure you are importing the correct module from 'astra-assistants' as per the official documentation.

• AttributeError: module 'astra_assistants' has no attribute 'patch'

  cause The 'patch' function is not available in the 'astra_assistants' module.
  fix Verify the correct usage of the 'astra_assistants' module and refer to the official documentation for guidance.

• TypeError: 'NoneType' object is not callable

  cause Attempting to call a function or method that is None, possibly due to incorrect initialization or missing dependencies.
  fix Check the initialization of your objects and ensure all dependencies are correctly installed and configured.

• ValueError: Invalid model specified: 'gpt-4-1106-preview'

  cause The specified model name is not recognized or supported by the 'astra-assistants' package.
  fix Refer to the official documentation for the list of supported models and use a valid model name.

Warnings

• breaking The `astra-assistants` library underwent a complete API overhaul in version 2.0.0 to align with OpenAI's 2024-02-15 API. This introduced new client structures, method calls (e.g., `client.beta.assistants.create`), and response object formats.
  Fix: Review the official documentation for v2.x. Update all client instantiations and method calls to match the new `openai`-like API surface.
• gotcha Astra Assistants requires `ASTRA_DB_APPLICATION_TOKEN` and `ASTRA_DB_API_ENDPOINT` to be set as environment variables or passed explicitly during client initialization. Forgetting either or providing incorrect values will result in authentication errors.
  Fix: Double-check your Astra DB credentials and ensure they are correctly set in your environment or passed as `astra_db_application_token` and `astra_db_api_endpoint` arguments to `AstraAssistants()`.
• gotcha When using models like `gpt-4o` or `gpt-3.5-turbo` that are provided by OpenAI, you still need to set your `OPENAI_API_KEY` environment variable, even though you are using the `astra-assistants` wrapper. Astra DB handles the persistence and vector search, but may delegate to OpenAI for the LLM itself.
  Fix: Ensure `OPENAI_API_KEY` is also set in your environment if you plan to use OpenAI's proprietary models through Astra Assistants.
• gotcha Accessing message content requires navigating through nested objects. The content is typically a list of content blocks, and for text, you'll often need `msg.content[0].text.value`.
  Fix: Always check `msg.content` type and structure. Use `isinstance` checks and `hasattr` or dictionary lookups to safely access nested text content.

Install

• pip install astra-assistants Install latest version

Imports

• AstraAssistants
  wrong:

  from astra_assistants.assistant import Assistant

  correct:

  from astra_assistants import AstraAssistants

  The primary client class changed significantly in v2.x to mirror OpenAI's API structure. `Assistant` was the main class in v1.x.
• ThreadMessage

  from astra_assistants.models import ThreadMessage

Quickstart

This quickstart demonstrates how to set up an `AstraAssistants` client, create an assistant, manage a conversation thread by adding messages, running the assistant, and retrieving its responses. Ensure your AstraDB authentication environment variables are correctly configured before running.

import os
from astra_assistants import AstraAssistants
from astra_assistants.models import ThreadMessage

# --- Authentication Configuration ---
# Ensure these environment variables are set:
# os.environ["ASTRA_DB_APPLICATION_TOKEN"] = "AstraCS:your-token"
# os.environ["ASTRA_DB_API_ENDPOINT"] = "https://<REGION>.aws.a.astra.datastax.com/api/rest"
# Optional: os.environ["OPENAI_API_KEY"] = "sk-..." # Only if using OpenAI models via AstraDB

# Initialize the client. It automatically picks up credentials from environment variables.
client = AstraAssistants()

# 1. Create an assistant
assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="You are a personal math tutor. Answer questions briefly.",
    tools=[{"type": "code_interpreter"}], # Example tool. For web_search, use {"type": "web_search"}
    model="gpt-4o", # Or a model accessible via your AstraDB setup, e.g., 'gpt-3.5-turbo'
)
print(f"Created Assistant: {assistant.id}")

# 2. Create a thread
thread = client.beta.threads.create()
print(f"Created Thread: {thread.id}")

# 3. Add a message to the thread
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="What is the result of 15 * 3 + 2?",
)
print("Added message to thread.")

# 4. Run the assistant on the thread and poll for completion
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as 'Student'.",
)
print(f"Run completed with status: {run.status}")

# 5. Retrieve and print the messages
if run.status == "completed":
    messages_page = client.beta.threads.messages.list(thread_id=thread.id, order="asc")
    for msg in messages_page.data:
        # The content can be a list of different block types. For text, access .text.value
        if msg.content and hasattr(msg.content[0], 'text'):
             print(f"{msg.role}: {msg.content[0].text.value}")
        else:
             print(f"{msg.role}: {msg.content}") # Fallback for other content types
else:
    print(f"Run finished with status {run.status}. Could not retrieve messages.")

# In a real application, you might delete the assistant and thread here.
# client.beta.assistants.delete(assistant.id)
# client.beta.threads.delete(thread.id)