Using knowledge

Attaching a knowledge base is one field. Getting an agent to use it well on a live call is a prompting problem, and that is most of this page.

Attaching one

config.kb_ids is a list of knowledge base ids. Only a ready one can be attached — anything still building, or in error, is refused at save.

AGENT_ID=0f9a1c3e-5d42-4b8a-9c11-6e2f7a4d8b30

# Read the config, add kb_ids, send the whole thing back
curl -sS "https://api.in.talqing.com/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
| jq '{config: (.config | .kb_ids = ["3d1f5a70-8c2b-4e19-9a63-b7f0c4d21e58"])}' \
| curl -sS -X PATCH "https://api.in.talqing.com/v1/agents/$AGENT_ID" \
    -H "Authorization: Bearer $TALQING_API_KEY" \
    -H "Content-Type: application/json" \
    --data @-

curl -sS -X POST "https://api.in.talqing.com/v1/agents/$AGENT_ID/publish" \
  -H "Authorization: Bearer $TALQING_API_KEY"

const agent_id = "0f9a1c3e-5d42-4b8a-9c11-6e2f7a4d8b30";

const agent = await talqing.agents.get({ agent_id });
const config = {
  ...agent.config,
  kb_ids: ["3d1f5a70-8c2b-4e19-9a63-b7f0c4d21e58"],
};

await talqing.agents.update({ agent_id, updateAgentRequest: { config } });
await talqing.agents.publish({ agent_id });

agent_id = "0f9a1c3e-5d42-4b8a-9c11-6e2f7a4d8b30"

agent = talqing.agents.get(agent_id)
config = {**agent["config"], "kb_ids": ["3d1f5a70-8c2b-4e19-9a63-b7f0c4d21e58"]}

talqing.agents.update(agent_id, config=config)
talqing.agents.publish(agent_id)

Writes replace the whole config, so read it, add the field and send it back — see agent overview. Attaching one that is not ready fails validation with the status named:

knowledge base 'Northwind help centre' is transcribing - only ready KBs can be attached

An id that does not exist reads knowledge base 3d1f5a70-… not found. Both are errors, so they block a publish. See validation. Knowledge works the same on voice, video and text. Agent tasks do not take knowledge bases — a task is one bounded run and reaches what it needs through its tools. kb_ids is frozen into a published version like the rest of the config, but a knowledge base is not versioned. The agent reads whatever the base contains at call time, so rebuilding it changes what live callers hear without a publish. Attaching a different base still takes a publish.

What the agent gets

Two things, both added at compile time: The knowledge map, appended to the system prompt. Every entry as one line — a short id, a title, a summary — indented to show the tree, preceded by the knowledge base’s name and its overview paragraph. No content. It is the same string on every turn of every call, so it lands in the model’s prompt cache after the first turn. Read the exact block with GET /v1/knowledge/{kb_id}/prompt — see editing. The map is appended after your prompt and after {{userdata.*}} substitution, so a stray {{...}} in crawled content is never mistaken for a template. A knowledge_fetch tool. The model calls it with the short ids from the map and gets the verbatim page text back.

{
  "name": "knowledge_fetch",
  "description": "Retrieve the verbatim content of one or more knowledge-base nodes by their short ids (e.g. k1, k3) as shown in the KNOWLEDGE MAP. Call this before answering questions about the knowledge base.",
  "parameters": {
    "type": "object",
    "properties": {
      "ids": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Short node ids from the KNOWLEDGE MAP, e.g. [\"k1\", \"k4\"]."
      }
    },
    "required": ["ids"]
  }
}

knowledge_fetch is a reserved tool name. So are stop_recording and submit_result. A tool of yours cannot use it, in this workspace or any agent in it. See tool schema and description.

The tool is scoped to the ids in this agent’s map. An agent cannot read a node from a knowledge base it does not have attached. If every attached knowledge base is empty of entries, neither the map nor the tool is added at all — the agent runs as though nothing were attached.

How a fetch behaves

Situation	What the model gets back
One or more page entries	`## {title}` followed by the verbatim Markdown, one block per entry
More than 24,000 characters across the call	The over-long block is cut with `[TRUNCATED — this entry continues beyond the fetch limit. Fetch it alone, or fetch a more specific entry.]` and the fetch stops there
A category entry	A listing of its children, each with its short id, title and summary, prefixed by “This is a section heading with no page of its own. Fetch one of its entries instead”
Ids that do not exist in this agent’s map	Ignored. If none of the ids match, “No matching knowledge entries were found for those ids.”
Entries that exist but hold nothing	”Those entries have no content.”
The lookup fails	”Sorry, I couldn’t access the knowledge base just now.”

The 24,000-character cap is on the whole call, not per entry, so asking for six large entries at once gets less of each than asking for one. Truncation is always marked, never silent: the model is told it is reasoning from a partial document so it can fetch again more narrowly. The category behaviour is what makes the tree useful. A model that fetches a section heading is handed the section’s contents and can go a level deeper, which is cheaper than putting every leaf’s summary in front of it at once.

The directive the platform adds

Above the map, the platform appends a fixed instruction. You do not write it and cannot change it:

When a question relates to the knowledge base, FIRST consult the KNOWLEDGE MAP below,
pick the most relevant node id(s), and call `knowledge_fetch` with them to read the
verbatim content before answering. Ground your answer ONLY in the fetched content. If
nothing in the map is relevant, say you don't have that information — never invent facts.

That covers the mechanics — consult the map, fetch, ground the answer, refuse rather than invent. What it cannot know is your business: which questions relate to the knowledge base, what to do when the answer is not in it, and how to behave on a call while a fetch is in flight. That is your prompt’s job.

Prompting for knowledge

This is what decides whether the feature works on a real call. Say what the knowledge base covers, in the agent’s own words. The model reads the map, but a sentence in the prompt is what makes it reach for the map in the first place. “You have a knowledge base covering returns, delivery, warranty and trade accounts” turns a vague question into a lookup. Say when to consult it, and be concrete about when not to. The failure mode is not an agent that never looks things up; it is an agent that looks things up for everything, including “hello”, and pauses for two seconds each time. Have the agent say something before it fetches. On a voice call a tool call is silence, and silence on a phone line reads as a dropped connection. One short line — “Let me check that for you” — covers it. Text agents do not need this. Say what to do when the answer is not there. The platform directive tells the model to say it does not have the information. Your prompt should say what happens next: transfer to a person, take a message, offer to email. An agent that stops at “I don’t have that” is a worse call than one that says “I don’t have that — let me put you through to someone who does.” Do not paste the same facts into the prompt as well. Two copies of a policy disagree the day one of them is updated, and the model has no way to know which is current. Do not use it for anything that must be exact. A price, stock, an order status, a booking slot — that is a tool calling your API. A knowledge base is a snapshot of a website.

Worked example

An inbound support agent with a knowledge base for policy and a tool for the caller’s own data. The prompt:

You are the support line for Northwind Tools, a shop selling power tools online.
You answer calls from customers about orders, deliveries, returns and warranties.

KNOWLEDGE
You have a knowledge base covering returns and refunds, delivery, warranty cover
and trade accounts. Consult it before answering anything about policy, timescales,
eligibility, or what is and is not covered. Do not answer those from memory.

Before you look something up, say one short line so the caller knows why you have
gone quiet — "let me check that for you" is enough. Then look it up and answer.

If the knowledge base does not cover what they asked, say so plainly and offer to
put them through to a person. Never guess at a policy.

Order-specific questions — where is my parcel, what did I order, has my refund
been processed — are not in the knowledge base. Use the check_order tool for those.

STYLE
Short sentences. One question at a time. Confirm the order number back to the
caller before you use it.

And the config it goes on, as a body you can POST to /v1/agents:

{
  "config": {
    "name": "Northwind support",
    "channel": "voice",
    "prompt": "You are the support line for Northwind Tools... (the text above)",
    "greeting": "Northwind support, how can I help?",
    "kb_ids": ["3d1f5a70-8c2b-4e19-9a63-b7f0c4d21e58"],
    "tools": [{ "tool_id": "8e2d4f19-7a05-4c6b-8f31-c9a2b40d5e76" }]
  }
}

The split is the point. Policy comes from the knowledge base; the caller’s own data comes from a tool. The prompt says which is which, so the model does not go looking for an order number in a help centre article, and does not answer a returns question from memory because it thinks a tool will cover it. Four sentences in that prompt are doing the work: what the knowledge covers, when to consult it, what to say before the pause, and what to do when the answer is not there. Drop any one and the agent gets noticeably worse on a live call.

What multiple knowledge bases cost

You can attach several. They are rendered one after another, each with its own heading and overview, and the short ids run continuously across all of them — k1 through k7 in the first, k8 onwards in the second. The model does not need to know which base an id came from. The cost is context. Every entry of every attached base is in the system prompt on every turn of every call, on your own provider key. chars on GET /v1/knowledge/{kb_id}/prompt is the exact size of one; add them up before attaching a fourth. The second cost is attention. Retrieval here is a model choosing from a list, and a longer list of similar-sounding entries is a harder choice. Two knowledge bases covering distinct subjects are fine. Three that overlap will produce worse fetches than one well-organized base would. If you find yourself attaching several because each one is too broad, the fix is usually to split the agent rather than the knowledge — a triage agent that hands off to specialists, each with the one base it needs. See agent teams.

Prompting

The rest of writing a system prompt, including what does not belong in one.

Fixing a knowledge base

When the agent will not fetch what you expected, this is where you find out why.

Get started

Agents

Tools

Knowledge

Agent teams

Agent tasks

Telephony

Web & chat

Integrations

Email outbound

Observability

Guides

Platform

Using knowledge

Attaching one

What the agent gets

How a fetch behaves

The directive the platform adds

Prompting for knowledge

Worked example

What multiple knowledge bases cost

Next

Prompting

Fixing a knowledge base

​Attaching one

​What the agent gets

​How a fetch behaves

​The directive the platform adds

​Prompting for knowledge

​Worked example

​What multiple knowledge bases cost

​Next

Prompting

Fixing a knowledge base

Attaching one

What the agent gets

How a fetch behaves

The directive the platform adds

Prompting for knowledge

Worked example

What multiple knowledge bases cost

Next