Pi Agent Thực Chiến: Hướng Dẫn Setup & 5 Best Practices

Hầu hết lập trình viên khi dùng AI coding agent đều vô tình chấp nhận một sự thỏa hiệp ngầm: cam chịu bị nhốt trong chiếc lồng tư duy của người khác. Bạn muốn agent có cơ chế duyệt lệnh bảo mật trước khi gõ lệnh bash? Phải đợi nhà phát hành cập nhật. Bạn muốn đổi model từ Claude sang Qwen chạy local giữa phiên làm việc để tiết kiệm tiền API? Bị khóa cứng.

Pi Agent (pi-coding-agent) sinh ra để đập tan sự gò bó đó. Không hoa mỹ, không áp đặt, Pi trao lại toàn bộ chìa khóa điều khiển vào tay bạn.

Lưu ý kiến trúc: Nếu bạn muốn mổ xẻ sâu về cấu trúc 7 packages và triết lý monorepo nền tảng, hãy đọc trước bài phân tích Pi Mono Giải Thích: Anti-Framework Cho AI Coding Agent. Bài viết này là cẩm nang thực chiến chuyên biệt từ A-Z về quy trình cài đặt, cấu hình model nội bộ và tự viết extension TypeScript.

Tóm tắt (TL;DR)

Hộp Trả Lời Nhanh (Google Search Featured Snippet):

• Làm sao để setup và triển khai Pi Agent hiệu quả nhất? Cài đặt toàn cục qua npm (npm i -g --ignore-scripts @earendil-works/pi-coding-agent), chọn phương thức xác thực (/login hoặc kết nối Ollama/vLLM local qua models.json), và tận dụng 7 công cụ phẫu thuật có sẵn (read, write, edit, bash, grep, find, ls). Để mở rộng agent mà không cần fork mã nguồn, bạn có thể tận dụng thang bậc tùy biến từ Prompt Templates, Agent Skills cho đến TypeScript Extensions.
• Triết lý vận hành: Anti-Framework tối giản, tách rời hoàn toàn giữa giao diện terminal (TUI), vòng lặp thực thi (pi-agent-core) và cổng kết nối hơn 20 nhà cung cấp mô hình AI (pi-ai).
• Điểm ăn tiền nhất: Khả năng phân nhánh cây phiên làm việc (/tree, /fork, /clone), 4 chế độ vận hành linh hoạt (interactive, -p, json, rpc), và phím tắt điều khiển steering (Enter vs Alt+Enter).
• Mã nguồn chính thức: earendil-works/pi và badlogic/pi-mono.

---

Bản đồ tư duy (Beginner Map)

Hãy tưởng tượng các công cụ như Cursor hay Claude Code là một chiếc xe hơi nguyên chiếc đã khóa kín nắp capô; bạn chỉ việc ngồi lái nhưng không thể chỉnh sửa động cơ. Ngược lại, Pi Agent là bộ khung gầm xe đua mô-đun: bạn tự chọn động cơ AI, tự lắp phanh an toàn và tự thiết kế bảng điều khiển theo ý mình.

---

Phần 1: Nền tảng (Foundations)

Sự ức chế lớn nhất khi dùng các AI coding agent đóng gói sẵn nằm ở sự bất lực. Khi agent tự ý sửa hàng loạt file mà không hỏi, hoặc khi bạn muốn tích hợp một công cụ nội bộ của công ty vào quy trình xử lý, bạn phải viết những đoạn system prompt dài dằng dặc để van xin mô hình tuân thủ.

Pi Agent giải quyết triệt để vấn đề này bằng triết lý Primitives First (Ưu tiên các khối nguyên bản). Thay vì phỏng đoán quy trình của bạn, Pi cung cấp các khối xây dựng cốt lõi và trao toàn quyền lắp ghép:

Toàn bộ sức mạnh của Pi nằm ở việc bạn hoàn toàn sở hữu vòng lặp điều khiển (agent loop). Mọi thứ đều minh bạch và có thể kiểm soát bằng code TypeScript tiêu chuẩn.

---

Phần 2: Khảo sát (Investigation): Cài Đặt & Cấu Hình Thực Tế

Quá trình đưa Pi Agent vào môi trường làm việc thực tế diễn ra trong chưa đầy 3 phút:

Bước 1: Cài đặt CLI toàn cục

Gói phát hành chính thức hiện được phân phối dưới scope @earendil-works (yêu cầu Node.js phiên bản 22.19 trở lên):

# Cài đặt CLI toàn cục từ npm
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# Hoặc cài qua script chính thức
curl -fsSL https://pi.dev/install.sh | bash

# Kiểm tra phiên bản
pi --version

Bước 2: Cấu hình Khóa API & Local Inference

Pi hỗ trợ các phương thức quản lý thông tin xác thực sau:

1. Đăng nhập tương tác qua lệnh /login: Khởi chạy pi và chọn nhà cung cấp mong muốn. Khóa API được lưu trữ an toàn trong file ~/.pi/agent/auth.json với quyền bảo mật 0600.
2. Biến môi trường trực tiếp: Phù hợp cho CI/CD (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY).
3. Cấu hình Model Local qua ~/.pi/agent/models.json: Trỏ trực tiếp về instance Ollama hoặc vLLM chạy nội bộ:

   {
     "providers": {
       "ollama": {
         "baseUrl": "http://localhost:11434/v1",
         "api": "openai-completions",
         "apiKey": "ollama",
         "models": [{ "id": "qwen2.5-coder:32b" }]
       }
     }
   }

   Sau đó gõ /model trong terminal và bấm Ctrl+S để lưu làm model mặc định.

Bước 3: Vận hành 7 Công Cụ Cốt Lõi & Giới Hạn Quyền

Pi Agent mặc định tích hợp sẵn 7 công cụ phẫu thuật:

• read, write, edit: Thao tác file chuẩn xác theo từng khối văn bản duy nhất.
• bash: Thực thi lệnh shell với giới hạn timeout.
• grep, find, ls: Tìm kiếm regex và quét cấu trúc thư mục tốc độ cao.

Áp đặt chính sách sandbox chỉ cho phép đọc bằng cờ --tools:

# Giới hạn agent chỉ được đọc và tìm kiếm, cấm tuyệt đối ghi đè file hoặc chạy bash
pi --tools read,grep,find,ls --print "Review kiến trúc dự án này"

---

Phần 3: Chẩn đoán (Diagnosis): Thang Tùy Biến & Extension Chuẩn

Hiểu rõ Thang bậc tùy biến 4 tầng (Customization Ladder) của Pi để chọn giải pháp tối ưu:

1. Prompt Templates (*.md trong ~/.pi/agent/templates/): Nhanh gọn nhất, gõ /tên-template để chèn prompt định sẵn.
2. Agent Skills (SKILL.md trong ~/.pi/agent/skills/ hoặc .agents/skills/): Progressive disclosure (chỉ nạp tên và mô tả vào system prompt, khi cần mới tải nội dung).
3. TypeScript Extensions (*.ts trong ~/.pi/agent/extensions/): Dành cho can thiệp runtime, đăng ký lệnh /command, thêm custom tool hoặc bắt sự kiện.
4. Custom Providers (models.json): Định tuyến endpoint AI nội bộ hoặc chạy GGUF qua /llama.

Tự tạo Extension Kiểm Duyệt Lệnh Trong 20 Dòng Code

Tạo file ~/.pi/agent/extensions/guardrails.ts:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("status", {
    description: "In trạng thái an toàn của phiên làm việc",
    handler: async (_args, ctx) => {
      ctx.ui.notify("Guardrail đang hoạt động: Chế độ kiểm duyệt lệnh bật.", "info");
    },
  });

  pi.on("tool_call", async (event, _ctx) => {
    if (event.toolName === "bash") {
      const command = String(event.params.command || "").trim();
      const forbidden = [/rm\s+-rf\s+[\/~]/, /git\s+push\s+.*--force/, /mkfs/];
      for (const pattern of forbidden) {
        if (pattern.test(command)) {
          throw new Error(`Lệnh bị chặn bởi Security Guardrail: "${command}" vi phạm quy tắc an toàn.`);
        }
      }
    }
  });
}

Nạp extension bằng lệnh pi --extension ./guardrails.ts. Sau khi chỉnh sửa, bạn chỉ cần gõ /reload ngay trong terminal mà không cần khởi động lại.

4 Chế Độ Vận Hành Cho Tự Động Hóa

• Interactive Mode (pi): Giao diện TUI toàn diện với phím tắt điều khiển.
• Print Mode (pi -p "tóm tắt diff" < <(git diff)): Chạy một lần, in kết quả ra terminal rồi thoát, tối ưu cho piping shell script.
• JSON Event Stream (pi --mode json "task" > events.jsonl): Xuất toàn bộ tiến trình reasoning và tool calls dạng JSON Lines cho pipeline CI/CD.
• RPC Mode (pi --mode rpc): Giao tiếp qua stdin/stdout dạng JSONL, biến Pi thành backend cho các ứng dụng tùy biến.

3 Cạm Bẫy Thực Chiến Cần Tránh

1. Bẫy quên nén ngữ cảnh (/compact): Khi cây hội thoại phình to, gõ /compact kèm hướng dẫn rõ ràng (ví dụ /compact "giữ nguyên các đoạn code mẫu và quyết định kiến trúc") để giải phóng token.
2. Bẫy lạm dụng lệnh bash để sửa file: Model có xu hướng dùng sed hoặc cat << 'EOF' qua bash làm hỏng cú pháp các file lớn. Hãy dùng cờ --tools read,edit,write để ép model dùng công cụ sửa file chuẩn xác.
3. Bẫy nhầm lẫn cơ chế Trust với Sandbox: File trust.json của Pi chỉ ghi nhớ quyền cho phép chạy lệnh, không phải là môi trường ảo hóa cách ly. Luôn chạy Pi bên trong Docker container nếu thao tác với mã nguồn lạ.

---

