Khám phá Pi Agent Harness: AI Coding Agent Mở Rộng

Trong thế giới trợ lý lập trình AI (AI Coding Agents), hầu hết các công cụ hiện nay đều được đóng gói dưới dạng “hộp đen” (monolithic black box). Bạn bắt buộc phải tuân theo luồng làm việc (workflow), giao diện và chế độ lập kế hoạch (plan mode) được định sẵn. Nếu muốn thêm một công cụ tùy chỉnh hay thay đổi quy trình làm việc, giải pháp duy nhất thường là chờ nhà phát triển cập nhật hoặc viết các script bao bọc phức tạp.

Pi (@earendil-works/pi) ra đời nhằm giải quyết triệt để vấn đề này với triết lý: Hãy để công cụ thích nghi với luồng làm việc của bạn, chứ không phải ngược lại.

[!NOTE] Pi là dự án mở nguồn (Open Source Agent Harness) được phát triển bởi earendil-works (dẫn đầu bởi Mario Zechner / badlogic). Pi cung cấp các khối kiến trúc tối giản nhưng mạnh mẽ để bạn xây dựng trợ lý AI theo đúng nhu cầu.

1. Khái niệm đơn giản (ELI5)#

Hãy tưởng tượng bạn mua một chiếc xe ô tô nguyên khối: bạn không thể đổi vô lăng, không thể nâng cấp động cơ hay gắn thêm đồng hồ đo phụ trợ trừ khi nhà sản xuất bán linh kiện riêng.

Pi Agent Harness giống như một bộ khung xe đua mô-đun (modular chassis):

• Bạn có thể gắn động cơ của bất kỳ hãng nào (OpenAI, Anthropic, Gemini, DeepSeek hoặc model chạy cục bộ llama.cpp).
• Bạn có thể tự làm thêm nút bấm, bảng điều khiển (TypeScript Extensions).
• Bạn có thể viết thêm các “kỹ năng” mới cho xe (Skills & Prompt Templates).
• Xe tự động lưu lại toàn bộ hành trình dưới dạng sơ đồ đường đi (Tree-structured Sessions), cho phép bạn “tua ngược” lại bất kỳ ngã rẽ nào để đi thử con đường khác.

2. Kiến trúc 4 tầng của Pi#

Dự án Pi không chỉ là một ứng dụng CLI đơn lẻ mà là một hệ sinh thái được phân chia thành các gói độc lập:

┌─────────────────────────────────────────────────────────┐
│        @earendil-works/pi-coding-agent (CLI)             │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-tui (Terminal UI)             │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-agent-core (Agent Engine)     │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-ai (Unified Provider API)    │
└─────────────────────────────────────────────────────────┘

3. Các tính năng nổi bật của Pi#

Khả năng tự mở rộng (Self-Extensible)#

Pi đi kèm với 4 công cụ mặc định cơ bản: read, write, edit, và bash. Tuy nhiên, sức mạnh thực sự nằm ở cơ chế mở rộng:

• Skills (/skill:name): Định nghĩa các tập lệnh kịch bản chuyên biệt.
• Extensions: Viết mã TypeScript để thêm công cụ mới, thay đổi giao diện TUI, hoặc tương tác với tiến trình bên ngoài.
• Prompt Templates: Các mẫu prompt mở rộng nhanh thông qua lệnh / lệnh tùy chỉnh.
• Pi Packages: Đóng gói extension và skill để chia sẻ qua npm hoặc git.

Quản lý phiên làm việc dạng cây (Tree-Structured Sessions)#

Mỗi phiên làm việc của Pi được lưu trữ dưới dạng một tệp JSONL có cấu trúc cây (mỗi entry có id và parentId).

Lệnh /tree cho phép bạn xem lại toàn bộ lịch sử phân nhánh, chuyển đổi qua lại giữa các nhánh hoặc tiếp tục từ một câu hỏi trong quá khứ mà không làm mất dữ liệu cũ.

[!TIP] Bạn có thể sử dụng phím tắt Ctrl+O trong giao diện /tree để lọc các tin nhắn theo nhiều chế độ: chỉ xem tin nhắn người dùng, ẩn công cụ, hoặc chỉ hiển thị các mốc được đánh dấu (bookmarks).

Hỗ trợ đa dạng LLM Provider & Local Models#

Pi không khóa bạn vào một nhà cung cấp duy nhất. Bạn có thể sử dụng API key hoặc gói đăng ký (Subscription):

• Cloud Models: Anthropic Claude 3.7 / 3.5, OpenAI GPT-4o / Codex, Google Gemini 2.5, DeepSeek R1 / V3, Groq, Mistral, OpenRouter, v.v.
• Local Models: Tích hợp trực tiếp với server llama.cpp thông qua lệnh /llama để tải và chọn model cục bộ hoàn toàn riêng tư.

Bảo mật & Sandboxing Flexible#

Pi mặc định chạy với quyền của người dùng khởi chạy. Tuy nhiên, nếu cần môi trường cách ly an toàn khi chạy code tự động, Pi hỗ trợ 3 mô hình sandbox:

1. Gondolin Extension: Giữ pi trên host nhưng đẩy công cụ bash vào một micro-VM Linux nhẹ.
2. Docker Container: Chạy toàn bộ tiến trình pi trong Docker.
3. OpenShell: Giới hạn quyền hạn bằng các chính sách bảo mật chi tiết.

4. Hướng dẫn sử dụng nhanh#

Cài đặt#

Cài đặt Pi thông qua npm hoặc script tự động:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Hoặc qua curl:

curl -fsSL https://pi.dev/install.sh | sh

Khởi chạy & Cấu hình Model#

Đặt API key và chạy pi:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Trong giao diện interactive của Pi:

• /model: Mở menu chọn mô hình AI.
• /login: Đăng nhập bằng tài khoản dịch vụ (Claude Pro, ChatGPT, Copilot).
• /tree: Mở cây lịch sử phiên làm việc.
• /compact: Chủ động nén ngữ cảnh khi hội thoại quá dài.
• /reload: Nạp lại cấu hình, extensions và skills mà không cần khởi động lại CLI.

5. So sánh Pi với OpenCode, Claude Code & Codex#

6. Đóng góp dữ liệu phiên làm việc cho cộng đồng OSS#

Tác giả dự án khuyến khích cộng đồng chia sẻ dữ liệu phiên làm việc mã nguồn mở (Open Source sessions) thông qua công cụ badlogic/pi-share-hf. Dữ liệu thực tế từ luồng làm việc của các lập trình viên sẽ giúp cải thiện các mô hình AI, prompt và hệ thống đánh giá (evaluation) mã nguồn mở trong tương lai.

Tài liệu tham khảo#

• Mã nguồn Pi Agent trên GitHub ↗
• Trang chủ Pi Dev ↗
• Tài liệu hướng dẫn chính thức ↗
• Hệ thống RFCs của Earendil Works ↗