# deepagents: dựng agent AI làm việc dài hơi, có sẵn đồ nghề — hướng dẫn cài đặt và dùng

> deepagents là một agent harness mã nguồn mở bằng Python, xây trên LangGraph, giúp bạn tạo agent AI làm việc nhiều bước chỉ với vài dòng code. Agent có sẵn khả năng lập kế hoạch, đọc ghi file, chia việc cho sub-agent và tự quản lý ngữ cảnh. Cài đặt khá gọn: một lệnh `uv add deepagents`, nhưng bạn cần biết chút Python.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-19 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/deepagents-agent-ai-lam-viec-dai-hoi-huong-dan-cai-dat

Deep Agents (repo `langchain-ai/deepagents`) là một "agent harness" mã nguồn mở bằng Python. Hiểu đơn giản: đây là một bộ khung dựng sẵn để tạo ra agent AI có thể làm việc nhiều bước, dài hơi, mà bạn không phải tự ráp từng mảnh. Tác giả mô tả nó là "batteries-included", nghĩa là pin đã lắp sẵn, bật lên là chạy.

Nếu bạn từng thử gọi một model AI rồi thấy nó chỉ trả lời một lượt, còn muốn nó tự lên kế hoạch, đọc file, ghi file, chia việc nhỏ cho "trợ lý phụ" thì phải tự code rất nhiều. Deep Agents gói sẵn những thứ đó. Bạn chỉ cần chọn model, viết một câu mô tả vai trò cho agent, rồi giao việc.

Repo hiện có khoảng 31.249 sao và 4.415 fork, giấy phép MIT, và vẫn được cập nhật trong vài tháng gần đây. Điểm đáng giá nhất: nó chạy được với bất kỳ model nào hỗ trợ gọi công cụ (tool calling), từ các dịch vụ lớn đến model mã nguồn mở hay model tự chạy trên máy bạn. Người hợp nhất là lập trình viên, hoặc người đã biết chút Python và muốn tự xây trợ lý AI cho công việc của mình.

```repo
- repo | langchain-ai/deepagents
- kind | Framework
- desc | Deep Agents là bộ khung agent mã nguồn mở của LangChain, có sẵn sub-agent, hệ thống file, quản lý ngữ cảnh và skills, chạy với nhiều loại model.
- stars | 31k
- lang | Python
- license | MIT
```

## Deep Agents làm được gì

README nêu một loạt tính năng. Mình diễn giải theo lợi ích thực tế cho bạn:

- **Sub-agent**: agent chính có thể giao việc cho các agent phụ, mỗi agent phụ có "cửa sổ ngữ cảnh" riêng. Lợi ích: việc phụ không làm rối đầu óc của agent chính, nên việc dài vẫn gọn.
- **Hệ thống file**: agent đọc, ghi, sửa, tìm kiếm file. Nơi chứa file có thể là máy local, môi trường sandbox hoặc nơi từ xa, tùy bạn cắm vào. Lợi ích: agent có "bàn làm việc" để ghi nháp, lưu kết quả trung gian.
- **Quản lý ngữ cảnh**: tự tóm tắt những cuộc trò chuyện dài và đẩy kết quả công cụ ra đĩa. Lợi ích: việc kéo dài nhiều giờ không bị tràn bộ nhớ của model.
- **Chạy lệnh shell**: agent chạy lệnh trong sandbox bạn chọn. Lợi ích: làm được những việc cần thao tác máy, nhưng nằm trong khu vực bạn kiểm soát.
- **Bộ nhớ bền vững**: có các backend lưu trạng thái để agent nhớ giữa các phiên làm việc.
- **Người duyệt từng bước (human-in-the-loop)**: bạn có thể duyệt, sửa hoặc từ chối một lệnh gọi công cụ trước khi nó chạy. Đây là chốt an toàn quan trọng.
- **Skills**: những hành vi tái sử dụng, agent nạp khi cần.
- **Công cụ riêng**: bạn thêm hàm Python của mình, hoặc nối với bất kỳ MCP server nào.

Về nguyên tắc thiết kế, README nhấn mạnh bốn ý: có chủ kiến (mặc định đã tinh chỉnh cho việc nhiều bước), mở rộng được (thay từng phần mà không cần fork), không phụ thuộc model, và sẵn sàng cho production vì xây trên LangGraph (streaming, lưu trạng thái, checkpoint) cùng LangSmith để theo dõi và đánh giá.

Một điểm dễ nhầm: Deep Agents khác LangGraph và LangChain thế nào? README giải thích như các tầng chồng lên nhau. LangGraph là phần chạy đồ thị bên dưới. `create_agent` của LangChain là một agent tối giản đặt trên nó. Deep Agents là tầng có nhiều chủ kiến hơn nữa, gói sẵn file, sub-agent, quản lý ngữ cảnh và skills.

