Generated banner for Nemo Relay Debug Runtime Integration
Generated logo for Nemo Relay Debug Runtime Integration

Nemo Relay Debug Runtime Integration

NVIDIAOfficialCreated by NVIDIA Corporation and Affiliates

  • Skill
  • Review and audit
  • Software development
  • Apache-2.0
  • Medium risk

From the author

Use this skill when NeMo Relay is installed or imported but application-side runtime behavior is missing or incorrect, including load failures, inactive scopes, missing events, and plugin or adaptive wiring problems.
— the description by NVIDIA Corporation and Affiliates

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured troubleshooting framework for diagnosing and resolving runtime failures when using NeMo Relay. It focuses on identifying issues related to native artifact loading, scope management, event registration, and plugin configuration, helping developers isolate whether a failure stems from the build environment, the application's lifecycle management, or specific integration components.

What it does

  • Provides a diagnostic checklist for verifying runtime layer health.
  • Categorizes common failure classes including native extension and library loading issues.
  • Offers an embedded troubleshooting matrix for specific language bindings like Python, Node.js, and Go.
  • Addresses scope stack management and concurrency-related integration problems.
  • Guides the verification of event registration, middleware ordering, and adaptive component initialization.
  • Assists in debugging export failures for OpenTelemetry and OpenInference.

When to use it

  • When NeMo Relay is installed but application runtime behavior is missing or incorrect.
  • When encountering load failures for native artifacts or bindings.
  • When events are missing or scope stacks appear inactive during execution.
  • When troubleshooting plugin wiring or adaptive component behavior.
  • When debugging issues with middleware registration or event subscriber lifecycle.

Advantages

  • Systematic approach to isolating failures before modifying configurations.
  • Language-specific troubleshooting steps for Python, Node.js, and Go.
  • Clear guidance on complex topics like scope stack isolation and concurrency.
  • Helps distinguish between build-time environment issues and runtime logic errors.

Usage examples

“My Python application is failing to load the NeMo Relay native extension, what should I check?”
The agent will guide you to rebuild the virtual environment and native extension using the recommended sync process and verify the import from the application environment.
“I am not seeing any lifecycle events in my NeMo Relay integration, why?”
The agent will help you verify if you are using managed execute helpers or balanced manual start/end APIs, and check if your subscribers are registered before events are emitted.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/nvidia/nemo-relay-debug-runtime-integration/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip nemo-relay-debug-runtime-integration.zip -d .agents/skills

Documentation by NVIDIA Corporation and Affiliates

Debug Runtime Integration

Use this skill when NeMo Relay is present in the application but something is not working. Start by proving which runtime layer is failing before changing configuration.

First Checks

  • Can the binding or native artifact load?

  • Is there an active scope when the failing call runs?

  • Is the work happening on the expected scope stack?

  • Is the subscriber/exporter/plugin configuration actually active?

  • Did the app choose the right public API layer: managed execute vs manual lifecycle vs typed wrappers vs adaptive/plugins?

Common Failure Classes

  • Python native extension missing

  • Go dynamic library not on the loader path

  • Node native addon not built or not loading

  • Execute call outside a scope

  • Missing events because registration never happened

  • Concurrency causing the wrong scope stack to be active

  • Adaptive component never initialized or config validation ignored

Embedded Troubleshooting Matrix

  • Rust build failure: run the narrowest core build first, then expand to the affected binding or workspace command.

  • Python import failure: rebuild the virtual environment and native extension with uv sync, then run a small Python test or import check from the same environment as the application.

  • Node.js addon failure: reinstall and rebuild the native addon from the Node binding package before debugging application code.

  • Go loader failure: build the release FFI shared library and point both the linker and runtime loader at the release output directory; use the macOS dynamic-library path variable (DYLD_LIBRARY_PATH) on macOS.

  • Scope stack empty: the work is outside an active scope or crossed a thread, task, goroutine, or worker boundary without the intended stack.

  • Work leaks across requests: separate requests are sharing one scope stack; create a fresh stack per independent request or agent.

  • Middleware missing or ordered incorrectly: check global vs scope-local registration, active scope ancestry, names, and priority values.

  • Subscriber missing events: register before the events are emitted; for scope-local subscribers, ensure the current scope is the owner or descendant.

  • Event fields missing: managed helpers populate semantic fields; manual lifecycle calls require explicit params for input, output, model names, and tool call IDs.

  • ATIF empty or mixed: register before work starts, use one exporter per run or clear between runs, and separate concurrent agents by root scope.

  • Provider payload conversion failure: convert non-JSON provider objects, SDK handles, callbacks, streams, or class instances with explicit codecs.

  • Plugin validation failure: validate config independently from runtime registration and check required fields, value types, defaults, and config source.

  • Adaptive behavior unchanged: confirm instrumentation emits events, the adaptive component is enabled, policy allows the behavior, and the call path reaches the configured component.

  • OpenTelemetry or OpenInference export failure: first identify the Relay version. For 0.6, check the separate exporter, http_binary versus grpc, endpoint, headers, target support, and an active Tokio runtime for native gRPC. For 0.7, check the typed projection, endpoint, headers, TLS, and target support; the subscriber owns the native gRPC runtime.

  • Callback succeeded but no lifecycle events appear: confirm the integration uses managed execute helpers or balanced manual start/end APIs, not only the underlying business callback.

  • nemo-relay-get-started

  • nemo-relay-instrument-context-isolation

  • nemo-relay-plugin-adaptive-tuning

  • nemo-relay-plugin-build

