autonomous-hr-chatbot

场景切入：当 HR 遇上大模型

想象一下这样的场景：周一早上，HR 专员同时被三位员工围住——A 问"我还有多少天年假"，B 问"Joseph Santos 手下的直接下属有谁"，C 问"我要是把 10 天未休年假折现，能拿多少钱"。以前 HR 只能翻 Excel、查手册、打一圈电话。如今，一个 AI Agent 可以同时搞定这三件事，甚至把推理过程也展示出来。stepanogil/autonomous-hr-chatbot 就是这样一个项目——一个能调用真实工具的 HR 问答 Agent。

背景：从 LangChain 演进到原生 SDK

这个项目由独立开发者 Stephen Bonifacio 创建，最初版本（2023）采用 LangChain + Pinecone 向量数据库 + Streamlit 构建，使用 gpt-3.5-turbo 作为大脑，依赖 text-embedding-ada-002 创建 HR 政策文档的向量嵌入，存入 Pinecone 索引。员工数据以 CSV 格式存储，通过 LangChain 的 PythonAstREPLTool 让模型执行任意 Python 代码来查询。

2026 年，作者发布了 v2 分支，完成了一次彻底重构：用纯 OpenAI Python SDK 替代 LangChain，用 OpenAI 内置的 file_search 工具替代 Pinecone 向量数据库，模型升级为 gpt-5.2，支持原生推理摘要输出。整个技术栈从"框架堆叠"变成了"SDK 直连"，代码量减少，依赖更轻量。

图1：v2 版本 HR Agent 对话界面，展示了 gpt-5.2 的推理摘要面板和工具调用追踪

核心功能：三类工具，覆盖 HR 高频场景

工具一：员工档案查询（get_employee_record）

输入员工姓名，Agent 可查询其完整档案：工号、职位、部门、职级、入职日期、转正日期、年假剩余、病假剩余、基本工资、雇佣状态和直接上级。所有数据来自项目附带的 employee_data.csv 示例数据集，通过 pandas DataFrame 查询，无需向量检索或 RAG。模型以类型化函数工具（JSON Schema strict 模式）接收参数，相比 v1 的任意代码执行，安全性大幅提升。

工具二：组织架构查询（list_direct_reports）

输入上级姓名，返回该上级所有直接下属的姓名、职位和职级。这是一个典型的链表式组织图查询场景，在企业 HR 系统中极为常见。例如问"Joseph Santos 的直接下属是谁"，Agent 自动调用此工具，返回人员列表并附加自然语言回答。

工具三：年假折现计算（compute_leave_encashment_value）

这是最有意思的一个工具。根据 HR 政策手册中的公式：**基本工资（PHP）/ 30 × 折现天数**，Agent 可以精确计算任意员工折现任意天数的金额。相比传统查表或手工计算，这个工具确保了政策公式的一致性应用——每次计算都用同一个公式，不存在理解偏差。

文件搜索：HR 政策 RAG

v2 版本使用 OpenAI 的 file_search 内置工具处理 HR 政策文档问答。与 v1 手动 embedding + Pinecone 存储的方案相比，file_search 将向量化和检索全部托管给 OpenAI 服务端，开发者只需上传政策文本到 OpenAI Vector Store，API 层面无需任何额外基础设施。

图2：v1 版本 HR Agent 聊天界面，支持多轮对话和工具调用可视化

技术架构解析

v2 架构：Agent Loop + Responses API

v2 的核心是一个事件驱动的 Agent 循环（agent_loop.py），基于 OpenAI Responses API 的流式响应设计。整个流程如下：用户输入 → API 调用（携带 previous_response_id 维持会话状态）→ 模型输出事件流 → 遇到 function_call 事件时调用本地工具（tools.py 中的 dispatch() 函数）→ 工具结果以 function_call_output 形式喂回模型 → 循环直到模型输出纯文本答案。

推理摘要（reasoning summary）通过 response.reasoning_summary_text.delta 事件实时流式传输，前端（app.py）用 Streamlit 的 st.status() 组件渲染为独立的"推理面板"，让用户看到模型的思考过程，而非只能看到最终答案。

事件流设计

agent_loop.py 定义了七种事件类型，所有事件以 tagged tuple 形式从生成器 yield 出来，被 Streamlit 前端消费：

• reasoning_delta：推理摘要增量文本
• tool_call_started：工具调用开始
• tool_call_finished：工具执行完成（附 JSON 结果）
• file_search_started：服务端文件搜索开始
• file_search_done：文件搜索结果
• text_delta：最终回答增量文本
• done：会话完成（附 response_id）