Ngoài ra, README còn nhắc tới **Deep Agents Code**, một agent lập trình có sẵn chạy trong terminal, kiểu Claude Code hay Cursor, dùng được với nhiều model. Bài này tập trung vào thư viện Python chính.

## Cần chuẩn bị gì

README ghi rất ngắn gọn phần này, nên mình chỉ nêu những gì có trong tư liệu:

- **Python**: ngôn ngữ chính của repo. README không ghi phiên bản tối thiểu, bạn xem thêm trong tài liệu chính thức.
- **uv**: lệnh cài đặt trong README dùng `uv`. README không hướng dẫn cách cài uv, nên nếu máy bạn chưa có, hãy tìm trang cài đặt của uv.
- **Một model hỗ trợ gọi công cụ**: có thể là API của OpenAI, Anthropic, Google; model mã nguồn mở host trên Baseten hay Fireworks; hoặc model tự chạy qua Ollama, vLLM, llama.cpp.
- **Khóa API của nhà cung cấp model** nếu bạn dùng dịch vụ trả phí. README không nói tên biến môi trường cần đặt, nên hãy xem tài liệu của từng nhà cung cấp trong phần LangChain chat models.
- **Hệ điều hành và phần cứng**: README không nêu yêu cầu cụ thể. Dùng model qua API thì mình đoán không cần GPU, nhưng README không khẳng định, nên đây chỉ là suy luận. Nếu tự chạy model trên máy thì cấu hình phụ thuộc vào model bạn chọn.

Bạn cũng nên có sẵn một thư mục dự án riêng và một terminal mở trong thư mục đó.

## Cài đặt từng bước

```steps
- Chuẩn bị Python và uv | Đảm bảo máy đã có Python và công cụ uv
- Mở terminal trong thư mục dự án | Đứng đúng thư mục bạn muốn làm việc
- Cài deepagents | Chạy lệnh uv add deepagents
- Tạo file agent | Chép đoạn code mẫu của README vào một file .py
- Chạy thử | Chạy file và đọc kết quả agent trả về
```

### Chuẩn bị Python và uv

README dùng `uv` để cài, nên bạn cần có nó. README chưa ghi cách cài uv, bạn xem hướng dẫn trên trang của uv. Muốn kiểm tra máy đã có chưa, mở terminal rồi gõ:

```bash
uv --version
```

Nếu ra số phiên bản là ổn. Nếu báo không tìm thấy lệnh, tức là chưa cài hoặc terminal chưa nhận. Hãy đóng và mở lại terminal sau khi cài.

### Mở terminal trong thư mục dự án

Chỗ người mới hay vấp: lệnh cài phải chạy đúng trong thư mục dự án của bạn. Ví dụ bạn tạo thư mục `agent-cua-toi` rồi vào đó:

```bash
cd agent-cua-toi
```

Tên thư mục chỉ là ví dụ, bạn đặt tên nào cũng được. Lệnh `uv add` thường dùng trong một dự án uv, nếu thư mục chưa phải dự án uv thì bạn xem tài liệu của uv để khởi tạo. README của Deep Agents không nói bước này.

### Cài deepagents

Đây là lệnh cài duy nhất README ghi cho thư viện Python:

```bash
uv add deepagents
```

Lệnh này thêm gói `deepagents` vào dự án của bạn. Chờ nó tải xong, không báo lỗi đỏ là được.

### Tạo file agent

Tạo một file, ví dụ `agent.py`, và chép đoạn mẫu của README vào:

```python
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"})
```

Giải thích từng phần:

- `create_deep_agent` là hàm tạo agent.
- `model` là tên model, viết theo dạng `nhà-cung-cấp:tên-model`. Đây là ví dụ trong README, bạn có thể đổi sang model khác bạn có quyền dùng.
- `system_prompt` là câu dặn vai trò cho agent. Ở đây là "Bạn là trợ lý nghiên cứu".
- `agent.invoke(...)` giao việc. Nội dung việc nằm ở `messages`. Ví dụ trên bảo agent nghiên cứu về LangGraph rồi viết bản tóm tắt.

Đoạn này chưa in kết quả ra màn hình. Bạn có thể thêm một dòng cuối:

```python
print(result)
```

### Chạy thử

Chạy file trong terminal:

```bash
uv run python agent.py
```

Nếu model của bạn cần khóa API mà chưa khai báo, bước này sẽ báo lỗi. Cách khai báo xem tài liệu của nhà cung cấp model.

