Undead Agent SDK 與 Replay

最後更新：2026-05-25

入口

• src/agent-sdk：fetch-based TypeScript client
• src/agent-sdk/node：Node.js replay logger
• scripts/agent-starter-bot.ts：最小可跑 bot

快速執行

``bash UNDEAD_API_KEY=<key> npm run agent:starter ``

可選環境變數：

• UNDEAD_API_BASE：預設 http://localhost:3000
• UNDEAD_BOT_ID：replay 中的 bot id
• UNDEAD_BOT_NAME：若尚未建立角色，starter bot 會用這個名稱建立
• UNDEAD_BOT_PROFESSION：預設 drifter
• UNDEAD_REPLAY_PATH：指定 JSONL replay 輸出位置

Replay 格式

Replay 使用 JSONL，每行一個事件：

• observation：GET /api/agent/state 的摘要與可選完整 payload
• decision：bot 本輪意圖、理由、信心與輸入線索
• action_submitted：已送出的 action id 與 alias
• action_result：GET /api/v1/actions 的佇列 / resolved 回讀
• api_error：HTTP status、API error code、錯誤細節
• debug：bot 自訂診斷訊息

SDK 範例

```ts import { UndeadAgentClient, JsonlAgentReplayLogger } from './src/agent-sdk/node';

const client = new UndeadAgentClient({ baseUrl: 'http://localhost:3000', apiKey: process.env.UNDEAD_API_KEY!, botId: 'demo-bot', replayLogger: new JsonlAgentReplayLogger('agent-replays/demo.jsonl'), });

const state = await client.getState(); const terminal = await client.submitActionAndWait('move', { targetX: state.character.tileX + 1, targetY: state.character.tileY, }, { intent: 'safe_exploration_step', reason: 'adjacent tile selected by simple heuristic', }, { pollIntervalMs: 2_000, timeoutMs: state.gameConfig.tickIntervalMs * 3, });

if (terminal.outcome !== 'completed') { const refreshed = await client.getState(); console.log(terminal.reason, refreshed.agentIntel.recovery); } ```

Lifecycle helpers:

• getAction(id)：讀單一 action，不受 50 筆 feed 上限影響。
• waitForAction(id, options)：輪詢到 completed、failed 或以 result.cancelled 辨識出的 cancelled。
• submitActionAndWait(alias, body, decision, options)：提交後等待 terminal result。
• cancelAction(id)：只可取消仍為 queued 的 action，並沿用伺服器 AP 退款規則。

waitForAction 預設 10 分鐘 timeout，timeout 會拋出 UndeadAgentWaitTimeoutError，其中包含最後一次 action snapshot；SDK 不會無限重試或偷偷提交替代行動。失敗後應重新呼叫 getState()，根據 result.reason 與 agentIntel.recovery 重規劃。

測試

``bash npm run test:agent-sdk ``