Build and populate a knowledge base

Principle — ground, then verify. A knowledge base is a MUST-follow source, not a hint. Scope its coverage in instructions, and always confirm a real question retrieves before you rely on it — an empty search means the agent will answer "not covered". More in Design principles.

A mounted knowledge base is auto-retrieved every turn — the model does not decide whether to look; relevance is by vector distance. That is deliberate: a KB is a MUST-follow source, not an optional tool.

1. Create it

create_knowledge_base(
  name="Company policy",
  description="Mortgage policy and rates, effective 2026",     # for humans
  instructions="Authoritative current mortgage policy; overrides any industry norm. "
               "Covers home mortgages only; for car or personal loans, say so and hand off.",  # for the model
)

2. Add content

add_knowledge_text(kb_name="Company policy", title="2026 late-fee rule",
                   content="From 1 July 2026 the daily late fee is 0.019% …")

Binary files (pdf/docx) and whole folders (zipped) go through add_knowledge_file — subfolders are walked and each md/txt/pdf/html/docx is imported under its in-archive path.

3. ★ Verify retrieval — don't skip ★

search_knowledge_base(kb_name="Company policy", query="how is the late fee calculated")
#   hits  → the agent can answer this
#   empty → the agent will treat it as "not covered" and say so

4. Mount it

update_agent(name="Support", knowledge_bases=["Company policy"])

Don't write "always cite the passage" in instructions — that behaviour is built in. Only write what is specific to this library: authority ordering, coverage boundaries, special usage (e.g. "quoting a rate must state its effective date").

Report back — don't stop at "imported". Tell the user how many chunks landed and give them the clickable link to open the knowledge base and its knowledge starmap (a 3D view of what was ingested): https://console.agent4.io/#/knowledge-bases/Company%20policy — then confirm it's attached to the agent.