• 示例工程
• 人工智能

本文深入解析开源仓库 500-AI-Agents-Projects 中的人力资源场景示例 Resume Parser Agent：一个基于 LangChain + GPT-4o-mini 的 AI Agent，可将 TXT/PDF 简历解析为结构化 JSON，并可选地与职位描述进行匹配度评分。读完本文，你将掌握该 Agent 的完整安装、三种运行方式、输出 JSON 的每个字段含义，以及其背后 prompt 工程与鲁棒 JSON 解析的源码实现原理。

一、项目概览：这个简历解析 Agent 能做什么

Resume Parser Agent 位于仓库agents/目录下第 09 号位置，属于 500-AI-Agents-Projects 中「可以直接运行的工作实现（Working Implementations）」之一。它解决的是招聘场景中的两个核心问题：

1. 结构化抽取：把非结构化的简历文本（TXT 或 PDF）解析成字段完整的 JSON——包含姓名、邮箱、技能、经历、教育背景等；
2. 匹配度评估：将解析出的候选人画像与一份职位描述（Job Description）对比，输出 0-100 的匹配分数（Fit Score）以及 Hire / Consider / Pass 录用建议。

按照 metadata.yaml 的定义，该 Agent 的关键定位信息如下：

整个agents/目录的设计理念是"每个目录都是独立可运行的 Agent，无需 monorepo 环境"，这一点在 agents/README.md 中有明确说明。本项目所有关键逻辑都集中在一个入口文件 agent.py 中，非常适合作为学习 LangChain 结构化抽取（Structured Extraction）的入门范本。

二、环境搭建：依赖安装与密钥配置

该 Agent 依赖清单集中在 requirements.txt 中，共 5 个包，版本均已锁定：

搭建步骤如下（与 README.md 中 Setup 部分一致）：

pip install -r requirements.txt cp .env.example .env

复制后，需要在.env中填入你的 OpenAI API Key。环境变量模板 .env.example 内容如下：

OPENAI_API_KEY=your_openai_api_key_here

在 agent.py 中，通过from dotenv import load_dotenv和load_dotenv()在程序启动时加载.env配置，随后ChatOpenAI会从环境中自动读取OPENAI_API_KEY。因此运行前必须配置有效的 OpenAI API Key，且账号需具备访问gpt-4o-mini模型的权限——这是本项目能够运行的前提条件。

三、三种运行方式与命令行参数

根据 README.md 的 Run 部分，该 Agent 支持三种典型的运行场景，全部通过agent.py的命令行参数切换：

# 1. 仅解析（使用内置示例简历） python agent.py # 2. 解析你自己的简历 python agent.py --resume path/to/resume.pdf # 3. 解析 + 匹配评分 python agent.py --resume resume.pdf --job-desc "Senior Python Engineer with K8s experience..."

命令行参数的解析逻辑位于 agent.py 的main()函数中，使用标准库argparse：

parser = argparse.ArgumentParser(description="Resume Parser Agent") parser.add_argument("--resume", help="Path to resume file (.txt or .pdf)") parser.add_argument("--job-desc", help="Job description to match against")

三种模式的行为差异可以总结为：

• 不传任何参数：使用内置示例简历（SAMPLE_RESUME）完成一次解析演示，输出解析结果；
• 只传--resume：解析指定简历文件并输出结构化结果；
• 同时传--resume与--job-desc：在解析基础上，追加候选人匹配度分析（Fit Score、优劣势、录用建议）。

四、解析输出：结构化 JSON 的完整字段

README 声明其输出包括：结构化 JSON（姓名、邮箱、技能、经历、教育）、候选人摘要、匹配度分数（0-100）、Hire/Consider/Pass 录用建议。其中"结构化 JSON 包含哪些字段"的权威定义，就在源码的PARSE_PROMPT中（agent.py）。这是一段完整的 JSON Schema 风格提示词，要求 LLM 返回如下结构：

{ "name": "full name", "email": "email or null", "phone": "phone or null", "location": "city, country or null", "linkedin": "URL or null", "github": "URL or null", "summary": "2-3 sentence professional summary", "years_experience": number, "current_title": "current/most recent job title", "skills": { "languages": ["Python", "JavaScript", ...], "frameworks": ["Django", "React", ...], "tools": ["Docker", "Git", ...], "soft_skills": ["leadership", ...] }, "experience": [{"title": "...", "company": "...", "duration": "...", "highlights": ["..."]}], "education": [{"degree": "...", "institution": "...", "year": "..."}], "certifications": ["..."], "languages_spoken": ["English", ...] }

