LangChain中的单智能体任务交接:构建IT服务台工作流
一个会在每一步更改提示词和工具的LangChain智能体:具备真实身份验证、中间件传递功能以及超出处理范围时自动退出机制的分阶段IT服务台。
想象一下,当你无法登录账户时打电话给IT服务台。接听电话的人不会在每个环节都询问相同的问题,而且他们能采取的措施也取决于通话的进展阶段。首先他们会通过员工编号或经理姓名来确认身份,在这个问题解决之前不会处理账户相关的问题。接着他们会查明问题所在:是账户被锁定、密码遗忘还是认证设备丢失。只有在确定问题后,他们才会采取行动,比如重新激活账户、发送重置链接或将通话转接给安全团队。对来电者来说,这似乎只是一次对话,但实际上随着通话的推进,处理的范围也在不断变化。
交接流程使人工智能代理保持相同的结构。该代理会根据交互的当前阶段调整其可执行的操作。起初它只会收集识别信息,收集完成后会询问实际问题,待问题明确后才会采取行动。
两种构建方式
- 类型1:中间件方法,使用一个权限会随着对话进展而变化的代理,就像同一位客服人员按照清单处理问题一样。
- 类型2:多代理方法,使用多个代理相互传递对话内容,就像当第一人无法解决问题时将其转接给其他部门一样。
下面的实现属于第一类,因其代码中仅包含一个智能体,故常被称为单智能体类型。该智能体会先验证用户身份,再诊断问题,最后解决问题。整个过程中不会出现新的智能体,只有在各阶段开始时其指令和工具集会发生变化。第二类则不同,它会创建多个独立的智能体,并让这些智能体之间进行对话。
项目内容
目标是一个IT服务台智能体,代码中实施了三条规则:
- 在用户的身份能通过真实记录验证之前,不得讨论任何账户问题。
- 只有在问题属于三种支持范畴之一时,才会采取相应措施。
- 如果问题不符合任何一类,智能体会直接说明,而不会猜测。
示例运行
一名用户因无法登录公司账户而联系客服支持。客服人员要求提供员工编号和经理姓名。第一次查询未找到对应员工记录,于是客服再次询问,第二次查询才确认信息。随后客服询问问题所在。用户首先提到了个人网上银行账户,客服正确地指出这不在服务范围内。在用户明确说明问题是出在公司IT门户上后,客服将其归类为账户锁定问题,恢复了访问权限,并在确认问题已解决后结束了对话。
代码流程解析
1. 状态架构
class HelpdeskState(AgentState):
current_step: NotRequired[HelpdeskStep]
identity_verified: NotRequired[bool]
verification_attempts: NotRequired[int]
issue_type: NotRequired[Literal["locked_account", "forgotten_password", "lost_mfa_device"]]
current_step字段决定了STEP_CONFIG中的哪一项内容将用于生成下一个响应,这一点在第4节中会再次提及。另外三个字段(identity_verified、verification_attempts和issue_type)用于存储对话目前收集到的信息。这些信息会通过.format()函数被插入到提示语中,这样解决方案提示语就可以包含类似EMPLOYEE STATUS: identity_verified = {identity_verified}这样的内容。
2. 验证的真实值
EMPLOYEE_DIRECTORY = {
"EMP-4471": {"name": "Amit Rao", "manager": "Priya Nair", "department": "Finance"},
"EMP-1029": {"name": "Sara Khan", "manager": "David Chen", "department": "Engineering"},
"EMP-3305": {"name": "Neha Verma", "manager": "Priya Nair", "department": "Finance"},
}
MAX_VERIFICATION_ATTEMPTS = 3
def normalize_employee_id(raw_id: str) -> str:
digits = "".join(ch for ch in raw_id if ch.isdigit())
return f"EMP-{digits}" if digits else raw_id.strip().upper()
该模型从不判定员工编号是否有效。verify_identity函数会将编号与EMPLOYEE_DIRECTORY进行比对,因此结果来自查询结果而非模型的判断。标准化工具还能处理人们输入相同编号时的不同写法:在查询之前,4471、emp4471和EMP-4471都会被转换为统一格式,从而避免因格式差异导致有效编号被拒绝。
3. 工具
工具分为两类。转换工具会返回一个Command对象,该对象会将新值写入工作流状态,并将current_step推进到下一个阶段。
@tool
def verify_identity(
employee_id: str,
manager_name: str,
runtime: ToolRuntime[None, HelpdeskState],
) -> Command:
attempts = (runtime.state.get("verification_attempts") or 0) + 1
normalized_id = normalize_employee_id(employee_id)
record = EMPLOYEE_DIRECTORY.get(normalized_id)
verified = bool(record and manager_name.strip().lower() == record["manager"].lower())
if verified:
content = f"Identity verified for {normalized_id} ({record['name']})."
elif attempts >= MAX_VERIFICATION_ATTEMPTS:
content = f"Verification failed {attempts} times. Session locked — visit IT in person."
elif record is None:
content = f"No employee found with ID '{employee_id}'. Please retry."
else:
content = "The manager name doesn't match our records. Please retry."
return Command(
update={
"messages": [ToolMessage(content=content, tool_call_id=runtime.tool_call_id)],
"identity_verified": verified,
"verification_attempts": attempts,
"current_step": "issue_diagnosis" if verified else "identity_verification",
}
)
验证共有四种可能的结果。只有当员工编号和经理姓名都与记录一致时,验证才会成功。其余三种结果分别是尝试次数达到上限、使用了不存在的编号,或是使用了存在的编号但对应的经理姓名有误。每种情况都会显示不同的消息。经过验证的用户会进入issue_diagnosis步骤,而其他所有情况都会停留在identity_verification步骤,因此在身份得到确认之前不会继续执行后续操作。
由于工作流已进入最后阶段,终端工具只会返回一个普通字符串,而不会更改current_step的值。
@tool
def flag_out_of_scope(reason: str) -> str:
return (
f"This request appears to be about a personal account, not your "
f"company IT account ({reason}). This helpdesk can't assist with "
f"that — please contact the relevant provider directly."
)
flag_out_of_scope与分类器同样重要。如果没有它,工作流会试图将每个请求归类到支持的议题类型中,甚至是无关的类型,这样一来个人银行问题就可能会被错误地标记为IT支持问题。该工具为客服人员提供了一种清晰的方法,用于识别那些超出工作流处理范围的请求。
4. 提示语与步骤配置
每个阶段都有各自的提示语和工具列表,这些内容存储在同一个字典中,并由current_step的当前值来决定使用哪一组。
STEP_CONFIG = {
"identity_verification": {"prompt": IDENTITY_VERIFICATION_PROMPT, "tools": [verify_identity], "requires": []},
"issue_diagnosis": {"prompt": ISSUE_DIAGNOSIS_PROMPT, "tools": [record_issue_type, flag_out_of_scope], "requires": ["identity_verified"]},
"resolution": {"prompt": RESOLUTION_PROMPT, "tools": [unlock_account, send_password_reset_link, escalate_mfa_recovery, go_back_to_verification], "requires": ["identity_verified", "issue_type"]},
}
requires字段可作为中间件的防护机制,它在应用某一步骤的配置之前会检查所需条件是否满足。
5. 中间件
@wrap_model_call
def apply_step_config(
request: ModelRequest,
handler: Callable[[ModelRequest], ModelResponse],
) -> ModelResponse:
current_step = request.state.get("current_step", "identity_verification")
step_config = STEP_CONFIG[current_step]
for key in step_config["requires"]:
if request.state.get(key) is None:
raise ValueError(f"'{key}' must be set before reaching '{current_step}'")
system_prompt = step_config["prompt"].format(**request.state)
request = request.override(system_prompt=system_prompt, tools=step_config["tools"])
return handler(request)
该名称源于代码的运行位置:当前工作流状态与模型调用之间。在模型生成回复之前,中间件会读取状态,为当前步骤替换相应的提示词和工具,然后再将控制权传递下去。它在每次模型调用之前运行,读取current_step,加载匹配的配置,确认所需条件已满足,用当前状态值格式化提示词,并分配合适的工具。正是这样,随着工作流的推进,智能体的行为也会随之改变。
6. 构建智能体
agent = create_agent(
model,
tools=all_tools,
state_schema=HelpdeskState,
middleware=[apply_step_config],
checkpointer=InMemorySaver(),
)
检查点机制至关重要,因为它能够保留消息之间的工作流状态。如果没有它,current_step会在每次调用时重置,导致智能体每次都从第一步重新开始,无法继续前进。
避免错误的设计选择
为防止这类工作流中出现常见故障,设计时考虑了多项细节。
- 验证功能会检查真实记录。如果让
verify_identity向模型提问,判断身份证号和经理姓名是否正确,那么任何看似合理的答案都会通过验证。而通过查询EMPLOYEE_DIRECTORY则可以消除猜测的成分。 - 在匹配之前会对身份证号进行标准化处理。要求必须使用如EMP-4471这样的固定格式,会导致像4471或emp4471这样格式正确的输入因输入方式不同而被拒绝。标准化工具会先将各种常见格式转换为统一的规范形式。
record_issue_type仅接受三类选项。如果没有flag_out_of_scope,诸如银行相关问题这类不相关的请求会被强制归入最接近的类别中。user_input in {"quit", "exit"}这样的简单测试仅当整个输入恰好是该单词之一时才有效。而基于单词边界的正则表达式则能在句子中的任何位置捕获匹配项,包括“quit and exit”这类表达。在每种情况下,最简单的实现看似可行,但在实际输入面前却会失败。
简要总结模式
单智能体任务交接仅需三个部分。current_step字段用于记录当前阶段,工具会修改该字段,而中间件在每次调用模型之前都会查询它。三者共同决定工作流的推进方式。正确的行为仍取决于细节处理:与真实记录进行验证、对ID进行标准化处理、提供超出处理范围的解决方案以及正确匹配退出指令。状态机负责控制工作流的顺序,而验证逻辑则确保每个步骤都能按预期运行。
相关阅读
- 实用笔记:使用LangChain Deep Agents构建深度研究智能体 — 该笔记提供了可操作的指导,包括合同设计、检查机制以及供采用该模式的团队直接使用的代码片段。