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à harness mã nguồn mở cho agent AI đa bước, được đóng gói sẵn các khả năng như lập kế hoạch, dùng công cụ, quản lý file, bộ nhớ và sub-agent. Repo phù hợp với người muốn xây agent có cấu trúc mà không phải tự lắp từng thành phần. Cài đặt cơ bản khá ngắn bằng uv, nhưng việc chọn model và cấu hình môi trường cần đọc thêm tài liệu dự án.
Deep Agents là một harness mã nguồn mở bằng Python giúp bạn tạo agent AI có thể xử lý công việc dài, nhiều bước ngay từ đầu. Thay vì chỉ gửi một câu hỏi cho mô hình rồi nhận câu trả lời, agent có thể lập kế hoạch, gọi công cụ, đọc và ghi file, chia việc cho agent phụ, rồi tự quản lý ngữ cảnh trong quá trình làm.
Repo này dành cho lập trình viên muốn xây trợ lý nghiên cứu, agent xử lý tài liệu, công cụ tự động hóa nội bộ hoặc coding agent. Người mới cũng có thể bắt đầu từ đoạn Quickstart rất ngắn. Điểm đáng giá nhất là bạn có một bộ khung đã tích hợp sẵn nhiều khả năng thường phải tự xây: filesystem, shell, bộ nhớ lâu dài, human-in-the-loop, skills và MCP.
Deep Agents được thiết kế theo hướng có thể mở rộng. Bạn dùng mặc định có sẵn, ghi đè từng phần hoặc thay hẳn một thành phần mà không cần fork toàn bộ repo. Nó cũng không khóa vào một nhà cung cấp model cụ thể, miễn là model bạn chọn hỗ trợ tool calling.
langchain-ai/deepagents
Framework Python giúp tạo agent AI có lập kế hoạch, dùng công cụ, đọc ghi file, quản lý ngữ cảnh và phối hợp sub-agent.
I.Deep Agents làm được gì
A.Tạo agent có sẵn bộ khung xử lý công việc dài
Deep Agents cung cấp một agent có quan điểm thiết kế rõ ràng cho các nhiệm vụ nhiều bước. Agent không chỉ trả lời một lượt mà có thể lập kế hoạch, tiến hành từng phần và điều chỉnh cách làm khi cần.
Điều này hữu ích khi bạn muốn xây trợ lý nghiên cứu, trợ lý phân tích tài liệu hoặc một quy trình tự động hóa có nhiều thao tác nối tiếp. Bạn không phải tự viết toàn bộ vòng lặp điều phối từ đầu.
B.Giao việc cho sub-agent
Agent chính có thể ủy thác những phần việc riêng cho các sub-agent. Mỗi agent phụ có ngữ cảnh được tách riêng, giúp công việc chuyên biệt không làm đầy cửa sổ ngữ cảnh của agent chính.
Ví dụ, một agent có thể giao việc tìm thông tin cho agent nghiên cứu, giao việc kiểm tra file cho agent khác, rồi tổng hợp kết quả cuối cùng. Cách này phù hợp với nhiệm vụ lớn cần chia nhỏ.
C.Đọc, ghi, sửa và tìm kiếm file
Deep Agents có filesystem để làm việc với file. Backend filesystem có thể là cục bộ, sandbox hoặc từ xa, tùy cách bạn cấu hình.
Với người làm văn phòng, khả năng này phù hợp cho việc xử lý một thư mục tài liệu. Với lập trình viên, agent có thể đọc mã nguồn, tìm file liên quan, chỉnh sửa nội dung và lưu kết quả. Tuy vậy, quyền truy cập thực tế phụ thuộc vào công cụ và sandbox bạn cấp cho agent.
D.Quản lý ngữ cảnh dài
Khi hội thoại hoặc kết quả từ tool quá dài, agent có thể tóm tắt chuỗi trao đổi và đẩy kết quả tool ra file. Nhờ đó, agent không phải giữ toàn bộ dữ liệu trong cửa sổ ngữ cảnh cùng lúc.
Đây là phần quan trọng với những việc như đọc nhiều tài liệu, phân tích một codebase lớn hoặc thực hiện quy trình kéo dài nhiều lượt.
E.Chạy lệnh trong sandbox
Deep Agents hỗ trợ shell access để agent chạy lệnh trong môi trường sandbox bạn chọn. Tính năng này có thể giúp agent kiểm tra file, chạy công cụ xử lý dữ liệu hoặc thực hiện các bước kỹ thuật.
Quyền chạy lệnh cần được giới hạn ở tầng tool hoặc sandbox. Không nên dựa vào việc mô hình tự biết dừng đúng lúc.
F.Ghi nhớ qua nhiều phiên
Repo hỗ trợ persistent memory thông qua các backend state và store có thể thay thế. Agent có thể lưu và truy xuất thông tin giữa các phiên nếu bạn cấu hình backend phù hợp.
Điều này hữu ích cho trợ lý làm việc lâu dài, nhưng dữ liệu được lưu ở đâu, lưu bao lâu và ai có quyền đọc phụ thuộc vào backend bạn chọn.
G.Cho phép con người duyệt tool call
Bạn có thể cấu hình human-in-the-loop để phê duyệt, chỉnh sửa hoặc từ chối một lần gọi tool trước khi nó chạy. Đây là lớp kiểm soát quan trọng khi agent có quyền ghi file, chạy lệnh hoặc thực hiện thao tác có ảnh hưởng.
Trong quy trình doanh nghiệp, bạn có thể cho agent chuẩn bị hành động trước, sau đó yêu cầu nhân viên duyệt ở những bước nhạy cảm.
H.Nạp skills khi cần
Skills là những hành vi có thể tái sử dụng mà agent nạp theo nhu cầu. Thay vì nhồi mọi hướng dẫn vào prompt ban đầu, bạn có thể tổ chức hành vi thành các skill riêng.
Cách này giúp cấu hình agent dễ bảo trì hơn, nhất là khi cùng một agent phải xử lý nhiều loại công việc.
I.Kết nối tool riêng và MCP server
Deep Agents cho phép bạn đưa vào các hàm riêng hoặc dùng MCP server. Nhờ đó, agent có thể kết nối với những hệ thống và quy trình mà bạn tự xây.
Repo cũng được thiết kế để thay thế hoặc ghi đè từng thành phần. Bạn có thể bắt đầu với thiết lập mặc định rồi mở rộng dần khi yêu cầu thực tế tăng lên.
II.Cần chuẩn bị gì
README cho biết Deep Agents là thư viện Python và lệnh cài đặt dùng uv. Repo không nêu một phiên bản Python cụ thể trong phần Quickstart được cung cấp, nên bạn cần xem thêm tài liệu hoặc cấu hình của repo trước khi chọn phiên bản môi trường.
README không nêu hệ điều hành cụ thể. Vì vậy, chưa thể khẳng định đầy đủ cách chạy trên Windows, macOS hay Linux chỉ từ phần tư liệu này.
Bạn cần một model hỗ trợ tool calling. Deep Agents có thể làm việc với model API thương mại, model open-weight được host qua các nhà cung cấp, hoặc model tự host qua Ollama, vLLM hay llama.cpp. README không ghi tên biến môi trường hay cách đặt API key cụ thể cho từng model.
README cũng không yêu cầu GPU riêng. Với model tự host, phần cứng thực tế sẽ phụ thuộc vào model và cách bạn triển khai, nhưng repo không đưa ra thông số phần cứng cụ thể.
Nếu muốn phát triển, debug và triển khai agent, README khuyến nghị dùng LangSmith cho tracing, evaluation và monitoring. Đây là lựa chọn hỗ trợ trong hệ sinh thái, không phải lệnh bắt buộc trong Quickstart.
Agent có thể làm bất cứ điều gì mà các tool được cấp quyền cho phép. Hãy giới hạn quyền ở tool hoặc sandbox, đặc biệt khi cho phép ghi file và chạy shell. Không nên kỳ vọng model tự kiểm soát mọi hành động nguy hiểm.
III.Cài đặt từng bước
- Chuẩn bị môi trườngCài uv và mở terminal tại thư mục làm việc
- Cài thư việnThêm deepagents vào môi trường Python bằng uv
- Tạo agentDùng create_deep_agent với model hỗ trợ tool calling
- Gửi nhiệm vụGọi agent.invoke với một yêu cầu cụ thể
- Mở rộngThêm tool, đổi model, prompt hoặc cấu hình sub-agent
A.Chuẩn bị thư mục làm việc
Bạn mở Terminal hoặc PowerShell tại nơi muốn đặt mã nguồn. Nếu muốn lấy toàn bộ repo để xem ví dụ và mã nguồn, có thể clone repo rồi đi vào thư mục. Đây là lệnh Git phổ thông; README được cung cấp không đưa lệnh clone riêng.
git clone https://github.com/langchain-ai/deepagents.git
cd deepagentsgit clone tải mã nguồn về máy. cd deepagents chuyển terminal vào thư mục repo. Lỗi người mới hay gặp là chạy lệnh ở thư mục không có quyền ghi hoặc gõ sai tên thư mục sau khi clone.
Tuy nhiên, Quickstart của README cài package trực tiếp bằng uv, nên bạn không nhất thiết phải clone repo chỉ để dùng thư viện. README chưa ghi cách cài uv; bạn cần cài công cụ này theo hướng dẫn riêng của uv trước khi chạy lệnh tiếp theo.
B.Cài gói Deep Agents
Chạy đúng lệnh trong README:
uv add deepagentsLệnh này thêm package deepagents vào dự án đang dùng uv. Hãy chạy trong thư mục dự án có thể quản lý dependency bằng uv. Nếu terminal báo không nhận diện uv, vấn đề nằm ở việc uv chưa được cài hoặc chưa có trong PATH; README được cung cấp không có hướng dẫn xử lý lỗi này.
README không ghi phiên bản package cụ thể và cũng không cung cấp lệnh cài bằng pip. Vì vậy, không nên tự thay lệnh trên bằng một tên gói hoặc cờ lệnh khác khi chưa kiểm tra tài liệu tương ứng.
C.Tạo agent tối thiểu
Sau khi cài package, tạo một file Python trong dự án và đưa đoạn Quickstart này vào:
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"})from deepagents import create_deep_agent nạp hàm tạo agent. create_deep_agent tạo một agent với model và system prompt bạn chỉ định.
Giá trị model="openai:gpt-6-astra" là đúng mẫu trong README. Khi dùng thực tế, model phải hỗ trợ tool calling và phải tương thích với cách bạn cấu hình nhà cung cấp model. README không ghi cách đặt thông tin xác thực, nên bạn cần xem tài liệu model tương ứng thay vì tự đoán tên biến môi trường.
system_prompt đặt vai trò chung cho agent. Trong mẫu, agent được yêu cầu đóng vai trợ lý nghiên cứu. agent.invoke gửi một nhiệm vụ qua trường messages; mẫu yêu cầu agent nghiên cứu LangGraph và viết bản tóm tắt.
Người mới hay vấp ở chỗ copy đoạn mã nhưng chưa chuẩn bị model hoặc thông tin xác thực. Nếu lỗi xuất hiện ở bước gọi model, đó có thể là vấn đề cấu hình model chứ không nhất thiết là lỗi cài Deep Agents.
D.Mở rộng agent sau Quickstart
README nói bạn có thể thêm tool riêng, đổi model, tùy biến prompt, cấu hình sub-agent và nhiều thành phần khác. Phần Quickstart không cung cấp đoạn lệnh cụ thể cho từng phần mở rộng.
Vì vậy, sau khi chạy được mẫu tối thiểu, hãy xem các thư mục examples/, libs/ và tài liệu dự án trong repo để tìm mẫu phù hợp. Không nên tự đặt tên hàm, tham số hoặc biến môi trường khi chưa thấy chúng trong tài liệu.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra cơ bản là chạy file Python có đoạn Quickstart. Nếu package được cài đúng, Python có thể import create_deep_agent, tạo agent và tiến hành lời gọi agent.invoke.
Kết quả mong đợi theo README là agent có thể nghiên cứu LangGraph và viết một bản tóm tắt. README không cung cấp output mẫu cụ thể, vì vậy không thể khẳng định chính xác nội dung hoặc định dạng kết quả.
Bạn cũng có thể kiểm tra theo ba dấu hiệu sau:
- Lệnh
uv add deepagentshoàn tất mà không báo lỗi dependency. - Dòng
from deepagents import create_deep_agentkhông gây lỗi import. - Lệnh
agent.invoke(...)gọi được model và trả về kết quả.
Nếu import thành công nhưng lời gọi model thất bại, hãy kiểm tra model có hỗ trợ tool calling và thông tin xác thực của nhà cung cấp. Nếu agent gọi được model nhưng không thể đọc file hoặc chạy lệnh, hãy kiểm tra tool và backend bạn đã cấp; bản thân Quickstart không tự mô tả toàn bộ cấu hình quyền.
V.Dùng vào việc thật
A.Chủ shop cần tổng hợp phản hồi khách hàng
Một chủ shop có thể dùng agent làm trợ lý nghiên cứu. Bạn chuẩn bị các file phản hồi trong một filesystem mà agent được phép đọc, rồi giao nhiệm vụ tổng hợp những phàn nàn lặp lại, nhóm chủ đề và viết bản tóm tắt.
Mẫu nhiệm vụ có thể bắt đầu từ ý tưởng trong README:
result = agent.invoke({"messages": "Research the customer feedback files and write a summary"})Kết quả là một phản hồi do agent tạo ra sau khi dùng khả năng lập kế hoạch và xử lý file được cấu hình. README không quy định định dạng báo cáo hay cách kết nối file cụ thể, nên phần đó cần tùy theo backend và tool bạn thêm.
B.Nhân viên văn phòng xử lý thư mục tài liệu
Một nhân viên có thể giao cho agent việc tìm các file liên quan, đọc nội dung và tạo bản tổng hợp. Agent có filesystem để đọc, viết, sửa và tìm kiếm, còn việc agent được phép chạm vào thư mục nào phụ thuộc vào backend hoặc sandbox.
Bạn có thể đặt system prompt theo vai trò:
agent = create_deep_agent(
model="openai:gpt-6-astra",
system_prompt="You are a document review assistant.",
)Sau đó gửi nhiệm vụ cụ thể qua agent.invoke. Nên giới hạn quyền ghi file nếu agent chỉ cần đọc và tổng hợp. Nếu cần chỉnh sửa tài liệu, hãy dùng human-in-the-loop để duyệt hành động trước khi chạy.
C.Lập trình viên muốn agent nghiên cứu codebase
Dev mới có thể dùng Deep Agents để tạo trợ lý đọc mã nguồn. Agent có thể lập kế hoạch, tìm file, đọc nội dung và viết bản tóm tắt. Với codebase lớn, khả năng quản lý ngữ cảnh giúp đẩy bớt kết quả tool ra file hoặc tóm tắt các luồng trao đổi dài.
Một yêu cầu mẫu:
result = agent.invoke({"messages": "Inspect this codebase and write a summary of its main components"})Đây là ví dụ bám theo khả năng mà README mô tả, không phải một lệnh phân tích codebase có sẵn. Bạn cần cấu hình filesystem và tool phù hợp trước khi giao nhiệm vụ.
D.Nhóm phát triển xây agent chuyên môn
Một nhóm có thể tạo agent chính để phân tích yêu cầu, sau đó giao các phần việc cho sub-agent. Một sub-agent nghiên cứu, một sub-agent kiểm tra dữ liệu, còn agent chính tổng hợp kết quả.
Bạn cũng có thể đưa tool riêng hoặc MCP server vào để kết nối hệ thống nội bộ. Khi một tool có thể thay đổi dữ liệu hoặc chạy lệnh, hãy yêu cầu con người phê duyệt trước.
Một agent tốt không chỉ biết trả lời; nó phải biết chia việc, dùng đúng công cụ và làm việc trong ranh giới bạn cấp.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Terminal báo không tìm thấy uv
Lệnh cài đặt trong README dùng uv. Nếu terminal báo không nhận diện lệnh, hãy kiểm tra uv đã được cài và đã có trong PATH chưa. README không cung cấp hướng dẫn cài uv, nên cần xem tài liệu của uv hoặc môi trường bạn đang dùng.
B.Lỗi import deepagents
Nếu from deepagents import create_deep_agent thất bại, có thể lệnh uv add deepagents được chạy ở một dự án khác với nơi bạn chạy file Python. Hãy kiểm tra terminal đang ở đúng thư mục dự án và môi trường chạy Python đang dùng dependency đó.
C.Model không gọi được tool
Deep Agents yêu cầu model hỗ trợ tool calling. Nếu model không có khả năng này, hãy đổi sang một model được README mô tả là hỗ trợ tool calling, gồm model frontier, open-weight được host hoặc model tự host tương thích.
D.Agent không đọc được file hoặc chạy được lệnh
Filesystem và shell access không có nghĩa là agent tự động được toàn quyền trên máy. Bạn cần cấu hình backend, tool và sandbox phù hợp. Hãy kiểm tra quyền được cấp, đường dẫn làm việc và giới hạn sandbox trước khi mở rộng quyền.
E.Agent thực hiện hành động ngoài dự kiến
README nhấn mạnh mô hình bảo mật “trust the LLM”: agent có thể làm mọi thứ mà tool cho phép. Cách xử lý an toàn là thu hẹp quyền ở tầng tool hoặc sandbox, bật human-in-the-loop cho thao tác nhạy cảm và tránh cấp quyền ghi hoặc chạy lệnh rộng hơn nhu cầu.
VII.Có nên dùng không
Deep Agents đáng dùng khi bạn muốn xây agent xử lý công việc dài và cần nhiều khả năng có sẵn: lập kế hoạch, filesystem, context management, sub-agent, memory, skills, shell và MCP. Nó cũng phù hợp với đội ngũ muốn bắt đầu nhanh nhưng vẫn có đường mở rộng lên tracing, evaluation và deployment qua LangGraph và LangSmith.
Điểm mạnh khác là repo không khóa bạn vào một loại model. Bạn có thể dùng model API, model open-weight hoặc model tự host miễn là hỗ trợ tool calling. Kiến trúc có thể thay thế từng phần nên phù hợp với dự án cần tùy biến.
Giới hạn là Quickstart khá ngắn. README không cung cấp đầy đủ cách cấu hình API key, filesystem, sandbox, memory, sub-agent hay human-in-the-loop. Người mới muốn làm một ứng dụng hoàn chỉnh vẫn phải đọc thêm examples và tài liệu trong repo.
Bạn nên chọn LangChain create_agent nếu chỉ cần một harness nhẹ hơn, không cần toàn bộ middleware đi kèm. Bạn nên chọn LangGraph trực tiếp nếu vòng lặp agent của bạn có hình dạng đặc biệt và cần tự thiết kế graph. Deep Agents phù hợp nhất khi bạn muốn một harness nhiều tính năng chạy được theo hướng tổng quát 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 vậy, README không nói chi phí model, nhà cung cấp model, hạ tầng tự host hoặc dịch vụ đi kèm, nên tổng chi phí sử dụng chưa thể xác định chỉ từ tư liệu này.
Có cần GPU để chạy không?
README không yêu cầu GPU cụ thể. Deep Agents có thể dùng model API, model open-weight được host hoặc model tự host qua Ollama, vLLM và llama.cpp; phần cứng thực tế phụ thuộc vào lựa chọn model và cách triển khai.
Deep Agents có chạy trên Windows không?
README không nêu hệ điều hành được hỗ trợ, nên chưa thể khẳng định cách chạy trên Windows chỉ từ tư liệu đã cung cấp. README chỉ cho biết đây là thư viện Python và Quickstart dùng uv.
Có cần API key không?
Deep Agents cần một model hỗ trợ tool calling, nhưng README không ghi tên biến môi trường hay cách cấu hình API key. Nếu dùng model API, bạn cần xem tài liệu của nhà cung cấp model tương ứng.
Deep Agents khác LangChain và LangGraph thế nào?
Theo README, LangGraph là graph runtime, còn LangChain `create_agent` là harness tối giản. Deep Agents là harness có nhiều quan điểm thiết kế hơn, tích hợp planning, context management, delegation, filesystem, sub-agent và skills; bạn vẫn có thể đưa một LangGraph CompiledStateGraph vào làm sub-agent.
Dữ liệu của agent có an toàn không?
README cảnh báo agent có thể làm mọi điều mà tool được phép làm. Bạn cần thực thi ranh giới ở tool hoặc sandbox, đồng thời có thể dùng human-in-the-loop để duyệt hành động; README không cam kết một chính sách bảo mật dữ liệu cụ thể.


