Using Knowledge Bases | Smallest AI Docs

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:

1 from smallestai.atoms.kb import KB
2 from smallestai.atoms import AtomsClient
3 
4 # Initialize separate managers
5 kb = KB()
6 client = AtomsClient()
7 
8 # Create KB
9 response = kb.create(
10     name="Product Documentation",
11     description="Technical specs and troubleshooting guides"
12 )
13 
14 kb_id = response["data"]

The response contains the KB ID you’ll use for all subsequent operations:

1 {
2   "status": true,
3   "data": "696ddd64b9f099f0679fdb41"
4 }

Retrieving KB Details

Single Knowledge Base

get() retrieves the full details of a specific KB:

1 details = kb.get(kb_id)

Returns the full KB object:

1 {
2   "status": true,
3   "data": {
4     "_id": "696ddd64b9f099f0679fdb41",
5     "name": "Product Documentation",
6     "description": "Technical specs and troubleshooting guides",
7     "organization": "693abd625a5f74726c0450a4",
8     "createdBy": "693abd625a5f74726c0450a1"
9   }
10 }

All Knowledge Bases

list() returns every KB in your organization:

1 all_kbs = kb.list()
2 
3 for item in all_kbs["data"]:
4     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:

1 agent = client.new_agent(
2     name="Support Agent",
3     prompt="You are a helpful support agent. Use your knowledge base to answer product questions accurately.",
4     description="Agent with product KB",
5     kb_id=kb_id
6 )
7 
8 agent_id = agent.data

The agent now has access to all content in that knowledge base during conversations.

Verifying the Link

get_agent_by_id() returns the agent with its globalKnowledgeBaseId field:

1 agent_details = client.get_agent_by_id(id=agent_id)
2 
3 linked_kb = agent_details["data"]["globalKnowledgeBaseId"]
4 print(f"Agent is linked to KB: {linked_kb}")

The response includes the linked KB ID:

1 {
2   "status": true,
3   "data": {
4     "_id": "696ddd6593f50590da907bcf",
5     "name": "Support Agent",
6     "globalKnowledgeBaseId": "696ddd64b9f099f0679fdb41",
7     "globalPrompt": "You are a helpful support agent..."
8   }
9 }

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:

1 # First, remove the agent
2 client.delete_agent(id=agent_id)
3 
4 # Then delete the KB
5 kb.delete(kb_id)

SDK Reference

Method	Description
`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

Can I link multiple KBs to one agent?

Currently, each agent supports one knowledge base via globalKnowledgeBaseId. For multiple knowledge sources, combine them into a single KB before linking.

What file types can I upload?

PDF files are fully supported. Text upload is available but may require backend deployment. Check with your administrator.

How do I update KB content?

Upload new documents to the same KB. The agent will automatically use the updated content in future conversations.

Why can't I delete my KB?

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.