# Knowledge Article Recommendation

**Categories:** Knowledge Base

Suggest relevant knowledge base articles to agents and users during ticket creation.

## What Knowledge Article Recommendation does

Knowledge Article Recommendation is Harmony's AI-powered capability that surfaces relevant company knowledge base content and proven past resolutions directly inside helpdesk conversations. When an employee sends a question, the agent automatically queries two knowledge sources - the organization's official KB and a library of insights distilled from previously resolved tickets - and delivers a personalized, context-aware answer without the employee ever leaving the chat. The result is faster self-service resolution and fewer tickets escalated to human agents.

## Who Knowledge Article Recommendation Is For

**Persona:** Employees across all departments who need answers to IT, HR, or policy questions via the Harmony helpdesk chatbot.

**Pain point:** Before this capability, employees had to hunt through separate knowledge base portals or wait for an IT agent to respond. The recommendation engine brings the right article to the conversation automatically - personalized for the employee's location, role, and device - so the answer appears in context rather than requiring a separate search.

## How Knowledge Article Recommendation Works

**Trigger:** An employee sends a message in the Harmony helpdesk chatbot (via Slack, Teams, or the portal).

1. **Context gathering** - Before querying any knowledge source, the agent first gathers user context: device type, OS, app, location, job title, and conversation history. The KB query is intentionally blocked until this step completes.

2. **Parallel knowledge retrieval** - The agent queries two sources simultaneously: - **Official KB** (query_kb): Sends a context-enriched query to Bedrock's retrieve-and-generate API, using the employee's profile and conversation history to personalize the generated answer. Permission filters ensure the employee only sees content their group has access to. - **Insights KB** (query_insights): Retrieves step-by-step resolution procedures extracted from past helpdesk conversations that closely match the current problem. Full articles are fetched from S3.

3. **Personalized answer assembly** - The agent evaluates which policy variant applies to this specific employee (user-specific match, global policy, or other contexts only), leads the answer with that determination, and supplements with proven resolution steps from insights if available. Video links from KB sources are always surfaced.

**Outcome:** The employee receives a tailored, cited answer in the conversation. If the KB is exhausted or the answer doesn't resolve the issue, the agent proceeds to ticket creation or escalation.

## Capabilities

- **Query the official knowledge base** - Searches the organization's KB using Bedrock `retrieve_and_generate` with a hybrid vector search, returning an AI-generated answer grounded in official policy documents.
- **Personalize answers by employee context** - Tailors responses based on the employee's country, city, job title, work location, device, OS, and tenure. HR and compensation policies always include country context; device questions always include device type and OS.
- **Enforce KB access permissions** - Filters results to content the employee's groups are authorized to see, using a least-privilege intersection of actor and reporter group memberships.
- **Surface insights from past resolutions** - Retrieves step-by-step procedures distilled from previously resolved tickets that match the current problem, providing practical how-to guidance beyond what's in official policy docs.
- **Determine policy applicability** - Explicitly identifies whether the returned policy is user-specific, company-wide, or only documented for other contexts - and states this clearly at the start of the answer, reducing employee confusion.
- **Surface video and media sources** - Detects video links in KB sources and always includes them in the response; video sources are treated as high priority.
- **Respect conversation history** - Injects conversation history into the KB generation template so follow-up questions produce contextually continuous answers.
- **Retry on empty results** - When the first KB query returns nothing, the agent is instructed to retry with added context (country, job title, device) before falling back to general guidance or ticket creation.

## Main use cases

**Employee Asking About a Location-Specific HR Policy** - An employee in Israel asks about PTO policy and whether it differs by country. The agent detects the employee's country from their profile, appends it to the KB query, and leads the answer with "This policy applies to your location (Israel):" - serving the relevant variant first rather than a generic global answer.

**Troubleshooting a Recurring Technical Issue** - An employee's VPN keeps dropping when switching networks and they message the helpdesk. The insights KB is queried in parallel with the official KB. If similar cases have been resolved before, the agent presents proven step-by-step instructions framed as "Based on Harmony's analysis of similar resolved tickets, here's what works..." - before the issue needs to be escalated.

**New Employee Asking About Equipment and Allowances** - A recently onboarded employee asks what home office stipend they're eligible for. The agent uses the employee's job title and country to retrieve the correct allowance policy, calculates any tenure-based eligibility using their start date, and presents a personalized answer that references their specific situation.

**IT Agent Handling a Ticket on Behalf of an Employee** - An IT agent opens a conversation to investigate an employee's software access issue. The KB query uses both the IT agent's groups and the employee's groups - only content accessible to both parties is returned, ensuring the agent isn't served information the employee isn't permitted to see.

## Integrations

Knowledge base content is synced from external sources into Harmony. The agent searches whatever sources are connected for that tenant.

| Integration | Role in the agent flow |
| --- | --- |
| Confluence | Pages and spaces are synced into Harmony's KB; the agent retrieves policies, procedures, and documentation published there |
| Notion | Pages are synced from connected Notion workspaces; the agent can surface any content published to Notion |
| SharePoint | Documents and pages from SharePoint sites are indexed and made searchable through the agent |
| Freshservice | KB articles from Freshservice are synced and searchable alongside content from other sources |
| ServiceNow | KB articles from ServiceNow are synced into Harmony's KB for retrieval |
| Manual File Upload | Admins can upload documents directly to Harmony's KB; these are indexed and treated the same as synced content |

## FAQ

### What exactly is Knowledge Article Recommendation - is it a bot, a separate system, or part of the helpdesk?

It's a capability embedded in Harmony's AI Helpdesk chatbot - not a separate product. When an employee chats with the helpdesk, the agent automatically decides when to search the knowledge base and surfaces the relevant content inline. There's no separate "recommendation service" the employee interacts with directly.

### How does it know which article to surface - is it keyword search or something smarter?

It uses AWS Bedrock's hybrid search, combining semantic (vector) search with keyword matching across up to 50 candidate documents, then generates a personalized answer using a prompt that injects the employee's profile (location, role, tenure, device) and conversation history. The query itself is also enriched with mandatory context keywords (country for HR policies, device type for tech questions) to ensure the right variant is retrieved.

### What does it handle and what does it hand off to a human?

It handles answering questions that are covered in the KB or solvable from past ticket resolutions. If the KB returns nothing after a second retry, or if the answer doesn't resolve the issue after one round of guidance, the agent moves to ticket creation or desk routing. It never enters extended troubleshooting loops - one round of guidance per issue is the limit before escalating.

### Does it show every employee the same articles, or is content restricted?

Content is permission-filtered. In private access mode, results are scoped to content that both the person asking and the person being helped share group access to (using the intersection of their group memberships). This means an IT agent helping a specific employee will only surface articles both of them are authorized to see.

### What does it need to be set up before it works?

It requires a Bedrock Knowledge Base to be provisioned and populated with the organization's KB content (controlled by `BEDROCK_KB_ID` and `BEDROCK_KB_MODEL_ARN`). The insights feature additionally requires a separate Bedrock insights KB and an S3 bucket for article storage. The KB access mode (public vs. private with permission filtering) is configured per tenant via the KB Data API.

## Related platform features

- **AI Helpdesk Chatbot (Service Desk Agent)** - Host agent - KB recommendation is a toolkit within the helpdesk chatbot, triggered during conversation processing
- **Insights Engine** - Upstream pipeline that clusters resolved conversations and generates the structured articles stored in the insights KB that `query_insights` retrieves
- **Service Catalog / Ticket Creation** - Downstream fallback - when KB search is exhausted or the answer doesn't resolve the issue, the agent proceeds to ticket creation or service catalog routing