SDK 教學 · 7 / 10
處理回合結果
請以 structured result fields 進行 rendering 與 automation。不要解析 assistant prose 或 raw provider error 來決定 retry、billing 或 credential behavior。
客製化深度
層級 3 · Structured result handling
託管深度
任何 conversation-engine host
文件狀態
支援的 SDK 邊界
前置假設
- 產品在 turn settled 後需要 deterministic behavior。
- Provider diagnostics 不可未經處理就跨越 public API boundary。
- 產品專屬 response schema 會從 Heddle host-facing result 投影而來。
Heddle 負責
- 回傳 persisted summary、安全 failure category、updated session、trace path、session artifacts 與 current-turn tool results。
- 正規化 model failure，不包含 credential 或 raw provider message。
- 區分 quota exhaustion 與可重試的 rate limiting。
產品端負責
- 把 Heddle outcome 與 failure code 對應到 product API error、UI state、metric 與 retry policy。
- 跨越 transport boundary 時，只投影預定公開的 fields。
- 讓 trace file 與 internal tool payload 留在產品 authorization 後方。
讀取 host-facing result
const result = await engine.turns.submit({
sessionId,
prompt,
host,
})
console.log(result.outcome)
console.log(result.summary)
console.log(result.failure)
console.log(result.session.id)
console.log(result.traceFile)
console.log(result.artifacts.map((artifact) => artifact.id))
console.log(result.toolResults.map((entry) => entry.call.tool))每個 field 有不同責任：
| Field | 用途 |
|---|---|
outcome | Runtime execution 結束的原因。 |
summary | 該 turn 持久化的 assistant summary。 |
failure | 穩定且安全的 model-failure classification。 |
session | 更新後的 persisted conversation record。 |
traceFile | 選用的本機 lower-level evidence 路徑。 |
artifacts | 目前與 session 關聯的 artifacts。 |
toolResults | 本次 turn 已完成的 calls，包含 input、result、duration、step 與 timestamp。 |
依 failure code 分支，不要解析 prose
switch (result.failure?.code) {
case 'authentication':
throw new ProductModelCredentialError()
case 'quota':
throw new ProductModelQuotaError()
case 'rate_limit':
scheduleBoundedRetry()
break
}目前的 model failure codes：
authentication— credential 被拒絕或沒有可用 credential；permission— credential 存在，但無權執行 request；quota— billing/quota capacity 已耗盡，外部狀態改變前不可重試；rate_limit— 暫時性 throttling，可依產品 policy 重試；request— 無效或 provider 不支援的 request；transport— network 或 provider transport failure；empty_response— 模型未回傳可用 response；unknown— 無法提供更安全、穩定的 classification。
failure 絕不包含 credential 或 raw provider message。不要在 summary 中尋找 error string；summary 是 user-facing assistant content，可以獨立變動。
投影 public result
Turn 跨越 API boundary 時，建立明確的 product schema：
const publicResult = {
outcome: result.outcome,
message: result.summary,
failureCode: result.failure?.code,
artifacts: result.artifacts.map(({ id, kind, title }) => ({
id,
kind,
title,
})),
}預設不要把 traceFile、未受限制的 tool input/result、storage path 或 provider diagnostic 傳給不可信任的 client。
只有需要更深證據時才使用 trace
大多數產品行為應使用 turn-result fields 與 semantic activity。只有 authorized operator 需要 audit evidence、debugging 或 custom analysis 時，才讀取 raw trace。