```note
Khóa API là tiền của bạn. Đừng dán thẳng khóa vào file code rồi đưa lên GitHub hay gửi cho người khác. Agent chạy nhiều bước có thể gọi model rất nhiều lần, nên chi phí có thể cao hơn bạn nghĩ. Hãy thử với việc nhỏ trước và theo dõi chi phí ở trang quản lý của nhà cung cấp.
```

### Nếu bạn muốn agent lập trình trong terminal

README có một lệnh riêng cho Deep Agents Code, bản agent lập trình dựng sẵn:

```bash
curl -LsSf https://langch.in/dcode | bash
```

Lệnh này tải một script về rồi chạy ngay bằng bash. Hãy chắc bạn tin nguồn đó trước khi chạy. Lệnh dùng cú pháp bash nên trên Windows bạn cần một môi trường có bash. README không nói rõ về Windows, hãy xem trang tài liệu riêng của Deep Agents Code.

## Kiểm tra đã chạy được chưa

README không mô tả một màn hình "thành công" cụ thể. Dựa trên đoạn mẫu, bạn có thể tự kiểm tra như sau:

1. Lệnh `uv add deepagents` chạy xong mà không báo lỗi.
2. Dòng `from deepagents import create_deep_agent` không báo lỗi khi chạy file (nghĩa là gói đã vào đúng môi trường).
3. Sau vài chục giây đến vài phút, `print(result)` hiện ra một cấu trúc có chứa các tin nhắn, trong đó có phần tóm tắt về LangGraph do agent viết.

Nếu bước 2 báo không tìm thấy module, nhiều khả năng bạn đang chạy Python ở môi trường khác với nơi đã cài. Dùng `uv run` như ở trên sẽ giúp tránh chuyện này.

## Dùng vào việc thật

README mô tả khả năng chung, không có kịch bản theo ngành. Dưới đây là những tình huống mình thấy khớp với các tính năng có trong tư liệu. Đây là gợi ý ứng dụng, không phải ví dụ có sẵn trong README.

### Nhân viên văn phòng cần bản tóm tắt nghiên cứu

Bối cảnh: bạn phụ trách marketing và cần một bản tổng hợp về một chủ đề mới trước buổi họp. Bạn giữ nguyên đoạn mẫu của README và đổi nội dung giao việc:

```python
result = agent.invoke({"messages": "Research LangGraph and write a summary"})
```

Bạn thay câu trong `messages` bằng đề tài của mình. Kết quả là một bản tóm tắt do agent tự lập kế hoạch, ghi nháp vào file làm việc rồi tổng hợp. Vì README nói agent có thể lên kế hoạch và đọc ghi file, việc dài vẫn giữ được mạch.

> Agent không chỉ trả lời một lượt, nó có bàn làm việc để ghi nháp, chia việc và nhớ mình đang làm tới đâu.
>
> — Ông T

### Lập trình viên muốn đổi model theo ngân sách

Bối cảnh: bạn làm thử bằng một dịch vụ trả phí, sau thấy tốn nên muốn chuyển sang model tự chạy. README xác nhận mọi model hỗ trợ tool calling đều dùng được, kể cả qua Ollama, vLLM hay llama.cpp. Bạn chỉ cần đổi chuỗi `model` trong `create_deep_agent`, phần còn lại của code giữ nguyên. Cách ghi tên model cho từng nhà cung cấp, bạn xem trang LangChain chat models mà README dẫn tới.

### Dev cần agent có người duyệt trước khi làm

Bối cảnh: bạn muốn agent được chạy lệnh hoặc ghi file nhưng không muốn nó tự làm bừa. Tính năng human-in-the-loop cho phép bạn duyệt, sửa hoặc từ chối từng lệnh gọi công cụ trước khi nó chạy. Cách bật cụ thể README chưa ghi, bạn xem trong tài liệu chính thức. Kết quả mong đợi: agent dừng lại hỏi bạn trước những bước nhạy cảm.

### Nhóm kỹ thuật nối agent với công cụ nội bộ

Bối cảnh: công ty bạn có sẵn hàm Python tra cứu dữ liệu hoặc một MCP server nội bộ. README nói bạn có thể mang hàm của mình hoặc bất kỳ MCP server nào vào làm công cụ cho agent. Bạn cũng có thể truyền một đồ thị LangGraph tự viết vào làm sub-agent, để phần điều phối riêng của bạn chạy cạnh phần mặc định. Kết quả là agent dùng được dữ liệu của chính doanh nghiệp bạn.

## Lỗi hay gặp và cách xử lý

**Báo không tìm thấy lệnh `uv`.** Máy chưa cài uv hoặc terminal chưa nhận. Cài uv theo hướng dẫn của họ rồi mở lại terminal.

