Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Tutorial: Building an IT Helpdesk Agent with Multiple Knowledge Bases

Build an AI agent that answers employee IT questions by automatically deciding which knowledge base to search: an internal IT procedures database or a vendor software documentation database. The agent reads the question, picks the right tool, and synthesizes an answer from the relevant documents.

The agent uses two search pipelines as tools. One pipeline searches the internal IT documentation, the other searches the vendor software documentation. The agent decides which tool to use based on the question.

  • Level: Intermediate
  • Time to complete: 25 minutes
  • Prerequisites:
    • A basic understanding of pipelines and indexes in Haystack Platform. For details, see Pipelines and Indexes.
    • A basic understanding of agents in Haystack Platform. For details, see AI Agent.
    • A workspace in Haystack Platform, where you'll create your agent and its tools. For help, see Quick Start Guide.
    • An API key from an active OpenAI account (or another model provider that supports tool calls). Connect Haystack Enterprise Platform to your OpenAI account. For help, see Use OpenAI Models.
  • Goal: After completing this tutorial, you'll have an IT helpdesk agent that answers employees questions based on two knowledge bases: an internal one and vendor documentation. This tutorial uses sample files for the knowledge bases. You can replace them with your own files.
  • Keywords: agent, tools, pipeline tool, knowledge base, RAG, routing

What You're Building​

Employees ask two very different types of IT questions:

  • Internal process questions: "How do I request a software license?" or "What's the VPN access procedure?" These need answers from company-specific documentation and internal policies, IT procedures, and how-tos.
  • Software how-to questions: "How do I share my screen in Zoom?" or "How do I set up email on my phone?" These need answers from vendor product documentation.

A single knowledge base struggles with both types of questions and combining them in one search often dilutes relevance.

This tutorial shows you how to create two focused search pipelines, each backed by its own index, and wire them together into an agent that picks the right one for each question.

Upload Files​

First, upload the sample files to your workspace:

  1. Download the agent-it-helpdesk folder from gdrive and save it to a location on your computer.
  2. Unzip the folder and open it.
  3. In Haystack Enterprise Platform, go to Files>Upload Files and choose all the files in the folder.
  4. Click Upload.

Result: You have four files in your workspace: vpn-access.md, software-requests.md, zoom-guide.md, and microsoft365-guide.md.

Add Metadata to the Files​

We'll add metadata to the files to mark internal knowledge base files and vendor documentation files. Based on the metadata, we'll create two separate indexes: one for internal IT documentation and one for vendor documentation.

As we only have four files, we'll add metadata to the files manually. You can also use the SDK or REST API to add metadata to the files. For details, see Add Metadata to Your Files.

  1. On the Files page, click More Actions next to the zoom-guide.md file and choose View Metadata.

    The View Metadata menu

  2. Click Add Metadata.

  3. Leave Keyword as type, type knowledgebase as the key, and product as the value, and save your changes.

    The file metadata with added knowledgebase and product metadata

  4. Repeat steps 1 to 3 for the microsoft365-guide.md file.

  5. For the vpn-access.md and software-requests.md files, leave Keyword as type, type knowledgebase as the key, and internal as the value, and save your changes.

Result: You have added metadata to the files to differentiate between internal and vendor documentation.

Create the Knowledge Bases​

We'll need two knowledge bases: one for internal documentation and one for vendor documentation. These knowledgebases will act as tools for the agent to help it answer user questions.

Each knowledgebase needs an index and a search pipeline.

Create the Index for Internal Documentation​

As we only have Markdown files, we'll create a simple index that uses the MarkdownToDocument component to convert the files to documents. Then, we'll use MetadataRouter to write only the documents with the knowledgebase metadata set to internal to the document store.

Other File Types

