Enseñar nuevas habilidades a los Deep Agents: planificación, subagentes y archivos SKILL.md
Cómo los DeepAgents de LangChain combinan la planificación, los subagentes, la memoria del sistema de archivos y la carga progresiva de habilidades, junto con un plan de desarrollo, consejos de pruebas y notas de despliegue.
La IA agente se refiere a sistemas compuestos por varios agentes que colaboran entre sí para dividir un problema largo y complejo, intercambiar información y trabajar como un pequeño equipo de especialistas. Un chatbot solitario responde a una sola pregunta. Un sistema agente necesita planificación, memoria y uso de herramientas para poder llevar a cabo una tarea a través de numerosos pasos. El aprendizaje por refuerzo es el enfoque clásico para agentes que aprenden mediante la prueba y el error: una red profunda observa el entorno, elige acciones como llamadas a herramientas o ejecución de código, y recibe recompensas que orientan su estrategia. El aprendizaje profundo por refuerzo ha generado rendimientos sobrehumanos en el Go y el ajedrez, además de resultados sólidos en robótica, todo ello al maximizar la recompensa acumulativa esperada. Aplicar estas ideas a agentes impulsados por LLM plantea una posibilidad interesante: agentes que adquieren rutinas o habilidades reutilizables y luego planifican y ejecutan con menos esfuerzo.
¿Qué hace que un agente sea “profundo”?
Los agentes profundos amplían las capacidades de un asistente LLM con cuatro funciones:
- Una herramienta de planificación que divide el trabajo complejo en pasos.
- Subagentes para trabajar en paralelo y aislar el contexto.
- Un sistema de archivos persistente que funciona también como memoria.
- Un prompt de sistema detallado que incluye objetivos y restricciones.
Juntos, estos elementos permiten que un agente planifique, mantenga el estado y ejecute flujos de trabajo complicados sin saturar su contexto de prompt. Un chatbot superficial responde una sola vez. Un agente profundo repite el proceso: planifica, busca, guarda los resultados, los sintetiza y los perfecciona. Si se le pide un informe, podría crear una lista de tareas, realizar búsquedas en la web o análisis, almacenar notas en archivos, y luego redactar y revisar el documento, todo impulsado por el modelo sin intervención humana.
Aprendizaje por refuerzo y de dónde provienen las habilidades
El RL es la base para los agentes que aprenden al actuar. El agente observa un estado, realiza una acción y recibe una recompensa o una penalización; al maximizar la suma esperada de recompensas futuras, mejora su política. Se diferencia del aprendizaje supervisado, que cuenta con etiquetas, y del aprendizaje no supervisado, que busca estructuras ocultas, ya que se ocupa de decisiones secuenciales bajo incertidumbre. El RL profundo utiliza redes neuronales como aproximadores de funciones para poder manejar imágenes, texto y datos sensoriales en bruto. Entre los hitos más conocidos se encuentran las redes Deep Q-Networks para Atari y los métodos de gradiente de política como PPO y A2C para juegos de control continuo y estrategia. Los trabajos más recientes exploran el aprendizaje jerárquico de habilidades, en el cual los agentes descubren opciones, es decir, acciones extendidas en el tiempo que resuelven subobjetivos, lo cual facilita la exploración y la transferencia de conocimientos.
Para los agentes de LLM, el RL desempeña dos funciones. Una es el ajuste fino del propio modelo con señales de retroalimentación. Por ejemplo, el RLHF ha alineado los modelos para que sean más seguros y estén más relacionados con el tema. DeepSeek-R1 demostró que el RL puro, sin datos etiquetados, puede entrenar un modelo de razonamiento capaz de competir con los sistemas más avanzados en matemáticas y código: el modelo genera varias respuestas, un sistema de puntuación automático recompensa las correctas y penaliza al resto, y a lo largo de muchas rondas un algoritmo como PPO mejora la política de toma de decisiones. Los pipelines reales pueden añadir ajuste fino supervisado y muestreo de rechazo para mejorar la legibilidad y la seguridad.
El otro rol se encuentra a nivel del marco de los agentes, donde los métodos inspirados en el RL pueden ayudar a adquirir habilidades. Un agente podría registrar las trayectorias de sus acciones (qué herramientas se utilizaron, qué resultados se obtuvieron) y enviarlas al RL offline o al aprendizaje por imitación para extraer procedimientos reutilizables. Al analizar éxitos y fracasos anteriores, podría comprimir secuencias de herramientas que se repiten con frecuencia en rutinas de nivel superior. Esas rutinas, escritas como archivos de script o instrucciones en formato markdown, pueden revelarse gradualmente al agente en tareas posteriores. El sistema adquiere una forma de aprendizaje continuo: al enfrentarse a algo nuevo, aprende una habilidad al instante y la almacena como un módulo.
Cómo se construye la biblioteca DeepAgents
La biblioteca DeepAgents de LangChain convierte estas ideas en una herramienta lista para su uso en entornos reales, con una arquitectura diseñada para agentes de múltiples pasos como Claude Code y Manus.
- Planificación con
write_todos. Una herramienta integrada permite al agente elaborar una lista paso a paso antes de actuar. Esta lista guía el trabajo y puede modificarse a medida que llega nueva información. - Sistema de archivos y memoria. Las herramientas de archivos (
ls,read_file,write_file,edit_file) permiten al agente guardar el contexto en archivos o bases de datos. Al almacenar los resultados intermedios y las notas se evita el desbordamiento de la ventana de contexto y se puede volver a consultar los pasos anteriores. Un backend intercambiable, ya sea en memoria, en disco local, en almacenamiento en la nube o en un entorno aislado, se encarga de la persistencia y de la ejecución segura del código.
task integrada genera asistentes especializados, como un subagente de investigación o uno de crítica. Cada uno funciona en su propio contexto, lo que mantiene al agente principal organizado, y puede tener su propio prompt del sistema y herramientas. El agente principal puede encargar búsquedas en la web o análisis de código y recibir resúmenes a cambio. Un subagente de uso general simplemente replica la configuración del agente principal cuando lo que se desea es solo aislamiento.SKILL.md y, opcionalmente, scripts o documentos. Las habilidades difieren de las herramientas porque no se cargan completamente en el prompt. Solo el frontmatter en formato YAML (nombre, descripción, etiquetas) entra en el contexto, y las instrucciones completas se revelan progresivamente cuando el agente decide que son relevantes. Esto reduce drásticamente el uso de tokens. Una habilidad en PDF podría incluir un tutorial largo que el agente solo lee cuando la tarea del usuario involucra PDFs. Las habilidades distribuyen conocimientos y procedimientos por distintos agentes, y estos incluso pueden crear nuevas definiciones de habilidades a medida que se enfrentan a tareas nuevas.Debido a este diseño, los agentes profundos rinden mucho mejor que los superficiales en problemas largos y de múltiples pasos. Ellos planifican con antelación, utilizan la memoria, aprenden de la experiencia y gestionan contextos extensos. Los informes del sector indican que las tareas de los agentes se están volviendo cada vez más complejas, con una longitud que se duplica aproximadamente cada pocos meses, y es precisamente aquí donde estas características son cruciales. La evolución consiste en pasar de responder consultas aisladas a resolver problemas de forma autónoma.
Desarrollo paso a paso
El plan que se presenta a continuación combina la arquitectura de agentes con ideas de aprendizaje por refuerzo, allí donde son aplicables. Utiliza Python y el SDK DeepAgents. Comience instalando las bibliotecas y configurando el entorno:
# Install deepagents and necessary tools
!pip install --upgrade deepagents langchain tavily-python
# Import libraries and set API keys (e.g., for LLM and search tool)
import os
from getpass import getpass
os.environ["OPENAI_API_KEY"] = getpass("OpenAI API Key: ")
os.environ["TAVILY_API_KEY"] = getpass("Tavily API Key: ")
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from deepagents.middleware.filesystem import FileData
from langchain.chat_models import init_chat_model
from tavily import TavilyClient
Definir el agente y sus habilidades
A continuación viene el agente avanzado con sus herramientas y cualquier habilidad predefinida. Para entornos de producción, un backend duradero, como el disco local o LangGraph, es una mejor opción que la memoria efímera. Esta versión utiliza un FilesystemBackend ubicado en el directorio actual y carga las carpetas de habilidades:
from deepagents import create_deep_agent
# Assume we have local skill directories under "./skills"
skill_dirs = ["./skills/pdf_processing", "./skills/data_analysis"]
agent = create_deep_agent(
model=model,
system_prompt="""
You are a highly capable AI assistant. Your objectives:
1. Break tasks into steps using write_todos().
2. Use internet_search and file tools to gather and store information.
3. When given a task, plan and execute it step-by-step, writing to files as needed.
4. Load skills from the filesystem to handle specialized tasks when relevant.
5. Summarize results and refine final output before returning.
""",
tools=[internet_search], # Web search tool
backend=FilesystemBackend(root_dir="./workspace"), # Persistent file storage
skills=skill_dirs, # Load skills from local directories
)
La instrucción del sistema enfatiza la planificación y el uso de habilidades. El parámetro skills apunta a directorios cuyas subcarpetas contienen cada una un archivo SKILL.md además de archivos de soporte. Por ejemplo, ./skills/pdf_processing/SKILL.md podría enseñarle al agente cómo analizar PDFs. Con las habilidades cargadas de esta manera, el agente inicialmente solo ve nombres y descripciones. Cuando la tarea de un usuario involucra PDFs, lee el archivo SKILL.md relevante y cualquier archivo a él referenciado para aprender el procedimiento.
Un ejemplo de estructura:
skills/
├── pdf_processing/
│ └── SKILL.md
└── data_analysis/
├── SKILL.md
└── analysis_script.py
Y un posible pdf_processing/SKILL.md:
---
name: pdf-processing
description: Skill to extract and analyze content from PDF documents.
---
# PDF Processing Skill
To use this skill, follow these steps:
1. Use `pdf-tools` to read PDF content.
2. Summarize key findings from the PDF text.
...
Las instrucciones completas solo se leen si el agente decide que la solicitud actual concierne a PDFs. Eso es lo que significa la divulgación progresiva: los archivos grandes con muchas instrucciones no sobrecargan cada solicitud.
Así es un proceso
Ahora dele al agente una tarea compleja. La solicitud inicial lo induce a elaborar un plan primero.
from langchain.schema import HumanMessage
query = "Organize the latest quarterly sales data and write a summary report."
response = agent.invoke({
"messages": [HumanMessage(content=query)]
})
print(response["messages"][-1]["content"])
Conceptualmente, el agente probablemente realizará lo siguiente:
- Llamará a
write_todos()para generar una lista de verificación, como cargar el archivo de ventas, crear gráficos, calcular totales y escribir el informe. - Realizará llamadas a herramientas, utilizando
internet_searcho lecturas de archivos integradas para recopilar datos existentes. - Posiblemente asignará la limpieza o el análisis a un subagente cuando la tarea requiera un procedimiento especializado.
- Usará habilidades. Si existe una habilidad de análisis de datos, podría leer
SKILL.mddesde./skills/data_analysisy seguir sus instrucciones. - Guardará los artefactos intermedios, como los conjuntos de datos limpiados o los gráficos, en el sistema de archivos.
- Escribirá y pulirá el resumen final.
Una ejecución completa llama a los LLM remotos, por lo que la verificación aquí se centra principalmente en asegurar que la estructura sea correcta. El código elige un backend fiable, envuelve los pasos riesgosos en bloques try/except (una versión completa debe capturar errores de API y de archivos) y puede ampliarse con middleware de registro. Las pruebas unitarias para cada herramienta, con las respuestas del LLM simuladas, servirían para validarlo.
Pruebas y evaluación
Los flujos de trabajo de los agentes se evalúan sobre todo mediante juicio. La comprobación consiste en determinar si el agente completa las tareas correctamente y se adhiere a su plan. Un enfoque utiliza tareas sintéticas con respuestas conocidas: se le da un pequeño proyecto matemático y se compara el informe final con la solución. También son útiles las métricas automatizadas, como la tasa de éxito de las tareas (si cada paso se completó) o la similitud con una respuesta de referencia evaluada por un juez basado en LLM. El texto de formato libre podría seguir necesitando revisión humana o crítica basada en modelos para la decisión final.
Si se utiliza el aprendizaje por refuerzo para el aprendizaje de habilidades, se puede medir el progreso mediante curvas de recompensa. Crea un entorno en el que completar subtareas genere una recompensa y gráfica la recompensa total por episodio, quizás utilizando OpenAI Gym o una configuración personalizada. Las métricas importantes son la eficiencia de muestreo (qué tan rápido converge el aprendizaje), el rendimiento final y la estabilidad con diferentes semillas aleatorias. En la práctica, también se ejecutaría un conjunto de tareas en áreas como investigación, programación y análisis, registrando la tasa de éxito y el uso de tokens para cada una.
La observabilidad es esencial en entornos de producción. Equipe al agente con funciones de seguimiento y registro, ya que LangSmith puede capturar cada llamada a las herramientas y respuesta del LLM. En un sistema desplegado, los registros pueden enviarse a CloudWatch o Prometheus con información sobre el número de pasos, la latencia por llamada y los errores. Para los componentes de RL, registre la historia de recompensas, las curvas de pérdida y los hiperparámetros. Las pruebas de estrés con lotes grandes, sesiones prolongadas e inputs inusuales ayudan a confirmar la estabilidad.
Desplegándolo como servicio
En un despliegue real, el agente funciona como un microservicio. Una estructura escalable se ve así:
+------------------+ +--------------+
| Client/User | <--> | API Gateway | <---> [HTTP requests]
+------------------+ +------+-------+
|
v
+-------------+
| AgentCore | <-- AWS Bedrock AgentCore (managed runtime)
+-------------+
|
+-------------+-------------+
| |
+-------------------+ +-------------------+
| Deep Agent Service | | Storage (S3/DB) | <-- File/memory backend, logs
+-------------------+ +-------------------+
| |
+-------------+-------------+
|
+---------------+
| LLM Models | <-- e.g., OpenAI, Anthropic, local LLMs
+---------------+
Un servicio de agente en AWS AgentCore o algo similar recibe instrucciones, coordina subagentes y realiza llamadas a herramientas, siendo que cada interacción se registra en un almacenamiento persistente para fines de observabilidad y memoria. Algunos aspectos del diseño destacan.
- Escalabilidad y fiabilidad. Ejecutar el agente en un entorno sin servidores o contenerizado como AWS Bedrock AgentCore, Azure AI Agent Service o Kubernetes. Escala según la carga y inicia instancias nuevas por cada solicitud, y cada sesión puede ejecutarse en su propia micro-VM. Un backend persistente (S3, una base de datos o el almacén LangGraph) mantiene el estado y la memoria a través de los reinicios.
- Observabilidad. Haga un seguimiento de cada llamada. En AWS, el kit de inicio Bedrock AgentCore conecta CloudWatch y X-Ray para monitorear la latencia y los fallos. Al registrar hashes de las solicitudes y respuestas en lugar de los datos sensibles en bruto, sigue siendo posible rastrear el rendimiento, así como el uso de tokens, el número de llamadas a la API y las tasas de éxito.
- Seguridad. Limite lo que puede acceder el agente. Las herramientas del sistema de archivos deben funcionar únicamente dentro de directorios designados, y la ejecución de código bajo el backend
sandboxdebe realizarse en entornos reforzados como Modal o Daytona. Asigne a los recursos en la nube a los que accede el agente roles IAM de mínimo privilegio, y agregue validación de entrada y filtrado de contenido a través de verificaciones de seguridad de LLM contra solicitudes maliciosas. - Costo. Equilibrio entre el modelo y las opciones del backend. Un modelo de Anthropic más económico puede encargarse de tareas rutinarias, mientras que un modelo de alta gama como GPT-4o se utiliza para los pasos de planificación que son cruciales. Al transferir el contexto a la memoria y reutilizar los resultados de las herramientas, se reducen los tokens de solicitud repetidos.
Un ejemplo completo
Este ejemplo en Python implementa el plan, con manejo de errores y comentarios. Es conceptual y necesita claves API reales además de un entorno para ejecutarse.
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from deepagents.middleware.filesystem import FileData
from langchain.chat_models import init_chat_model
from tavily import TavilyClient
import os
def setup_agent():
"""Initialize the Deep Agent with tools, skills, and system prompt."""
# Model and tools initialization
model = init_chat_model(model="openai:gpt-4o")
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def web_search(query: str, max_results: int = 3) -> str:
results = tavily_client.search(query, max_results=max_results)
return "\n".join(f"{r.title}: {r.summary}" for r in results)
# Create the deep agent with planning, files, and skills
try:
agent = create_deep_agent(
model=model,
tools=[web_search],
system_prompt="""You are an expert agent. Your workflow:
1. Create a plan with write_todos().
2. Use tools (e.g. web_search) and file system to research and work.
3. If specialized tasks arise, load relevant skills from the 'skills' directory.
4. Save results and refine the output at each step.
""",
backend=FilesystemBackend(root_dir="./workspace"),
skills=["./skills/pdf_processing", "./skills/data_analysis"]
)
return agent
except Exception as e:
print(f"Error initializing agent: {e}")
raise
def invoke_agent(agent, user_query):
"""Invoke the agent on a user query and return the final answer."""
try:
messages = [{"role": "user", "content": user_query}]
result = agent.invoke({"messages": messages})
return result["messages"][-1]["content"]
except Exception as e:
print(f"Agent invocation failed: {e}")
return None
# Example usage
if __name__ == "__main__":
agent = setup_agent()
task = "Analyze the recent research on climate change and summarize key findings."
answer = invoke_agent(agent, task)
print("Agent response:", answer)
La creación e invocación de agentes se realizan mediante funciones con strings de documentación y bloques try/except. La herramienta web_search utiliza Tavily para obtener datos externos, y el prompt del sistema indica al agente que planifique, utilice sus habilidades y perfeccione su salida. Una versión en producción verificaría casos límite como resultados de búsqueda vacíos y tiempos de espera de la API, además de registrar los detalles de las excepciones en lugar de imprimirlos. Los secretos deben almacenarse en un entorno seguro, no en el código fuente. La estructura se puede expandir naturalmente con más herramientas o subagentes.
Para validarlo adecuadamente, es necesario escribir pruebas unitarias. Se debe simular al LLM para que devuelva una salida de planificador fija y comprobar que el agente escriba los archivos esperados o llame a las herramientas en el orden correcto. También se debe medir la latencia de inferencia y el costo en tokens en tareas de referencia.
Compromisos a considerar
Los agentes avanzados combinan la planificación, la memoria, la delegación de subagentes y habilidades cargables para manejar tareas de múltiples pasos que los chatbots simples no pueden realizar. Una instrucción de sistema clara, un flujo de trabajo centrado en la planificación y una amplia gama de herramientas proporcionan una base sólida para asistentes autónomos. Las habilidades albergan conocimientos modulares, como pdf-processing o deploy-to-prod, que se cargan según sea necesario para mantener un contexto ligero y permitir que el agente siga aprendiendo.
- Exactitud frente al costo. Los modelos potentes como GPT-4o o Claude Sonnet, sumados a búsquedas exhaustivas, mejoran la precisión pero aumentan los gastos por tokens y API. Combinar tamaños de modelo y usar caché ayuda a equilibrar calidad y costo.
- Escalabilidad frente a la complejidad. Un entorno de ejecución de agentes sin servidores como AWS AgentCore ofrece capacidad de escalado automático y capacidad de observación, pero se requiere trabajo de integración: contenerizar el código del agente y configurar la red.
De cara al futuro, la adquisición de habilidades en sí podría automatizarse: el aprendizaje por refuerzo o el aprendizaje no supervisado a partir de trayectorias anteriores podría generar nuevas definiciones de habilidades. Los marcos multiagente como Microsoft AutoGen o Salesforce AgentForce podrían coordinar a varios agentes especializados que comunican entre sí mediante protocolos LangGraph.
Para crear un agente que aprenda habilidades se necesitan dos cosas: el conjunto de software adecuado y, si se desea, técnicas de aprendizaje por refuerzo que lo mejoren con el tiempo. Con DeepAgents y una ingeniería rigurosa, se pueden desarrollar asistentes capaces de resolver problemas complejos por sí mismos, aprender nuevos procedimientos y funcionar de manera fiable a gran escala.
Leer más
- Flujos de trabajo multi-agente de LangGraph: Comparación entre enjambre y supervisor — Divida un flujo de trabajo de LangGraph en subagentes con puntos de control, luego cree un asistente financiero tanto como enjambre como supervisor, y observe dónde falla cada patrón.
- Triaje de tiquetes de soporte multi-agente con LangGraph y Ollama — Construya un grafo de triaje de tiquetes con tres agentes usando LangGraph: un clasificador, un respondiente y un control humano, que funcione con Ollama local o mediante una API, con solo una línea modificada.