Install & Compatibility
Where this runs
tested against v2.5.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
240MB installed
● package 240MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAIWithDefaultKey
✓ from astra_assistants import OpenAIWithDefaultKey
✗ from astra_assistants import AstraAssistants
AsyncOpenAIWithDefaultKey
✓ from astra_assistants import AsyncOpenAIWithDefaultKey
patch
✓ from astra_assistants import patch
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)
Debug
Known issues
breakingThe `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.fixReview the official documentation for v2.x. Update all client instantiations and method calls to match the new `openai`-like API surface.
affects: >=2.0.0 (migrating from <2.0.0)
gotchaAstra 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.fixDouble-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()`.
affects: All
gotchaWhen 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.fixEnsure `OPENAI_API_KEY` is also set in your environment if you plan to use OpenAI's proprietary models through Astra Assistants.
affects: All
gotchaAccessing 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`.fixAlways check `msg.content` type and structure. Use `isinstance` checks and `hasattr` or dictionary lookups to safely access nested text content.
affects: All (similar to OpenAI's recent API changes)
Upgrade
Version history
2.5.5latest on PyPI · released Apr 19, 2025
Audit
Dependencies
No dependency data recorded yet.