AI 代理

client.aiAgent (TypeScript) / client.ai_agent (Python) 提供聊天串流、嵌入管理、parquet 生成與 AI 代理的分散式追蹤。

如需逐步指南，請參閱 SDK 指南中的 AI Agent。

---

結構定義

StreamChatBody

初始化串流聊天會話的參數。

欄位	類型	必填	說明
assistant_id	string	✓	要聊天的 AI 代理 ID
messages	array	✓	對話歷史記錄（role + content 成對）
id	string		要繼續的現有聊天會話 ID
model_id	string		覆寫代理的預設 LLM 模型
provider_id	string		覆寫代理的預設 LLM 提供者
user_id	string		外部使用者識別碼

注意

回應格式取決於代理的 streaming 欄位（在建立時透過 createAiAgent 設定），而非此 body 中的任何內容。以 streaming: true 建立的代理會回傳 Content-Type: text/event-stream（SSE — 可由 streamChatText / stream_chat_text 解析）。streaming: false 的代理（新建立代理的預設值）會回傳 Content-Type: text/plain，完整回覆為單一字串。

StreamSubAgentChatBody

欄位	類型	必填	說明
assistant_id	string	✓	AI 代理 ID
session_id	string	✓	父會話 ID
chat_id	string	✓	會話中的聊天 ID
messages	array	✓	對話訊息

---

方法

方法	TypeScript	Python	說明
串流聊天	streamChat	stream_chat	與 AI 代理開始串流聊天會話 — 傳回原始 Response
串流聊天（解析後文字）	streamChatText	stream_chat_text	包裝 streamChat，並逐一產出從 SSE 事件串流解析出的純文字片段（需要代理設定 streaming: true）
串流子代理聊天	streamSubAgentChat	stream_sub_agent_chat	在子代理會話範圍內進行串流聊天
取得子代理歷史	getSubAgentHistory	get_sub_agent_history	擷取子代理聊天的訊息歷史
列出聊天	listChats	list_chats	列出組織的聊天會話
取得聊天	getChat	get_chat	取得單一聊天會話
刪除聊天	deleteChat	delete_chat	刪除聊天會話
提示建議	getAgentPromptSuggestion	get_agent_prompt_suggestion	取得代理的建議提示
分類檔案	classifyFile	classify_file	將檔案分類至類別
建議欄位類型	suggestFieldTypes	suggest_field_types	從範例文件建議 JSON 結構
處理嵌入	processEmbedding	process_embedding	將檔案嵌入知識庫
列出嵌入檔案	listEmbeddingFiles	list_embedding_files	列出所有已嵌入的檔案
取得嵌入檔案	getEmbeddingFile	get_embedding_file	取得單一已嵌入的檔案
預覽嵌入檔案	previewEmbeddingFile	preview_embedding_file	預覽已嵌入的內容
更新嵌入狀態	updateEmbeddingFileStatus	update_embedding_file_status	更新檔案嵌入狀態
刪除嵌入檔案	deleteEmbeddingFile	delete_embedding_file	從知識庫移除檔案
產生 parquet	generateParquet	generate_parquet	將資料陣列轉換為 parquet 檔案
列出 parquet 檔案	listParquetFiles	list_parquet_files	列出已生成的 parquet 檔案
刪除 parquet 檔案	deleteParquetFile	delete_parquet_file	依名稱刪除 parquet 檔案
取得追蹤清單	getTraces	get_traces	查詢分散式追蹤
取得追蹤	getTrace	get_trace	依 ID 取得單一追蹤
取得追蹤服務	getTraceServices	get_trace_services	列出發出追蹤的服務

---

streamChat / stream_chat

傳回原始 HTTP Response。其 body 為 text/event-stream（當代理設定 streaming: true 時）或 text/plain（當 streaming: false 時）。SSE 的情況建議改用下方的 streamChatText 輔助方法 — 它會替你完成解析。

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));   // 原始 SSE 位元組
  }
} else {
  console.log(await res.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

streamChat 的便利包裝。它會解析 Vercel-AI-SDK UI-Message-Stream（data: {"type":"text-delta","delta":"..."}），並將每個文字片段以字串形式逐一產出。需要代理以 streaming: true 建立 — 否則伺服器會回傳 text/plain（沒有 data: 行），此產生器將產出 0 個片段。

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

在父會話內，進行限定於子代理範圍的串流聊天。

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

將檔案嵌入代理的知識庫。

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

根據檔案內容將其分類至預定義類別。

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

分析範例文件並建議用於文件擷取的 JSON 結構與欄位類型。

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

在處理前預覽已嵌入檔案的內容。

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

更新嵌入檔案的處理狀態。

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

將記錄陣列轉換為 parquet 檔案以進行結構化資料匯入。

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

查詢分散式追蹤以進行除錯和可觀測性。

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",
)