Accueil / Articles

Transferts entre agents uniques dans LangChain : création d’un flux de travail pour un service client informatique.

Un agent LangChain qui modifie son prompt et ses outils à chaque étape : un service d’assistance informatique en plusieurs étapes avec des vérifications d’identité réelles, des transferts via du middleware et une sortie en cas de dépassement des limites.

Éditeur : REACTAPP.TOP7 min de lecture1587 mots

Sources: How to Build an AI Agent With LangChain Handoffs

Imaginez qu’on appelle un service d’assistance informatique après s’être retrouvé bloqué hors d’un compte. La personne au bout du fil ne pose pas les mêmes questions à chaque étape, et ce qu’elle peut faire dépend du stade atteint par l’appel. D’abord, elle vérifie l’identité, généralement à l’aide d’un numéro d’employé ou du nom d’un manager, et elle n’interviendra pas sur le problème du compte tant que cela n’aura pas été résolu. Ensuite, elle découvre ce qui ne va pas : un compte verrouillé, un mot de passe oublié ou un dispositif d’authentification manquant. Ce n’est qu’après cela qu’elle agit, en réactivant le compte, en envoyant un lien de réinitialisation ou en transférant l’appel à l’équipe de sécurité. Pour l’appelant, cela ressemble à une seule conversation, bien que son champ d’action évolue au fur et à mesure que l’appel avance.

Les transitions confèrent à un agent IA la même structure. Cet agent modifie ce qu’il est autorisé à faire en fonction de l’étape actuelle de l’interaction. Au début, il ne collecte que des informations d’identification. Une fois cela fait, il interroge sur le véritable problème, et une fois celui-ci clairement identifié, il prend des mesures.

Deux façons de le concevoir

  • Type 1, l’approche par middleware, utilise un seul agent dont les permissions changent au fur et à mesure que la conversation avance. Pensez à un même employé du service d’assistance qui suit une liste de contrôle.
  • Type 2, l’approche multi-agents, utilise plusieurs agents qui se transmettent la conversation les uns aux autres, un peu comme lorsqu’on est transféré à un autre service lorsque la première personne ne peut pas aider.

La configuration présentée ci-dessous suit le type 1, souvent appelé agent unique, car le code contient exactement un agent. Cet agent vérifie l’identité, diagnostique ensuite le problème et le résout. Aucun nouvel agent n’apparaît à aucun moment. Ce qui change, c’est ses instructions et son ensemble d’outils au début de chaque étape. Le type 2 diffère en créant des agents distincts et en gérant la conversation entre eux.

Le projet

La cible est un agent de service d’assistance informatique, et trois règles sont appliquées dans le code :

  • Aucun problème de compte n’est abordé tant que l’identité de l’utilisateur n’a pas été vérifiée contre un enregistrement réel.
  • Aucune action n’est entreprise tant que le problème ne relève pas de l’une des trois catégories prises en charge.
  • Lorsque le problème ne correspond à aucune de ces catégories, l’agent le mentionne plutôt que de deviner.

Un exemple de fonctionnement

Un utilisateur contacte le service d’assistance après avoir été bloqué sur son compte d’entreprise. L’agent demande un numéro d’employé ainsi que le nom du manager. La première tentative ne correspond à aucun dossier d’employé, alors l’agent demande à nouveau, et la deuxième tentative confirme l’identité. Ensuite, l’agent interroge sur le problème. L’utilisateur évoque d’abord un compte bancaire en ligne personnel, que l’agent identifie correctement comme ne relevant pas de sa compétence. Lorsque l’utilisateur précise que le problème concerne le portail informatique de l’entreprise, l’agent le classe comme un compte verrouillé, restaure l’accès et termine la conversation une fois la demande confirmée résolue.

Décortiquage du code

1. Schéma d’états

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

Le champ current_step détermine quelle entrée de STEP_CONFIG façonne la réponse suivante, un point abordé à nouveau dans la section 4. Trois autres champs (identity_verified, verification_attempts et issue_type) stockent les informations recueillies jusqu’à présent dans la conversation. Ils sont insérés dans les prompts à l’aide de .format(), de sorte que le prompt de résolution peut contenir une ligne telle que EMPLOYEE STATUS: identity_verified = {identity_verified}.

2. Vérité de référence pour la vérification

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

Le modèle ne décide jamais si un identifiant d’employé est valide. verify_identity compare l’identifiant avec EMPLOYEE_DIRECTORY, de sorte que la réponse provient d’une recherche et non de l’opinion du modèle. Un normaliseur s’occupe également des différentes façons dont les gens tapent le même identifiant : 4471, emp4471 et EMP-4471 sont tous transformés en un seul format avant la recherche, ce qui évite que des identifiants valides ne soient rejetés en raison de leur formatage.

