Registry / llm-agents / astra-assistants

astra-assistants

JSON →
library2.5.5pypypi✓ verified 82d ago

The `astra-assistants` library provides a Pythonic, drop-in replacement for OpenAI's Assistants API, powered by AstraDB. It allows developers to build AI assistants with capabilities like persistent memory, tool use (e.g., web search, code interpreter), and RAG, leveraging AstraDB as the vector database backend. The current version is 2.5.5, with regular releases aligning with OpenAI's API updates.

pip install astra-assistants
INSTALL
IMPORT
SIG · ASTRA-ASSISTANTS
A
astra-assistants
llm-agentspythonv2.5.5
Install
25.5s avg
Import
Disk
240MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
py 3.10
✓ —
✓ 39.4s
py 3.11
✓ —
✓ 26.2s
py 3.12
✓ —
✓ 18.2s
py 3.13
✓ —
✓ 18.3s
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.
fix
Review 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.
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()`.
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.
fix
Ensure `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`.
fix
Always 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.

Agent activity
83 hits · last 30 days
node
72
Perplexity
1
OpenAI (training)
1
Resources
astra-assistants — pip install astra-assistants · libregistry