# Deep Agents: bộ khung agent AI dựng sẵn cho việc dài hơi — hướng dẫn cài đặt và dùng

> Deep Agents là một agent harness mã nguồn mở bằng Python, giấy phép MIT, do LangChain phát triển. Nó cho bạn một agent AI dựng sẵn, có lập kế hoạch, hệ thống file, sub-agent và quản lý ngữ cảnh, để bạn khỏi tự lắp từng mảnh. Cài bằng một lệnh uv add deepagents, rồi viết vài dòng Python là chạy được.

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

Deep Agents là một “agent harness” mã nguồn mở: tức là một agent AI đã được lắp sẵn, có chủ kiến, chạy được ngay khi cài xong. Bạn không phải tự ghép từng linh kiện (vòng lặp agent, công cụ đọc ghi file, quản lý ngữ cảnh…). Cái nào không vừa ý, bạn có thể sửa, ghi đè hoặc thay hẳn.

Repo này dành cho lập trình viên (kể cả người mới biết chút Python) muốn dựng một trợ lý AI làm được việc nhiều bước, kéo dài: nghiên cứu một chủ đề, đọc và viết file, chia nhỏ việc cho các “agent con”. Nó được xây trên LangGraph, nên có sẵn nền tảng cho streaming, lưu trạng thái và checkpoint. Hiện repo có khoảng 31.249 sao và khoảng 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: bạn không bị khóa vào một hãng mô hình nào. README nói mô hình nào hỗ trợ gọi công cụ (tool calling) cũng dùng được, từ API của các hãng lớn đến mô hình mở hay mô hình chạy tại máy bạn. Tác giả cũng cho biết repo lấy cảm hứng từ Claude Code.

```repo
- repo | langchain-ai/deepagents
- kind | Framework
- desc | Deep Agents là bộ khung (harness) mã nguồn mở của LangChain: một agent AI dựng sẵn biết lập kế hoạch, đọc ghi file, chia việc cho sub-agent, chạy ngay.
- stars | 31k
- lang | Python
- license | MIT
```

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

Theo README, Deep Agents gói sẵn các khả năng sau. Mình giải thích theo kiểu “để làm gì” cho dễ hình dung.

