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

Các câu trả lời dưới đây đề cập tới Pi và dự án tài liệu này. Hãy mở GitHub issue nếu câu hỏi của bạn chưa có trong danh sách.

Pi là bộ công cụ coding agent mã nguồn mở. Monorepo của Pi chứa model API, agent runtime, TUI và ứng dụng dòng lệnh pi. Ba npm package chính là @earendil-works/pi-ai, @earendil-works/pi-agent-core và @earendil-works/pi-coding-agent.

Pi 1.0 ổn định hóa core và Coding Agent. Package @earendil-works/pi-durable riêng vẫn ở trạng thái thử nghiệm, hỗ trợ ứng dụng chạy lâu và không thay thế Coding Agent.

Pi khác Claude Code hoặc Codex ở điểm nào?

Pi giữ phần core nhỏ và cho phép tùy chỉnh bằng extension, skill, prompt template, theme và package. Claude Code và Codex có workflow tích hợp sẵn và service integration khác. Hãy so sánh theo workflow, provider, mô hình bảo mật và yêu cầu triển khai của dự án thay vì xem chúng là các agent tương đương.

Pi hỗ trợ những model provider nào?

Pi đăng ký sẵn provider cho Anthropic, OpenAI, Google, Bedrock, OpenRouter, một số subscription endpoint và nhiều dịch vụ hosted hoặc local khác. Bạn cũng có thể đăng ký custom provider hoặc server tương thích OpenAI. Xem Tích hợp model provider.

Các model chọn lọc dưới đây cho thấy một tên trong catalog có thể có nhiều provider route:

Model	Route hiện tại	Hành vi của route
`GPT-6.1 Sol` (`gpt-6.1-sol`)	`openai + azure-openai-responses + openai-codex`	`default hiện tại của provider OpenAI Codex cũ`
`Claude Opus 5.5`	`anthropic + github-copilot`	`adaptive thinking + route Copilot được hỗ trợ`
`GPT-6 Sol`	`openai + openai-codex + github-copilot`	`API key + OpenAI Codex subscription + route Copilot được hỗ trợ`
`GPT-6 Luna`	`openai + openai-codex + github-copilot`	`API key + OpenAI Codex subscription + route Copilot được hỗ trợ`
`Grok 4.7`	`xai`	`default cho xAI session mới`

Đây không phải toàn bộ catalog. Dùng /model hoặc pi --list-models để xem bản đã cài, và lưu ý model được chọn tường minh hoặc model đã lưu trong session được resume có độ ưu tiên cao hơn xAI default dành cho session mới.

Khi nào nên dùng direct Tool, Codemode, MCP, Virtual Model hoặc Durable?

Hãy chọn boundary nhỏ nhất đáp ứng được bài toán:

Cơ chế	Thời điểm sử dụng
direct Tool	Model cần một tập operation nhỏ, xác định trước và mỗi call nên xuất hiện trực tiếp trong transcript.
Codemode	Tập Tool lớn hoặc deferred sẽ làm prompt phình to, hay một chương trình JavaScript chạy trong sandbox cần tìm, sắp xếp và gọi song song nhiều Tool.
MCP	Tool nằm trong server stdio hoặc HTTP bên ngoài. Hãy cấu hình server, sau đó chọn exposure direct, Codemode hoặc deferred cho các Tool của nó.
Virtual Model	Extension cần route từng model request tới một physical model, trong khi session giữ một virtual identity ổn định. Cơ chế này route model call, không expose Tool.
Durable	Work thử nghiệm cần Document và Task được lưu bền vững, replay policy, recovery hoặc structured concurrency qua các lần khởi động lại process. Session Agent Core thông thường không bắt buộc dùng Durable.

Xem Dùng Codemode và MCP, Route Virtual Model và Xây dựng Durable Agent để biết đầy đủ boundary và ví dụ.

Pi có miễn phí không?

