Главная / Статьи

Передача задач одним агентом в LangChain: создание рабочего процесса службы технической поддержки

Один агент LangChain, который меняет свой промпт и инструменты на каждом шаге: поэтапная служба технической поддержки с проверкой реальной личности, передачей данных через промежуточные компоненты и возможностью выхода за рамки задачи.

Издатель: REACTAPP.TOP7 мин чтения1587 слов

Источники: How to Build an AI Agent With LangChain Handoffs

Представьте, что вы звоните в службу поддержки ИТ после того, как не можете войти в свой аккаунт. Сотрудник, отвечающий за разговор, не задаёт одни и те же вопросы на каждом этапе, и то, что он может сделать, зависит от того, на какой стадии находится разговор. Сначала он подтверждает вашу личность, обычно посредством идентификационного номера сотрудника или имени руководителя, и не будет заниматься проблемой с аккаунтом, пока это не будет урегулировано. Затем он выясняет, в чём проблема: заблокированный аккаунт, забытый пароль или отсутствующее устройство аутентификации. Только после этого он принимает меры: восстанавливает доступ к аккаунту, отправляет ссылку для сброса пароля или перенаправляет звонок в команду безопасности. Для звонящего всё кажется единым разговором, хотя его объём меняется по мере продвижения разговора.

Передачи данных обеспечивают ИИ-агенту единый формат работы. Агент меняет список действий, которые ему разрешены, в зависимости от текущей стадии взаимодействия. В начале он собирает только идентификационные данные. После этого он задаёт вопросы о реальной проблеме, и как только проблема становится ясной, он принимает меры.

Два способа её создания

  • Тип 1 — подход с промежуточным слоем, предполагает использование одного агента, чьи полномочия меняются по мере развития диалога. Можно представить себе сотрудника службы поддержки, который работает по чек-листу.
  • Тип 2 — подход с несколькими агентами, предполагает использование нескольких агентов, которые передают друг другу диалог, подобно переносу звонка в другой отдел, когда первый сотрудник не может помочь.

Приведённая ниже реализация соответствует типу 1, который часто называют типом с одним агентом, поскольку код содержит ровно одного агента. Этот агент проверяет личность пользователя, затем диагностирует проблему и после этого её решает. Новый агент не появляется ни на одном этапе. Изменяются лишь его инструкции и набор инструментов с началом каждого этапа. Тип 2 отличается тем, что создаёт отдельных агентов и передаёт им ведение диалога.

Проект

Целью является агент службы технической поддержки в сфере ИТ, и в коде соблюдаются три правила:

  • Проблемы с учётными записями обсуждаются только после подтверждения личности пользователя по реальным данным.
  • Никаких действий не предпринимается, пока проблема не относится к одной из трёх поддерживаемых категорий.
  • Если проблема не подходит ни под одну из категорий, агент сообщает об этом вместо того, чтобы догадываться.

Пример работы

Пользователь обращается в службу поддержки после того, как у него отказались вход в корпоративную учетную запись. Сотрудник службы просит указать идентификатор сотрудника и имя руководителя. При первой попытке найти соответствующую запись сотрудника не удается, поэтому сотрудник службы просит информацию снова, а при второй попытке удается подтвердить личность пользователя. Затем сотрудник спрашивает о проблеме. Сначала пользователь упоминает свой личный онлайн-банковский счет, что сотрудник службы правильно относит к вопросам, не входящим в компетенцию. После того как пользователь уточняет, что проблема связана с корпоративным 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 имеет такое же значение, как и классификатор. Без него рабочий процесс пытался бы отнести каждый запрос к одному из поддерживаемых типов проблем, даже к несвязанным, в результате чего проблема с личным банковским счётом могла бы быть неправильно отнесена к категории технической поддержки. Этот флаг позволяет оператору чётко распознавать запросы, выходящие за рамки заданного рабочего процесса.

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 хранит текущую стадию обработки; инструменты изменяют его значение, а промежуточное программное обеспечение обращается к нему перед каждым вызовом модели. Вместе они определяют ход выполнения рабочего процесса. Правильное функционирование всё равно зависит от деталей: проверки с использованием реальных данных, нормализации идентификаторов, предоставления пути для обработки случаев, выходящих за рамки задачи, и корректного сопоставления слов-триггеров для завершения процесса. Машина состояний контролирует порядок выполнения шагов, а логика проверки обеспечивает правильное поведение каждого этапа.

    Связанные материалы

  • Постоянная память агента с использованием Mem0, LangChain и Groq, полностью локальная — Создание памяти для агента LangChain, сохраняющейся между сессиями: Mem0 с ChromaDB и вкладками HuggingFace, Llama 3.1, работающий на сервере Groq, класс для настройок и четко сформулированный запрос.