{"id":6520,"library":"astra-assistants","title":"Astra Assistants","description":"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.","status":"active","version":"2.5.5","language":"en","source_language":"en","source_url":"https://github.com/datastax/astra-assistants","tags":["AI","Assistants","RAG","Vector Database","AstraDB","OpenAI API compatible","LLM"],"install":[{"cmd":"pip install astra-assistants","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary client class changed significantly in v2.x to mirror OpenAI's API structure. `Assistant` was the main class in v1.x.","wrong":"from astra_assistants.assistant import Assistant","symbol":"AstraAssistants","correct":"from astra_assistants import AstraAssistants"},{"symbol":"ThreadMessage","correct":"from astra_assistants.models import ThreadMessage"}],"quickstart":{"code":"import os\nfrom astra_assistants import AstraAssistants\nfrom astra_assistants.models import ThreadMessage\n\n# --- Authentication Configuration ---\n# Ensure these environment variables are set:\n# os.environ[\"ASTRA_DB_APPLICATION_TOKEN\"] = \"AstraCS:your-token\"\n# os.environ[\"ASTRA_DB_API_ENDPOINT\"] = \"https://<REGION>.aws.a.astra.datastax.com/api/rest\"\n# Optional: os.environ[\"OPENAI_API_KEY\"] = \"sk-...\" # Only if using OpenAI models via AstraDB\n\n# Initialize the client. It automatically picks up credentials from environment variables.\nclient = AstraAssistants()\n\n# 1. Create an assistant\nassistant = client.beta.assistants.create(\n    name=\"Math Tutor\",\n    instructions=\"You are a personal math tutor. Answer questions briefly.\",\n    tools=[{\"type\": \"code_interpreter\"}], # Example tool. For web_search, use {\"type\": \"web_search\"}\n    model=\"gpt-4o\", # Or a model accessible via your AstraDB setup, e.g., 'gpt-3.5-turbo'\n)\nprint(f\"Created Assistant: {assistant.id}\")\n\n# 2. Create a thread\nthread = client.beta.threads.create()\nprint(f\"Created Thread: {thread.id}\")\n\n# 3. Add a message to the thread\nclient.beta.threads.messages.create(\n    thread_id=thread.id,\n    role=\"user\",\n    content=\"What is the result of 15 * 3 + 2?\",\n)\nprint(\"Added message to thread.\")\n\n# 4. Run the assistant on the thread and poll for completion\nrun = client.beta.threads.runs.create_and_poll(\n    thread_id=thread.id,\n    assistant_id=assistant.id,\n    instructions=\"Please address the user as 'Student'.\",\n)\nprint(f\"Run completed with status: {run.status}\")\n\n# 5. Retrieve and print the messages\nif run.status == \"completed\":\n    messages_page = client.beta.threads.messages.list(thread_id=thread.id, order=\"asc\")\n    for msg in messages_page.data:\n        # The content can be a list of different block types. For text, access .text.value\n        if msg.content and hasattr(msg.content[0], 'text'):\n             print(f\"{msg.role}: {msg.content[0].text.value}\")\n        else:\n             print(f\"{msg.role}: {msg.content}\") # Fallback for other content types\nelse:\n    print(f\"Run finished with status {run.status}. Could not retrieve messages.\")\n\n# In a real application, you might delete the assistant and thread here.\n# client.beta.assistants.delete(assistant.id)\n# client.beta.threads.delete(thread.id)","lang":"python","description":"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."},"warnings":[{"fix":"Review the official documentation for v2.x. Update all client instantiations and method calls to match the new `openai`-like API surface.","message":"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.","severity":"breaking","affected_versions":">=2.0.0 (migrating from <2.0.0)"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `OPENAI_API_KEY` is also set in your environment if you plan to use OpenAI's proprietary models through Astra Assistants.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Always check `msg.content` type and structure. Use `isinstance` checks and `hasattr` or dictionary lookups to safely access nested text content.","message":"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`.","severity":"gotcha","affected_versions":"All (similar to OpenAI's recent API changes)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install astra-assistants'.","cause":"The 'astra-assistants' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'astra-assistants'"},{"fix":"Ensure you are importing the correct module from 'astra-assistants' as per the official documentation.","cause":"The 'Chroma' module is not part of the 'astra-assistants' package.","error":"ImportError: cannot import name 'Chroma' from 'astra-assistants'"},{"fix":"Verify the correct usage of the 'astra_assistants' module and refer to the official documentation for guidance.","cause":"The 'patch' function is not available in the 'astra_assistants' module.","error":"AttributeError: module 'astra_assistants' has no attribute 'patch'"},{"fix":"Check the initialization of your objects and ensure all dependencies are correctly installed and configured.","cause":"Attempting to call a function or method that is None, possibly due to incorrect initialization or missing dependencies.","error":"TypeError: 'NoneType' object is not callable"},{"fix":"Refer to the official documentation for the list of supported models and use a valid model name.","cause":"The specified model name is not recognized or supported by the 'astra-assistants' package.","error":"ValueError: Invalid model specified: 'gpt-4-1106-preview'"}]}