Work / Case Study

AI Event Discovery Agent

National Central Library

A conversational agent for searching National Central Library events in natural language

Role AI Solutions Consultant (requirements → production) Duration 2 months Domain Government / Public Services Status Deployed in Production

2 mo
requirements to production
76
automated tests
41
E2E tests against production
1
API call for most queries

作品集 / 案例

國家圖書館 AI 活動探索 Agent

讓民眾用自然語言查詢圖書館活動的對話式 AI agent

角色 AI 解決方案顧問(從需求到上線) 時程 2 個月 領域 政府/公共服務 狀態 已部署於正式環境

2 mo
從需求到上線
76
組自動化測試
41
組對正式環境的 E2E 測試
1
多數查詢僅 1 次 API 呼叫

Overview總覽

Built a conversational agent for Taiwan's National Central Library. Citizens ask for events in their own words ("family activities this weekend", "free workshops in Taipei"), and the agent turns the question into structured queries against the library's events API, then answers in Traditional Chinese.

The stack is the OpenAI Agents SDK in TypeScript, running GPT-5.4-mini on Cloudflare Workers behind Zero Trust authentication. Conversation memory sits in a server-side D1 database. Deploys are triggered from Git.

為國家圖書館設計並建置對話式 AI agent:民眾用自然語言描述需求(「這個週末的親子活動」、「台北的免費工作坊」),agent 將問題對應到活動類型、時間、地點等查詢維度,查詢活動資料 API 後,以結構化的繁體中文結果回覆。

系統以 OpenAI Agents SDK(TypeScript)搭配 GPT-5.4-mini 建置,部署於 Cloudflare Workers,以 Cloudflare Zero Trust 驗證;對話記憶存於伺服器端 D1 資料庫,經 Git 觸發 CI/CD 自動部署。

Challenge & Solution挑戰與解法

Challenge

The events API expects exact parameters: category IDs, date ranges, venues. People don't ask that way ("anything good for kids?"). The system has to produce correct structured queries from loose questions, keep the conditions straight across follow-ups, and turn away questions that have nothing to do with events.

Solution

The agent loads category and venue mappings into its system prompt at startup, so the model can turn a question into query parameters without extra lookups. Simple requests finish in one API call; detail queries take two. If a category search comes back empty, the agent retries on keywords. If the question is too vague, it asks the user to narrow it down. Off-topic questions get a polite refusal in Traditional Chinese.

挑戰

活動資料的查詢介面需要明確的分類、日期區間、場地等參數,而民眾的提問是模糊的口語(「有什麼適合小孩的?」)。系統要把口語轉成正確的結構化查詢、在多輪追問中維持條件連貫,並拒絕非活動相關的詢問。

解法

Agent 啟動時預載活動分類與場地對照表進系統提示,模型將自然語言直接對應成查詢條件(關鍵字、分類、場地、日期區間),以最少的 API 呼叫完成查詢:單純查詢 1 次、細節查詢至多 2 次。查無結果時自動改用關鍵字放寬補查;問題太模糊時反問使用者縮小範圍;非活動相關的詢問即時攔截並以繁體中文禮貌拒絕。

What Happens to a Question請求處理流程read top to bottom由上而下閱讀

Citizennatural language
AgentCloudflare Workers
Events APIgovernment contractor
Question, in their own words
"family activities this weekend"
Cloudflare Access verifies the requestZero Trust authentication
Off-topic? Polite refusal in zh-TW
guardrail short-circuit, the model never runs
GPT-5.4-mini maps intent to a structured querypreloaded category and venue mappings
Structured query
1 call for most requests
Results
empty? retry on keywords
Answer in Traditional Chinese
conversation saved to D1 for follow-ups

Every step a real request takes, including the guardrail path that stops off-topic questions before they cost anything.

