AI Agent

client.aiAgent (TypeScript) / client.ai_agent (Python) cung cấp chat streaming, quản lý embedding, sinh parquet, và distributed tracing cho AI agents.

Để xem hướng dẫn chi tiết, tham khảo AI Agent trong hướng dẫn SDK.

---

Schema

StreamChatBody

Tham số để khởi tạo một phiên chat streaming.

Trường	Kiểu	Bắt buộc	Mô tả
assistant_id	string	✓	ID của AI agent để chat
messages	array	✓	Lịch sử hội thoại (cặp role + content)
id	string		ID phiên chat có sẵn để tiếp tục
model_id	string		Ghi đè mô hình LLM mặc định của agent
provider_id	string		Ghi đè nhà cung cấp LLM mặc định của agent
user_id	string		Định danh người dùng bên ngoài

Lưu ý

Định dạng phản hồi phụ thuộc vào trường streaming của agent (được đặt khi tạo qua createAiAgent), không phụ thuộc vào bất kỳ giá trị nào trong body này. Agent được tạo với streaming: true trả về Content-Type: text/event-stream (SSE — có thể phân tích bằng streamChatText / stream_chat_text). Agent với streaming: false (mặc định cho agent mới tạo) trả về Content-Type: text/plain với toàn bộ câu trả lời trong một chuỗi duy nhất.

StreamSubAgentChatBody

Trường	Kiểu	Bắt buộc	Mô tả
assistant_id	string	✓	ID của AI agent
session_id	string	✓	ID phiên cha
chat_id	string	✓	ID chat trong phiên
messages	array	✓	Tin nhắn hội thoại

---

Phương thức

Phương thức	TypeScript	Python	Mô tả
Stream chat	streamChat	stream_chat	Bắt đầu phiên chat streaming với AI agent — trả về Response thô
Stream chat (văn bản đã phân tích)	streamChatText	stream_chat_text	Bao bọc streamChat và trả về từng đoạn văn bản thuần được phân tích từ luồng sự kiện SSE (yêu cầu agent có streaming: true)
Stream chat sub-agent	streamSubAgentChat	stream_sub_agent_chat	Streaming chat trong phạm vi phiên sub-agent
Lấy lịch sử sub-agent	getSubAgentHistory	get_sub_agent_history	Lấy lịch sử tin nhắn của sub-agent chat
Danh sách chat	listChats	list_chats	Danh sách phiên chat của tổ chức
Lấy chat	getChat	get_chat	Lấy một phiên chat
Xóa chat	deleteChat	delete_chat	Xóa một phiên chat
Gợi ý prompt	getAgentPromptSuggestion	get_agent_prompt_suggestion	Lấy gợi ý prompt cho agent
Phân loại file	classifyFile	classify_file	Phân loại file vào danh mục
Gợi ý kiểu trường	suggestFieldTypes	suggest_field_types	Gợi ý JSON schema từ tài liệu mẫu
Xử lý embedding	processEmbedding	process_embedding	Nhúng file vào kho tri thức
Danh sách file embedding	listEmbeddingFiles	list_embedding_files	Danh sách các file đã nhúng
Lấy file embedding	getEmbeddingFile	get_embedding_file	Lấy một file đã nhúng
Xem trước file embedding	previewEmbeddingFile	preview_embedding_file	Xem trước nội dung đã nhúng
Cập nhật trạng thái embedding	updateEmbeddingFileStatus	update_embedding_file_status	Cập nhật trạng thái nhúng file
Xóa file embedding	deleteEmbeddingFile	delete_embedding_file	Xóa file khỏi kho tri thức
Sinh parquet	generateParquet	generate_parquet	Chuyển đổi mảng dữ liệu thành file parquet
Danh sách file parquet	listParquetFiles	list_parquet_files	Danh sách file parquet đã sinh
Xóa file parquet	deleteParquetFile	delete_parquet_file	Xóa file parquet theo tên
Lấy traces	getTraces	get_traces	Truy vấn distributed traces
Lấy trace	getTrace	get_trace	Lấy một trace theo ID
Lấy dịch vụ trace	getTraceServices	get_trace_services	Danh sách dịch vụ phát ra traces

---

streamChat / stream_chat

Trả về một HTTP Response thô. Body có dạng text/event-stream (khi agent có streaming: true) hoặc text/plain (khi streaming: false). Với trường hợp SSE, nên dùng helper streamChatText bên dưới — nó sẽ phân tích giúp bạn.

TypeScript

const res = await client.aiAgent.streamChat({
  assistant_id: "agent_id",
  messages: [{ role: "user", content: "Hello" }],
  user_id: "user_123",
});

if ((res.headers.get("content-type") ?? "").includes("text/event-stream")) {
  const reader = res.body!.getReader();
  const decoder = new TextDecoder();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    console.log(decoder.decode(value));   // raw SSE bytes
  }
} else {
  console.log(await res.text());          // full reply, plain text
}

Python

res = client.ai_agent.stream_chat({
    "assistant_id": "agent_id",
    "messages": [{"role": "user", "content": "Hello"}],
    "user_id": "user_123",
})