If you have other file types, you can start from the Standard Index (English) template and then add the MetadataRouter component to filter the documents based on the metadata.

  1. In the navigation, go to Indexes>Create Index.

  2. Choose Build your own.

  3. Type internal-docs as the index name.

  4. Click Create Index. You're taken to the Builder.

  5. In Builder, switch to the YAML view and paste the following index configuration:

    # haystack-pipeline
    components:
      MarkdownToDocument:
        type: haystack.components.converters.markdown.MarkdownToDocument
        init_parameters:
          table_to_single_line: false
          progress_bar: true
          store_full_path: false
      DocumentWriter:
        type: haystack.components.writers.document_writer.DocumentWriter
        init_parameters:
          policy: NONE
          document_store:
            type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
            init_parameters:
              hosts:
              index: ""
              max_chunk_bytes: 104857600
              embedding_dim: 768
              return_embedding: false
              method:
              mappings:
              settings:
                index.knn: true
              create_index: true
              http_auth:
              use_ssl:
              verify_certs:
              timeout:
              nested_fields:
      MetadataRouter:
        type: haystack.components.routers.metadata_router.MetadataRouter
        init_parameters:
          rules:
            internal_documents:
              conditions:
                - field: meta.knowledgebase
                  value: internal
                  operator: ==
              operator: AND
          output_type: list[haystack.dataclasses.Document]
    connections:
      - sender: MarkdownToDocument.documents
        receiver: MetadataRouter.documents
      - sender: MetadataRouter.internal_documents
        receiver: DocumentWriter.documents
    max_runs_per_component: 100
    metadata: {}
    inputs:
      query: []
      filters: []
      files:
        - MarkdownToDocument.sources
      messages: []

  6. Save and enable the index.

Result: You have created an index for internal documentation. It filters the files to index based on their metadata. The query pipeline will use this index to search internal documents.

Create the Index for Vendor Documentation​

This index only indexes files with the metadata knowledgebase set to product.

  1. Go to Indexes>Create Index again.

  2. Choose Build your own.

  3. Type vendor-docs as the index name.

  4. Click Create Index. You're taken to the Builder.

  5. In Builder, switch to the YAML view and paste the following index configuration:

    # haystack-pipeline
    components:
      MarkdownToDocument:
        type: haystack.components.converters.markdown.MarkdownToDocument
        init_parameters:
          table_to_single_line: false
          progress_bar: true
          store_full_path: false
      DocumentWriter:
        type: haystack.components.writers.document_writer.DocumentWriter
        init_parameters:
          policy: NONE
          document_store:
            type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
            init_parameters:
              hosts:
              index: ""
              max_chunk_bytes: 104857600
              embedding_dim: 768
              return_embedding: false
              method:
              mappings:
              settings:
                index.knn: true
              create_index: true
              http_auth:
              use_ssl:
              verify_certs:
              timeout:
              nested_fields:
      MetadataRouter:
        type: haystack.components.routers.metadata_router.MetadataRouter
        init_parameters:
          rules:
            product_documents:
              conditions:
                - field: meta.knowledgebase
                  value: product
                  operator: ==
              operator: AND
          output_type: list[haystack.dataclasses.Document]
    connections:
      - sender: MarkdownToDocument.documents
        receiver: MetadataRouter.documents
      - sender: MetadataRouter.product_documents
        receiver: DocumentWriter.documents
    max_runs_per_component: 100
    metadata: {}
    inputs:
      query: []
      filters: []
      files:
        - MarkdownToDocument.sources
      messages: []

  6. Save and enable the index.

Result: You have created an index for vendor documentation. It filters the files to index based on their metadata. The query pipeline will use this index to search vendor documents.

Create the Internal Search Pipeline​

Let's create a RAG chat pipeline that the agent will use to query internal documentation.

  1. In the navigation, go to Pipeline Templates.

  2. Open the Conversational category, find the RAG Chat template, hover over it, and click Use Template.

  3. Type internal-it-search as the pipeline name and click Create Pipeline. You're taken to Builder.

  4. On the canvas, find the OpenSearchDocumentStore component and choose internal-docs from the Index field.

    The internal search pipeline with the OpenSearchDocumentStore component configured

  5. In the Index field, choose internal-it-docs from the list.

  6. Test the pipeline: Click Run on the toolbar and type "How do I request VPN access?". The pipeline should return the answer from the internal documentation.

    The test pipeline window

  7. Save and deploy the pipeline.

Result: You have created a RAG chat pipeline that searches the internal documentation. It's ready for the agent to use.

Create the Vendor Docs Search Pipeline​

  1. In the navigation, go to Pipelines, click More Actions next to the RAG Chat template and choose Duplicate. The duplicated pipeline opens in Builder.

    The Duplicate Pipeline menu

  2. Change the pipeline name to vendor-docs-search.

  3. Find the OpenSearchDocumentStore component and in its Index field, choose product-docs from the list.

  4. Test the pipeline: Click Run on the toolbar and type "How do I share my screen in Zoom?". The pipeline should return the answer from the vendor documentation.

  5. Save and deploy the pipeline.

