用途:当应用在同一进程内运行并发请求、工作池、异步任务、goroutine 或多个智能体时,使用本技能设置并推理 NeMo Relay 的 scope 栈隔离。
核心规则:每个独立请求、智能体或工作流都需要自己的 scope 栈。除非确实需要共享祖先与作用域局部中间件,否则不要让不相关的并发工作共用一个可变栈。
嵌入作用域模型:始终存在一个根作用域,压入的作用域在其下形成父子树。作用域层级决定事件父子关系、生命周期边界,以及作用域局部中间件与订阅者的可见性。标准作用域类型包括 Agent、Function、Tool、Llm、Retriever、Embedder、Reranker、Guardrail、Evaluator、Custom 和 Unknown。当作用域代表请求、任务或有意义的结果边界时,作用域开始与结束事件可携带语义输入输出负载。作用域局部注册在所属作用域关闭时消失,适合不应超出请求或智能体运行生命周期的行为。Mark 事件适用于重试、检查点、中断及非完整 span 的重要状态转换。
各语言默认做法:Python 依赖 get_scope_stack() 与 contextvars 的任务局部行为,工作离开当前执行上下文时需显式传播;Rust 核心在集成需要显式栈所有权时使用 create_scope_stack()、current_scope_stack() 和 set_thread_scope_stack(...);Go 使用 NewScopeStack() 与 ScopeStack.Run(...) 保证 goroutine 安全;Node.js 用 createScopeStack() 与 setThreadScopeStack(...) 为当前执行路径显式创建并设置 scope 栈。
常见失败:不同请求的事件出现在同一根 UUID 下;作用域局部中间件跨请求泄漏;工作线程任务在缺少预期活动作用域下运行;集成未显式初始化栈就激活 NeMo Relay;跨越异步任务、goroutine 或 JS worker 边界后仍依赖线程局部栈。
相关技能:nemo-relay-instrument-calls、nemo-relay-setup-observability、nemo-relay-debug-runtime-integration。