nemo-relay-instrument-context-isolation

使用上下文隔离

当应用运行并发请求、工作线程池、异步任务、goroutine，或在同一进程中运行多个 Agent 时，使用此技能。 将作用域栈的所有权视为请求边界的一部分。

核心规则

每个独立请求、Agent 或工作流都需要自己的作用域栈。除非希望共享祖先关系和作用域本地中间件，否则不要让无关的并发工作共享同一个可变栈。

嵌入式作用域模型

• 根作用域始终存在，推入的作用域会在其下方形成父子树。
• 作用域层级决定事件的父子关系、生命周期边界，以及作用域本地中间件和订阅者的可见性。
• 标准作用域类型包括 Agent、Function、Tool、Llm、 Retriever、Embedder、Reranker、Guardrail、Evaluator、Custom 和 Unknown。
• 当作用域代表请求、任务或有意义的结果边界时，作用域开始和结束事件可以携带语义化的 input 和 output 负载。
• 拥有作用域关闭时，其作用域本地注册项也会消失；对于不应超出请求或 Agent 运行生命周期的行为，请使用这些注册项。
• 对于重试、检查点、中断和并非完整跨度的重要状态转换，标记事件很有用。

各语言默认做法

• Python：通过 get_scope_stack() 和 contextvars 依赖任务本地行为；若工作离开当前执行上下文，则显式传递上下文
• Rust core：当集成需要显式管理栈所有权时，使用 create_scope_stack()、 current_scope_stack() 和 set_thread_scope_stack(...) 等运行时辅助函数
• Go：使用 NewScopeStack() 和 ScopeStack.Run(...)，以确保 goroutine 安全
• Node.js：使用 createScopeStack() 和 setThreadScopeStack(...)，为当前执行路径显式创建并设置作用域栈

常见故障

• 来自不同请求的事件显示在同一个根 UUID 下
• 作用域本地中间件泄漏到其他请求
• 工作线程中的工作运行时没有预期的活动作用域
• 集成在未显式初始化栈的情况下激活 NeMo Relay
• 在跨越异步任务、goroutine 或 JS 工作线程边界后，仍依赖线程本地栈

相关技能

• nemo-relay-instrument-calls
• nemo-relay-plugin-observability
• nemo-relay-debug-runtime-integration