各字段的实战含义如下：

• 联系方式类：name、email、phone、location、linkedin、github。注意 prompt 明确要求"不存在则为 null"，避免 LLM 编造缺失信息；
• 候选人概览类：summary（2-3 句职业摘要）、years_experience（数字，由 LLM 从经历推断）、current_title（当前/最近职位头衔）；
• 技能体系类：skills内部细分为languages（编程语言）、frameworks（框架）、tools（工具）、soft_skills（软技能）四个子数组，颗粒度比单一技能列表更便于后续检索筛选；
• 履历类：experience为数组，每项含title（职位）、company（公司）、duration（时间段）、highlights（亮点成就列表）；education为数组，每项含degree（学位）、institution（院校）、year（年份）；
• 附加信息类：certifications（证书列表）、languages_spoken（掌握的语种）。

提示词最后以Return only valid JSON.收尾，强制 LLM 输出纯 JSON，配合后文将要分析的鲁棒解析函数，保证结果可直接被json.loads消费。

五、候选人匹配评分：fit_score 与录用建议

当传入--job-desc时，Agent 会把解析出的候选人画像与职位描述一并交给 LLM 进行匹配分析。这一步的字段定义位于FIT_PROMPT（agent.py）：

{ "fit_score": 0-100, "fit_label": "Excellent|Good|Fair|Poor", "strengths": ["matching point 1", "matching point 2", ...], "gaps": ["missing skill 1", ...], "recommendation": "Hire|Consider|Pass", "recommendation_reason": "2-3 sentence explanation" }

这一输出的设计逻辑非常贴近真实 HR 决策流程：

• fit_score：0-100 的数值化匹配度，便于排序与阈值筛选；
• fit_label：把分数映射为 Excellent / Good / Fair / Poor 四档语义标签；
• strengths/gaps：分别列出候选人"与岗位匹配的点"和"缺失的点"，为招聘方提供可解释的依据；
• recommendation：最终录用建议，三选一（Hire 录用 / Consider 考虑 / Pass 淘汰）；
• recommendation_reason：2-3 句文字说明，解释推荐理由。

在终端展示时，main() 函数 会按 fit_label 给分数配上颜色表情符号：Excellent 为 🟢，Good 为 🟡，Fair 为 🟠，Poor 为 🔴，并输出前 3 条 Strengths、前 3 条 Gaps 与 Recommendation，形成一份紧凑的"候选人-岗位匹配报告"。

六、源码实现深度解析

理解了输出结构后，我们再从 agent.py 的源码角度，看这个 Agent 是如何一步步把简历变成结构化数据的。整个执行链路分为四个关键环节。

6.1 简历文本读取：TXT 直读 + PDF 走 pypdf

read_resume_text()（agent.py）根据文件扩展名分流：

def read_resume_text(path: str) -> str: if path.endswith(".pdf"): try: import pypdf with open(path, "rb") as f: reader = pypdf.PdfReader(f) return "\n".join(page.extract_text() for page in reader.pages) except ImportError: print("⚠️ pypdf not installed. Install with: pip install pypdf") raise with open(path) as f: return f.read()

关键点：PDF 场景使用pypdf.PdfReader逐页抽取extract_text()并拼接；若环境未安装 pypdf（即未执行pip install -r requirements.txt），会给出明确提示并抛出异常——依赖缺失是 PDF 解析失败的最常见原因，按 requirements.txt 安装即可规避。

6.2 LLM 调用：SystemMessage 承载提示词，temperature 归零

parse_resume()与score_fit()（agent.py）的调用模式完全一致，是 LangChain 结构化抽取的标准写法：

def parse_resume(text: str) -> dict: llm = ChatOpenAI(model="gpt-4o-mini", temperature=0) messages = [SystemMessage(content=PARSE_PROMPT), HumanMessage(content=text)] response = llm.invoke(messages) return parse_json_response(response.content)

值得注意的实现细节：

