Knowledge Base

The Knowledge Base feature lets you upload documents that agents can search and reference when answering your questions. This turns agents into context-aware assistants that draw on your own data.

How It Works

1. Upload documents to a workspace (organization, space, or project).
2. Documents are indexed by the KB Indexer service, which creates vector embeddings for semantic search.
3. When you chat with an agent that has knowledge base access, it uses a search_knowledge_base tool to find relevant passages from your documents.
4. The agent includes relevant information in its response and cites sources with the filename.

Knowledge Base Sources

Agents can draw from two types of knowledge base sources:

Agent-Uploaded Files

Files uploaded directly to an agent's knowledge base. These are scoped to a specific agent and are searched whenever that agent handles a task. When configuring an agent in the Agent Builder, you can attach files under the "Knowledge Base" section.

Workspace Connections

Agents can be connected to workspaces (spaces or projects) to access documents uploaded at the workspace level. A workspace connection specifies:

• Type -- either space or project.
• Space ID -- the space to connect to.
• Project ID -- (optional) a specific project within the space.
• Name -- a display name for the connection.

When an agent has workspace connections, it can search documents from those workspaces in addition to its own uploaded files.

Scoping

Knowledge bases follow the workspace hierarchy, which creates a layered retrieval system:

When an agent searches the knowledge base within a project context, it can access documents from all three levels: the project, its parent space, and the parent organization.

Uploading Documents

To upload documents:

1. Navigate to the workspace level (organization, space, or project) where you want the documents to be available.
2. Select the knowledge base or document upload option.
3. Upload your files.

Documents are processed asynchronously. After upload, the KB Indexer service splits documents into chunks and generates embeddings for semantic search. This process typically completes within a few seconds for small documents.

Retrieval in Agent Responses

When an agent has knowledge base access configured, it automatically searches relevant documents before generating a response. The search process:

1. The agent formulates a natural-language search query based on your message.
2. The knowledge base returns the most semantically similar document chunks (default: top 5 results, maximum: 20).
3. The agent incorporates relevant information into its response.
4. Sources are cited in the format [Source: filename] so you know where the information came from.

Configuring Knowledge Base Access

Knowledge base access is configured when building or editing an agent:

• KB Sources -- specify which agent's uploaded files to search.
• Workspace Connections -- connect the agent to spaces or projects for broader document access.

Both options can be combined so that an agent searches its own files and connected workspace documents simultaneously.

Best Practices

• Scope documents appropriately -- put broadly useful documents at the organization or space level, and project-specific documents at the project level.
• Use clear filenames -- agents cite documents by filename, so descriptive names help users verify sources.
• Keep documents focused -- shorter, topic-specific documents tend to produce better retrieval results than large monolithic files.
• Test retrieval -- after uploading documents, ask the agent questions that should be answerable from your documents to verify that retrieval is working correctly.