这种发布-订阅式的事件设计解耦了后端推理和前端渲染，是值得关注的设计模式。

工具定义与分发

tools.py 是 v2 的工具层核心。每个工具有三部分：

1. Python 函数实现：get_employee_record、list_direct_reports、compute_leave_encashment_value 三个函数，直接操作 pandas DataFrame，逻辑清晰。
2. JSON Schema 声明：OpenAI Responses API 的 function calling 遵循 Tool Schema 规范，v2 使用 strict: True 强制参数校验。
3. 分发表（TOOL_DISPATCH）：dispatch() 函数根据工具名称路由到对应函数，异常以 JSON error 对象返回而非抛出，确保 Agent 循环不中断。

前端渲染

app.py 使用 Streamlit 的原生聊天 API（st.chat_message）而非已弃用的 streamlit-chat 组件。会话历史存在 st.session_state['history'] 中用于 UI 重渲染，而真实会话上下文由服务端 previous_response_id 维护——这是一个聪明的设计，避免了每次重渲染都把完整历史发给 API。

v1 vs v2 对比

维度	v1（2023）	v2（2026）
LLM 框架	LangChain 0.0.220	纯 OpenAI SDK（无 LangChain）
模型	gpt-3.5-turbo	gpt-5.2（推理模型）
知识库	Pinecone 向量库 + 手动 embedding	OpenAI file_search 内置工具
员工数据工具	PythonAstREPLTool（任意代码执行）	Typed function tools（参数校验）
推理可见性	LangChain verbose scratchpad	gpt-5.2 reasoning summary 流式输出
会话状态	完整消息历史Replay	previous_response_id（服务端）
前端组件	streamlit-chat（已弃用）	原生 st.chat_message/st.status
依赖数量	~70个包	4个包

部署与上手

部署门槛（低）

项目无 Dockerfile 或 docker-compose，但部署本身并不复杂。以 v2 为例：

1. Python 3.10+ 环境
2. 虚拟环境：python -m venv .venv && source .venv/bin/activate
3. 安装依赖：pip install -r requirements.txt（v2 仅需 4 个包）
4. 配置密钥：复制 .env.example 为 .env，填入 OPENAI_API_KEY
5. 一次性导入政策文档：python ingest_policy.py，获得 Vector Store ID 后填入 .env
6. 启动：streamlit run app.py

整个过程约 10-15 分钟，所需硬件极低——纯 CPU 环境即可运行（无需 GPU），内存 2GB、磁盘 500MB 绰绰有余。

Azure OpenAI 路径

v2 同时支持 Azure OpenAI Service——只需将 BACKEND=azure 并配置相应的 AZURE_OPENAI_* 环境变量（端点、密钥、部署名、API 版本），即可在 Azure 上运行。对于企业用户，这意味着数据不离开 Azure 基础设施，满足合规要求。

局限与注意事项

1. 员工数据是示例数据：项目自带的 employee_data.csv 仅含虚拟员工，直接用于生产需替换为真实 HR 数据源（如 SAP HCM、Workday API）。
2. API 成本：v2 基于 OpenAI Responses API 和 file_search 工具，每次对话涉及 RAG 检索和模型推理，生产环境需评估 token 消耗。
3. 安全边界：当前工具集无访问控制——任何能访问聊天界面的用户可查询任意员工信息，生产部署需叠加身份认证和权限过滤。
4. HR 政策适用性：HR 政策文本（hr_policy.txt）基于菲律宾/东南亚劳动法框架，其他司法管辖区需替换本地政策。

行业意义

这个项目折射出一个更大的趋势：从"LangChain 狂热"回归"SDK 直连"。2023 年 LangChain 几乎是 LLM 应用的代名词，但随着底层 API（如 OpenAI Responses API）能力增强，很多 LangChain 做的事现在一行 SDK 调用就能搞定。依赖减少意味着维护成本降低、bug surface 缩小、升级路径更清晰。

同时，v2 展示了"推理可见性"的商业价值：让用户看到 AI 的思考过程，不只是接受一个答案——在 HR、医疗、法律等高风险场景，这种透明度能显著提升用户信任度，降低"AI 胡说"的投诉风险。

如果你正在构建企业内部知识问答系统（不只是 HR，客服、培训、合规等场景同理），这个项目是一个高质量的参考模板：从 RAG 策略、Agent 循环设计，到工具定义、会话状态管理，再到 Streamlit 前端实现，每个环节都有可借鉴的细节。

---

项目地址：https://github.com/stepanogil/autonomous-hr-chatbot
License: MIT
主要语言：Python