API Reference

DXA Agentic API

Stateful, tool-calling AI agents on Durable Objects

DXA Agentic is an enterprise AI agent platform — moving from "AI that analyzes" to "AI that acts". Agents keep conversation state in a Durable Object, call business tools (knowledge search, ROI estimation, ticket creation) and respond with streaming text. Supports Workers AI models (free) or frontier models via an OpenAI-compatible endpoint (BYO key).

Base URL

https://agentic.dxa.io.vn

Authentication

Each session maps to a Durable Object instance, identified via `?session=<id>` or the `x-agent-session` header. DXA Identity SSO is on the roadmap. OpenAI-compatible models require a server-side `MODEL_API_KEY` secret.

Agent

POST /api/chat

Send a message, receive a streamed response (with tool calling)

Auth: Per session (`?session=` or `x-agent-session` header)

Body parameters

Field	Type	Description
`message`*	`string`	User message
`route`	`object`	Model route (provider/model/useGateway…)

Example request

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));
}

Example response

// 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…"

Error codes

400 Empty message / body not JSON

GET /api/state

Get session state (route, system prompt, message history)

Auth: Per session

Example response

{
  "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

Update session config (model route / system prompt / tenant)

Auth: Per session

Body parameters

Field	Type	Description
`route`	`object`	Model route
`systemPrompt`	`string`	System prompt
`tenant`	`string`	Tenant id

Example response

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

POST /api/reset

Clear the session conversation history

Auth: Per session

Example response

{ "ok": true }

Business tools

POST tools (qua /api/chat)

Tools the agent can call while handling a message

Auth: Per session

Example response

// 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ộ