if "text/event-stream" in res.headers.get("content-type", ""):
    for line in res.iter_lines():
        if line:
            print(line)
else:
    print(res.text)

---

streamChatText / stream_chat_text

Wrapper tiện lợi bao quanh streamChat. Phân tích Vercel-AI-SDK UI-Message-Stream (data: {"type":"text-delta","delta":"..."}) và trả về từng đoạn văn bản dưới dạng chuỗi. Yêu cầu agent đã được tạo với streaming: true — nếu không, server trả về text/plain (không có dòng data:) và generator này trả về 0 chunk.

TypeScript

for await (const chunk of client.aiAgent.streamChatText({
  assistant_id: "agent_id",
  messages: [{ role: "user", content: "Hello" }],
})) {
  process.stdout.write(chunk);
}

Python

for chunk in client.ai_agent.stream_chat_text({
    "assistant_id": "agent_id",
    "messages": [{"role": "user", "content": "Hello"}],
}):
    print(chunk, end="", flush=True)

---

streamSubAgentChat / stream_sub_agent_chat

Stream chat trong phạm vi sub-agent trong một phiên cha.

TypeScript

const response = await client.aiAgent.streamSubAgentChat({
  assistant_id: "agent_id",
  session_id: "session_id",
  chat_id: "chat_id",
  messages: [{ role: "user", content: "Follow-up question" }],
});

Python

response = client.ai_agent.stream_sub_agent_chat({
    "assistant_id": "agent_id",
    "session_id": "session_id",
    "chat_id": "chat_id",
    "messages": [{"role": "user", "content": "Follow-up question"}],
})

---

listChats / list_chats

TypeScript

const { data: chats } = await client.aiAgent.listChats({
  organization_id: "org_id",
  user_id: "user_123",
  limit: 20,
});

Python

result = client.ai_agent.list_chats(
    organization_id="org_id",
    user_id="user_123",
    limit=20,
)
chats = result.get("data", [])

---

getSubAgentHistory / get_sub_agent_history

TypeScript

const history = await client.aiAgent.getSubAgentHistory({
  session_id: "session_id",
  chat_id: "chat_id",
});

Python

history = client.ai_agent.get_sub_agent_history(
    session_id="session_id",
    chat_id="chat_id",
)

---

processEmbedding / process_embedding

Nhúng file vào kho tri thức của agent.

TypeScript

const result = await client.aiAgent.processEmbedding({
  fileId: "file_id",
  options: { chunk_size: 512 },
});

Python

result = client.ai_agent.process_embedding(
    file_id="file_id",
    options={"chunk_size": 512},
)

---

classifyFile / classify_file

Phân loại file vào danh mục định sẵn dựa trên nội dung.

TypeScript

const result = await client.aiAgent.classifyFile({ fileId: "file_id" });
console.log(result.category);

Python

result = client.ai_agent.classify_file(file_id="file_id")
print(result.get("category"))

---

suggestFieldTypes / suggest_field_types

Phân tích tài liệu mẫu và gợi ý JSON schema với kiểu dữ liệu cho trích xuất tài liệu.

TypeScript

const schema = await client.aiAgent.suggestFieldTypes({
  fileUrls: ["https://example.com/invoice.pdf"],
});
console.log(schema);

Python

schema = client.ai_agent.suggest_field_types(
    file_urls=["https://example.com/invoice.pdf"],
)
print(schema)

---

previewEmbeddingFile / preview_embedding_file

Xem trước nội dung của file đã nhúng trước khi xử lý.

TypeScript

const preview = await client.aiAgent.previewEmbeddingFile({ fileId: "file_id" });
console.log(preview);

Python

preview = client.ai_agent.preview_embedding_file(file_id="file_id")
print(preview)

---

updateEmbeddingFileStatus / update_embedding_file_status

Cập nhật trạng thái xử lý của một file nhúng.

TypeScript

const result = await client.aiAgent.updateEmbeddingFileStatus("file_id", "completed");
console.log(result);

Python

result = client.ai_agent.update_embedding_file_status("file_id", "completed")
print(result)

---

generateParquet / generate_parquet

Chuyển đổi mảng bản ghi thành file parquet để nhập dữ liệu có cấu trúc.

TypeScript

const result = await client.aiAgent.generateParquet({
  data: [{ name: "Alice", score: 95 }, { name: "Bob", score: 87 }],
  fileName: "scores",
  folderName: "results",
});

Python

result = client.ai_agent.generate_parquet(
    data=[{"name": "Alice", "score": 95}, {"name": "Bob", "score": 87}],
    file_name="scores",
    folder_name="results",
)

---

getTraces / get_traces

Truy vấn distributed traces để debug và quan sát.

TypeScript

const traces = await client.aiAgent.getTraces({
  service: "ai-agent",
  limit: 50,
  timeRange: 3600,
  orgId: "org_id",
});

Python

traces = client.ai_agent.get_traces(
    service="ai-agent",
    limit=50,
    time_range=3600,
    org_id="org_id",
)