本技能适用于同一进程内运行并发请求、工作池、异步任务、goroutine 或多个智能体的场景,核心是把 scope 栈的所有权视为请求边界的一部分。每个独立请求、智能体或工作流都应拥有自己的 scope 栈;不要在不相关的并发工作间共享同一个可变栈,否则会产生共享祖先与共享的 scope 局部中间件。
嵌入式 scope 模型:始终存在一个根 scope,压入的 scope 在其下形成父子树。scope 层级决定事件归属、生命周期边界,以及 scope 局部中间件与订阅者的可见性。标准 scope 类型包括 Agent、Function、Tool、Llm、Retriever、Embedder、Reranker、Guardrail、Evaluator、Custom 与 Unknown。当 scope 代表请求、任务或有意义的结果边界时,其开始与结束事件可携带语义输入输出载荷。scope 局部的注册会在所属 scope 关闭时消失,适合不应超过请求或智能体运行生命周期的行为。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 下;scope 局部中间件跨请求泄漏;工作线程在没有预期活动 scope 的情况下运行;集成未显式初始化栈就激活 NeMo Relay;跨越异步任务、goroutine 或 JS worker 边界后仍依赖线程局部栈。相关技能包括 nemo-relay-instrument-calls、nemo-relay-plugin-observability 与 nemo-relay-debug-runtime-integration。