• 模型固定为gpt-4o-mini：兼顾抽取质量与成本，适合批量简历处理的场景；
• temperature=0：将采样温度设为 0，最大程度保证同一份简历多次解析结果稳定，这对需要可复现、可审计的招聘流程至关重要；
• 角色分工：SystemMessage 承载字段规范（即 PARSE_PROMPT / FIT_PROMPT），HumanMessage 承载待处理的具体简历文本（或画像+职位描述），职责清晰。

score_fit()则在 HumanMessage 中把候选人画像与职位描述拼接在一起：

HumanMessage(content=f"Candidate profile:\n{json.dumps(profile, indent=2)}\n\nJob description:\n{job_desc}")

即先由parse_resume()得到结构化画像，再序列化为 JSON 交给score_fit()，两个 LLM 调用形成"先抽取、后评估"的两阶段流水线。

6.3 鲁棒 JSON 解析：兼容 markdown 代码块

LLM 输出并不总是纯净 JSON，为此parse_json_response()（agent.py）做了两层防御：

def parse_json_response(text: str) -> dict: cleaned = text.strip() if cleaned.startswith("```"): cleaned = re.sub(r"^```(?:json)?\s*", "", cleaned) cleaned = re.sub(r"\s*```$", "", cleaned) match = re.search(r"\{.*\}", cleaned, re.DOTALL) if match: cleaned = match.group(0) return json.loads(cleaned)

它首先剥离```json或```代码围栏标记，再用正则\{.*\}（配合re.DOTALL让.匹配换行）截取第一个完整 JSON 对象，最后才交给json.loads。这套"清洗 + 截取 + 反序列化"的容错模式，是生产环境处理 LLM 结构化输出时非常实用的技巧。

6.4 主流程编排

main()（agent.py）把上述环节串起来：

1. 解析命令行参数；
2. 若传入--resume则读取文件，否则回退到内置SAMPLE_RESUME；
3. 调用parse_resume()得到画像，并在终端打印姓名、当前职位头衔、经验年限、技能语言列表与职业摘要等精选字段；
4. 若传入--job-desc，调用score_fit()并打印匹配报告。

也就是说，终端展示的是精选字段，而完整结构化 JSON（含 skills 四个子数组、experience、education、certifications 等全部字段）由PARSE_PROMPT定义并由 LLM 返回——实际集成时可直接复用parse_resume()的返回值（profile字典）接入下游 HR 系统。

七、内置示例简历：零配置体验

不传--resume运行时，Agent 使用源码中内置的SAMPLE_RESUME（agent.py）演示完整流程。示例候选人画像包括：7 年经验的资深 Python 工程师（Jane Doe），覆盖 FastAPI/Kubernetes 微服务架构、Spark/Airflow 数据管道、Django REST 后端、AWS 云服务等技能点，以及 UC Berkeley 计算机科学学位和 AWS 架构师认证。这份示例覆盖了语言、框架、工具、云、教育、认证等多维信息，足以演示全部字段的抽取效果，也方便新手在不准备简历文件的情况下快速跑通流程。

八、扩展建议与后续方向

该 Agent 的定位是beginner 难度、人力资源行业的独立示例。若想继续深入，可以从以下几个方向入手：

• 对比同类 Agent：仓库中还有 18-job-application-agent（基于 CrewAI 的求职申请 Agent）等人力资源场景示例，可对比不同框架下同一业务问题的建模差异；
• 理解 LangChain 基础：本 Agent 用到的ChatOpenAI、SystemMessage、HumanMessage、load_dotenv是最小可用的 LangChain 组合，理解它们即可快速扩展到其他抽取类任务（如发票解析、合同字段抽取）；
• 了解仓库运行范式：所有agents/目录下的 Agent 都遵循"独立目录 + requirements.txt + .env.example + agent.py"的自包含模式，参考 agents/README.md 可快速上手任意一个。

九、总结

Resume Parser Agent 是一个小而完整的 LangChain 结构化抽取范例：它用两段精心的 prompt（PARSE_PROMPT定义输出 Schema、FIT_PROMPT定义匹配评估 Schema）、一个鲁棒 JSON 解析函数、一条"读取 → 解析 → 评分"的线性流水线，实现了简历到结构化 JSON、再到候选人-岗位匹配评分的完整链路。对希望入门 AI Agent 开发或落地招聘自动化的开发者而言，README.md 提供了清晰的运行指南，而 agent.py 则提供了可直接复用的实现细节——两者结合，即可在几分钟内搭建一个可用的简历解析与匹配评估工具。

• 示例工程
• 人工智能