Startseite / Artikel

Übertragungen zwischen einzelnen Agenten in LangChain: Aufbau eines IT-Help-Desk-Arbeitsablaufs

Ein LangChain-Agent, der seinen Prompt und seine Tools bei jedem Schritt ändert: ein schrittweises IT-Help-Desk-System mit echten Identitätsprüfungen, Übertragungen über Middleware sowie einem Austritt bei Außengrenzen.

Verlag: REACTAPP.TOP7 Min. Lesezeit1587 Wörter

Quellen: How to Build an AI Agent With LangChain Handoffs

Stellen Sie sich vor, Sie rufen nachdem Sie von Ihrem Konto ausgesperrt wurden, eine IT-Hilfedesk an. Die Person am Telefon stellt nicht in jeder Phase dieselben Fragen, und das, was sie tun können, hängt davon ab, wie weit der Anruf fortgeschritten ist. Zuerst bestätigen sie die Identität, in der Regel über eine Mitarbeiter-ID oder den Namen eines Vorgesetzten, und kümmern sich erst danach um das Problem mit dem Konto. Anschließend finden sie heraus, was nicht in Ordnung ist: ein gesperrtes Konto, ein vergessenes Passwort oder ein fehlendes Authentifizierungsgerät. Erst danach handeln sie, indem sie das Konto wieder aktivieren, einen Wiederherstellungslink senden oder den Anruf an das Sicherheitsteam weiterleiten. Für den Anrufer wirkt es wie ein einziges Gespräch, obwohl sich dessen Umfang im Laufe des Anrufs ändert.

Übergaben verleihen einem KI-Agenten die gleiche Struktur. Der Agent ändert je nach aktueller Phase der Interaktion das, was er tun darf. Zunächst sammelt er nur identifizierende Details. Sobald dies erledigt ist, fragt er nach dem eigentlichen Problem, und sobald das Problem klar ist, ergreift er Maßnahmen.

Zwei Möglichkeiten, es zu konstruieren

  • Typ 1, der Middleware-Ansatz, verwendet einen einzigen Agenten, dessen Berechtigungen im Laufe des Gesprächs wechseln. Man kann sich den gleichen Helpdesk-Mitarbeiter vorstellen, der eine Checkliste abarbeitet.
  • Typ 2, der Multi-Agenten-Ansatz, verwendet mehrere Agenten, die das Gespräch untereinander weiterleiten, ähnlich wie bei einem Transfer in eine andere Abteilung, wenn die erste Person nicht helfen kann.

Die unten beschriebene Implementierung folgt dem Typ 1, der oft als Single-Agent bezeichnet wird, da der Code genau einen Agenten enthält. Dieser Agent überprüft die Identität, diagnostiziert anschließend das Problem und löst es. Zu keinem Zeitpunkt tritt ein neuer Agent auf. Was sich ändert, sind seine Anweisungen sowie sein Werkzeugset zu Beginn jeder Phase. Typ 2 unterscheidet sich dadurch, dass separate Agenten erstellt werden und die Kommunikation zwischen ihnen abgewickelt wird.

Das Projekt

Das Ziel ist ein IT-Helpdesk-Agent, und im Code werden drei Regeln durchgesetzt:

  • Es wird kein Kontoproblem besprochen, solange die Identität des Benutzers nicht mit einer echten Datenspur abgeglichen wurde.
  • Es wird keine Aktion unternommen, solange das Problem nicht in eine der drei unterstützten Kategorien fällt.
  • Falls das Problem nicht in eine dieser Kategorien passt, teilt der Agent dies mit, anstatt zu raten.

Ein Beispiellauf

Ein Benutzer wendet sich an den Support, nachdem er von einem Firmenkonto ausgesperrt wurde. Der Agent bittet um die Mitarbeiter-ID und den Namen des Vorgesetzten. Der erste Versuch ergibt kein passendes Mitarbeiterprofil, weshalb der Agent erneut nachfragt; beim zweiten Versuch wird die Identität bestätigt. Anschließend fragt der Agent nach dem Problem. Zunächst erwähnt der Benutzer ein persönliches Online-Banking-Konto, das der Agent korrekt als außerhalb des Zuständigkeitsbereichs einstuft. Nachdem der Benutzer klargestellt hat, dass das Problem am IT-Portal des Unternehmens liegt, klassifiziert der Agent es als ausgesperrtes Konto, stellt den Zugang wieder her und beendet das Gespräch, sobald die Lösung bestätigt wurde.

Durchgehen des Codes

1. Zustandsschema

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"]]

Das Feld current_step bestimmt, welche Eintragung aus STEP_CONFIG die nächste Antwort formt – ein Punkt, der auch in Abschnitt 4 erneut behandelt wird. Weitere drei Felder (identity_verified, verification_attempts und issue_type) speichern, was das Gespräch bislang erfasst hat. Sie werden mithilfe von .format() in die Anfragen eingefügt, sodass die Lösungsanfrage eine Zeile wie EMPLOYEE STATUS: identity_verified = {identity_verified} enthalten kann.

2. Grundwahrheit für die Überprüfung

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()

Das Modell entscheidet niemals, ob eine Mitarbeiter-ID gültig ist. verify_identity vergleicht die ID mit EMPLOYEE_DIRECTORY, sodass die Antwort aus einer Abfrage stammt und nicht aus der Meinung des Modells. Ein Normalisierer kümmert sich außerdem um die verschiedenen Schreibweisen derselben ID: 4471, emp4471 und EMP-4471 werden alle vor der Abfrage in ein einheitliches Format gebracht, wodurch gültige IDs nicht aufgrund von Formatierungsunterschieden abgelehnt werden.

3. Werkzeuge

