Transferencias entre agentes únicos en LangChain: Creación de un flujo de trabajo para el servicio de soporte técnico.
Un agente de LangChain que cambia su prompt y sus herramientas en cada paso: un servicio de soporte técnico por fases con verificaciones reales de identidad, transferencias de middleware y una salida cuando el tema está fuera del alcance.
Imagínese llamando al servicio de soporte de TI después de quedar bloqueado de su cuenta. La persona al otro lado de la línea no hace las mismas preguntas en cada etapa, y lo que puede hacer depende de en qué punto se encuentra la llamada. Primero confirman la identidad, generalmente a través de un número de empleado o el nombre de un supervisor, y no abordan el problema de la cuenta hasta que eso se resuelve. Luego averiguan cuál es el problema: una cuenta bloqueada, una contraseña olvidada o un dispositivo de autenticación faltante. Solo después de eso toman medidas, como reactivar la cuenta, enviar un enlace de restablecimiento o transferir la llamada al equipo de seguridad. Para quien llama, parece ser una sola conversación, aunque su alcance cambia a medida que avanza la llamada.
Las transiciones le dan al agente de IA la misma estructura. El agente modifica lo que puede hacer según la etapa actual de la interacción. Al principio, solo recopila detalles de identificación. Una vez hecho eso, pregunta sobre el problema real y, una vez que el problema queda claro, toma medidas.
Dos formas de construirlo
- Tipo 1, el enfoque de middleware, utiliza un único agente cuyos permisos cambian a medida que avanza la conversación. Imagínese al mismo empleado del servicio de atención al cliente trabajando siguiendo una lista de verificación.
- Tipo 2, el enfoque de múltiples agentes, emplea varios agentes que pasan la conversación entre sí, como cuando se transfiere un caso a otro departamento cuando la primera persona no puede ayudar.
La implementación que se muestra a continuación sigue el tipo 1, a menudo denominado de agente único, ya que el código contiene exactamente un agente. Ese agente verifica la identidad, luego diagnostica el problema y finalmente lo resuelve. En ningún momento aparece un nuevo agente. Lo que cambia son sus instrucciones y su conjunto de herramientas al comenzar cada etapa. El tipo 2 difiere al crear agentes separados y gestionar la conversación entre ellos.
El proyecto
El objetivo es un agente de servicio de asistencia técnica, y en el código se aplican tres reglas:
- No se discute ningún problema de cuenta hasta que la identidad del usuario se verifica contra un registro real.
- No se toma ninguna acción hasta que el problema pertenezca a una de las tres categorías admitidas.
- Cuando el problema no encaja en ninguna de ellas, el agente lo indica en lugar de adivinarlo.
Ejemplo de ejecución
Un usuario se pone en contacto con el servicio de soporte después de quedar bloqueado de su cuenta corporativa. El agente solicita el número de identificación del empleado y el nombre del gerente. El primer intento no coincide con ningún registro de empleado, por lo que el agente vuelve a preguntar, y el segundo intento confirma la información. Luego el agente pregunta sobre el problema. El usuario menciona primero una cuenta personal de banca en línea, que el agente identifica correctamente como fuera del alcance del servicio. Después de que el usuario aclara que el problema está relacionado con el portal de TI de la empresa, el agente lo clasifica como una cuenta bloqueada, restablece el acceso y finaliza la conversación una vez que se confirma que la solicitud se ha resuelto.
Desglose del código
1. Esquema de estados
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"]]
El campo current_step determina qué entrada de STEP_CONFIG dará forma a la próxima respuesta, un punto que se aborda nuevamente en la sección 4. Otros tres campos (identity_verified, verification_attempts y issue_type) almacenan la información recopilada hasta el momento por la conversación. Se insertan en los mensajes de solicitud mediante .format(), de modo que el mensaje de resolución pueda incluir una línea como ESTADO DEL EMPLEADO: identity_verified = {identity_verified}.
2. Verdad objetiva para la verificación
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()
El modelo nunca decide si un ID de empleado es válido. verify_identity compara el ID con EMPLOYEE_DIRECTORY, por lo que la respuesta proviene de una búsqueda y no de la opinión del modelo. Un normalizador también se ocupa de las diferentes formas en que las personas escriben el mismo ID: 4471, emp4471 y EMP-4471 se convierten todos a un mismo formato antes de la búsqueda, lo que evita que los IDs válidos sean rechazados por cuestiones de formato.
3. Herramientas
Existen dos tipos de herramientas. Las herramientas de transición devuelven un objeto Command. Este escribe nuevos valores en el estado del flujo de trabajo y avanza current_step a la siguiente etapa.
@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 verificación tiene cuatro resultados posibles. Solo tiene éxito cuando tanto el ID del empleado como el nombre del supervisor coinciden con el registro. Los otros tres resultados son alcanzar el número máximo de intentos, utilizar un ID que no existe y asignar un ID existente con el nombre del supervisor incorrecto. Cada caso genera un mensaje diferente. Un usuario verificado pasa a la etapa issue_diagnosis, mientras que los demás resultados permanecen en identity_verification; por lo tanto, nada avanza hasta que se confirme la identidad.
Las herramientas de terminal devuelven una cadena de texto simple y dejan current_step sin cambios, ya que el flujo de trabajo ha llegado a su última etapa.
@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 es tan importante como el clasificador. Sin él, el flujo de trabajo intentaría asignar cada solicitud a uno de los tipos de problemas soportados, incluso aquellos no relacionados, por lo que un problema relacionado con la banca personal podría ser etiquetado erróneamente como un problema de soporte informático. La herramienta brinda al agente una forma clara de reconocer las solicitudes que están fuera del alcance del flujo de trabajo.
4. Preguntas guía y configuración de pasos
Cada etapa tiene su propia pregunta guía y su propia lista de herramientas, las cuales se almacenan en un único diccionario y se seleccionan según el valor actual 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"]},
}
El campo requires funciona como una protección para el middleware, ya que verifica que se cumplan las condiciones necesarias antes de aplicar la configuración de un paso.
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)
El nombre proviene del lugar donde se ejecuta este código: entre el estado actual del flujo de trabajo y la llamada al modelo. Antes de que el modelo genere una respuesta, el middleware lee el estado, sustituye el prompt y las herramientas por los correspondientes al paso actual y luego transfiere el control. Se ejecuta antes de cada llamada al modelo. Lee current_step, carga la configuración correspondiente, verifica que se cumplan las condiciones requeridas, formatea el prompt con los valores del estado actual y asigna las herramientas adecuadas. Así es como cambia el comportamiento del agente a medida que avanza el flujo de trabajo.
6. Construcción del agente
agent = create_agent(
model,
tools=all_tools,
state_schema=HelpdeskState,
middleware=[apply_step_config],
checkpointer=InMemorySaver(),
)
El marcador de posición es esencial porque mantiene el estado del flujo de trabajo entre mensajes. Sin él, current_step se reinicia en cada llamada, y el agente comienza de nuevo desde el primer paso cada vez, sin avanzar nunca.
Elecciones de diseño que evitan errores
Existen varios detalles para prevenir fallos comunes en este tipo de flujo de trabajo.
- La verificación examina un registro real. Si
verify_identityhiciera la pregunta al modelo para determinar si un ID y el nombre del supervisor parecían correctos, cualquier respuesta plausible pasaría la validación. ConsultarEMPLOYEE_DIRECTORYelimina la posibilidad de conjeturas. - Los IDs se normalizan antes de la comparación. Exigir un formato exacto como EMP-4471 rechazaría entradas válidas como 4471 o emp4471 únicamente por la forma en que se escribieron. El normalizador convierte primero los formatos comunes en una forma canónica.
- El clasificador cuenta con una opción de salida “ninguna de estas”.
record_issue_typesolo acepta tres categorías. Sinflag_out_of_scope, las solicitudes no relacionadas, como una pregunta sobre banca, se verían obligadas a incluirse en la categoría más cercana. - La verificación de salida de la CLI coincide con una palabra. Una prueba sencilla como
user_input in {"quit", "exit"}solo funciona cuando todo el mensaje es exactamente una de esas palabras. Una expresión regular basada en los límites entre palabras las detecta en cualquier lugar de la oración, incluyendo frases como “quit and exit”.
En cada caso, la implementación más simple parece funcionar bien, pero falla con entradas reales.
El patrón en resumen
Las transferencias entre agentes individuales solo necesitan tres componentes. Un campo current_step almacena la etapa actual, las herramientas lo modifican y el middleware lo consulta antes de cada llamada al modelo. Juntos determinan cómo avanza el flujo de trabajo. Sin embargo, el comportamiento correcto depende de los detalles: verificar contra un registro real, normalizar los IDs, ofrecer una ruta fuera del alcance y manejar adecuadamente las palabras de salida. La máquina de estados controla el orden del flujo de trabajo, mientras que la lógica de validación se asegura de que cada paso funcione correctamente.