Pi Agent Platform

English

Pi Agent Platform cung cấp chat trực tiếp, công cụ có kiểm soát quyền, ngữ cảnh dự án và khung main/research/review cho tài khoản công ty.

Tài liệu public: piagent.io.vn

Cài đặt

Yêu cầu Node.js >=22.19.0. Chạy từ project cần sử dụng:

npm install -g @piagent/platform
piagent-setup

Sau khi setup:

cd /path/to/project
pi

Nhập yêu cầu bằng lời thường trong Pi hoặc WebUI. Từ bản 1.9.0 không còn bước /task hay /workflow, không còn task contract và không còn ngưỡng tiết kiệm token.

Agent Watch Auto trên macOS

Admin cấu hình model cho main, khảo sát và review trong Studio. Thành viên nhập URL/key ở Watch, chọn Piagent rồi Import. Mở Piagent công ty từ Watch hoặc chạy piagent studio; thêm --web để mở dashboard. Người dùng chọn mức suy luận; context theo model thực tế. Phiên cá nhân tiếp tục dùng pi và chọn model/OAuth riêng.

Key công ty cần loại Piagent công ty. Key CLI trực tiếp cũ giữ nguyên; Studio có nút tạo key đi kèm dùng chung hạn mức. Không đổi tài khoản công ty sang cá nhân trong cùng hội thoại.

Main có tối đa hai trợ lý chỉ đọc; không sinh nhánh con tiếp. Review gắn với bản chụp patch và báo hết hiệu lực khi code đổi. UI hiển thị token từng trợ lý. Bản macOS managed dùng công cụ cách ly và quyền ngắn hạn theo lượt; chế độ cá nhân vẫn là thực thi trên host.

Bản local này chưa phải bản phát hành có Developer ID. Trạng thái nghiệm thu phân biệt test nội bộ, gọi provider thật và phần còn thiếu.

Windows

Trên Windows, Piagent chạy trong WSL2 (Ubuntu): chế độ công ty với sandbox bubblewrap và Agent Watch cho Windows, và cả chế độ cá nhân. Một lệnh PowerShell cài tất cả. Chạy thẳng trên Windows mới là bản xem trước cho chế độ cá nhân. Cài đặt từng bước: Windows.

Web search và vision

Web research và đọc ảnh là hai capability tách biệt. Tích hợp pi-web-access được pin sẽ ưu tiên route openai-codex khi Pi đã xác thực và giữ fallback search tự động; credential không được đưa vào project hoặc browser state. Ảnh được gửi dưới dạng native image input cho model của session, không qua OCR service riêng do Piagent vận hành. Dashboard hiển thị đúng route tại Cài đặt → Nhà cung cấp & model: Codex Web Search khi route đó sẵn sàng, và Codex Vision chỉ khi model Codex hiện tại công bố hỗ trợ image input.

Workspace tài liệu trên WebUI

Session Hub cho phép đính kèm ảnh hoặc tài liệu do người dùng chọn vào cuộc trò chuyện mới hay session đang mở. File Markdown, text, PDF và DOCX được trích xuất cục bộ với giới hạn rõ ràng; chat chỉ giữ card file gọn, còn workspace Tài liệu hiển thị preview dễ đọc mà không tạo model turn. File vượt giới hạn gửi trực tiếp vẫn nằm trong workspace của project thay vì bị nhét vào prompt. Runtime tiếp tục áp protected path, redaction, session binding và attachment ref dùng một lần.

Màn hình New chat gửi đúng nội dung người dùng nhập; WebUI không còn bộ chọn workflow. Trong Cài đặt → Điều khiển project, operator có thể xem runtime/usage, profile, Context Engine, memory và MCP governance mà không cần nhớ slash command. WebUI gửi đúng command vào Pi runtime; thao tác read-only được kiểm tra là 0 model token, còn thao tác ghi hoặc semantic compact bắt buộc xác nhận rõ ràng. Muốn onboard project, hãy nhờ agent trong chat đọc project (chỉ đọc) và ghi lại context.

Command chính

Công việc được yêu cầu bằng lời thường; các command dưới đây là thiết lập và màn hình chỉ đọc, không command nào mở lượt model.

Command	Mục đích
/profile	Xem hoặc đổi project profile; /profile setup chọn tech cho từng vai trò
/permission	Đổi permission mode trong session
/context	Xem Context Engine, index, retrieval và telemetry
/usage	Xem session, model, thinking và context usage
/piagent-inspector	Mở menu read-only để xem task diff, command fail/block, safety warning và context budget; panel bốn dòng tự hiện sát footer native, toggle để ẩn trong session
Pi native /name	Đặt tên session; Piagent nhận rename event để map Agent Watch/report
/memory	Xem hoặc cập nhật explicit project memory
/piagent-mcp	Xem và quản lý MCP server, scope và phê duyệt
/piagent-status	Xem profile, guard, runtime và trạng thái model đã xác thực

