Skip to main content
Contextual AI provides a platform for creating enterprise-grade AI agents grounded in your documents and data. Our integrated system allows you to easily:
  • Parse and ingest documents into fully-managed vector stores
  • Create specialized agents that can answer questions and complete tasks by fetching relevant knowledge from your datastores
With Contextual AI, you get:
  • Best-in-class parsing capabilities and powerful chunking options that make wrangling unstructured data for RAG a breeze
  • Seamless orchestration of powerful RAG components and primitives, allowing you to build RAG agents that have exceptional accuracy and scalability
  • State-of-the-art capabilities and models, like our:
You can access Contextual AI through our intuitive UIs or programmatically via our APIs and SDKs. This guide walks you through creating your first agent using our Python SDK.

​
Get your API Key

Contextual AI uses API keys to authenticate requests. Only Contextual AI workspace admins can create API keys.
Sign up here if you don’t have a Contextual AI account yet. You’ll get $25 in free credits to trial the platform, or $50 in free credits if you sign up with a work email address.
Log in via the UI and follow these steps to create an API key:
  1. Expand the sidebar and click on API Keys
  2. Click the Create API Key button in the upper right and follow the instructions
  3. Save the generated key in a secure location

​
Create and query your first agent

​
Step 0: Install Python SDK

Run the following command in your terminal or shell: 
pip install contextual-client

​
Step 1: Create a datastore

Datastores contain the files that your agent(s) can access. Each agent must be associated with at least one datastore. Run the following code to create a datastore using the /datastores endpoint: 
from contextual import ContextualAI

# Initialize the client with your API key
contextual = ContextualAI(api_key="API_KEY")

# Create a datastore
datastore = contextual.datastores.create(name="Test Datastore")
Remember to replace $API_KEY with your key. You can rename the datastore if you want.
If the request is successful, Contextual AI will return the id of the newly created datastore. Be sure to save this id as you will need it later.

​
Step 2: Add documents into your datastore

Now that you’ve created a datastore, you can add documents to it. Contextual AI securely stores your documents and parses them in formats optimized for RAG pipelines and agents.
For best results:
  • Use renderable PDFs and documents with text that can be copied and pasted.
  • Don’t have your own documents ready? Use these sample documents.
Use the following code to upload a single document: 
from contextual import ContextualAI

# Initialize the client with your API key
contextual = ContextualAI(api_key="API_KEY")

# Upload a document
with open('file.pdf', 'rb') as f:
    ingestion_result = contextual.datastores.documents.ingest(datastore_id, file=f)
    document_id = ingestion_result.id
    print(f"Successfully uploaded document_id: {document_id} to datastore_id: {datastore_id}")
Remember to:
  • Replace {datastore_id} in the url path with the datastore id from the previous step
  • Replace $API_KEY with your API key
  • Replace {file_path} with the path to the document on your machine
If the request is successful, the id of the uploaded document will be returned to you. The time required to upload documents depends partly on their length and features. Some documents may require a few minutes to fully process after upload.

​
Step 3: View your document upload status

Use this code to check the status of documents uploaded into the datastore: 
from contextual import ContextualAI

# Initialize the client with your API key
contextual = ContextualAI(api_key="API_KEY")

# Get the status of documents in the datastore
metadata = contextual.datastores.documents.metadata(datastore_id=datastore_id, document_id=document_id)
print("Document metadata:", metadata)
Remember to:
  • Replace {datastore_id} in the url path with the id from the previous step
  • Replace $API_KEY with your API key
You should see the uploaded document in the list, along with its ingestion_job_status.

​
Step 4: Create an agent

Now that you have a datastore with some files, you can use the /agents endpoint to create your first agent. Run the following code: 
from contextual import ContextualAI

# Initialize the client with your API key
contextual = ContextualAI(api_key="API_KEY")

# Create an agent
agent = contextual.agents.create(name="Test Agent", description="Test Agent", datastore_ids=[datastore_id])
Remember to:
  • Replace $API_KEY with your API key
  • Populate the datastore_ids list field with the datastore id from above
If the request is successful, the agent_id of the newly created agent will be returned to you. You’ll need this to query your agent in the next step.

​
Step 5: Query your agent

With your agent configured and documents uploaded, use the /query endpoint to send messages: 
from contextual import ContextualAI

# Initialize the client with your API key
contextual = ContextualAI(api_key="API_KEY")

# Query the agent
response = contextual.agents.query.create(
  agent_id=agent_id,
  messages=[
    {
      "role": "user",
      "content": "What is the revenue of Apple?"
    }]
)
Remember to:
  • Replace {agent_id} in the url path with the agent_id from the previous step
  • Replace $API_KEY with your API key
  • Replace the content field with a question that is relevant to the document(s) you uploaded
If the request is successful, you’ll receive a response back that will contain:
  • The body of the response
  • The sources retrieved from the datastore that are relevant to the response
  • Attributions/citations of sources to specific text spans in the response
Note: You can query your agent only after at least one document in the datastore has been fully processed. See Step 3 for instructions on verifying your document’s upload status.
🙌 Congratulations! You’ve successfully created a Contextual AI agent.

​
Try out additional functionality

Now that you have a basic working agent, explore our advanced features:

Learn about advanced query features like multi-turn and structured outputs

Access easy-to-follow Jupyter notebooks for using Contextual AI APIs

⌘I