Sources

Sources are the backbone of answer quality. If the agent cannot retrieve the right material, no prompt tweak will save it.

What You Can Add

The Sources page supports:

• website URLs
• sitemaps
• file uploads
• image uploads
• ZIP archives for bulk upload

Which Source Type Should You Choose?

What The Page Is For

Use the main Sources page to:

• add new sources
• search across sources
• watch live ingestion progress
• bulk-select and delete sources
• expand ZIP uploads to inspect child files

Source Lifecycle

Every source moves through one of these states:

Source Detail Page

Open any source to see more than the list view shows.

The detail page includes:

• a status summary with counts and timestamps
• a configuration panel showing the original source setup
• automatic document metadata and editable custom fields
• a Documents tab with chunk counts and metadata
• a Jobs tab with a job timeline, progress, and errors
• a Raw Config tab for exact source configuration
• a Re-ingest action when you need to refresh content

Knowledge Metadata

Standard metadata is collected automatically during ingestion, not entered manually. It includes available source dates, file details, passage position, indexing time, and a content-version identifier. The source's ingestion status is also managed automatically; it is not an editorial status such as "current" or "superseded."

Only custom fields are editable. Open a source's detail page to add your own keys with string, number, boolean, or null values, such as product, region, or owner. Custom fields apply to every document in that source; use separate sources when documents need different custom context.

Saving or clearing custom fields does not require re-ingestion: the next knowledge-base search sees the updated values, including when earlier results were cached. Do not put secrets in these fields; they are sent to the model and its provider alongside retrieved passages.

What The Agent Receives

The search_knowledge_base tool returns each passage with its source name, source type, document identity, title, URL, and relevance score. Available context is returned in metadata:

documentStructure.elementTypes preserves the parser's type-to-count map, for example { "Title": 2, "NarrativeText": 10 }. Counts are nonnegative safe integers, including zero. Invalid count entries are omitted without discarding valid entries; legacy arrays of type names remain supported without invented counts. These values describe the whole document, not the matching passage.

Source-declared webpage dates and available parser-reported file dates are captured during ingestion. Existing documents need a re-ingest or scheduled recrawl to capture newly supported fields. Missing or invalid values stay unknown; Kravos does not infer an author's version, effective date, or editorial status from filenames, upload time, or indexing time. contentVersion changes when the ingested text changes. It is not an incrementing revision number and cannot establish which of two articles is newer or authoritative.

A parser-reported file modification date can describe processing of the uploaded file rather than the original article's revision. It is labelled fileModifiedAt with its origin, not treated as a content update date. Extracted dates and owner-defined custom fields stay separate; custom fields do not overwrite automatic metadata.

Define Your Agent's Policy

Metadata gives the model more evidence; it does not change retrieval ranking or automatically resolve conflicting articles. Use your agent's instructions to define preferred sources and what to do when evidence disagrees. For example:

When retrieved articles disagree, show which articles disagree. Use an explicit
version or effective date only when it establishes which policy applies to the
question. If neither source is clearly authoritative, ask for clarification rather
than guess. Cite the source you use.

Only retrieved passages can be compared. An article outside the search results is not checked for contradictions.

Good Starting Workflow

1. add the smallest high-value source set you can
2. wait until the source is Ready
3. test real user questions in Playground
4. open the source detail page if retrieval is weak or the job fails
5. expand carefully instead of adding every possible page at once

Bulk Uploads

ZIP uploads behave differently from single files:

• the parent source shows overall processing progress
• child files can be expanded under the source row
• processed and failed child counts help you spot bad files quickly

Best Practices

• start with your highest-value pages, not your entire internet footprint
• prefer clean, current help-center content over marketing pages with weak detail
• re-ingest after major content changes
• use source detail pages to inspect failed jobs before retrying blindly
• remove stale or duplicate content if retrieval keeps surfacing the wrong answer

Common Problems

The agent gives outdated answers

• check whether the source is stale
• re-ingest the source
• remove conflicting older files or pages

A source is stuck in error

• open the source detail page
• review the latest job error
• check whether the URL, sitemap, file, or ZIP contents are still valid
• confirm the source config still points to the right location
• fix the original source content or configuration
• try re-ingesting after the root cause is fixed

Retrieval quality is still weak

• add more focused content instead of more generic content
• review Interceptors for hard rules
• test in Playground with debug panels open

Related Docs