Agent 生命周期（5 函数）
xworkAgentConfigInit / Create / Destroy 生命周期
配置清零（工作区根、探索模式、预算）→ 创建不透明 Agent 句柄 → 销毁释放全部资源。配置含工作区策略：内部探索（零外部依赖）或委托 rg/fd 外部工具。
void xworkAgentConfigInit(xwork_agent_config* pConfig);
xwork_agent* xworkAgentCreate(const xwork_agent_config* pConfig);
void xworkAgentDestroy(xwork_agent* pAgent);
xworkAgentWorkspaceRoot 查询
返回 Agent 的工作区根路径（借用指针）——工具读写沙箱边界。
运行控制（6 函数）
xworkAgentRunBegin / Run / RunEnd 回合
回合三段式：Begin 发起任务（含提示词）、Run 驱动直到返回 false（回合结束）、RunEnd 释放回合状态。Run 内部自动调 xllm 发请求、解析工具调用、执行工具并回填。
xwork_agent_run xworkAgentRunBegin(xwork_agent* p, const char* sPrompt);
bool xworkAgentRun(xwork_agent* p, xwork_agent_run* pRun);
void xworkAgentRunEnd(xwork_agent* p, xwork_agent_run* pRun);
xworkAgentCancel / Resume 控制
取消进行中的回合（工具执行中断、状态保存）；恢复被取消或中断的回合。
工具注册（10 函数）
xworkAgentRegisterBuiltinTools / RegisterBuiltinReadOnlyTools 内建
一键注册内建工具集（读写文件、列目录、glob 等）；ReadOnly 变体只含只读子集（子 Agent / 探索场景）。
xworkAgentRegisterTool / UnregisterTool / UnregisterToolsBySource 自定义
注册自定义工具（名称、描述、参数 schema、回调）；按句柄或来源批量注销。工具注册有代际号（ToolRegistryGeneration），运行中热更工具集不中断进行中的回合。
bool xworkAgentRegisterTool(xwork_agent* p, const xwork_tool_def* pTool);
bool xworkAgentUnregisterTool(xwork_agent* p, const char* sName);
xworkAgentToolAt / ToolCount / ToolRegistryGeneration 查询
枚举已注册工具（供审批 UI 列清单）；代际号用于热更检测。
子 Agent 类型（5 函数）
xworkAgentRegisterSubagentType / UnregisterSubagentType / SubagentTypeCount 类型系统
注册/注销/枚举子 Agent 类型——每种类型可绑定不同工具集与权限档。配 RunReadOnlySubagent 派生只读子 Agent 形成多 Agent 拓扑。
xworkAgentRunReadOnlySubagent 派生
以指定类型派生一个只读子 Agent 并运行单回合（探索/检索场景）。
通知与查询（8 函数）
xworkAgentTakeTaskNotices 通知
取走积压的任务通知（工具调用开始/结束、产物生成、状态变更）——审批 UI 与前端轨迹的数据源，一次批量最多 N 条。
uint32 xworkAgentTakeTaskNotices(xwork_agent* p, xwork_task_notice* pNotices, uint32 iCapacity);
压缩（3 函数）
xworkAgentCompact / MaybeCompact / CommitCompaction 上下文收敛
手动/自动（MaybeCompact 按预算阈值）触发上下文压缩，与 xllm-session 压缩算子联动；Commit 确认压缩结果（read 标记保证工具产物不丢）。
xworkAgentDefaultCompactionOps 配置
获取默认压缩算子配置（75%/95% 两档阈值）。
实战范例见仓库
release/agent-demo/（xwork + xllm + xllm-session + 站点 VFS 四库组合）。完整源码见 lib/xwork。