Skip to main content
An agent can’t read a whole manual during a call. Instead, Hamsa cuts each knowledge base item into small pieces called chunks, turns each chunk into a list of numbers that captures its meaning (an embedding), and stores them. When a caller asks something, Hamsa finds the chunks closest in meaning to the question and hands them to the agent. Good chunks are what make the agent answer correctly. A chunk that holds one complete idea (a question and its answer, one policy, one step) is found when it should be, and gives the agent everything it needs. A chunk that cuts an idea in half, or mixes three topics, is found for the wrong questions or misses the right ones. This guide explains every step and setting. You don’t need to be technical to follow it; the API calls are there when you are ready to use them.

The journey of an item

  1. Add a text or a file.
  2. Read: Hamsa takes the text out of the file.
  3. Chunk: the text is cut into chunks, the way you choose.
  4. Review (optional): you read the chunks and fix them.
  5. Index: each chunk is embedded and stored, so it can be found.
  6. Search: on calls, agents that use the item search its chunks.

1. Add an item

POST /v1/voice-agents/knowledge-base takes one or more items: Each item needs an itemName (up to 100 characters). Every item, text or file, counts towards your plan’s knowledge base storage, which is shared by every project the owner of this project owns, each member’s items included.

How files are read

After reading, the text must have at least 50 characters, or the item fails with READING_FAILURE.
Headings help a lot. Most chunking methods keep each chunk inside one section and start it with the full path of headings it sits under, such as ## Orders > Refunds, even when a long section is cut into several chunks. So a chunk about “Refunds” under “Orders” carries both words. A document with clear headings gets clearer chunks.

2. Two ways to process an item

How you send the request decides the path: To choose a chunking method, or to see and edit chunks, send chunkingConfig or autoIndex: false.

Statuses

Read an item’s status with GET /v1/voice-agents/knowledge-base/{id}. Hamsa retries a failed step up to 3 times before marking it failed.

3. Choose a chunking method

Set chunkingConfig.strategy:

When a method can’t be used

The item is chunked with BY_PARAGRAPH instead when:
  • QA_PAIRS finds no questions.
  • BY_PAGE finds only one page (for example, a TEXT item).
  • LLM_GUIDED can’t reach the AI model, or it fails.
  • SEMANTIC can’t measure meaning for a section (only that section is cut by paragraph).

4. Size and structure settings

Chunk sizes are measured in tokens: small pieces of words. The default 400 tokens is about 270 English words or 180 Arabic words. Every language is counted the same way. A value outside its range is refused with 400 (for example ChunkingTargetTokensMustBeValid). Settings that contradict each other are refused with 400 too, never adjusted: minTokens and overlapTokens can be at most half of targetTokens (ChunkingMinTokensExceedsHalfTarget, ChunkingOverlapTokensExceedsHalfTarget), maxTokens must be at least targetTokens (ChunkingMaxTokensBelowTarget), minTokens can’t be above maxTokens (ChunkingMinTokensExceedsMaxTokens), and QA_PAIRS takes no overlapTokens, since each question and answer has to stand alone (ChunkingOverlapTokensNotAllowedForQaPairs). When you leave out targetTokens, these are checked against 400. What you send is what runs.

Where to start

Adding context (addContext)

A chunk like “It costs 50 SAR a month” is hard to find: what costs 50 SAR? With addContext, an AI model reads the document (for one over 60,000 characters, its outline and the part around the chunk) and writes a short line for each chunk, in the chunk’s language, such as “From the pricing section, about the Premium plan.”, and puts it at the start of the chunk. That line is searched along with the chunk. It makes chunking take longer, and it is skipped in previews. A chunk whose line can’t be written is saved without one. When no chunk got a line, contextApplied is false in the item’s chunking settings; you can regenerate to try again.

Marks on chunks

Chunks can come back marked so you know what to check: Exact duplicate chunks are dropped. With overlapTokens above 0, each chunk’s metadata says whether it got an overlap: overlapApplied, with overlapTokenCount when it did, or overlapSkipReason when it didn’t (for example first_chunk, table or after_qa_pair).

5. Preview before you commit

Try settings on an item without saving anything (it previews the first 20,000 characters; an item added with standard processing has no stored text to preview): POST /v1/voice-agents/knowledge-base/{id}/chunks/preview.

6. Review and edit chunks

While an item is PENDING_REVIEW, or any time after: All paths start with /v1/voice-agents/knowledge-base. Edits are refused (422) while the item is PROCESSING. After you edit, the item has changes that aren’t indexed yet: agents keep finding the old chunks until you index again. Changing only spaces doesn’t count as a change.

7. Index

POST /v1/voice-agents/knowledge-base/{id}/index makes the chunks searchable.
  • Only new and changed chunks are embedded again; deleted chunks are removed from search.
  • If nothing changed since the last index, nothing happens.
  • A chunk over 2,048 tokens isn’t indexed: it is marked with an index error, and the rest of the item is indexed. Shorten it and index again.
  • The item is PROCESSED when at least one chunk is stored.

8. Start over or stop

After you regenerate an item that agents already use, they keep finding its old chunks until you index the new ones.

9. How agents search on calls

An agent searches only the items you add to it, and only PROCESSED items can be added. The agent’s Agentic RAG setting decides who starts the search: Either way, every search:
  1. Turns the search into an embedding, the same way chunks were embedded. Arabic and English work the same way.
  2. Keeps the 3 closest chunks that are at least 75% similar, and no more than 5 points below the best one.
  3. Gives the agent those chunks, each cut to its first 600 characters.
With Agentic RAG off, chunks found on recent turns stay available for that turn and the next 2, so a follow-up such as “and for opened items?” still has the facts. If nothing is close enough, the agent gets no knowledge base text and answers from its prompt.
This is how agents run with the smart context manager on, the default for new agents. With it off, Hamsa searches on every caller turn (or when the agent calls the tool), keeps the 5 closest chunks at least 70% similar, gives them whole, and keeps nothing between turns.
This is why chunk quality matters: the agent sees at most 3 chunks, and only their first 600 characters. Keep each answer in one chunk and near its start: an answer split across chunks, or buried deep in a long one, may never reach the agent. A targetTokens of 150 to 250 keeps chunks within what the agent reads.

10. Errors

Examples

  1. Add it with "autoIndex": false and "chunkingConfig": {"strategy": "QA_PAIRS", "targetTokens": 200}.
  2. Wait for PENDING_REVIEW, then list the chunks and check each question has its answer.
  3. Fix or delete chunks, then call /index.
  4. When the item is PROCESSED, add it to your agent.
  1. Add the file with "chunkingConfig": {"strategy": "SEMANTIC", "targetTokens": 250, "overlapTokens": 40, "addContext": true}.
  2. It is chunked and indexed in one go; wait for PROCESSED.
  3. List the chunks marked too short or oversized and fix them, then index again.
  1. Edit the chunks you need to change.
  2. Call /index: only the changed chunks are embedded again.
  3. Agents find the new text from then on.

Knowledge base in Hamsa Agents

Add items and review chunks in the dashboard.

API reference

Every knowledge base endpoint.