Result: You have two search pipelines, each pointed at a different index. Now, let's create and agent that will use them as tools.

Build the Agent​

Now you'll create the agent that uses both search pipelines as tools and routes questions between them.

Create the Agent Pipeline​

  1. Go to Pipelines>Create Pipeline>Create empty pipeline.

  2. Type helpdesk-agent as the pipeline name and click Create Pipeline.

  3. Expand Components and drag the Input, Agent, and Output components onto the canvas.

    The components to add in the component library

  4. Connect Input's messages output to Agent.messages input.

  5. Connect Agents messages output to Output's `messages' input.

    The connections between the components

  6. Configure the Agent:

    1. Click Model on the Agent component card to open its configuration panel.

    2. Choose gpt-5.4 (or another model that supports tool calls) from the list.

    3. In the System Prompt field, paste the following prompt:

      You are an IT helpdesk assistant for Acme Corp. You help employees solve IT problems and answer questions about IT processes and software.

      You have two tools:
      - search_internal_it: Use this for questions about Acme Corp's internal IT policies and procedures—requesting software, getting VPN access, IT support processes, internal how-tos.
      - search_vendor_docs: Use this for questions about how to use software products—Zoom, Microsoft 365, and other applications.

      When a question involves both internal processes and software (for example, "I can't connect to Teams because my VPN is blocking it"), use both tools before answering.

      Base your answer only on the information you find. Cite which documents you used. If you can't find the answer in either knowledge base, say so clearly and tell the employee to contact the IT helpdesk directly at helpdesk@acmecorp.internal.

    4. Leave the User Prompt field empty. You connected Input.messages to Agent.messages, so user questions from the chat window reach the agent directly.

    5. In the Tools section, click Add Tool.

    6. Choose Pipeline as the tool type.

    7. On the Create Pipeline Tool window, choose to start from Existing pipeline and choose internal-it-search from the list.

    8. Leave Current draft as the pipeline version.

    9. Type search_internal_it as the tool name.

    10. Type the following as the tool description:

    Search Acme Corp's internal IT documentation. Use this tool for questions about internal
    IT policies, procedures, and processes—such as requesting software licenses, getting VPN
    access, IT support escalation, new employee IT setup, or any company-specific IT how-tos.
    1. Click Add Pipeline Tool. search_internal_it is added to the Tools section.
    2. Click Add Tool again to add the second tool.
    3. Choose Pipeline as the tool type.
    4. On the Create Pipeline Tool window, choose to start from Existing pipeline and choose vendor-docs-search from the list.
    5. Leave Current draft as the pipeline version.
    6. Type search_vendor_docs as the tool name.
    7. Type the following as the tool description:
    Search vendor software documentation. Use this tool for questions about how to use
    specific applications and products—such as Zoom features, Microsoft 365, setting up
    email on mobile, or any other software how-to questions.
    1. Click Add Pipeline Tool. search_vendor_docs is added to the Tools section.
    2. Close the Agent configuration panel.

Result: You have created an agent pipeline with two tools: search_internal_it and search_vendor_docs.

Test the Agent​

Before deploying, test the agent in Builder to confirm it routes questions correctly.

  1. Hover over the Agent component card and click Run Component.
  2. In messages, type "How do I request access to vpn?" and run the agent.

Result: The agent should call search_internal_it, find the VPN request procedure from vpn-access.md, and return step-by-step instructions including the IT Service Portal link. To check which tool was used, find a message with "_role": "assistant" in the component output and look for the "tool_name".

The test agent window

You can also test the agent with a question that requires both tools, such as: "I need to install Zoom on my laptop—how do I get a license and then set up the background?". The agent should call search_internal_it to find the software license request process, then call search_vendor_docs to find the virtual background instructions, and combine both into a single answer.

Deploy the Agent​

  1. In Builder, click Deploy.
  2. Wait until the pipeline status changes to Deployed.

Result: Congratulations! Your helpdesk agent is live. You can now share it with your team and start using it to answer IT questions. For instructions on how to share the agent, see Share a Pipeline Prototype.

What To Do Next​

Your agent is at the development service level. Before moving to production:

  • Test it with a wider range of employee questions to check that routing is accurate.
  • Adjust the tool descriptions and system prompt if the agent consistently picks the wrong tool for certain question types.