Files

evals/evals.json

[
  {
    "id": "nemo-relay-debug-runtime-integration-001",
    "question": "I need help with nemo-relay-debug-runtime-integration. My Python app fails to import the NeMo Relay native extension with a 'ModuleNotFoundError' even though I installed the package. How do I fix this?",
    "expected_skill": "nemo-relay-debug-runtime-integration",
    "expected_script": null,
    "ground_truth": "The agent used nemo-relay-debug-runtime-integration to diagnose the Python native extension import failure, recommending rebuilding the virtual environment and native extension with `uv sync` and verifying the import from the same environment as the application.",
    "expected_behavior": [
      "The agent read the nemo-relay-debug-runtime-integration SKILL.md before providing guidance",
      "The agent identified this as a Python import failure and referenced the troubleshooting matrix entry for rebuilding with `uv sync`",
      "The agent recommended running a small Python test or import check from the same environment as the application",
      "The agent suggested verifying the native extension was built correctly for the current platform",
      "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
    ]
  },
  {
    "id": "nemo-relay-debug-runtime-integration-002",
    "question": "I'm instrumenting my Node.js agent with NeMo Relay but no lifecycle events appear even though my business logic callbacks execute successfully. The managed execute helpers aren't being used — we just call the underlying functions directly. What's going wrong?",
    "expected_skill": "nemo-relay-debug-runtime-integration",
    "expected_script": null,
    "ground_truth": "The agent diagnosed the missing lifecycle events as caused by calling business callbacks directly without using managed execute helpers or balanced manual start/end APIs, and guided the user to adopt the correct API layer.",
    "expected_behavior": [
      "The agent identified the issue as matching the 'Callback succeeded but no lifecycle events appear' failure class from the troubleshooting matrix",
      "The agent explained that the integration must use managed execute helpers or balanced manual start/end APIs rather than only calling the underlying business callback",
      "The agent recommended switching to the managed execute API or adding explicit lifecycle start/end calls around the business logic",
      "The agent referenced the choice between managed execute vs manual lifecycle vs typed wrappers as a key decision point",
      "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
    ]
  },
  {
    "id": "nemo-relay-debug-runtime-integration-003",
    "question": "We have a Go microservice that handles concurrent requests. Each request creates a NeMo Relay scope, but we're seeing events from one request leaking into another request's trace. The scope stacks seem to be shared across goroutines. How do we isolate them?",
    "expected_skill": "nemo-relay-debug-runtime-integration",
    "expected_script": null,
    "ground_truth": "The agent diagnosed the cross-request event leakage as a scope stack sharing problem across goroutines and recommended creating a fresh scope stack per independent request or agent to achieve proper isolation.",
    "expected_behavior": [
      "The agent identified the problem as 'Work leaks across requests' where separate requests share one scope stack",
      "The agent explained that goroutine boundaries can cause the wrong scope stack to be active without explicit isolation",
      "The agent recommended creating a fresh scope stack per independent request or agent",
      "The agent referenced the nemo-relay-instrument-context-isolation skill as a related resource for further guidance",
      "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
    ]
  },
  {
    "id": "nemo-relay-debug-runtime-integration-004",
    "question": "How do I configure Kubernetes horizontal pod autoscaling based on custom Prometheus metrics for my Flask application?",
    "expected_skill": null,
    "expected_script": null,
    "ground_truth": "The agent recognized this as a Kubernetes/infrastructure scaling question unrelated to NeMo Relay runtime integration debugging and provided general Kubernetes HPA guidance without invoking the nemo-relay-debug-runtime-integration skill.",
    "expected_behavior": [
      "The agent did not invoke or reference the nemo-relay-debug-runtime-integration skill",
      "The agent addressed the Kubernetes HPA and Prometheus metrics question on its own merits",
      "The agent provided guidance about custom metrics adapters or HPA configuration without conflating it with NeMo Relay concerns",
      "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
    ]
  }
]

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA Corporation and Affiliates
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/nemo-relay-debug-runtime-integration · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA Corporation and Affiliates or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download nemo-relay-debug-runtime-integration.zip