民眾自然語言
AgentCloudflare Workers
活動 API政府包商
以口語提問
「這個週末的親子活動」
Cloudflare Access 驗證請求零信任驗證
離題?以繁體中文禮貌拒絕
護欄短路,模型不會執行
GPT-5.4-mini 將意圖轉為結構化查詢預載分類與場地對照表
結構化查詢
多數請求 1 次呼叫
查詢結果
零結果改用關鍵字補查
以繁體中文回覆
對話存入 D1 供追問

真實請求經過的每一步,包含在產生任何成本前攔下離題問題的護欄路徑。

Key Capabilities核心能力

  • Natural-language queriesThe model breaks a request into event type, date, and venue, and builds the query itself. No filters, no forms.
  • Preloaded mappingsCategory and venue tables load once at startup; most searches cost a single API call
  • Conversation memoryHistory lives server-side in Cloudflare D1 and is summarized automatically, keeping the key points. On follow-ups, the model decides whether earlier conditions still apply; "that event" resolves to the right one.
  • Fallback and counter-questionsEmpty category results trigger a keyword retry; vague questions get a narrowing question back
  • Off-topic protection17 keyword signals catch clearly off-topic requests (weather, stocks, small talk) before they cost anything; each gets a polite refusal in Traditional Chinese
  • Resilient API callsTimeouts with exponential backoff; server errors retry, client errors fail fast
  • 自然語言查詢對應模型將口語需求拆解為活動類型、時間、地點等維度,組合成結構化查詢條件,使用者不需操作任何篩選器
  • 預載優化與兩段式查詢啟動時預載分類/場地對照表,常見查詢 1 次 API 呼叫完成,降低延遲與 API 負載
  • 多輪對話記憶對話存於伺服器端(Cloudflare D1),自動總結歷史並保留重點;追問時由模型從語意判斷前輪條件是否延續(「那個活動」能正確指回前文)
  • 補查與反問策略分類查詢零結果時自動改用關鍵字補查;問題模糊時主動反問縮小範圍
  • 離題防護以 17 組關鍵字訊號即時攔截明顯離題的詢問(天氣、股票、閒聊等),命中即以繁體中文禮貌拒絕,零額外 LLM 成本
  • 韌性 API 整合逾時控制與指數退避重試;伺服器錯誤才重試、參數錯誤快速失敗

Technology Stack技術棧

LLM & Agent
OpenAI Agents SDK, GPT-5.4-mini, TypeScript
Platform
Cloudflare Workers, Wrangler, Workers Builds (Git CI/CD)
Data
Cloudflare D1 (SQLite), government events API
Quality
76 Vitest tests (41 E2E against production), single- and multi-turn eval scripts, response-time tracking
LLM & Agent
OpenAI Agents SDK、GPT-5.4-mini、TypeScript
平台
Cloudflare Workers、Wrangler、Workers Builds(Git CI/CD)
資料
Cloudflare D1(SQLite)、政府活動資料 API
品質
Vitest 76 組測試(含 41 組對正式環境的 E2E)、單輪+多輪評測腳本、回應時間追蹤

My Contribution我的貢獻

  • Sole consultant on the engagement: requirements, agent architecture, LLM integration, deployment, and follow-up releases
  • Query strategy that keeps API calls low: preloaded mappings, two-stage queries, keyword fallback, counter-questioning
  • Memory design: D1 persistence with message replay; the model judges from context whether earlier conditions carry over
  • Test coverage: 76 automated tests, including 41 end-to-end against production with response-time baselines
  • Guardrails and localization: off-topic interception with polite refusals in Traditional Chinese
  • 端到端交付:以獨立顧問身分,從利害關係人需求、agent 架構、LLM 整合到正式部署與迭代發布
  • 查詢策略設計:預載對照表、兩段式查詢、補查與反問策略,將 API 呼叫次數壓到最少
  • 多輪記憶設計:D1 儲存與訊息重放,由模型以語意判斷條件是否延續
  • 品質與韌性:76 組自動化測試、E2E 對正式環境含回應時間基準、逾時與指數退避重試
  • 離題防護與在地化:非活動詢問的攔截與繁體中文禮貌拒絕
← All work← 全部作品