首页 / 文章

LangChain中的单智能体任务交接:构建IT服务台工作流

一个会在每一步更改提示词和工具的LangChain智能体:具备真实身份验证、中间件传递功能以及超出处理范围时自动退出机制的分阶段IT服务台。

发布者:REACTAPP.TOP阅读约 7 分钟1587 词

来源: How to Build an AI Agent With LangChain Handoffs

想象一下,当你无法登录账户时打电话给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会在每次调用时重置,导致智能体每次都从第一步重新开始,无法继续前进。

避免错误的设计选择

为防止这类工作流中出现常见故障,设计时考虑了多项细节。

  1. 验证功能会检查真实记录。如果让verify_identity向模型提问,判断身份证号和经理姓名是否正确,那么任何看似合理的答案都会通过验证。而通过查询EMPLOYEE_DIRECTORY则可以消除猜测的成分。
  2. 在匹配之前会对身份证号进行标准化处理。要求必须使用如EMP-4471这样的固定格式,会导致像4471或emp4471这样格式正确的输入因输入方式不同而被拒绝。标准化工具会先将各种常见格式转换为统一的规范形式。
  • 分类器提供“以上均不符合”的退出选项。 record_issue_type仅接受三类选项。如果没有flag_out_of_scope,诸如银行相关问题这类不相关的请求会被强制归入最接近的类别中。
  • CLI退出检查是按单词匹配的。像user_input in {"quit", "exit"}这样的简单测试仅当整个输入恰好是该单词之一时才有效。而基于单词边界的正则表达式则能在句子中的任何位置捕获匹配项,包括“quit and exit”这类表达。
  • 在每种情况下,最简单的实现看似可行,但在实际输入面前却会失败。

    简要总结模式

    单智能体任务交接仅需三个部分。current_step字段用于记录当前阶段,工具会修改该字段,而中间件在每次调用模型之前都会查询它。三者共同决定工作流的推进方式。正确的行为仍取决于细节处理:与真实记录进行验证、对ID进行标准化处理、提供超出处理范围的解决方案以及正确匹配退出指令。状态机负责控制工作流的顺序,而验证逻辑则确保每个步骤都能按预期运行。

    相关阅读

  • 利用 Mem0、LangChain 和 Groq 实现完全本地化的持久化智能体内存 — 为 LangChain 智能体提供可跨会话保留的记忆功能:结合 ChromaDB 与 HuggingFace 嵌入模型的 Mem0、由 Groq 运行的 Llama 3.1、配置数据类以及基于实体的提示词。