Hướng dẫn nhanh: Tạo Pi agent đầu tiên

Hướng dẫn này dùng release Pi 0.85.0 chính thức để tạo một chương trình TypeScript nhỏ nhận phản hồi streaming từ model. Bạn sẽ cài @earendil-works/pi-ai, đăng ký các provider có sẵn, chọn một model và xử lý luồng sự kiện. Bạn không cần biết Pi từ trước.

Trước khi bắt đầu

Bạn cần:

• Node.js 22.19 trở lên - kiểm tra bằng node --version
• API key của một provider - ví dụ Anthropic, OpenAI, Google hoặc local proxy tương thích với OpenAI Chat Completions. Ví dụ dưới đây dùng Anthropic.
• Terminal đang mở tại một thư mục rỗng

1. Khởi tạo dự án

mkdir pi-quickstart && cd pi-quickstart
npm init -y
npm pkg set type=module
npm install @earendil-works/pi-ai@0.85.0
npm install --save-dev tsx

Bạn sẽ có:

• package.json được cấu hình để dùng ECMAScript modules
• @earendil-works/pi-ai và TypeScript loader tsx trong node_modules

2. Thêm API key

Tạo file .env trong cùng thư mục:

ANTHROPIC_API_KEY=sk-ant-...

Thêm .env vào .gitignore:

node_modules
.env

3. Viết agent

Tạo agent.ts:

import { builtinModels } from "@earendil-works/pi-ai/providers/all";

const models = builtinModels();
const model = models.getModel("anthropic", "claude-sonnet-4-5");
if (!model) throw new Error("Model not found");

const stream = models.streamSimple(model, {
  systemPrompt: "You are a concise assistant. Reply in one sentence.",
  messages: [
    {
      role: "user",
      content: "What is the capital of France?",
      timestamp: Date.now(),
    },
  ],
});

for await (const event of stream) {
  if (event.type === "text_delta") {
    process.stdout.write(event.delta);
  } else if (event.type === "done") {
    console.log("\n[done] reason:", event.reason);
  }
}

Bốn bước diễn ra trong file này:

1. builtinModels() tạo một Models collection và đăng ký các provider có sẵn.
2. models.getModel("anthropic", "claude-sonnet-4-5") lấy model descriptor từ collection đó.
3. models.streamSimple(model, context) mở request streaming và trả về một async iterable.
4. Vòng for await xử lý sự kiện cho đến khi stream kết thúc. text_delta chứa từng phần văn bản; done là sự kiện cuối.

4. Nạp key và chạy

Provider đọc ANTHROPIC_API_KEY từ environment của process. Node có thể nạp trực tiếp file .env:

node --env-file=.env --import tsx agent.ts

{
  "scripts": {
    "start": "node --env-file=.env --import tsx agent.ts"
  }
}

Kết quả sẽ tương tự:

The capital of France is Paris.
[done] reason: stop

Nếu thấy vậy, bạn đã có một Pi agent hoạt động.

5. Thử một biến thể

Đổi user message và chạy lại:

const stream = models.streamSimple(model, {
  systemPrompt: "You are a concise assistant. Reply in one sentence.",
  messages: [
    {
      role: "user",
      content: "Name three Pi SDK packages.",
      timestamp: Date.now(),
    },
  ],
});

Metadata {6} yêu cầu code renderer của Fumadocs làm nổi bật dòng 6.

Tiếp theo

Bạn đã có một lệnh Models.streamSimple() hoạt động. Chọn nội dung tiếp theo theo mục tiêu của bạn:

Khắc phục sự cố

Error: ANTHROPIC_API_KEY is not set

Provider không tìm thấy key. Xác nhận .env nằm trong thư mục hiện tại và bạn đã chạy Node với --env-file=.env.

Error: model not found

models.getModel() không tìm thấy descriptor. Kiểm tra provider ID và model ID. Xem Tham khảo cấu hình.

SyntaxError: Cannot use import statement outside a module

package.json của bạn thiếu "type": "module". Chạy npm pkg set type=module rồi thử lại.