Knowledge bases

Knowledge bases hold indexed source material for search. They are separate from an agent’s instructions and from brand context documents. Use them when an assistant needs to retrieve evidence from a collection of documents or webpages.

These tools require a connection exposing the knowledge-base operations in the agents_ family. Check tool availability first.

Build a knowledge base

1. Find or create a collection with agents_listKnowledgeBases or agents_createKnowledgeBase.
2. Add a public source URL with agents_addKnowledgeSource.
3. Inspect sources using agents_listKnowledgeSources and agents_getKnowledgeSource.
4. Wait for ingestion before searching with agents_searchKnowledgeBases.

The source-creation tools support URL ingestion. Use the Simplified interface for file uploads when the tool schema does not provide byte upload support. A source URL must be publicly reachable; local and private-network URLs are not suitable.

Search and maintain sources

Search with a natural-language question. Constrain the knowledge_bases list when the answer should come from specific collections; omitting it searches accessible workspace knowledge. A collection’s total source count is not its ready-to-search count.

Reingest a source or collection when its content changes. Preserve returned source references when summarizing results so readers can trace the answer. Adding a collection does not by itself prove an agent is configured to use it; inspect that agent’s supported configuration separately.

Example: maintain a product documentation collection

1. Search existing collections for the product name before creating another.
2. Add the public documentation URLs you want the collection to cover.
3. Check each source’s ingestion state. A created source record is not proof that its content is searchable.
4. Search with a specific product question and constrain the request to this collection.
5. Review the returned evidence and source references. If the source is not ready or does not cover the question, report that gap.
6. Reingest changed sources and repeat the query after processing completes.

Search the Acme product collection for the supported export formats. Answer only from the retrieved evidence and include the source references.

Control the search scope

agents_searchKnowledgeBases accepts a natural-language query and top_k from 1 to 50, with a default of 8. Start with a specific question and a small useful result set. More results do not guarantee a better answer.

Use knowledge_bases to restrict the search to selected accessible collections. An unrelated workspace’s collection ID is not a way to expand access.

Remove or refresh a source

Read the source before calling agents_deleteKnowledgeSource; delete the collection only when you intend to remove the collection itself. For updated content, use reingestion rather than deleting and recreating everything. Verify readiness again before evaluating the new search results.

API reference

For direct integrations, see knowledge-base collections, source ingestion, and search. These endpoints use the Agents service host shown in the reference.