Mã nguồn và npm package của Pi dùng giấy phép mã nguồn mở. Model provider vẫn có thể tính phí inference, vì vậy hãy đặt giới hạn tài khoản trước khi gọi API.

Đọc tài liệu

Có nên đọc các chương theo thứ tự không?

Hãy đọc chương 1 đến 3 theo thứ tự để nắm tổng quan dự án, kiến trúc package và vòng lặp Agent. Sau đó, có thể đọc độc lập từng chương 4 đến 11 theo subsystem bạn quan tâm.

Tài liệu này mô tả revision nào của Pi?

Baseline hiện tại của tài liệu là release Pi 1.0.0 chính thức. Review ledger ghim việc kiểm chứng tại a13d35a742c6ef8462812a28fbe1d8c8b7431c32, được review ngày 2026-10-06. Hãy kiểm tra lại upstream trước khi phụ thuộc vào API hoặc giá trị mặc định có thể thay đổi theo version.

Vì sao ví dụ dùng TypeScript?

Pi được viết bằng TypeScript và phát hành type declaration cùng các package. Tài liệu dùng TypeScript khi type giúp API rõ ràng hơn; shell, JSON và JavaScript được dùng khi phù hợp với runtime hoặc định dạng cấu hình.

Có thể dùng lại ví dụ trong dự án riêng không?

Có. Hãy cài đúng package được ghi trong ví dụ và dùng đúng phiên bản Node.js yêu cầu. Hướng dẫn nhanh cung cấp một setup hoàn chỉnh có thể chạy ngay.

Đóng góp

Báo lỗi dịch như thế nào?

Mở issue tại github.com/pifydev/docs/issues. Ghi rõ đường dẫn trang, câu bị lỗi và đề xuất sửa.

Có thể thêm trang hoặc chương mới không?

Có. Hãy gửi đủ file tiếng Anh và tiếng Việt, giữ cấu trúc heading và code fence đồng bộ, đồng thời tuân theo CONTRIBUTING.md.

Quy ước thuật ngữ nằm ở đâu?

Glossary của tài liệu định nghĩa thuật ngữ chuẩn. Giữ nguyên identifier và chỉ dịch các khái niệm được glossary cho phép.

Lỗi thường gặp

Các chi tiết implementation dưới đây hữu ích khi chẩn đoán lỗi riêng của provider trong baseline 1.0.0 hiện tại:

Trường hợp	Hành vi cần kiểm tra
`OpenAI-compatible`	Bỏ text part rỗng khỏi request chỉ có image; giữ nguyên image block.
`Claude Fable 5.1 + split-turn compaction`	Giữ nội dung trước đó dưới `# Conversation` và chỉ dẫn tiếp tục dưới `# Instructions`.

Các sửa đổi này không expose public API. Nếu endpoint tương thích OpenAI vẫn từ chối lượt chỉ có image, hãy kiểm tra các content part đã serialize. Với split-turn compaction, việc tách này tránh để chỉ dẫn tiếp tục bị coi là conversation trước đó; không có public compaction option điều khiển hành vi này.

Ở các bản cũ, Claude Fable đôi khi từ chối khi tóm tắt một lượt split-turn. Đây là phép so sánh chẩn đoán lịch sử, không phải cấu hình API hiện tại: hãy kiểm tra transcript trước đó nằm dưới # Conversation, còn riêng phần chỉ dẫn tiếp tục nằm dưới # Instructions. Hành vi 1.0.0 hiện tại vẫn giữ hai vai trò này tách biệt.

Kết quả Tool không đến được model

Implementation của AgentTool.execute trả về AgentToolResult gồm content cùng details hoặc usage tùy chọn; implementation không tự dựng ToolResultMessage. Agent Core liên kết result với ToolCall hiện tại rồi tạo protocol message có call ID và tên Tool khớp. Nếu model không nhận được kết quả, hãy kiểm tra các content block được trả về và sự kiện tool_execution_end.