Es gibt zwei Arten von Werkzeugen. Übergangswerkzeuge geben ein Command-Objekt zurück. Dieses schreibt neue Werte in den Workflow-Zustand ein und verschiebt current_step auf die nächste Stufe.

@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",
        }
    )

Die Überprüfung kann vier mögliche Ergebnisse haben. Sie ist nur dann erfolgreich, wenn sowohl die Mitarbeiter-ID als auch der Name des Vorgesetzten mit den im System gespeicherten Daten übereinstimmen. Die anderen drei Ergebnisse entstehen, wenn die maximale Anzahl an Versuchen erreicht ist, eine nicht existierende ID verwendet wird oder eine existierende ID mit dem falschen Vorgesetztennamen angegeben wird. Jeder Fall führt zu einer anderen Meldung. Ein überprüfter Benutzer gelangt zum Schritt issue_diagnosis, während alle anderen Fälle im Schritt identity_verification verbleiben – somit geht nichts weiter, bis die Identität bestätigt ist.

Terminal-Tools geben einen einfachen String zurück und lassen current_step unverändert, da der Workflow seine letzte Stufe erreicht hat.

@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 ist genauso wichtig wie der Klassifikator. Ohne ihn würde der Workflow versuchen, jede Anfrage in einen der unterstützten Problemtypen einzuordnen – auch solche, die nichts miteinander zu tun haben – wodurch ein Problem im Bereich der Privatbanking-Finanzierung fälschlicherweise als IT-Support-Problem gekennzeichnet werden könnte. Das Tool bietet dem Agenten eine klare Möglichkeit, Anfragen außerhalb des Zuständigkeitsbereichs des Workflows zu erkennen.

4. Anfragen und Schrittkonfiguration

Jeder Schritt verfügt über seine eigene Anfrage sowie seine eigene Liste an Tools, die in einem einzigen Wörterbuch gespeichert sind und je nach aktuellen Wert von current_step ausgewählt werden.

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"]},
}

Das Feld requires dient als Schutzmechanismus für das Middleware, das prüft, ob die erforderlichen Bedingungen erfüllt sind, bevor die Konfiguration eines Schritts angewendet wird.

5. Middleware

@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)

Der Name leitet sich davon ab, wo dieser Code ausgeführt wird: zwischen dem aktuellen Workflow-Zustand und dem Aufruf des Modells. Bevor das Modell eine Antwort erstellt, liest das Middleware den Zustand, ersetzt den Prompt sowie die Tools für den aktuellen Schritt und gibt anschließend die Kontrolle weiter. Es wird vor jedem Modellaufruf ausgeführt. Es liest current_step ein, lädt die entsprechende Konfiguration, prüft, ob die erforderlichen Bedingungen erfüllt sind, formatiert den Prompt mit den Werten des aktuellen Zustands und weist die richtigen Tools zu. So ändert sich das Verhalten des Agents, je weiter der Workflow voranschreitet.

6. Aufbau des Agents

agent = create_agent(
    model,
    tools=all_tools,
    state_schema=HelpdeskState,
    middleware=[apply_step_config],
    checkpointer=InMemorySaver(),
)

Der Checkpointer ist unerlässlich, da er den Zustand des Workflows zwischen den Nachrichten aufrechterhält. Ohne ihn wird current_step bei jedem Aufruf zurückgesetzt, wodurch der Agent jedes Mal von dem ersten Schritt aus neu startet und nie weiterkommt.

Entwurfsentscheidungen zur Vermeidung von Fehlern

Es gibt mehrere Details, die dazu dienen, häufige Fehler in dieser Art von Workflow zu verhindern.

  1. Die Überprüfung prüft ein echtes Datensatz. Würde verify_identity die Frage an das Modell richten, ob eine ID und ein Managername plausibel erscheinen, würden alle möglichen Antworten als gültig durchgehen. Das Abfragen der EMPLOYEE_DIRECTORY beseitigt das Raten.
  2. IDs werden vor dem Abgleich normalisiert. Die Anforderung nach einem exakten Format wie EMP-4471 würde gültige Eingaben wie 4471 oder emp4471 allein aufgrund der Eingabemethode ablehnen. Der Normalisierer wandelt zunächst die gängigen Formate in eine einheitliche Normform um.
  • Der Klassifikator verfügt über einen „Keines davon“-Ausgang. record_issue_type akzeptiert nur drei Kategorien. Ohne flag_out_of_scope würden unverwandte Anfragen wie eine Bankfrage in die nächstgelegene Kategorie eingeteilt.
  • Die CLI-Ausgangsprüfung vergleicht ein Wort. Ein einfacher Test wie user_input in {"quit", "exit"} funktioniert nur, wenn die gesamte Nachricht genau eines dieser Wörter ist. Ein Regex für Wortgrenzen erkennt sie überall in einem Satz, auch in Ausdrücken wie „quit and exit“.
  • In jedem Fall scheint die einfachste Implementierung in Ordnung zu sein, versagt aber bei realistischem Eingabetext.

    Zusammenfassung des Musters

    Die Übertragung zwischen einzelnen Agenten benötigt nur drei Komponenten. Ein Feld current_step enthält den aktuellen Zustand, Werkzeuge ändern diesen, und Middleware bezieht sich darauf vor jedem Aufruf des Modells. Gemeinsam steuern sie den Fortschritt des Workflows. Korrektes Verhalten ergibt sich jedoch aus den Details: Überprüfung anhand echter Datensätze, Normalisierung von IDs, Bereitstellung eines Ausweichpfads außerhalb des Aufgabengebiets sowie richtige Verarbeitung von Abschlussbegriffen. Die Zustandsmaschine kontrolliert die Reihenfolge des Workflows, während die Validierungslogik sicherstellt, dass jeder Schritt ordnungsgemäß funktioniert.