Галоўная / Артыкулы

Перадачы ўнутры аднаго агента ў LangChain: працэс IT-службы падтрымкі

Адзін агент LangChain, які мяняе промпт і інструменты на кожным кроку: паэтапная IT-падтрымка з рэальнай праверкай асобы, перадачамі праз middleware і выхадам для запытаў па-за межамі.

Выдавец: REACTAPP.TOP7 хв чытання1587 слоў

Крыніцы: How to Build an AI Agent With LangChain Handoffs

Уявіце, што вы тэлефануеце у службу падтрымкі IT пасля таго, як вас не пускаюць у абанк. Чалавек на лініі не ставіць тыя ж запытанні на кожным этапе, а тое, што ён можа зрабіць, залежыць ад таго, на якім етапе знаходзіцца размова. Спачатку ён парабяляеся ў вашу аідэнтычнасць, зазвычай за дапамогою ідэнтыфікацыйнага номера працавальніка або імені керавальніка, і не будзе займацца проблемай абанка, пакуль гэта не будзе рашанае. Потым ён з’ясоўвае, у чым проблэма: абанк, забуты пароль або відсутнае прыстройства автэнтыкацыі. Лячын таго ён прыемліе заходы — паўтарна актывацыя абанка, аправленне лінку для перазначэння пароля або перадача размовы калядзі безпекі. Для таго, хто тэлефануе, гэта выглядае як адна размова, хоць ўсё больш зміняецца ў меры ўзростання размовы.

Перадачы даюць агенту AI аднаковы фармат. Агент змініць тое, што яму дазволена робіць, залежна ад тэкушчага этапа взаімадзеяння. Спачатку ён толькі збірае інформацыю для ідэнтыфікацыі. Калі гэта завершана, ён запытае пра рэальную проблему, а калі проблема стане ясной, ён прыемліе заходы.

Два спосабы яго стварэння

  • Тып 1, падход з проміжнай суперасобою, выкарыстоўвае аднаго агента, чыя правыя зміняюцца па меры працы над размовай. Падумайце пра таго ж працавальніка службы падтрымкі, які працуе за чарткай.
  • Тып 2, падход з калькамі агентаў, выкарыстоўвае калькі агентаў, якія перадаюць размову аднам другаму, падобна да перадачы справы іншаму аддзелу, калі першы чалавек не можа дапамогчы.

Прынцыпы стварэння, паказаны ніжэй, адпавядаецца да тыпу 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 ставіла запыткі модэлю, запытваючы, чы рэквізіты ID і імя керавальніка выглядаюць правільна, то ўсё правдападобнае працавало бы. Перагляд EMPLOYEE_DIRECTORY усунець можлівасць здагадкаў.
  2. ID-ы нормалізуюцца пры паўтарнай адпаведнасці. Адмова ад вярных значэнняў, такіх як EMP-4471, могла бы адхіліць такія правільныя варыянты, як 4471 або emp4471, проста праз спосаб іх введэння. Нормалізатор спачатку перакладае распашчацыяе фарматы ў адну стандартную форму.
  • Класыфікатор мае варыянт выходу „ніякога з гэтых“. record_issue_type прымае толькі тры катэгорыі. Без flag_out_of_scope некалякія запыткі, такія як запыткі па банкавуччу, будуць прымушаны паўтарыцца ў найбліжэйшую катэгорыю.
  • Перакананне выходу праз CLI падтрымляе паўтарэнне слова. Просты тэст на кшталт user_input in {"quit", "exit"} працюе толькі тады, калі весь тэкст запытку ўсё роўна ўтварае адно з гэтых слов. Рэгулярны выраз, які адлічае межы слоў, фіксуе іх у будзь-якім месцы ў рэчы, укладаючы нават выразы на кшталт „quit and exit“.
  • У кожным случае простэйшая рэалізацыя здаецца працэсна, але зазнае бягучых проблем паўтарным вводам рэалістычных дадзенняў.

    Короткая характарыстыка шаблона

    Для перадачы задачы адзінам агенту патрабуецца толькі трыя элементы. Поле current_step храніць стадыю, інструменты яе зміняюць, а мідлвэр выкарыстоўвае яе перад кожным вызовам модэлю. Разам яны керуюць ходам выканання задачы. Правільна праця агента ўсё ж залежыць ад дэталей: пераканання ў правядзібнасці даных з рэальнай базы, нормалізацыя ID, запрошэнне на выкарыстоўвання альтэрнатыўнага падходу і правільная падбірка слов для завершэння задачы. Машына станоў керуе порадкам выканання задачы, а логіка верыфікацыі стараецца, каб кожны крок працаваў належным чынам.