Agent Core SDK

📦 Cài đặt

Yêu cầu: Bun (hoặc Node.js >= 18)

# Cài đặt dependencies
bun install

Thiết lập file .env ở thư mục gốc:

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=https://api.openai.com/v1

🚀 Hướng dẫn sử dụng cơ bản

1. Khởi tạo LLM Adapter và Agent

import { Agent, OpenAIAdapter } from "./src";

const model = new OpenAIAdapter({
  apiKey: process.env.OPENAI_API_KEY!,
  model: process.env.OPENAI_MODEL,
  baseURL: process.env.OPENAI_BASE_URL,
});

const agent = new Agent({
  model,
  instructions: "Bạn là trợ lý ảo hữu ích.",
  // Ép trả về JSON nếu cần (Tuỳ chọn)
  // responseFormat: 'json_object'
});

const result = await agent.run("Xin chào!");
console.log(result.content); // Output: Chào bạn! Mình có thể giúp gì cho bạn?
console.log(`Tokens dùng: ${result.usage.promptTokens}`);

2. Sử dụng Công cụ (Tools)

Tools giúp LLM thực hiện các tác vụ bên ngoài như lấy thời tiết, tính toán, gọi API.

import type { ITool } from "./src";

const getWeatherTool: ITool = {
  name: "getWeather",
  description: "Lấy thời tiết hiện tại.",
  schema: {
    type: "object",
    properties: { location: { type: "string" } },
    required: ["location"],
  },
  execute: async ({ location }) => {
    return `Thời tiết ở ${location} là 28°C.`;
  },
};

const agent = new Agent({
  model,
  instructions: "Sử dụng công cụ nếu người dùng hỏi thời tiết.",
  tools: [getWeatherTool],
});

3. Kỹ năng tải động (Lazy Skills)

Gom nhóm nhiều Tools lại thành 1 Skill. Agent sẽ chỉ nạp Tools này vào context khi nó cho rằng cần thiết, giúp giữ System Prompt luôn gọn nhẹ.

import type { ISkill } from "./src";

const mathSkill: ISkill = {
  name: "MathExpert",
  description: "Dùng khi cần tính toán số học phức tạp.",
  instructions: "Không tự tính nhẩm, hãy gọi tool calculate.",
  tools: [calculateTool],
};

const agent = new Agent({
  model,
  skills: [mathSkill],
});

4. Streaming và Memory (Chat CLI)

Tạo ứng dụng Chat có khả năng ghi nhớ và phản hồi từng chữ (Streaming).

import { LocalMemory } from "./your-memory-impl";

const agent = new Agent({
  model,
  memory: new LocalMemory(),
  maxHistoryMessages: 20, // Tự động xoá chat cũ nếu quá 20 tin nhắn
  callbacks: {
    onStream: (chunk) => process.stdout.write(chunk), // In ra từng chữ
    onToolStart: (name) => console.log(`[Đang chạy ${name}...]`),
  },
});

// sessionId giúp nhận diện người dùng / phiên chat
const result = await agent.run("Xin chào, tôi tên là Bacoor", {
  sessionId: "user_123",
});

(Tham khảo mã nguồn đầy đủ của ứng dụng chat tại examples/chat.ts)

🧱 Kiến trúc (Architecture)

Hệ thống được thiết kế hoàn toàn theo nguyên tắc SOLID, bao gồm các thành phần (Interfaces) có thể thay thế độc lập:

• ILanguageModel: Chịu trách nhiệm giao tiếp với Provider (Ví dụ: OpenAIAdapter).
• IMemoryProvider: Chịu trách nhiệm quản lý lịch sử (Có thể thay thế bằng RedisMemory, MongoDBMemory).
• ITool / ISkill: Khả năng mở rộng vô hạn.
• Middleware: Can thiệp và chỉnh sửa chuỗi xử lý (Ví dụ: nhúng hệ thống RAG/VectorDB).

Build & Dev

bun run build # Dịch ra thư mục ./dist