Guided Program Search & Search Guide

Guided program search helps prospective students describe what they want to study in plain language, run a targeted EducationPlannerBC program search, and receive a clear summary of the results — without the assistant inventing programs or filters that are not in your search index.

The feature uses two specialist agents that work together:

The Concierge does not list or analyse search hits itself. Once the search completes, control passes to Search Guide for that step.

End-to-End Flow

sequenceDiagram
    participant User
    participant Concierge as Study Pathways Concierge
    participant Search as search_guided()
    participant Guide as Search Guide

    User->>Concierge: "I want a nursing diploma with co-op near Vancouver"
    Concierge->>Concierge: Build /search/url/... path from Query Building rules
    Concierge->>Search: search_guided(search_url)
    Search->>Search: Fetch results JSON, normalise hits by count tier
    Search->>Guide: Activate Search Guide agent
    Guide->>User: Summarise, link, recommend, or suggest narrowing

At a high level:

1. The user describes their study interests, goals, or constraints.
2. Study Pathways Concierge converts that into a canonical search path (for example /search/url/epbc/website?query=nursing&clive=programs&...) and calls the search_guided function.
3. The platform fetches live search results from your indexed program content, compacts them according to how many hits were returned, and adds a tool message to the conversation.
4. Search Guide is activated automatically and reads that tool message plus the conversation history.
5. Search Guide replies to the user — comparing programs when there are few results, grouping or narrowing when there are many, or suggesting recovery steps when there are none.

Search Guide does not run new searches. It summarises what was already retrieved.

The Two Prompts

Study Pathways Concierge prompt

The Concierge prompt (agent_study_pathways_concierge.prompt) focuses on conversation and URL construction, not result analysis.

Key behaviours:

• Search-first, low friction — run a useful first search rather than collecting every possible filter up front.
• Minimal clarifiers — at most two clarifying questions before the first search; one question at a time.
• Clickable segments — finite choices (program type, credential, region, and so on) use the segment mechanism from your Output Format component so users can click instead of type.
• Hard filters vs soft preferences — only add URL facets when the user clearly wants them as requirements.
• Keywords vs facets — put subject or career intent in the query parameter; put institution, region, credential, study length, co-op, and similar constraints in facet parameters when they match supported values.

The Concierge includes {{prompt:Query Building}} for URL rules and calls search_guided when it has enough information to build a path.

On the Configure Agents screen, the Concierge agent must have search_guided enabled under Functions for its prompt. It should not use the standard search() function for this workflow.

Search Guide prompt

The Search Guide prompt (agent_search_guide.prompt) focuses on result presentation and next steps.

Key behaviours:

• Reads the prior tool message (hit count, search path, public results URL, and individual result blocks).
• Uses conversation history for the user's goals and constraints.
• Applies tiered summarisation rules based on total hit count (see below).
• Uses markdown links for program pages and public search URLs.
• Uses square-bracket clickables for recovery and narrowing suggestions the user can click as replies.
• Does not call search tools — the search has already run.

Search Guide also includes {{prompt:Query Building}} so it can build refined public search URLs when grouping or narrowing (for example linking to "3 diplomas at BCIT" with one extra facet added).

On the Configure Agents screen, Search Guide should have no search functions enabled. Its role description tells the Frontline agent when to delegate, but in normal operation it is activated automatically by search_guided() rather than by Frontline routing.

The Query Building Sub-Prompt

URL construction rules live in a shared Prompt Component called Query Building (sub_query_building.prompt in the global prompt library). Both agent prompts reference it with:

{{prompt:Query Building}}

Keeping URL rules in one component means:

• Concierge and Search Guide always use the same facet names, value formats, and parameter ordering.
• You can update search URL rules once and both agents pick up the change.
• The Concierge prompt stays focused on conversation flow instead of hundreds of lines of URL syntax.

The component covers:

When editing URL behaviour, start in Edit Prompts → Prompt Components → Query Building. After changing the component, review both agent prompts in Admin Chat to confirm Concierge still builds correct paths and Search Guide still links to valid refined searches.

See Editing a Prompt for how substitutions work and Prompts Overview for the difference between Agent Prompts and Prompt Components.

The search_guided Function

search_guided is a customer function that wraps the platform's guided search pipeline. The LLM calls it with a fully constructed path-only search URL:

/search/url/{account}/{service}?query=...&clive=programs&...

Important details:

When search_guided succeeds:

