Creating assistants

Assistants (agents) are chat backends that you implement and register in Admin → Agents. Each has an alias and base URL (e.g. http://your-server.com:8020 — no trailing slash). Users choose an assistant from the sidebar; the portal provides the chat UI, embed, and multi-language.

Required endpoints

1. GET /metadata

Return JSON with at least name; recommended: description, capabilities, supported_models, sample_prompts, status ("active" | "inactive").

Example call:

curl -s http://your-server:8020/metadata

Example response (JSON):

{
  "name": "Document Assistant",
  "description": "Search and summarize documents",
  "capabilities": ["search", "summarize"],
  "supported_models": [
    { "model_id": "gpt-4o-mini", "name": "GPT-4o Mini", "accepted_file_types": ["pdf", "docx"] }
  ],
  "sample_prompts": ["Summarize an article about AI"],
  "provided_data_types": [{ "type": "documents", "description": "List of documents" }],
  "status": "active"
}

2. POST /ask — Request and response (important for developers)

Request body the Portal sends: session_id, model_id, user, prompt, output_type, and context.

• output_type — output_type — The Portal always sends "markdown". If your agent API validates output type, it must accept "markdown". Using only "text" as valid will cause errors (e.g. "Invalid output type: text") when users chat from the portal.
• context — context — May include language, project, extra_data.document (file URLs), history (previous messages).

Response your agent must return: JSON with status: "success" and at least one of content_markdown, answer, or content (string). Prefer content_markdown for rich display. Without these, the Portal shows "Agent error" to the user.

Base URL: Use no trailing slash (e.g. http://host:8020). A trailing slash can cause 404 on /ask when the portal calls your agent.

Example call:

curl -X POST 'http://your-server:8020/ask' \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"test-123","model_id":"gpt-4o-mini","user":"admin-test","prompt":"Hello","output_type":"markdown","context":{}}'

Example request body (Portal sends):

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "model_id": "gpt-4o-mini",
  "user": "https://portal.example.com/api/users/email/user@example.com",
  "prompt": "Summarize this document",
  "output_type": "markdown",
  "context": {
    "language": "en",
    "extra_data": { "document": ["https://.../file.pdf"] },
    "history": []
  }
}

Example response (agent must return):

{
  "status": "success",
  "content_markdown": "## Summary\n\nSummary content here..."
}

3. GET /data (optional)

Use when your agent has data to list (documents, experts, …). The Portal calls with query type (e.g. documents, experts).

Example call:

curl -s 'http://your-server:8020/data?type=documents'

Example response (JSON):

{
  "status": "success",
  "data_type": "documents",
  "items": [
    { "id": "1", "title": "Document A", "url": "https://..." },
    { "id": "2", "title": "Document B", "url": "https://..." }
  ]
}

4. Huong dan cho dev: tao Tools va gan vao tro ly

Goi y thuc te la tach phan xu ly thanh cac Tool nho, sau do endpoint/ask se goi Tool tuong ung theo y dinh cua nguoi dung. Cach nay giup de test, de debug va tai su dung trong nhieu tro ly.

1. Viet tung Tool thanh ham don (input JSON, output JSON ro rang).
2. Viet lop hoac ham toolManifest de mo ta schema input.
3. Trong POST /ask, map prompt hoac intent sang Tool can goi.
4. Tra ket qua ve content_markdown cho AI-Portal render.

4.1 Mau Tool HelloWorld (TypeScript)

export function helloWorldTool(input: { name?: string; language?: "vi" | "en" } = {}) {
  const finalName = input.name?.trim() || "developer";
  const language = input.language ?? "vi";
  const greeting = language === "en" ? `Hello, ${finalName}!` : `Xin chao, ${finalName}!`;

  return {
    ok: true,
    message: `${greeting} This response comes from helloWorldTool.`
  };
}

4.2 Gan Tool vao endpoint /ask

app.post("/ask", async (req, res) => {
  const { prompt } = req.body;

  if (prompt?.toLowerCase().includes("hello")) {
    const toolResult = helloWorldTool({ name: "AI-Portal user", language: "vi" });
    return res.json({
      status: "success",
      content_markdown: `## Tool result\n\n${toolResult.message}`
    });
  }

  return res.json({
    status: "success",
    content_markdown: "Khong tim thay Tool phu hop cho prompt nay."
  });
});

4.3 Dong goi Tool bang Vite (library mode)

Voi Tool viet bang TypeScript, ban co the dung Vite de build file phan phoi gon nhe:

npm install
npm run build
npm run pack:tgz

Trong mau ben duoi, vite.config.ts da duoc cau hinh o che do build.lib de xuat ra file .mjs hoac.umd.js.

4.4 Tai bo mau HelloWorld Tool

• Tai hello-world-tool-vite.zip — Mau chao don co schema input, build ra ESM va UMD.
• Tai hello-time-tool-vite.zip — Mau tra ve thoi gian hien tai theo timezone.
• Xem source truc tiep: hello-world-tool-vite, hello-time-tool-vite.

Registration & testing

Admin → Agents → Add: alias (e.g. papers), base URL, icon. You can set a routing hint so the Central assistant selects this agent when the user does not choose one. Use Test API in Admin to send a sample request.

Full request/response examples and system APIs (user, project) that the portal sends in context: frontend/docs/README.md (Agent API) and docs/DEVELOPERS.md in the repository.