/nemo-relay-integrate-upstream

name: nemo-relay-integrate-upstream
description: Use this skill when assessing, extending, or implementing NeMo Relay support in an agent harness or agent framework, including coding agents and orchestration runtimes, when the host lacks Relay support or an existing integration needs deeper coverage. It identifies the host's execution boundaries and extension points, selects an appropriate attachment method for each boundary, and verifies the resulting coverage.
license: Apache-2.0
metadata:
  author: NVIDIA Corporation and Affiliates

Integrate Relay Into An Agent Harness

Use this skill to determine the right NeMo Relay integration for an agent framework or harness that lacks support or needs deeper coverage. First identify how the host runs tools, model calls, streams, subagents, and lifecycle events and what its extension points can control. Then choose the integration depth and Relay attachment methods that meet the required coverage and fit the host's architecture, support model, and lifecycle, using an extension, separate adapter, core wiring, or hybrid as appropriate.

Choose The Work Mode

Choose one mode from the user's request. Do not silently move from assessment to implementation.

1. **Assess**: Determine whether and how Relay can integrate. Inspect only; do not edit the host, Relay, issues, or pull requests. Read [Assess The Host](references/assess-host.md). 2. **Implement**: Make an already approved integration change. Reconfirm the exact boundary and read [Implement The Integration](references/implement-integration.md). 3. **Qualify**: Test an existing integration at an exact host and Relay revision. Treat this as read-only unless the user also requests fixes. Read [Qualify The Integration](references/qualify-integration.md).

If the host already has a maintained Relay integration, treat it as the starting point and verify its coverage against the requested outcome. Use it when it owns the required boundaries. When it does not, identify the missing ownership and evaluate whether to extend the existing integration, combine it with another attachment method, or move a named boundary deeper into host core. Do not create a competing adapter without first proving that gap. Moving from a host plugin to core may be appropriate when requirements need deeper execution ownership or when the intended first-party support, lifecycle, performance, and release model call for core integration. Hermes uses core to own real callbacks and lifecycle rather than relying on its former observability plugin.

If an application directly owns only a few tool or model callbacks, hand off to `nemo-relay-instrument-calls`.

Establish The Evidence Baseline

Before recommending a shape:

1. Pin the host: record its exact revision or release and every distribution form the integration must support. 2. Establish the Relay release baseline separately. Check the latest stable and prerelease GitHub releases, then read the matching Relay release notes, support matrix, migration guide, package metadata, and relevant API docs. Distinguish a published stable release from a release candidate, nightly or alpha artifact, and current `main`. Choose and record one Relay target with a reason; do not silently design against whichever source tree is open. 3. Build a host-to-Relay packaging matrix. For each host distribution, record its runtime and extension language, OS, architecture, libc, and package or bundle format. Compare it with the Python, Node.js, Rust, gateway, or advanced FFI or sidecar artifacts actually published for the selected Relay release. Verify compatible versions and test installation and loading in the real host distribution; source support or a CI build is not proof that a compatible artifact was published or can load in a bundled host. 4. Determine which host integration shapes exist: built-in Relay support, an optional plugin or extension system, public middleware or adapter APIs, direct core wiring, and configurable provider base URLs. 5. Inspect those surfaces in source and tests. Trace representative tool and model calls through retries, streaming, errors, cancellation, and subagents; classify whether each surface owns a callback, honors a decision or mutation, exposes paired lifecycle events, or only observes. 6. Map every required boundary to an exact public API in the selected Relay release. Then verify configuration, activation, health, cleanup, and duplicate-instrumentation behavior. Binding availability alone does not prove that the required API or semantics exist, and an integration that can be silently skipped needs an explicit verification story.

Use source and targeted tests as evidence. When only a closed binary or public documentation is available, state that limitation and do not claim complete coverage.

Build An Ownership Matrix

Evaluate these surfaces independently:

• process, session, run, turn, and compaction lifecycle;
• tool request, execution, result, and MCP bridge behavior;
• LLM request, provider attempt, response, and streaming finalization;
• subagent creation and cross-task, thread, or process context propagation;
• approvals, human-in-the-loop decisions, retries, and queued work;
• configuration, activation, health, flush, and shutdown.

Split a broad surface into separate rows when its paths have different owners or hooks. For example, do not combine a main-loop model call, provider retry, compaction call, and extension-owned provider call into one LLM row.

For each independently owned path, record:

• the exact call path, Relay attachment point, covered dispatch families, and

bypasses;

• logical-versus-physical cardinality across retries, streams, re-entry, and

concurrency;

• the owning scope stack or execution context, callback thread or event loop,

and whether siblings can finish out of order;

• callback or network ownership, hook ordering, honored retur