- **Sub-agent**: agent chính có thể giao việc cho các agent con, mỗi agent con có cửa sổ ngữ cảnh riêng. Lợi ích: việc phụ không làm “rối đầu” 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 trong file. Nơi chứa file có thể là máy local, môi trường sandbox hoặc nơi từ xa. Nhờ đó agent có chỗ nháp, lưu kết quả trung gian thay vì nhồi hết vào đoạn chat.
- **Quản lý ngữ cảnh**: tóm tắt các cuộc trò chuyện dài và đẩy kết quả công cụ ra đĩa. Việc càng dài, tính năng này càng đáng giá.
- **Chạy lệnh shell**: agent chạy lệnh trong sandbox bạn chọn.
- **Bộ nhớ lâu dài**: có backend lưu trạng thái để agent nhớ giữa các phiên làm việc.
- **Người duyệt (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**: các hành vi dùng lại được, agent tải khi cần.
- **Công cụ**: bạn tự viết hàm làm công cụ, hoặc nối với bất kỳ MCP server nào.

Ngoài ra có thêm hai điều nên biết. Thứ nhất, README nói có thể truyền một đồ thị LangGraph (`CompiledStateGraph`) vào làm sub-agent, nên bạn có thể gắn quy trình tự viết vào cùng bộ khung. Thứ hai, thư viện này cũng có bản JavaScript/TypeScript là deepagents.js (repo riêng).

Nếu bạn đang phân vân với LangChain hay LangGraph, README giải thích như sau: LangGraph là lớp chạy đồ thị bên dưới; `create_agent` của LangChain là bộ khung agent tối giản đặt trên đó; Deep Agents là bộ khung có chủ kiến hơn, đặt trên `create_agent`, đóng gói thêm hệ thống file, sub-agent, quản lý ngữ cảnh và skills.

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

Tư liệu của repo nói khá ít về yêu cầu, nên mình chỉ ghi những gì có:

- **Python**: ngôn ngữ chính của repo. README chưa ghi phiên bản Python tối thiểu; bạn xem trang tài liệu để chắc chắn.
- **Công cụ `uv`**: lệnh cài trong README dùng `uv`. README không hướng dẫn cài `uv`, bạn xem tài liệu của uv nếu chưa có.
- **Một mô hình ngôn ngữ**: ví dụ trong README dùng mô hình của OpenAI. Mô hình nào của hãng nào thì bạn cần quyền truy cập của hãng đó. README chưa ghi tên biến môi trường hay cách khai báo key, nên bạn xem trong tài liệu chính thức của LangChain về chat model.
- **Hệ điều hành, phần cứng**: README không nêu yêu cầu cụ thể. Nếu chạy mô hình tự host (Ollama, vLLM, llama.cpp) thì cấu hình máy phụ thuộc mô hình bạn chọn, README chưa có thông tin chi tiết.

```note
Agent có thể làm mọi việc mà công cụ của nó cho phép, kể cả ghi file và chạy lệnh. Hãy thử trong thư mục hoặc sandbox riêng, đừng cho nó chạm vào dữ liệu quan trọng, và giữ key của nhà cung cấp mô hình ở nơi kín.
```

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

```steps
- Chuẩn bị uv và môi trường Python | Có sẵn uv, mở terminal trong thư mục dự án của bạn
- Cài thư viện | Chạy uv add deepagents
- Có quyền dùng một mô hình | Chọn mô hình hỗ trợ tool calling và lấy quyền truy cập từ nhà cung cấp
- Viết file Python đầu tiên | Tạo agent bằng create_deep_agent
- Chạy thử | Gọi agent.invoke với một yêu cầu đơn giản
```

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

Bạn cần một thư mục dự án quản lý bằng `uv`. Trên Windows, mở PowerShell; trên macOS/Linux, mở Terminal; rồi đi vào thư mục của bạn (đổi tên thư mục cho đúng):

```bash
cd ten-thu-muc-du-an
```

Chỗ người mới hay vấp: lệnh `uv add` chỉ có tác dụng khi bạn đứng trong thư mục dự án, nên hãy kiểm tra mình đang ở đúng thư mục trước khi chạy.

### Cài thư viện

Đây là lệnh cài trong README:

```bash
uv add deepagents
```

Lệnh này thêm gói `deepagents` vào dự án của bạn. README không nói gì thêm về cách cài khác (ví dụ pip), nên nếu cần, bạn xem thêm trong tài liệu của dự án.

### Chuẩn bị mô hình

Bước này README không viết chi tiết. Bạn cần chọn một mô hình hỗ trợ gọi công cụ và có quyền truy cập vào nó. Cách khai báo key phụ thuộc nhà cung cấp, bạn xem trong trang tài liệu LangChain về chat model (đường dẫn nằm trong phần Resources của README). Đừng dán key trực tiếp vào mã rồi đưa lên GitHub.

### Viết agent đầu tiên

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

```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 nhanh:

- `create_deep_agent` tạo ra agent với toàn bộ bộ khung dựng sẵn.
- `model` là mô hình dùng, viết theo dạng `nhà-cung-cấp:tên-mô-hình`. Đây là chuỗi đúng như trong README; bạn có thể đổi sang mô hình khác mà bạn có quyền dùng.
- `system_prompt` là lời dặn vai trò cho agent (ở đây: trợ lý nghiên cứu).
- `agent.invoke(...)` gửi yêu cầu cho agent. Kết quả trả về nằm trong biến `result`.

### Chạy thử

Chạy file bằng Python trong môi trường của dự án. README không ghi lệnh chạy cụ thể, nên cách phổ biến là:

```bash
uv run agent_dau_tien.py
```

Lệnh này là cách thông dụng của `uv` để chạy một file Python trong môi trường của dự án.

### Muốn dùng ngay trong terminal như Claude Code?

README có ghi chú về Deep Agents Code, một agent lập trình dựng sẵn chạy trong terminal, chạy bằng mô hình bạn chọn. Lệnh cài trong README:

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

Lệnh này tải một script rồi chạy luôn. Hãy tự cân nhắc trước khi chạy script từ internet, và xem tài liệu của Deep Agents Code (README có dẫn link) để biết cách dùng. Trên Windows PowerShell, lệnh này có thể không chạy trực tiếp; README chưa nói rõ về Windows, nên bạn xem tài liệu.

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

README không có lệnh kiểm tra riêng, nên cách đơn giản là dựa vào chính ví dụ mẫu:

1. Lệnh `uv add deepagents` chạy xong 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 Python.
3. `agent.invoke(...)` chạy xong và trả về `result`. Bạn in nó ra để xem:

```python
print(result)
```

Kết quả mong đợi theo README: agent lập kế hoạch, có thể đọc/ghi file và tự quản lý ngữ cảnh để hoàn thành yêu cầu. Nếu bạn có kết quả là một đoạn tóm tắt về LangGraph thì xem như đã chạy được. Nếu báo lỗi về mô hình hoặc key thì lỗi nằm ở bước chuẩn bị mô hình, xem phần lỗi bên dưới.

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

Dưới đây là các tình huống bám đúng khả năng README mô tả. Phần mã là gợi ý dựa trên ví dụ mẫu, bạn đổi nội dung yêu cầu cho hợp việc của mình.

### Dev nhỏ cần một trợ lý nghiên cứu

Bối cảnh: bạn là lập trình viên đang cân nhắc công nghệ mới và cần bản tóm tắt nhanh. Bạn dùng đúng ví dụ mẫu, chỉ đổi yêu cầu:

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

Kết quả: agent tự lập kế hoạch, làm nhiều bước và trả về bản tóm tắt. Việc dài hơn bình thường vẫn ổn nhờ cơ chế quản lý ngữ cảnh.

> Đừng tự lắp một agent từ con số không. Hãy bắt đầu từ bộ khung dựng sẵn, chỗ nào không hợp thì thay.
>
> — Ông T

### Chủ shop muốn gắn agent với công cụ của riêng mình

Bối cảnh: bạn có hàm Python tra đơn hàng hoặc đọc bảng giá và muốn agent dùng nó. README nói bạn có thể mang hàm của riêng mình hoặc bất kỳ MCP server nào làm công cụ. README chưa kèm đoạn mã mẫu cho phần này trong phần Quickstart, nên bạn xem hướng dẫn về tools trong tài liệu chính thức và thư mục `examples/` của repo (chứa các agent và mẫu chạy được). Kết quả: agent gọi đúng hàm của bạn khi cần, thay vì chỉ trả lời chung chung.

### Nhóm làm việc cần người duyệt trước khi agent hành động

Bối cảnh: bạn cho agent quyền ghi file hoặc chạy lệnh nhưng muốn kiểm soát. 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 nằm trong tài liệu, README chưa ghi lệnh cụ thể. Kết quả: agent vẫn tự động hoá việc nặng, còn quyết định rủi ro vẫn do người ra.

### Người thích làm việc trong terminal

Bối cảnh: bạn muốn một trợ lý lập trình trong terminal giống Claude Code nhưng dùng mô hình mình chọn. Cài Deep Agents Code bằng lệnh đã nêu ở phần cài đặt, rồi đọc tài liệu của nó để biết các lệnh. Kết quả: bạn có một agent lập trình trong terminal, không bị buộc vào một hãng mô hình.

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

**1. Lỗi `uv: command not found` (hoặc tương tự).** Máy bạn chưa có `uv`. README không hướng dẫn cài `uv`, bạn xem tài liệu của uv, cài xong mở lại terminal rồi chạy lại.

**2. `uv add` báo không tìm thấy dự án.** Bạn đang đứng sai thư mục. Hãy `cd` vào thư mục dự án (nơi có file cấu hình của dự án Python) rồi chạy lại.

**3. Lỗi xác thực khi gọi `agent.invoke`.** Thường do chưa khai báo key hoặc không có quyền với mô hình trong `model=`. Kiểm tra lại cách khai báo key theo tài liệu của nhà cung cấp/LangChain. Không dán key vào mã nguồn công khai.

**4. Mô hình trong ví dụ không dùng được với tài khoản của bạn.** Chuỗi `model` là mẫu từ README. Nếu bạn không có quyền với mô hình đó, hãy thay bằng mô hình bạn có quyền dùng và hỗ trợ tool calling.

**5. Agent làm quá tay (ghi đè file, chạy lệnh ngoài ý muốn).** README nói rõ Deep Agents theo mô hình “tin LLM”: agent làm được mọi thứ công cụ cho phép. Cách xử lý an toàn: giới hạn quyền ở cấp công cụ/sandbox, làm việc trong thư mục riêng, và bật bước duyệt của người trước khi lệnh chạy.

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

**Điểm mạnh:** Chạy được ngay với vài dòng mã; có sẵn các thứ khó tự làm như sub-agent, quản lý ngữ cảnh, hệ thống file; không khóa vào một hãng mô hình; xây trên LangGraph nên có đường đi lên môi trường thật (có thể kết hợp LangSmith để theo dõi và đánh giá); giấy phép MIT và repo còn được cập nhật.

**Giới hạn:** Đây là thư viện cho người viết mã, không phải ứng dụng bấm là dùng (trừ Deep Agents Code trong terminal). README khá ngắn về cài đặt: chưa ghi phiên bản Python, cách khai báo key hay yêu cầu hệ điều hành, nên bạn sẽ phải đọc thêm tài liệu. Vì agent có thể ghi file và chạy lệnh, bạn phải tự đặt ranh giới an toàn ở cấp công cụ.

**Khi nên chọn cách khác:** Theo README, nếu bạn chỉ cần một agent nhẹ, không cần bộ phần mềm trung gian đi kèm, hãy dùng `create_agent` của LangChain. Nếu vòng lặp agent không hợp với bài toán và bạn cần đồ thị riêng, hãy xuống LangGraph. Nếu bạn không biết lập trình và chỉ cần dùng AI để trả lời, một ứng dụng chat có sẵn sẽ phù hợp hơn.

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

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

Bản thân thư viện là mã nguồn mở, giấy phép MIT. Tuy nhiên nếu bạn dùng API của một hãng mô hình, chi phí gọi mô hình do hãng đó tính, README chưa có thông tin về giá. Dùng mô hình tự host thì không tốn phí API nhưng cần máy chạy được mô hình.

### Deep Agents khác LangChain và LangGraph thế nào?

Theo README, LangGraph là lớp chạy đồ thị, `create_agent` của LangChain là bộ khung agent tối giản đặt trên đó, còn Deep Agents là bộ khung có chủ kiến hơn đặt trên `create_agent`. Nó đóng gói sẵn hệ thống file, sub-agent, quản lý ngữ cảnh và skills.

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

Có. README nói mọi mô hình hỗ trợ tool calling đều dùng được: API của OpenAI, Anthropic, Google, mô hình mở trên các nhà cung cấp như Baseten hay Fireworks, và mô hình tự host qua Ollama, vLLM hoặc llama.cpp.

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

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

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

README không nói rõ về hệ điều hành. Thư viện là Python nên về nguyên tắc cài bằng uv trong dự án Python, nhưng tư liệu chưa xác nhận hỗ trợ Windows. Lệnh cài Deep Agents Code dùng curl và bash, bạn nên xem tài liệu của nó trước khi dùng trên Windows.

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

README nói Deep Agents theo mô hình tin LLM: agent có thể làm mọi thứ mà công cụ của nó cho phép. Vì vậy bạn nên đặt giới hạn ở tầng công cụ hoặc sandbox, và có thể bật bước duyệt của người trước khi lệnh chạy.

### Dùng được cho sản phẩm thật không?

README trả lời là có: nó xây trên LangGraph, thiết kế cho agent triển khai thật, và có thể kết hợp LangSmith để theo dõi, đánh giá. Hướng dẫn chi tiết nằm ở mục Going to production trong tài liệu chính thức.
