***

title: Using Knowledge Bases
sidebarTitle: Usage
description: 'Create, upload content, and connect knowledge bases to your agents.'
----------------------------------------------------------------------------------

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:

```python
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:

```json
{
  "status": true,
  "data": "696ddd64b9f099f0679fdb41"
}
```

***

## Retrieving KB Details

### Single Knowledge Base

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

```python
details = kb.get(kb_id)
```

Returns the full KB object:

```json
{
  "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:

```python
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:

```python
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.

***

## Verifying the Link

`get_agent_by_id()` returns the agent with its `globalKnowledgeBaseId` field:

```python
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:

```json
{
  "status": true,
  "data": {
    "_id": "696ddd6593f50590da907bcf",
    "name": "Support Agent",
    "globalKnowledgeBaseId": "696ddd64b9f099f0679fdb41",
    "globalPrompt": "You are a helpful support agent..."
  }
}
```

***

## Deleting a Knowledge Base

<Warning>
  A knowledge base cannot be deleted while it's connected to an agent. Delete or archive the agent first.
</Warning>

Use `delete_agent()` to archive the agent, then `delete()` to remove the KB:

```python
# First, remove the agent
client.delete_agent(id=agent_id)

# Then delete the KB
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="What file types can I upload?">
    PDF files are fully supported. Text upload is available but may require backend deployment. Check with your administrator.
  </Accordion>

  <Accordion title="How do I update KB content?">
    Upload new documents to the same KB. The agent will automatically use the updated content in future conversations.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>