nemo-relay-instrument-calls

对工具调用和大模型调用进行埋点

当应用已有工具函数或模型／提供方调用，并需要通过 NeMo Relay 正确运行时，使用此技能。 添加 Relay 生命周期捕获的同时，保持原有可调用对象的行为稳定。

默认指南

• 在自然的 Agent、请求、工作流或图边界周围设置作用域。
• 优先使用托管执行 API：
  • Rust：tool_call_execute(ToolCallExecuteParams::builder()...)、 llm_call_execute(LlmCallExecuteParams::builder()...)
  • Python：tools.execute(...)、llm.execute(...)
  • Node.js：toolCallExecute(...)、llmCallExecute(...)
  • Go：tools.Execute(...)、llm.Execute(...) 或顶层包装器
• 仅当宿主框架无法通过托管执行辅助函数包装时，才使用手动生命周期 API。

嵌入式运行时语义

• 托管工具和大模型执行会先对原始输入运行条件执行护栏。如果输入被拒绝，运行时会发出独立的标记事件，且不会运行请求拦截器或可调用对象。
• 请求拦截器在条件执行护栏之后运行，并会重写实际传递给执行拦截器和回调的输入。
• 请求清理护栏仅影响发出的开始事件载荷，不会重写调用方可见的请求或参数。
• 执行拦截器通过中间件 next 模式包装回调，也可以通过返回自己的结果来短路执行。
• 响应清理护栏仅影响发出的结束事件载荷。返回给应用代码的值仍是原始回调或执行拦截器的结果。
• 如果在发出开始事件后执行失败，运行时仍会发出结束事件，但不包含语义输出载荷。
• 工具调用是具有 JSON 兼容参数和结果的命名操作。让原有工具可调用对象负责业务逻辑；由 NeMo Relay 负责生命周期事件、中间件和元数据。
• 大模型调用使用由元数据和内容组成的 LLMRequest。如果模型名称和稳定的调用标识符对跟踪导出或诊断很重要，请传入它们。
• 手动生命周期 API 适用于已经负责执行的框架适配器。使用这些 API 时，每个开始调用都必须对应一个结束或错误路径，并显式提供相关语义载荷。
• request_intercepts(...) 和 conditional_execution(...) 等部分中间件 API 适用于高级适配器，可在手动调用提供方之前使用一类中间件。
• 流式大模型包装器会收集数据块，并在流结束时完成响应；提前丢弃流可能导致终结器和订阅者无法看到完整输出。

检查清单

• 在首次工具或大模型调用之前选定作用域边界
• 包装现有工具函数，同时保留其原有参数和结果
• 在合适的抽象层包装现有大模型／提供方调用
• 在有用之处附加可选元数据、属性或模型名称
• 如果调用跨越线程或异步任务，则处理上下文传播

以下情况请使用其他技能

当任务需要相邻工作流时，请选择其他技能：

• 对于跟踪、ATIF 或导出设置，请使用 nemo-relay-plugin-observability。
• 对于缺失事件或加载失败的调试，请使用 nemo-relay-debug-runtime-integration。
• 对于按请求隔离或工作池指南，请使用 nemo-relay-instrument-context-isolation。
• 对于可复用、由配置激活的运行时行为，请使用 nemo-relay-plugin-build。

相关技能

以下技能适用于相邻工作流：

• 使用 nemo-relay-get-started 开始上手。
• 使用 nemo-relay-instrument-typed-wrappers 添加类型化包装器。
• 使用 nemo-relay-plugin-observability 配置导出。
• 使用 nemo-relay-plugin-build 打包可复用行为。