Phần 4: Giải pháp (Resolution): 5 Best Practices Thực Chiến

1. Phân biệt rõ ràng bộ tứ session: /tree, /fork, /clone và /resume

• /tree: Chuyển node trên cây hội thoại trong cùng một session file.
• /fork: Tách ra một session mới độc lập từ một lượt trao đổi cụ thể.
• /clone: Sao chép toàn bộ nhánh hiện tại sang file mới.
• /resume: Bật giao diện tìm kiếm, đổi tên và dọn dẹp các session cũ.

2. Chiến lược kết hợp Model đa tầng (Model Handoff)

Tận dụng package pi-ai để phân tách nhiệm vụ: dùng model tư duy đầu bảng (như Claude 3.7 Sonnet) cho bước phân tích kiến trúc, sau đó gõ /model để chuyển sang model tốc độ cao (như Qwen 2.5 Coder 32B) cho bước viết code. Bấm Ctrl+S để lưu lựa chọn.

3. Tận dụng Prompt Caching và Session Affinity

Pi tự động gửi header x-session-id tới các gateway hỗ trợ prompt caching. Giữ nguyên một session tree cho một chuỗi công việc liên quan giúp máy chủ inference tái sử dụng KV-cache, giảm độ trễ và tiết kiệm chi phí token đáng kể.

4. Kỹ thuật điều khiển Steering bằng phím tắt

• Enter: Steer (can thiệp ngay sau khi tool hiện tại thực thi xong).
• Alt + Enter: Follow-up (xếp hàng tin nhắn sau khi agent hoàn tất toàn bộ chuỗi task).
• Esc: Hủy tác vụ đang chạy và nạp lại toàn bộ nội dung prompt vào editor để chỉnh sửa.
• Ctrl + T: Đổi nhanh mức độ thinking (/thinking off/low/medium/high/max).

5. Giới hạn phạm vi file bằng ký hiệu @ và file AGENTS.md

Sử dụng cú pháp @path/to/file để chỉ định chính xác các file phụ thuộc. Đồng thời đặt file AGENTS.md ở thư mục gốc dự án để lưu trữ quy chuẩn kiến trúc và checklist kiểm thử; Pi sẽ tự động nạp ngữ cảnh này vào phiên làm việc.

---

Bảng So Sánh Quyết Định: Khi Nào Nên Dùng Pi Agent?

---

Lời khuyên cuối (Final Take)

Công cụ lập trình AI mạnh nhất không phải là công cụ làm sẵn nhiều tính năng màu mè nhất, mà là công cụ trao cho bạn toàn quyền kiểm soát cách nó suy nghĩ và hành động.

Pi Agent không cố gắng làm hài lòng tất cả mọi người. Nó được tạo ra cho những kỹ sư phần mềm thực thụ: những người muốn hiểu rõ từng tool call, làm chủ từng byte ngữ cảnh và tự tay lập trình trợ lý AI của chính mình.

---

Thử thách thực hành (Student First Assignment)

Dành 20 phút tự tay hoàn thiện luồng làm việc đầu tiên với Pi Agent:

1. Cài đặt @earendil-works/pi-coding-agent và kết nối với provider yêu thích của bạn qua lệnh /login.
2. Tạo file extension ~/.pi/agent/extensions/status.ts để đăng ký lệnh /status in ra thông báo chào mừng qua ctx.ui.notify().
3. Khởi chạy pi, yêu cầu agent refactor một hàm TypeScript nhỏ trong dự án của bạn và dùng lệnh /tree để quan sát cấu trúc cây phiên làm việc.

---

Câu hỏi thường gặp (FAQ)

1. Khi nào nên dùng Prompt Template, khi nào nên dùng Skill hoặc Extension?

Dùng Prompt Template khi bạn chỉ cần tái sử dụng một đoạn prompt cố định. Dùng Agent Skill (SKILL.md) khi cần cung cấp cho agent kiến thức chuyên sâu kèm tài liệu và script hỗ trợ. Chỉ dùng TypeScript Extension khi bạn cần can thiệp vào vòng lặp runtime, bắt sự kiện tool call hoặc thêm công cụ mới.

2. Chế độ --mode rpc dùng trong trường hợp nào?

Chế độ RPC cho phép Pi chạy như một tiến trình ngầm (daemon), nhận lệnh và trả về kết quả qua luồng nhập xuất chuẩn (stdin/stdout) dưới định dạng JSON Lines. Đây là giải pháp hoàn hảo để tích hợp Pi vào các ứng dụng mở rộng như VS Code extension, giao diện web nội bộ hoặc hệ thống automation riêng.

3. Tôi có thể chạy Pi Agent offline hoàn toàn với file GGUF không?

Hoàn toàn được. Bạn có thể dùng router llama.cpp tích hợp sẵn qua lệnh /llama hoặc kết nối Pi với máy chủ Ollama/vLLM nội bộ qua file models.json. Agent sẽ chạy trực tiếp trên phần cứng của bạn mà không gửi bất kỳ dữ liệu nào ra ngoài internet.