**Lỗi thiếu khóa API hoặc xác thực khi chạy.** Model của nhà cung cấp cần khóa. README chưa ghi tên biến môi trường, nên hãy xem tài liệu của nhà cung cấp model đó và khai báo khóa ở môi trường của bạn, không viết thẳng vào code.

**Lỗi tên model không đúng.** Chuỗi `openai:gpt-6-astra` chỉ là ví dụ trong README. Nếu bạn không có quyền dùng model đó, hãy thay bằng model bạn có. Dạng ghi là `nhà-cung-cấp:tên-model`.

**Model không hoạt động như mong đợi.** README yêu cầu model phải hỗ trợ tool calling. Model không có tính năng này sẽ không dùng được các công cụ của agent. Hãy chọn model khác.

**Agent làm quá tay hoặc tốn nhiều lượt gọi.** README nêu rõ mô hình "tin tưởng LLM": agent có thể làm bất cứ điều gì công cụ của nó cho phép. Hãy giới hạn quyền ở tầng công cụ và sandbox, đừng trông chờ model tự kiềm chế. Với việc quan trọng, bật bước duyệt của người dùng.

## Có nên dùng không

**Điểm mạnh.** Bạn có ngay một agent biết lập kế hoạch, dùng file, chia việc và quản lý ngữ cảnh, chỉ bằng vài dòng code. Nó không khóa bạn vào một nhà cung cấp model. Nó xây trên LangGraph nên phù hợp khi muốn đưa vào sản phẩm thật, có thể kết hợp LangSmith để theo dõi và đánh giá. Giấy phép MIT, dự án đông người dùng và còn được cập nhật.

**Giới hạn.** Đây là thư viện cho người viết code, không phải ứng dụng bấm là dùng. README khá ngắn, nhiều chi tiết như phiên bản Python, tên biến môi trường, cách bật duyệt từng bước đều phải xem tài liệu chính thức. Mô hình bảo mật là "tin tưởng LLM", nên an toàn phụ thuộc vào cách bạn giới hạn công cụ và sandbox.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần một agent nhẹ, không cần các phần đi kèm, README gợi ý dùng `create_agent` của LangChain. Nếu vòng lặp của agent không hợp hình dạng bạn cần và phải tự thiết kế đồ thị, hãy xuống LangGraph. Nếu bạn không biết lập trình và chỉ muốn một trợ lý lập trình sẵn, hãy xem Deep Agents Code, hoặc một công cụ dạng ứng dụng khác.

## Câu hỏi thường gặp

### Deep Agents có miễn phí không?

Thư viện là mã nguồn mở, giấy phép MIT nên dùng không mất phí bản quyền. Tuy nhiên nếu bạn gọi model của các nhà cung cấp trả phí thì sẽ tốn tiền theo mức dùng của họ. README không nêu chi tiết giá.

### Deep Agents khác gì LangGraph hay LangChain?

Theo README, LangGraph là phần chạy đồ thị bên dưới, còn `create_agent` của LangChain là agent tối giản đặt trên nó. Deep Agents là agent có nhiều chủ kiến hơn, gói sẵn file, sub-agent, quản lý ngữ cảnh và skills. Bạn chọn tầng nào tùy mức độ muốn tự kiểm soát.

### Có dùng được với model mã nguồn mở hoặc chạy trên máy mình không?

Có. README nói mọi model hỗ trợ tool calling đều dùng được, gồm API của OpenAI, Anthropic, Google, model mở host trên Baseten hay Fireworks, và model tự chạy qua Ollama, vLLM, llama.cpp.

### Có cần GPU không?

README không nêu yêu cầu GPU. Nếu bạn dùng model qua API của nhà cung cấp thì phần nặng chạy ở phía họ. Nếu tự chạy model trên máy thì cấu hình phụ thuộc vào model bạn chọn, tư liệu chưa có thông tin cụ thể.

### Chạy được trên Windows không?

README không nói rõ về hệ điều hành. Lệnh cài thư viện là `uv add deepagents`. Lệnh cài Deep Agents Code dùng `curl ... | bash` nên cần môi trường có bash. Bạn nên xem tài liệu chính thức để biết chi tiết cho Windows.

### Dữ liệu và thao tác của agent có an toàn không?

README theo mô hình tin tưởng LLM: agent có thể làm mọi thứ công cụ của nó cho phép. Vì vậy bạn cần đặt ranh giới ở tầng công cụ và sandbox, không dựa vào việc model tự kiềm chế. Có tính năng cho phép bạn duyệt hoặc từ chối lệnh gọi công cụ trước khi chạy.

### Có phiên bản JavaScript/TypeScript không?

Có. README cho biết Deep Agents cũng có dạng thư viện JavaScript/TypeScript, tên là deepagents.js, nằm ở một repo riêng của langchain-ai.