1. Results are fetched from your live search index (same backend as Site Search).
2. Hits are normalised by result count (see next section).
3. A tool message is added to the conversation, including the search path and a public results URL (https://www.educationplannerbc.ca/search.html?... with the same query string).
4. Search Guide is activated for the next assistant turn.

If the URL is invalid or the fetch fails, the error is returned to the Concierge agent and Search Guide is not activated — the Concierge can apologise, adjust the URL, or ask a clarifying question.

The function schema is defined in the global search_guided customer function. You do not need to write AirScript for EPBC unless you are adapting the pattern for another service.

How Results Are Prepared for Search Guide

Before Search Guide sees the results, the platform normalises them based on total hit count. This keeps tool messages appropriately sized and matches the tier rules in the Search Guide prompt.

Search Guide uses the total hit count from the tool message for its tier rules, not necessarily the number of Result [n] blocks shown (when more than 10 hits exist, fewer blocks may be shown than the total).

How Search Guide Presents Results

Search Guide adapts its reply based on how many programs matched. These tiers are defined in agent_search_guide.prompt.

Zero results

• States clearly that nothing matched the current search.
• Infers active filters from the search path.
• Suggests 2–3 recovery actions as square-bracket clickables, following the broaden order in Query Building (co-op → study length → credential → institution → location → program type).
• Does not invent programs or unsupported filters.

Example tone: "Would you like to [remove the co-op requirement] or [broaden the location to all of BC]?"

1–5 results

• Opens with a markdown link to the full result set on the public search page.
• Summarises how the programs differ using metadata (institution, credential, study length, co-op, region).
• Recommends 1–2 programs that best match the user's stated goals.
• Links recommended programs by title.
• Does not claim tuition, cost, or eligibility unless that information appears in the result text.

6–10 results

• Links to the full result set.
• Groups results by 2–4 meaningful dimensions present in the metadata (for example institution, credential, co-op).
• Each group phrase links to a refined public search URL with one facet added or adjusted.
• Adds up to 2 targeted recommendations when metadata supports them.
• Links individual program pages only for stand-out results — not every title.

More than 10 results

• Focuses on narrowing, not listing programs.
• Links to the full result set.
• Summarises how results spread across major categories with markdown links to refined searches.
• Offers 2–3 high-value narrowing paths as square-bracket clickables.

Example tone: "Would you like to [filter to diplomas only] or [limit to Vancouver Region]?"

Links vs Clickable Replies

Search Guide uses two different link mechanisms. Mixing them up produces confusing UX.

Markdown links open pages. Square-bracket text is meant to be clicked as a chat reply so the user types less.

Search Guide must not use markdown links for recovery or narrowing phrases that are meant to be clicked as user replies.

Configuration Checklist

Use this checklist when setting up or reviewing guided program search.

Agents

Set each agent's Role so the Frontline agent knows when to delegate to the Concierge. Search Guide's role describes post-search summarisation; in practice it is usually reached via automatic handoff after search_guided.

See Editing an Agent and Creating an Agent.

Prompts

Routing

Ensure the Frontline agent (or your service router) delegates study-pathway questions to Study Pathways Concierge. Typical triggers include program discovery, credential choice, and "what should I study" questions scoped to EducationPlannerBC programs.

Search Guide does not need separate Frontline routing for the happy path — search_guided() activates it directly.

Testing in Admin Chat

Use Admin Chat and the Trace Log to verify the full flow before going live.

Suggested test scenarios:

In the Trace Log, confirm:

1. The conversation starts with (or delegates to) Study Pathways Concierge.
2. search_guided is called with a path-only URL.
3. The active agent switches to Search Guide after the function returns.
4. Search Guide's reply follows the tier rules for the hit count.

Set Concierge status to Testing (Admin Chat) while iterating on prompts; switch to Live when satisfied.

What You Can Customise

Search Guide guardrails explicitly prevent re-running search tools. If you need the assistant to run a new search after summarising, that requires a product change — the intended pattern is for the user to click a square-bracket suggestion or ask a follow-up, which routes back through the Concierge to call search_guided again with an updated URL.

Limitations to Be Aware Of

• No admissions or eligibility guarantees — both agents are instructed to help users find programs, not confirm admission, immigration outcomes, scholarships, or job placement.
• No cost comparisons unless indexed — there is no cost facet; do not expect tuition comparisons unless cost data appears in result text.
• Search Guide cannot search again — it only summarises the tool message from the most recent search_guided call.
• Voice mode — automatic agent switching after search_guided may behave differently in voice/realtime sessions compared with text chat. Test voice separately if you offer it.
• Grounding — recommendations and groupings must come from result metadata and Query Building rules; the prompts instruct agents not to hallucinate institutions, credentials, or filters.

Related Guides

• Configure Agents — agent list, status, and delegation
• Editing an Agent — functions, prompts, and Force call first
• Prompts Overview — Agent Prompts vs Prompt Components
• Editing a Prompt — substitutions, saving, and version history
• Admin Chat — interactive testing and Trace Log
• Site Search Overview — index, filters, scopes, and result cards that underpin program search

← Back to Agents & Prompts overview