Skip to main content
This guide walks through the complete knowledge base workflow—from creation to agent integration.

​
Creating a Knowledge Base

Every KB starts with a name and optional description. Use the create method: 
from smallestai.atoms.kb import KB
from smallestai.atoms import AtomsClient

# Initialize separate managers
kb = KB()
client = AtomsClient()

# Create KB
response = kb.create(
    name="Product Documentation",
    description="Technical specs and troubleshooting guides"
)

kb_id = response["data"]
The response contains the KB ID you’ll use for all subsequent operations: 
{
  "status": true,
  "data": "696ddd64b9f099f0679fdb41"
}

​
Retrieving KB Details

​
Single Knowledge Base

get() retrieves the full details of a specific KB: 
details = kb.get(kb_id)
Returns the full KB object: 
{
  "status": true,
  "data": {
    "_id": "696ddd64b9f099f0679fdb41",
    "name": "Product Documentation",
    "description": "Technical specs and troubleshooting guides",
    "organization": "693abd625a5f74726c0450a4",
    "createdBy": "693abd625a5f74726c0450a1"
  }
}

​
All Knowledge Bases

list() returns every KB in your organization: 
all_kbs = kb.list()

for item in all_kbs["data"]:
    print(f"{item['name']}: {item['_id']}")

​
Linking a KB to an Agent

The connection happens at agent creation time. Pass kb_id to the new_agent helper: 
agent = client.new_agent(
    name="Support Agent",
    prompt="You are a helpful support agent. Use your knowledge base to answer product questions accurately.",
    description="Agent with product KB",
    kb_id=kb_id
)

agent_id = agent.data
The agent now has access to all content in that knowledge base during conversations.
get_agent_by_id() returns the agent with its globalKnowledgeBaseId field: 
agent_details = client.get_agent_by_id(id=agent_id)

linked_kb = agent_details["data"]["globalKnowledgeBaseId"]
print(f"Agent is linked to KB: {linked_kb}")
The response includes the linked KB ID: 
{
  "status": true,
  "data": {
    "_id": "696ddd6593f50590da907bcf",
    "name": "Support Agent",
    "globalKnowledgeBaseId": "696ddd64b9f099f0679fdb41",
    "globalPrompt": "You are a helpful support agent..."
  }
}

​
Deleting a Knowledge Base

A knowledge base cannot be deleted while it’s connected to an agent. Delete or archive the agent first.
Use delete_agent() to archive the agent, then delete() to remove the KB: 
# First, remove the agent
client.delete_agent(id=agent_id)

# Then delete the KB
kb.delete(kb_id)

​
SDK Reference

MethodDescription
kb.create(name, description)Create a new knowledge base
kb.list()List all KBs in your organization
kb.get(id)Retrieve a specific KB
kb.delete(id)Delete a KB (must be unlinked first)

​
Tips

PDF files are fully supported. Text upload is available but may require backend deployment. Check with your administrator.
Upload new documents to the same KB. The agent will automatically use the updated content in future conversations.
The error “This knowledge base is connected to an agent” means you must delete or archive the linked agent first. KBs with active connections cannot be removed.