Các command workflow (/workflow, /task, /scout, /fresh, /onboard, /commands, /model-options) đã bỏ từ bản 1.9.0. Hãy nói điều mình cần, ví dụ "scout luồng thanh toán, chỉ đọc, không sửa", "review diff hiện tại", "commit hai file này". Session đã nặng thì mở session mới bằng /new của Pi. git push, thao tác ghi lên GitHub và publish đều hỏi xác nhận trước.

Architecture

Code được quản lý theo các layer:

1. Composition root đăng ký Pi extension.
2. Runtime adapter xử lý Pi hook, command, tool và session UI.
3. Core service xử lý policy, context và state (bản ghi task cũ chỉ còn để đọc lịch sử).
4. Integration quản lý MCP, capability và security primitive.
5. CLI trong scripts/ chỉ parse argument và gọi use case.

Chạy gate kiến trúc:

npm run architecture:check

Đọc chi tiết:

• Architecture tiếng Việt
• Maintainer guide tiếng Việt
• Tài liệu tiếng Việt
• Operator manual tiếng Việt
• Command reference tiếng Việt

Cấu trúc repository

piagent/
├─ architecture/                      quy tắc layer và giới hạn file cho máy kiểm tra
├─ adapters/                          profile project tái sử dụng
├─ catalog/                           capability index xác định
├─ docs/                              tài liệu chuẩn EN/VI và hướng dẫn vận hành ổn định
├─ evals/                             kịch bản đánh giá có governance
├─ packs/                             capability manifest và recipe có version
├─ packages/
│  ├─ piagent-core/                   Pi package: extension, runtime, skill, managed harness
│  └─ piagent-webui/                  dashboard: contract, client, server, gateway, ownership
├─ schemas/                           JSON schema
├─ scripts/                           setup, doctor và helper kiểm tra
└─ templates/                         template project/global

piagent-core là Pi extension và có thể chạy headless độc lập. piagent-webui là giao diện piagent dashboard, nằm trên một dependency spine riêng: WebUI đọc platform nhưng platform không phụ thuộc ngược vào WebUI, nên runtime vẫn hoạt động khi không mở dashboard. Cả hai sơ đồ layer đều được kiểm tra bằng npm run architecture:check; xem Architecture.

Adaptive model routing

Adaptive model routing cho fresh task dùng piagent-route --prompt "<task>" --json. Chỉ --execute --yes mới mở provider-backed Pi process; /model/CLI pin luôn được giữ và extension không đổi model giữa conversation.

Verification

npm run verify

Gate riêng cho parity WebUI/Terminal (không gọi provider) và suite logic sâu dùng baseline Luna/medium so với codex-cli:

npm run benchmark:webui-parity
npm run benchmark:deep -- --dry-run
npm run benchmark:deep

deep-logic-v1 có 7 scenario difficulty large, khóa Piagent/codex-cli ở Luna/medium và chạy 3 repeat trên 2 surface (42 model session). Suite phủ event reconciliation, fair dependency scheduling, layered policy, graph-aware context, resumable stream, transactional config và temporal usage billing chính xác; claim chỉ được phép khi đủ full suite, token và duration gate, đồng thời không có retry. Retry diagnostic vẫn được ghi rõ nhưng làm release gate fail. --dry-run chỉ validate kế hoạch, không dùng quota.

Run production-v1 public của v1.6.0, production-v1-20260824T040017Z-05b7cf, được đo trên đúng commit 3bba8f0b3ff521bc2a355e1f6bef6d1bbdc09511 bằng GPT-5.6 Luna Medium với 108 session. Piagent hoàn thành 54/54 task, so với 48/54 của codex-cli. Tỷ lệ fresh token theo family fixed-workload chính là 0,3857 (thấp hơn 61,43%), với khoảng tin cậy 95% 0,3073..0,4840; cận trên cho phép phát biểu thận trọng rằng Piagent dùng ít hơn ít nhất 51,60% fresh token trên đúng workload đã khai báo trước và đúng release này. Usage của cả 108 session đều exact và không có retry. Xem bằng chứng benchmark và phương pháp.

Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release.

Bản phát hành hiện tại là v1.34.3. Với team hoặc production, hãy pin tag này hoặc một commit đã review thay vì dựa vào nguồn package không cố định.

Security

Pi Agent Platform là application-level policy layer, không phải OS sandbox. Với untrusted code hoặc adversarial workload, vẫn cần container hoặc VM có filesystem, process, network và credential boundary riêng.

Không commit OAuth token, API key, auth.json, session, cache, trust state hoặc dữ liệu nội bộ.

License

MIT License. Xem LICENSE.