LangChain @dynamic_prompt para instrucciones de sistema conscientes de la tarea
Un agente de LangChain HR intercambia las solicitudes del sistema de licencias, beneficios y administración por el middleware @dynamic_prompt del contexto en tiempo de ejecución, mientras que la autorización permanece en el código.
El decorador @dynamic_prompt de LangChain construye el prompt del sistema a partir del contexto en tiempo de ejecución en lugar de una cadena fija incluida en la definición del agente.
Úsalo siempre que las instrucciones deban cambiar según la tarea actual, el rol, el usuario, la etapa del flujo de trabajo o la configuración de la aplicación, sin necesidad de crear un agente separado para cada variante.
Ejemplo concreto: un asistente de recursos humanos se encarga de permisos y asistencia, beneficios para empleados y administración de recursos humanos. La misma instancia del agente cambia sus instrucciones del sistema según el área que haya seleccionado el usuario. El modelo sigue viendo una sola conversación; solo cambia el preámbulo del sistema, que es invisible.
Contexto en tiempo de ejecución vs autorización
El contexto de ejecución son los datos que la aplicación proporciona para esta invocación: claves de tarea, configuración regional, nivel del plan y flags de funcionalidades. @dynamic_prompt lee ese conjunto de datos y devuelve el prompt del sistema para la próxima llamada al modelo.
No se trata de un mecanismo de control de acceso. Las verificaciones de permisos deben realizarse en la capa de la aplicación o dentro de las herramientas. El decorador solo determina qué debe hacer el modelo. Mezclar estos dos aspectos es un error común: un prompt que dice “eres un administrador” no otorga acceso a las API de administrador.
Situaciones prácticas en las que es útil
- Paquetes de instrucciones específicas para tareas en un agente compartido
- Tono, profundidad o ejemplos adaptados al rol
- SaaS multiinquilino con textos de políticas diferentes para cada cliente
- Etapas del flujo de trabajo que requieren reglas diferentes a lo largo de la sesión
- Flags de funcionalidades que modifican el comportamiento del modelo sin necesidad de volver a desplegar agentes
Guía paso a paso: Asistente de recursos humanos con tres tareas
Tareas mostradas en la interfaz de usuario:
- Permisos y asistencia
- Beneficios para empleados
- Administración de recursos humanos
Rol: empleado o administrador. Los permisos y beneficios están disponibles para ambos; la administración solo es accesible para administradores. Esa división es importante a la hora de decidir dónde colocar los controles de acceso.
1. Definir el objeto de contexto
UserContext contiene campos que la aplicación completa cuando se ejecuta el agente. task determina qué bloque de instrucciones devuelve @dynamic_prompt. role es verificado por la aplicación antes de que se invoque al agente para tareas administrativas. Excluir el rol del generador de prompts facilita la auditoría de la seguridad.
2. Construir el prompt dinámicamente
@dynamic_prompt
def hr_dynamic_prompt(request):
user = request.runtime.context
if user.task == "leave":
return """
You are an HR assistant responsible for Leave and Attendance.
Help the user with questions about:
- Leave types
- Leave balances
- Leave application
- Leave carry-forward
- Attendance
Answer only within the Leave and Attendance area.
Keep the response clear and concise.
"""
elif user.task == "benefits":
return """
You are an HR assistant responsible for Employee Benefits.
Help the user with questions about:
- Health insurance
- Employee benefits
- Wellness programs
- Company benefit programs
Answer only within the Employee Benefits area.
Keep the response clear and concise.
"""
elif user.task == "admin":
return """
You are an HR Administration assistant.
Help the user with administrative HR processes such as:
- Employee onboarding
- Employee offboarding
- HR documentation
- Employee records
- Administrative procedures
Answer only within the HR Administration area.
Keep the response clear and concise.
"""
return """
You are a general HR assistant.
Answer the user's question clearly and concisely.
"""
El decorador marca la función como middleware. LangChain pasa la solicitud del modelo; usted obtiene request.runtime.context. Cuando task es "leave", devuelva instrucciones para irse; cuando es "benefits", devuelva una copia de la información sobre beneficios; cuando es "admin", devuelva orientación para la administración. Un único grafo de agentes, múltiples prompts del sistema, sin conexiones duplicadas de herramientas.
3. Conecte el modelo y el agente una sola vez
El mismo modelo de chat y el mismo agente sirven para cada tarea. Registre hr_dynamic_prompt como middleware para que LangChain lo invoque justo antes del paso del modelo. Las herramientas, la memoria y las funciones de callback se mantienen compartidas; solo cambia el prefijo inicial.
4. Asocie las opciones de la interfaz con las claves de tarea
Un menú sencillo asocia las etiquetas visibles para el usuario con claves estables:
1 → leave 2 → benefits 3 → admin
Esas claves se convierten en el campo task del objeto de contexto. Las claves estables son importantes: el texto de la interfaz puede cambiar sin necesidad de reescribir la función de prompt.
5. Autorizar fuera del decorador
La verificación de administradores tiene lugar antes de que se ejecute agent.invoke. Si un empleado elige Administración de RR. HH., se debe detener el proceso de inmediato mostrando un error claro. Los prompts dinámicos modifican las instrucciones, pero no determinan los derechos de acceso. Coloque la lógica de denegación en el código de la aplicación, donde ya se encuentran los registros y las métricas.
6. Pasar el contexto a la llamada de invoke
context=UserContext(
user_name="Nachiket",
role="admin",
task="leave"
)
Durante el paso del modelo, @dynamic_prompt detecta task="leave" y devuelve el prompt correspondiente al sistema de permisos. La pregunta del usuario sigue transmitiéndose como un mensaje normal de usuario. El contexto y el historial de chat permanecen completamente separados.
7. Mostrar la respuesta
print("\nAssistant:")
print(result["messages"][-1].content)
El contenido del último mensaje del agente es lo que se imprime en la consola o se muestra en la interfaz de usuario. Desde aquí se pueden agregar transmisiones en tiempo real, citas o rastros de llamadas a herramientas sin cambiar el middleware de prompts dinámicos.
Por qué este patrón es escalable
Se evita clonar agentes para cada interfaz de producto. Las instrucciones permanecen junto a la función del middleware, por lo que quienes redactan el contenido pueden editarlo en un solo lugar. Los roles y permisos se mantienen en el código de la aplicación, donde primero se realizan las revisiones de seguridad. El modelo siempre recibe un prompt adaptado al canal actual, sin necesidad de codificar manualmente tres agentes separados o tres implementaciones distintas.
Lecturas relacionadas
- Herramientas Gate Agent por Usuario con LangChain Wrap Middleware — Un agente calculador, tres niveles de acceso: el middleware de tipo wrap sobrescribe la lista de herramientas según el user_type en tiempo de ejecución en lugar de clonar tres agentes.
- Parar Herramientas Condicionalmente: Artifacts Vencen a return_direct en LangGraph — Detener/continuar por llamada basado en los artefactos de las herramientas: middleware ReAct y create_agent desarrollados manualmente, cuando return_direct estático no puede tomar una decisión.