JobRadar/docs/agent-contract.md

JobRadar Agent 契约

Agent 名称与目标

第一版只实现“岗位研究 Agent（Job Research Agent）”。它根据当前用户的岗位目标和个人画像，自主选择必要工具，查找候选岗位、补充企业证据、执行筛选与评分，最终输出可解释、可追溯的岗位研究结果。

输入

• 当前用户和个人画像编号
• 岗位关键词、地区、薪资、经验和学历边界
• 企业性质、行业偏好及排除条件
• 评分配置版本和目标招聘网站
• 最大岗位数量、运行时间和工具调用预算

结构化输出

• Agent Run 状态
• 候选、淘汰、推荐和待复核岗位数量
• 推荐岗位、维度分数和硬规则命中情况
• 企业性质、证据来源和置信度
• 风险提示、信息缺口和人工处理要求
• 工具调用及运行摘要

第一版工具

工具	单一责任	副作用
search_jobs	获取候选岗位	保存原始记录
normalize_jobs	标准化并识别重复岗位	保存标准化结果
apply_hard_filters	执行确定性筛选规则	保存筛选结果
research_company	查询企业主体、性质和证据	保存企业证据
analyze_job_match	生成结构化匹配维度分析	保存分析结果
calculate_job_score	使用固定公式计算最终分数	保存评分结果
save_research_report	保存本次最终报告	完成运行状态

工具实现前可以调整命名，但必须保持类型化参数、结构化返回值、单一职责和清晰的副作用说明。

状态与上下文

运行上下文至少包含 user_id、agent_run_id、search_task_id、个人画像版本、规则版本、评分配置版本和当前运行预算。上下文不包含网站明文密码、Cookie、模型 API Key 等敏感值；工具在服务端根据授权范围读取凭据。

模型运行配置在 Gateway 调用前根据当前用户的默认服务商解析。Agent 上下文和持久化运行请求只记录服务商编码与模型标识，不携带可解密密文或明文 API Key。服务商配置缺失、密钥不可解密或默认模型为空时，应在真实调用前以配置错误终止，不影响登录、配置页和历史运行查询。

人工确认边界

以下情况必须暂停或转人工处理：

• 遇到验证码、登录失效或网站访问限制。
• 企业主体或企业性质证据冲突。
• 准备执行超出用户配置范围的大规模采集。
• 任何简历投递、消息发送或对外联系行为。
• 删除历史岗位、证据或运行记录。

第一版不向 Agent 提供自动投递、自动联系、任意 Shell 或任意 SQL 工具。

可观测性

每次运行记录 Agent、模型、指令和工具版本，以及开始、结束、暂停和失败时间。每次工具调用记录名称、参数摘要、结果摘要、耗时和错误，同时保存最终结构化输出、trace 标识、token 用量、成本和人工确认结果。

WebUI提供“最终结果”和“执行过程”两个视角，使项目既可用于求职，也可展示 Agent 如何完成真实任务。

非目标

• 不使用多 Agent 伪造复杂度。
• 不通过兼容层同时支持多个 Agent 框架。
• 不引入 pgvector、向量数据库或无明确需求的 RAG。
• 不允许模型直接访问数据库、执行任意代码或绕过工具权限。

多 Agent 演进条件

只有单一 instructions 无法表达职责、工具和上下文导致稳定性下降、评测证明不同领域互相干扰，或者某类任务需要独立模型和安全边界时，才拆分专家 Agent。拆分后使用 Agents SDK 正式 handoff 或 manager pattern，并通过评测证明收益。