Knowledge Search

With the Knowledge Search functionality in HALO, you can search through your Knowledge and generate an answer. Watch this E-learning to find out how to use Knowledge Search.

The Knowledge Search option will, using a query as input, search through your Knowledge to find the most relevant Sources and try to generate an answer. There are three possible outcomes:

Answer

If HALO can answer the user query using Knowledge, an answer will be generated. The tool result includes the answer text, the reasoning behind it, and the sources that were used.

Example tool result:

{
  "type": "answer",
  "response": "You can return your product within 14 days of receiving it. Register your return via the return portal and send it back using the provided shipping label.",
  "reasoning": "The user asks about the return policy. Source 3 and 7 describe the return process and timeframes.",
  "sources": [
    {"type": "web-page", "url": "https://example.com/returns", "content": "..."},
    {"type": "file", "file_name": "return-policy.pdf", "content": "..."}
  ],
  "instruction": "Use the response field to answer the user. Do not add information, suggestions, or actions that are not in the response."
}

Field	Description
`type`	`"answer"`
`response`	The generated answer based on your Knowledge. This text is ready to be sent to the end user as is.
`reasoning`	A short explanation of how the answer was derived. For internal use only, should not be shown to the end user.
`sources`	The Knowledge Sources that were used to compose the answer. See Source types below.
`instruction`	Tells the calling agent how to handle the response.

Clarifying Question

If the user query is too vague or unclear to generate a good answer, HALO will respond with a clarifying question. This helps guide the user to provide more context so a proper answer can be given in a follow up.

Example tool result:

JSON

{
  "type": "clarifying_question",
  "response": "Could you let me know what specifically you'd like to know about your order? For example, are you looking for delivery status, return options, or payment information?",
  "reasoning": "The user query is too vague to determine intent. A clarifying question is needed.",
  "sources": [],
  "instruction": "Ask the user this clarifying question. Do not add information that is not in the response."
}

Field	Description
`type`	`"clarifying_question"`
`response`	A clarifying question to send back to the user. This text is ready to be sent to the end user as is.
`reasoning`	A short explanation of why a clarifying question was asked. For internal use only.
`sources`	Can be empty, since no Sources were used.
`instruction`	Tells the calling agent how to handle the response.

No Answer

If the available Knowledge does not contain enough information to answer the user query, HALO returns a no_answer type. This means you should handle the conversation yourself, for example by forwarding to a live agent or showing a fallback message.

Example tool result:

JSON

{
  "type": "no_answer",
  "response": "I'm sorry, I can't help with that. Is there something else I can help you with?",
  "reasoning": "The user asks about opening hours. None of the available Sources contain this information.",
  "instruction": "Use the response field to answer the user. Do not add information, suggestions, or actions that are not in the response."
}

Field	Description
`type`	`"no_answer"`
`response`	A default fallback message. This can be overridden in your bot flow.
`reasoning`	A short explanation of why no answer could be given. For internal use only.
`instruction`	Tells the calling agent how to handle the response.

Date and time awareness

HALO knows the current day of the week, date, and time. This allows it to answer time-sensitive questions, for example "Are you open today?", "Is the summer promotion still valid?", or "When will my order arrive if I order now?".

The current_datetime system context can be configured to change the timezone, so that HALO reasons with the correct local time for your customers.

Source types

When the Knowledge Search uses Sources to generate an answer, those Sources are included in the tool result. Depending on the type of Knowledge Source, they are formatted differently:

Source type	`type` in response	Fields	Description
Web crawler	`"web-page"`	`url`, `content`	A page that was crawled from a website. The `url` field contains the original page URL.
API connection	`"external-knowledge"`	`url`, `content`	Data retrieved from an external API connection. The `url` field contains the url to the original knowledge source page (depending on the integration).
File	`"file"`	`file_name`, `content`	An uploaded file (e.g. PDF, document). The `file_name` field contains the original file name.
Other	`"other"`	`content`	Any other source type.

Using the output

The response field in the tool result contains text that is ready to be sent directly to the end user. The calling agent should use the response field verbatim as its reply. The instruction field reinforces this: do not add information, suggestions, or actions that are not in the response.

When the type is "answer" or "clarifying_question", the calling agent replies to the user with the exact text from the response field. When the type is "no_answer", a default fallback message is provided, but this can also be handled in your bot flow (e.g. forwarding to a live agent or showing a custom message). Below you will find to examples of how you can use Knowledge Search within your agent.

Example: relay the output directly

In the simplest setup, the calling agent relays the Knowledge Search output exactly as it is. This is useful when you want the generated answer to reach the end user without any modifications.

You are a customer service assistant that can answer user queries using a tool.

Always immediately use [knowledge_search] to answer the user's question.
Never reply to the user without having called [knowledge_search].

This tool can return 3 types of responses:

- If the tool returns an answer, relay it exactly. Do not add, change, or omit information.
- If the tool returns a clarifying question, relay it exactly. Do not add, change, or omit information.
- If the tool returns no answer, immediately call the breakout tool.

Example: customize the output

What makes the Knowledge Search really powerful is that you can fully control what happens with the output. You can alter the answer, enrich it with source URLs, trigger follow up actions, or handle each response type differently. The calling agent prompt is where you define this behavior.

For example, you can configure your Agent to add the URL of the source it used to the answer, and to show the feedback options after giving an answer. You can also configure different behavior when the Knowledge Search cannot find an answer, for example to handover:

You are a customer service assistant that can answer user queries using a tool.

Always immediately use [knowledge_search] to answer the user's question.
Never reply to the user without having called [knowledge_search].

This tool can return 3 types of responses:

- If the tool returns an answer, shorten it into one sentence. If a web-page source
  was used and has a URL, add it to the end of the answer between brackets.
  Always show_feedback to the user after an answer.
- If the tool returns a clarifying question, relay it exactly. Do not add, change,
  or omit information.
- If the tool returns no answer, ask the user if they want to be transferred to a
  live agent.