API Reference

DXA Agentic API

AI Agent có state + gọi công cụ, chạy trên Durable Objects

DXA Agentic là nền tảng AI Agent cho doanh nghiệp — chuyển từ "AI phân tích" sang "AI hành động". Agent giữ trạng thái hội thoại trong Durable Object, gọi công cụ nghiệp vụ (tra cứu tri thức, tính ROI, tạo ticket) và phản hồi dạng luồng (streaming). Hỗ trợ mô hình Workers AI (miễn phí) hoặc mô hình frontier qua endpoint tương thích OpenAI (BYO key).

Base URL

https://agentic.dxa.io.vn

Xác thực

Mỗi phiên gắn với một instance Durable Object, định danh qua tham số `?session=<id>` hoặc header `x-agent-session`. SSO qua DXA Identity nằm trong lộ trình. Mô hình tương thích OpenAI cần secret `MODEL_API_KEY` phía máy chủ.

Agent

POST /api/chat

Gửi tin nhắn, nhận phản hồi dạng luồng (có gọi công cụ)

Xác thực: Theo phiên (`?session=` hoặc header `x-agent-session`)

Tham số (body)

Trường	Kiểu	Mô tả
`message`*	`string`	Tin nhắn người dùng
`route`	`object`	Định tuyến mô hình (provider/model/useGateway…)

Ví dụ yêu cầu

curl -X POST 'https://agentic.dxa.io.vn/api/chat?session=demo' \
  -H 'Content-Type: application/json' \
  -d '{ "message": "Tính ROI cho 12 nhân viên Sales lương 20 triệu" }'

const res = await fetch('https://agentic.dxa.io.vn/api/chat?session=demo', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Tạo ticket sự cố đăng nhập' }),
});
const reader = res.body.getReader();
const dec = new TextDecoder();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(dec.decode(value));
}

Phản hồi mẫu

// Content-Type: text/plain; charset=utf-8 — luồng văn bản từng phần.
// Agent có thể gọi công cụ nghiệp vụ trong tối đa 5 bước rồi trả lời.
//   "Theo ước tính, tự động hóa cho 12 nhân viên Sales có thể tiết kiệm…"

Mã lỗi

400 Tin nhắn rỗng / body không phải JSON

GET /api/state

Lấy trạng thái phiên (route, system prompt, lịch sử tin nhắn)

Xác thực: Theo phiên

Phản hồi mẫu

{
  "tenant": "default",
  "route": { "provider": "workers-ai", "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast" },
  "systemPrompt": "Bạn là trợ lý AI nghiệp vụ của DXA Agentic…",
  "messageCount": 3,
  "messages": [ { "id": "…", "role": "user", "content": "…", "ts": 1769990400000 } ]
}

POST /api/config

Cập nhật cấu hình phiên (route mô hình / system prompt / tenant)

Xác thực: Theo phiên

Tham số (body)

Trường	Kiểu	Mô tả
`route`	`object`	Định tuyến mô hình
`systemPrompt`	`string`	Lời nhắc hệ thống
`tenant`	`string`	Mã tổ chức

Phản hồi mẫu

{ "ok": true, "route": { "provider": "openai-compatible", "model": "deepseek-chat" } }

POST /api/reset

Xóa lịch sử hội thoại của phiên

Xác thực: Theo phiên

Phản hồi mẫu

{ "ok": true }

Công cụ nghiệp vụ

POST tools (qua /api/chat)

Công cụ agent có thể gọi khi xử lý tin nhắn

Xác thực: Theo phiên

Phản hồi mẫu

// Agent tự quyết định gọi công cụ phù hợp (mô hình frontier hỗ trợ tool calling):
// • knowledgeBaseSearch { query, topK? }                       → tra cứu tri thức (RAG)
// • estimateAiRoi { department, headcount, avgMonthlySalaryVnd } → ước tính ROI
// • createTicket { title, priority?, details? }                 → tạo ticket nội bộ