deepagents: xây agent AI đa bước — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về langchain-ai/deepagents — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: deepagents: xây agent AI đa bước — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Deep Agents là agent harness mã nguồn mở cho Python, giúp tạo agent AI có thể lập kế hoạch, dùng công cụ, đọc ghi file, chia việc cho sub-agent và ghi nhớ qua nhiều phiên. README có lệnh cài nhanh bằng uv; bạn cần tự cấu hình một mô hình ngôn ngữ hỗ trợ tool calling.
Deep Agents là một agent harness mã nguồn mở cho Python. Repo cung cấp sẵn một agent có định hướng rõ ràng để xử lý công việc dài, nhiều bước, thay vì buộc bạn tự lắp từng phần như lập kế hoạch, quản lý ngữ cảnh và gọi công cụ.
Repo phù hợp với dev muốn xây trợ lý nghiên cứu, agent xử lý tài liệu, agent tự động hóa công việc văn phòng hoặc hệ thống AI dùng trong sản phẩm. Điểm đáng giá nhất là bạn có thể dùng ngay các khả năng quan trọng, rồi thay mô hình, công cụ, bộ nhớ, sandbox hoặc sub-agent theo nhu cầu mà không cần fork toàn bộ dự án.
Deep Agents hoạt động với mọi mô hình ngôn ngữ có hỗ trợ tool calling. Nó được xây trên LangGraph nên có nền tảng cho streaming, persistence và checkpointing. Khi đưa vào môi trường thật, bạn có thể kết hợp LangSmith để tracing, đánh giá và triển khai.
langchain-ai/deepagents
Deep Agents là bộ khung agent AI Python có sẵn lập kế hoạch, đọc ghi file, chia việc và quản lý ngữ cảnh.
I.Deep Agents làm được gì
Deep Agents cung cấp một bộ khung tương đối đầy đủ cho những agent phải làm việc lâu và qua nhiều bước. Bạn không chỉ gửi một câu hỏi rồi nhận câu trả lời. Agent có thể lập kế hoạch, gọi công cụ, lưu kết quả trung gian và tự điều chỉnh cách làm.
A.Lập kế hoạch cho công việc nhiều bước
Agent có thể chia một yêu cầu lớn thành các bước nhỏ trước khi thực hiện. Ví dụ, với yêu cầu nghiên cứu một chủ đề, agent có thể lập kế hoạch đọc tài liệu, tổng hợp thông tin rồi viết bản tóm tắt. Điều này hữu ích khi công việc không thể giải quyết tốt bằng một lần gọi mô hình.
B.Giao việc cho sub-agent
Bạn có thể giao một phần nhiệm vụ cho các agent con có ngữ cảnh riêng. Cách này giúp tách các phần việc như nghiên cứu, kiểm tra dữ liệu hoặc viết nội dung. Ngữ cảnh riêng cũng giúp giảm việc một cuộc hội thoại quá dài làm loãng yêu cầu chính.
C.Đọc, ghi, sửa và tìm kiếm trong filesystem
Agent có thể làm việc với file thông qua các backend có thể thay thế. Backend có thể là filesystem cục bộ, sandbox hoặc hệ thống từ xa. Với người làm văn phòng, khả năng này phù hợp để xử lý bộ tài liệu. Với dev, nó giúp agent đọc mã nguồn, sửa file hoặc tìm kiếm trong một dự án.
D.Quản lý ngữ cảnh dài
Khi cuộc hội thoại và kết quả từ công cụ trở nên dài, Deep Agents có thể tóm tắt các phần cũ và đưa kết quả công cụ ra đĩa. Nhờ vậy, agent có thêm cách giữ thông tin quan trọng mà không phải nhồi toàn bộ dữ liệu vào một lần gọi mô hình.
E.Chạy lệnh trong sandbox
Deep Agents hỗ trợ shell access. Bạn có thể chọn sandbox phù hợp để giới hạn nơi agent được phép chạy lệnh. Đây là nền tảng hữu ích cho agent lập trình hoặc các quy trình cần gọi chương trình bên ngoài.
F.Ghi nhớ qua nhiều phiên
Bộ nhớ bền vững có thể dùng các state backend và store backend có thể thay thế. Khi cấu hình đúng, agent có thể sử dụng thông tin từ những phiên trước thay vì bắt đầu lại hoàn toàn ở mỗi lần chạy.
G.Có người duyệt trước khi gọi công cụ
Tính năng human-in-the-loop cho phép người dùng phê duyệt, chỉnh sửa hoặc từ chối một lần gọi công cụ trước khi nó chạy. Đây là lớp kiểm soát quan trọng khi agent có quyền sửa file, chạy lệnh hoặc thao tác với dữ liệu thật.
H.Nạp skills khi cần
Skills là các hành vi có thể tái sử dụng mà agent nạp theo nhu cầu. Bạn có thể tổ chức quy tắc hoặc cách làm cho từng loại nhiệm vụ, rồi để agent sử dụng chúng khi phù hợp.
I.Tự mang công cụ hoặc dùng MCP server
Deep Agents cho phép bạn đưa vào các hàm riêng của ứng dụng hoặc kết nối bất kỳ MCP server nào. Vì vậy, agent có thể được mở rộng để làm việc với hệ thống nội bộ, dữ liệu doanh nghiệp hoặc dịch vụ bên ngoài mà không phải thay đổi toàn bộ harness.
II.Cần chuẩn bị gì
README chỉ rõ Deep Agents là thư viện Python và lệnh cài đặt dùng uv. Bạn cần một môi trường Python có thể cài thư viện bằng uv. README không nêu phiên bản Python tối thiểu, vì vậy không nên tự suy đoán một phiên bản cụ thể.
Bạn cần một mô hình ngôn ngữ hỗ trợ tool calling. README cho biết có thể dùng mô hình từ các API frontier như OpenAI, Anthropic và Google, mô hình open-weight được lưu trữ qua các nhà cung cấp như Baseten hoặc Fireworks, hoặc mô hình tự chạy qua Ollama, vLLM hay llama.cpp.
Bạn cũng cần cấu hình quyền truy cập tương ứng với mô hình bạn chọn. Phần README được cung cấp không ghi tên biến môi trường hay cách đặt API key cụ thể cho từng nhà cung cấp. Hãy xem tài liệu của mô hình và phần tài liệu Deep Agents trước khi chạy.
README không yêu cầu GPU cụ thể. Tuy nhiên, nếu bạn tự chạy mô hình qua Ollama, vLLM hoặc llama.cpp thì phần phần cứng còn phụ thuộc vào chính mô hình và cách triển khai bạn chọn.
Nếu muốn dùng các khả năng như file, shell, bộ nhớ bền vững hoặc MCP, bạn cần tự chuẩn bị backend và công cụ tương ứng. README xác nhận các điểm mở rộng này tồn tại nhưng không cung cấp đầy đủ cấu hình chi tiết trong nội dung được gửi.
Deep Agents tuân theo mô hình “tin tưởng LLM”. Agent có thể làm mọi việc mà các tool của nó cho phép. Hãy giới hạn quyền ở cấp tool và sandbox, không trông chờ mô hình tự kiểm soát hoàn toàn.
III.Cài đặt từng bước
- Chuẩn bị môi trườngMở terminal trong môi trường Python có uv
- Cài thư việnThêm gói deepagents bằng uv
- Tạo agentGọi create_deep_agent với mô hình và system prompt
- Chạy thửGửi một yêu cầu qua agent.invoke
- Mở rộngThêm tool, đổi model hoặc cấu hình sub-agent
A.Chuẩn bị terminal và dự án
Mở terminal tại thư mục dự án Python mà bạn muốn dùng Deep Agents. README không đưa ra lệnh tạo môi trường hay khởi tạo dự án, nên phần này phụ thuộc vào cách bạn đang quản lý dự án Python.
Nếu bạn lấy mã nguồn để xem ví dụ hoặc phát triển tiếp, có thể clone repo bằng lệnh phổ thông sau:
git clone https://github.com/langchain-ai/deepagents.git
cd deepagentsLệnh đầu tiên tải mã nguồn về thư mục deepagents. Lệnh thứ hai chuyển terminal vào thư mục đó. Nếu mục tiêu của bạn chỉ là dùng thư viện, README hướng dẫn cài bằng uv add deepagents, không bắt buộc phải clone repo.
B.Cài gói Deep Agents
Chạy lệnh cài đặt được README cung cấp:
uv add deepagentsLệnh này thêm gói deepagents vào dự án bằng uv. Bạn cần chạy nó trong đúng thư mục dự án. Lỗi thường gặp ở bước này là mở terminal sai thư mục hoặc chưa cài uv. README không ghi lệnh cài uv, nên hãy xem tài liệu của uv nếu máy chưa có công cụ này.
C.Tạo agent tối giản
Sau khi thêm thư viện, tạo một file Python trong dự án và đặt đoạn mã tối giản theo README:
from deepagents import create_deep_agent
agent = create_deep_agent(
model="openai:gpt-6-astra",
system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})create_deep_agent tạo agent với cấu hình mặc định đã bao gồm các khả năng cho công việc dài và nhiều bước. Tham số model chỉ ra mô hình cần dùng. Ví dụ trong README dùng openai:gpt-6-astra, nhưng bạn có thể dùng mô hình khác nếu mô hình đó hỗ trợ tool calling.
system_prompt mô tả vai trò của agent. Trong ví dụ, agent được giao vai trò trợ lý nghiên cứu. Bạn nên thay câu này bằng vai trò phù hợp với công việc thật, chẳng hạn trợ lý xử lý tài liệu hoặc người kiểm tra mã nguồn.
agent.invoke gửi yêu cầu đến agent. Trường messages trong ví dụ chứa yêu cầu nghiên cứu LangGraph và viết bản tóm tắt. Kết quả được lưu vào biến result để chương trình tiếp tục xử lý hoặc hiển thị.
README không ghi tên file chạy, lệnh chạy file Python hay cách cấu hình key cho OpenAI. Vì vậy, không nên tự thêm một lệnh chạy hoặc biến môi trường cụ thể rồi coi đó là hướng dẫn chính thức. Hãy dùng cấu hình của nhà cung cấp mô hình bạn chọn và xem tài liệu liên quan nếu lần gọi đầu tiên báo lỗi xác thực.
D.Thêm công cụ và thay đổi cấu hình
Sau khi chạy được ví dụ cơ bản, bạn có thể mở rộng agent bằng cách thêm tool riêng, đổi model, tùy chỉnh prompt, cấu hình sub-agent hoặc thay các thành phần mặc định. README xác nhận các điểm mở rộng này nhưng không đưa ra đoạn mã cụ thể cho từng trường hợp.
Nếu bạn cần kết nối dịch vụ theo chuẩn MCP, hãy kiểm tra file .mcp.json và phần tài liệu trong repo. Đây là file khai báo cách chạy có trong cấu trúc gốc của repo. Nội dung được cung cấp chưa có cấu hình cụ thể trong file này, nên bạn không nên tự bịa tên server, tham số hay đường dẫn.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra cơ bản là chương trình có thể import create_deep_agent, tạo agent và gọi agent.invoke mà không gặp lỗi cài đặt hoặc xác thực mô hình.
Bạn cũng có thể kiểm tra kết quả bằng cách xem biến result sau lần gọi. Theo README, agent sẽ có khả năng lập kế hoạch, đọc và ghi file, đồng thời quản lý ngữ cảnh. Với yêu cầu mẫu, kết quả mong đợi là phản hồi liên quan đến việc nghiên cứu LangGraph và viết bản tóm tắt.
Nếu lỗi xuất hiện trước khi agent bắt đầu xử lý, hãy kiểm tra lần lượt: gói deepagents đã được thêm vào đúng dự án chưa, terminal có đang ở đúng thư mục không, mô hình có hỗ trợ tool calling không và thông tin xác thực của nhà cung cấp đã được cấu hình chưa.
README không nêu một màn hình kiểm tra riêng, một chuỗi kết quả cố định hoặc một lệnh test độc lập cho người dùng cuối. Các ví dụ trong thư mục examples/ là nơi phù hợp để xem những mẫu agent đang hoạt động.
V.Dùng vào việc thật
A.Chủ shop cần tổng hợp thông tin sản phẩm
Một chủ shop có nhiều file mô tả sản phẩm và muốn tạo bản tóm tắt dễ đọc cho nhân viên. Bạn có thể tạo agent với system prompt yêu cầu đóng vai trợ lý nghiên cứu, sau đó giao nhiệm vụ đọc các file liên quan và viết bản tổng hợp. Khả năng filesystem giúp agent làm việc với tài liệu, còn quản lý ngữ cảnh giúp xử lý một yêu cầu dài hơn một lần hỏi đáp thông thường.
Prompt có thể bắt đầu như sau:
Đọc các tài liệu sản phẩm được cung cấp, lập kế hoạch xử lý, sau đó viết bản tóm tắt gồm đặc điểm chính, điểm khác nhau và thông tin còn thiếu.Kết quả mong đợi là một bản tổng hợp từ các tài liệu mà agent được cấp quyền đọc. Bạn cần giới hạn agent chỉ được truy cập thư mục tài liệu cần thiết.
B.Nhân viên văn phòng muốn chuẩn bị báo cáo
Nhân viên văn phòng có thể dùng agent để gom thông tin từ nhiều file, tóm tắt nội dung và soạn bản nháp báo cáo. Nếu yêu cầu có nhiều phần, agent có thể lập kế hoạch trước rồi xử lý lần lượt. Bạn có thể giao phần nghiên cứu hoặc kiểm tra cho sub-agent để tách ngữ cảnh.
Một yêu cầu mẫu:
Lập kế hoạch xử lý bộ tài liệu này. Tách phần tổng hợp dữ liệu và phần kiểm tra thiếu sót thành các nhiệm vụ riêng, sau đó viết bản nháp báo cáo ngắn gọn.Kết quả là bản nháp và danh sách vấn đề cần người dùng kiểm tra. Nếu agent có quyền ghi file, nên yêu cầu nó tạo bản nháp riêng thay vì ghi đè tài liệu gốc.
C.Dev muốn kiểm tra một dự án mã nguồn
Dev mới có thể dùng Deep Agents làm trợ lý đọc mã nguồn. Agent có thể tìm kiếm file, đọc cấu trúc, lập kế hoạch kiểm tra và đề xuất thay đổi. Với tác vụ cần chạy lệnh, shell access cho phép agent làm việc trong sandbox được cấp.
Bạn có thể giao yêu cầu như sau:
Đọc cấu trúc dự án, tìm phần xử lý lỗi liên quan đến chức năng đăng nhập, lập kế hoạch kiểm tra và báo cáo các file cần xem trước khi sửa.Nếu muốn agent sửa mã, hãy bật quyền ở mức tối thiểu và dùng human-in-the-loop để duyệt các lần gọi công cụ trước khi chúng chạy. Kết quả có thể là báo cáo, thay đổi trong file được phép hoặc danh sách đề xuất tùy quyền bạn cấp.
D.Nhóm phát triển xây agent chuyên biệt
Một nhóm dev có thể bắt đầu bằng Deep Agents rồi thay từng thành phần khi yêu cầu tăng lên. Nhóm có thể đưa vào tool nội bộ, kết nối MCP server, đổi mô hình hoặc thêm skills cho các quy trình lặp lại. Nếu đã có một CompiledStateGraph của LangGraph, README cho biết graph đó có thể được truyền vào như một sub-agent của Deep Agent.
Cách này phù hợp khi nhóm muốn có một harness dùng được ngay nhưng vẫn cần giữ khả năng tùy biến. Bạn có thể bắt đầu từ agent mặc định, đo chất lượng, rồi thay đúng phần cần thay vì xây toàn bộ vòng lặp agent từ đầu.
Một agent tốt không chỉ trả lời; nó cần biết lập kế hoạch, dùng công cụ và giữ được ngữ cảnh của công việc.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Chưa cài được gói bằng uv
Nếu uv add deepagents không chạy, hãy kiểm tra bạn đã cài uv chưa và terminal có đang ở thư mục dự án đúng không. README chỉ cung cấp lệnh thêm gói, chưa ghi hướng dẫn cài uv, nên hãy tham khảo tài liệu của uv thay vì tự đổi tên gói hoặc dùng một cờ chưa được xác nhận.
B.Mô hình không hỗ trợ tool calling
Deep Agents yêu cầu mô hình hỗ trợ tool calling. Nếu mô hình chỉ tạo văn bản mà không gọi được công cụ, các khả năng như filesystem, shell hoặc sub-agent có thể không hoạt động đúng. Hãy đổi sang một LangChain chat model có hỗ trợ tool calling hoặc kiểm tra lại khả năng của nhà cung cấp.
C.Sai hoặc thiếu thông tin xác thực
README không nêu biến môi trường API key cụ thể. Khi lỗi xác thực xảy ra, hãy kiểm tra tài liệu của nhà cung cấp mô hình bạn chọn và bảo đảm key được cấp cho đúng tiến trình chạy. Không đưa key trực tiếp vào file mã nguồn hoặc commit key vào repo.
D.Agent có quyền quá rộng
Agent có thể làm bất kỳ điều gì mà tool cho phép. Nếu cấp quyền đọc toàn bộ máy, ghi đè file hoặc chạy shell không giới hạn, một yêu cầu sai có thể gây hậu quả lớn. Hãy dùng sandbox, giới hạn thư mục, giới hạn tool và bật phê duyệt thủ công cho thao tác nhạy cảm.
E.Kết quả dài làm agent mất ngữ cảnh
Công việc nhiều bước có thể tạo ra nhiều kết quả trung gian. Deep Agents có cơ chế tóm tắt thread và đưa output của tool ra đĩa, nhưng hiệu quả còn phụ thuộc cấu hình và backend. Hãy chia nhiệm vụ rõ ràng, dùng sub-agent cho phần việc độc lập và yêu cầu agent ghi kết quả trung gian vào nơi được kiểm soát.
VII.Có nên dùng không
Bạn nên chọn Deep Agents nếu muốn xây agent Python có sẵn lập kế hoạch, quản lý ngữ cảnh, filesystem, sub-agent, skills và human-in-the-loop. Repo cũng phù hợp khi bạn muốn dùng nhiều loại mô hình, từ API thương mại đến mô hình open-weight hoặc mô hình tự chạy, miễn là chúng hỗ trợ tool calling.
Điểm mạnh là thiết kế “batteries-included” nhưng vẫn cho phép thay thế từng thành phần. Nền tảng LangGraph bổ sung các khả năng phù hợp cho hệ thống production, còn LangSmith có thể dùng cho tracing, đánh giá và theo dõi.
Giới hạn là README không phải tài liệu cài đặt đầy đủ cho mọi nhà cung cấp mô hình, hệ điều hành hoặc backend. Bạn vẫn phải tự cấu hình xác thực, sandbox, filesystem, bộ nhớ và MCP theo hệ thống của mình. Vì agent có thể làm mọi việc mà tool cho phép, việc thiết kế quyền là phần bắt buộc chứ không phải bước phụ.
Nếu bạn chỉ cần một agent nhẹ với ít middleware, README khuyên dùng create_agent của LangChain. Nếu cần tự thiết kế vòng lặp hoặc dạng đồ thị khác, hãy dùng LangGraph trực tiếp. Deep Agents phù hợp nhất khi bạn muốn có full harness cho công việc dài, có lập kế hoạch, quản lý ngữ cảnh và delegation ngay từ đầu.
Câu hỏi thường gặp
Deep Agents có miễn phí không?
Repo có giấy phép MIT và là dự án mã nguồn mở. Tuy nhiên, README không nói chi phí của mô hình, nhà cung cấp API, LangSmith hoặc hạ tầng sandbox; các khoản đó có thể phụ thuộc cấu hình bạn chọn.
Có cần GPU không?
README không yêu cầu GPU cụ thể. Bạn có thể dùng các mô hình qua API hoặc mô hình tự chạy như Ollama, vLLM và llama.cpp; nếu tự chạy mô hình thì phần cứng còn phụ thuộc vào mô hình và cách triển khai.
Có chạy được trên Windows không?
README được cung cấp không nêu hệ điều hành được hỗ trợ và không có hướng dẫn riêng cho Windows. Vì vậy chưa có đủ thông tin để khẳng định quy trình Windows cụ thể.
Deep Agents khác LangChain và LangGraph thế nào?
LangGraph là graph runtime, còn LangChain `create_agent` là agent harness tối giản trên đó. Deep Agents là lớp harness có định hướng hơn, gói sẵn lập kế hoạch, quản lý ngữ cảnh, delegation, filesystem và skills.
Có dùng được mô hình local không?
Có. README nói mọi mô hình hỗ trợ tool calling đều có thể dùng, gồm mô hình tự chạy qua Ollama, vLLM hoặc llama.cpp.
Dữ liệu có an toàn không?
README cảnh báo Deep Agents theo mô hình “tin tưởng LLM”: agent có thể làm mọi việc mà tool cho phép. Bạn cần thực thi giới hạn ở cấp tool và sandbox, đồng thời kiểm soát quyền đọc, ghi và chạy lệnh.
Có thể dùng Deep Agents trong production không?
Có. README cho biết Deep Agents được xây trên LangGraph và hướng tới triển khai production; có thể kết hợp LangSmith cho tracing, đánh giá và monitoring. Cách triển khai cụ thể cần xem hướng dẫn production.