3. Outils

Il existe deux types d’outils. Les outils de transition renvoient un objet Command. Celui-ci écrit de nouvelles valeurs dans l’état du flux de travail et fait avancer current_step à l’étape suivante.

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

La vérification peut avoir quatre résultats possibles. Elle réussit uniquement lorsque tant l’ID du employé que le nom du manager correspondent aux données enregistrées. Les trois autres résultats sont l’atteinte du nombre maximal d’essais, l’utilisation d’un ID inexistant, ou l’attribution d’un ID existant avec un nom de manager incorrect. Chaque cas génère un message différent. Un utilisateur vérifié passe à l’étape issue_diagnosis, tandis que tous les autres résultats restent dans identity_verification ; rien ne progresse tant que l’identité n’a pas été confirmée.

Les outils de terminal renvoient une chaîne de caractères simple et laissent current_step inchangé, car le flux de travail a atteint sa dernière étape.

@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 est tout aussi important que le classificateur. Sans lui, le flux de travail tenterait d’attribuer chaque demande à l’un des types de problèmes pris en charge, y compris ceux qui ne sont pas liés, ce qui pourrait faire que des problèmes bancaires personnels soient mal étiquetés comme des demandes d’assistance informatique. Cet outil permet à l’agent de reconnaître facilement les demandes hors du champ d’application du flux de travail.

4. Prompts et configuration des étapes

Chaque étape dispose de son propre prompt ainsi que de sa propre liste d’outils, stockés dans un seul dictionnaire et sélectionnés en fonction de la valeur actuelle de 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"]},
}

Le champ requires agit comme une protection pour le middleware, qui vérifie que les conditions nécessaires sont remplies avant d’appliquer la configuration d’une étape.

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)

Le nom provient du lieu où ce code s’exécute : entre l’état actuel du flux de travail et l’appel au modèle. Avant que le modèle ne produise une réponse, le middleware lit l’état, remplace le prompt et les outils par ceux correspondant à l’étape actuelle, puis transmet le contrôle. Il s’exécute avant chaque appel au modèle. Il lit current_step, charge la configuration correspondante, vérifie que les conditions requises sont remplies, formate le prompt en utilisant les valeurs de l’état actuel et attribue les bons outils. C’est ainsi que le comportement de l’agent change au fur et à mesure que le flux de travail avance.

6. Construction de l’agent

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

Le pointeur de contrôle est essentiel car il conserve l’état du flux de travail entre les messages. Sans lui, current_step est réinitialisé à chaque appel, et l’agent redémarre à la première étape à chaque fois sans jamais progresser.

Choix de conception pour éviter les erreurs

Plusieurs détails permettent de prévenir les échecs fréquents dans ce type de flux de travail.

  1. La vérification examine un enregistrement réel. Si verify_identity posait la question au modèle pour savoir si un identifiant et un nom de manager semblaient corrects, tout ce qui semblait plausible serait accepté. La consultation de EMPLOYEE_DIRECTORY élimine les suppositions.
  2. Les identifiants sont normalisés avant la comparaison. Exiger un format précis comme EMP-4471 rejeterait des entrées valables telles que 4471 ou emp4471 simplement en raison de la manière dont elles ont été saisies. Le normaliseur convertit d’abord les formats courants en une forme canonique.
  3. Le classificateur dispose d’une option « aucun de ces choix ». record_issue_type ne prend en compte que trois catégories. En l’absence de flag_out_of_scope, les demandes non pertinentes, comme une question bancaire, seraient forcées d’être classées dans la catégorie la plus proche.
  4. Vérification de la sortie via la CLI : recherche d’un mot précis. Un test simple tel que user_input in {"quit", "exit"} ne fonctionne que lorsque le message entier correspond exactement à l’un de ces mots. Une expression régulière basée sur les frontières des mots permet de les détecter n’importe où dans une phrase, y compris dans des expressions comme « quit and exit ».

Dans chaque cas, l’implémentation la plus simple semble fonctionner, mais échoue avec des entrées réalistes.

En bref, le schéma

Les transferts entre agents uniques nécessitent seulement trois éléments. Un champ current_step indique l’étape en cours, les outils le modifient, et le middleware le consulte avant chaque appel au modèle. Ensemble, ils déterminent le déroulement du flux de travail. Un comportement correct dépend néanmoins des détails : vérification contre un enregistrement réel, normalisation des identifiants, proposition d’une voie hors champ et correspondance adéquate des mots de sortie. La machine à états contrôle l’ordre du flux de travail, tandis que la logique de validation s’assure que chaque étape fonctionne correctement.