Xagent Docs
Get started

Knowledge Bases

A knowledge base lets an agent answer from your own documents rather than from general knowledge. You upload files; Xagent reads them, splits them into passages and indexes them, so that when an agent needs an answer it pulls the most relevant passages back out and works from those. The technical name for this is retrieval-augmented generation, usually shortened to RAG.

How It Works

  1. Ingest — upload files or point at a cloud source. PDFs and other documents are parsed and split into chunks.
  2. Embed — each chunk is embedded and stored in a vector store.
  3. Retrieve — at query time the agent searches for the chunks most relevant to the task.
  4. Ground — retrieved passages are fed to the model, with citations back to the source.

Ingesting Documents

Add content from local uploads or a cloud bucket:

POST /api/kb/ingest          # ingest uploaded documents
POST /api/kb/ingest-cloud    # ingest from a cloud source

Ingestion returns a result per document so you can track which succeeded and which need attention.

Evidence-Based RAG

The built-in evidence-based-rag skill makes agents cite the passages they relied on, so answers stay traceable to the source material. Attach it to an agent alongside one or more knowledge bases.

Grounding agents

Attach a knowledge base to an agent in its configuration (knowledge_bases). The agent will automatically retrieve from it during planning and execution.

Managing Knowledge Bases

Knowledge bases support search, updates, and deletion of documents through the /api/kb endpoints. Content is scoped to your team.

When an agent belongs to a team, the knowledge bases it declares in its own configuration are resolved against that agent's team — not whichever collection the person running it happens to own. If the team doesn't have a matching knowledge base, the agent's search falls back to the collection owned by the agent's creator; if neither resolves, the search reports it found nothing rather than silently reaching for someone else's same-named collection, and task creation for that agent can fail with a 503 (see the Chat / Tasks API) if the resolution itself cannot complete.

Personal and Team Knowledge Bases

A knowledge base starts out personal — only you can see and use it. You can promote it to your team so everyone can build agents on the same material. If you're on a team, you can also choose team ownership right in the creation dialog, before any files are uploaded — the name is claimed for the team immediately, so nobody else can take it while you're still adding content.

ActionWho can do it
Create a new knowledge base as team-ownedAny team member
Promote a personal knowledge base to the teamAny team member
Add to or edit a team knowledge baseAny team member
Demote it back to personal, or delete itTeam admins only
Cancel a team claim before any content was addedThe member who created the claim (or a team admin, via demote)

Promoting moves the content into team-owned storage, so a shared knowledge base keeps working even after the person who created it leaves the team.

Things that block a change

You cannot demote or delete a team knowledge base while a team agent still uses it — remove it from that agent first. A knowledge base that is mid-upload is also briefly busy, and a name already claimed or promoted by a different team cannot be taken again until it is released.

Storage Limits

Team knowledge base storage is capped by your plan and measured as a live total across everything your team has uploaded — not a monthly allowance that resets. When the team reaches its cap, further uploads are refused with a message asking you to upgrade. Freeing space by deleting files restores capacity immediately.

Next Steps