Skip to main content

​
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.

​
Additional Resources