Instrument a Tool Call

Use this guide when you have an application tool callback and want NeMo Relay to emit lifecycle events, apply middleware, and preserve the active agent scope around the call.

What You Build

You will wrap one existing tool callback with the managed tool execution API. The result is a tool call that:

• Receives JSON-compatible arguments.
• Runs request intercepts, guardrails, execution intercepts, and response guardrails.
• Emits tool start and tool end events.
• Keeps the tool span attached to the current agent or request scope.
• Returns the original tool result to the application.

Before You Start

Complete one binding Quick Start guide first:

• Python Quick Start
• Node.js Quick Start
• Rust Quick Start

Create a scope for the active request or agent run before adding tool instrumentation. If you have not done that yet, start with Adding Scopes and Marks.

The tool arguments and result must be JSON-compatible. If your framework passes clients, sockets, streams, callbacks, or other opaque objects, use Handle Non-Serializable Data before you instrument the callback.

Integration Pattern

Follow this sequence to keep framework work attached to the expected runtime context.

1. Identify the stable tool boundary in your application.
2. Create or inherit a scope for the current agent run, request, or workflow.
3. Register a temporary subscriber while validating the integration.
4. Replace the direct callback invocation with the managed tool execute helper.
5. Pass the active scope handle when the binding supports it.
6. Check that the application result is unchanged and lifecycle events are emitted.

Minimal Example

The examples below wrap a search callback and print emitted events.

1
import asyncio
2
3
import nemo_relay
4
5
def log_event(event) -> None:
6
    print(f"{event.kind} {event.name}")
7
8
async def search(args):
9
    return {
10
        "query": args["query"],
11
        "hits": [{"title": "NeMo Relay"}],
12
    }
13
14
async def main() -> None:
15
    nemo_relay.subscribers.register("instrumentation-check", log_event)
16
17
    try:
18
        with nemo_relay.scope.scope("agent-run", nemo_relay.ScopeType.Agent) as handle:
19
            result = await nemo_relay.tools.execute(
20
                "search",
21
                {"query": "runtime instrumentation"},
22
                search,
23
                handle=handle,
24
            )
25
            print(result)
26
    finally:
27
        nemo_relay.subscribers.flush()
28
        nemo_relay.subscribers.deregister("instrumentation-check")
29
30
asyncio.run(main())

Validate the Integration

Check both behavior and instrumentation:

• The tool result matches what the application returned before the wrapper was added.
• The subscriber prints an agent or request scope event.
• The subscriber prints tool start and tool end events for search.

Native subscriber delivery is asynchronous. Flush subscribers before validating printed output. In Node.js, also wait one event-loop tick after flushSubscribers() so JavaScript callbacks can run.

• Tool start input contains the request arguments after request intercepts and sanitize-request guardrails.
• Tool end output contains the tool result after response guardrails.

If only the business result appears, the callback ran but instrumentation did not run. Confirm that the call goes through tools.execute, toolCallExecute, or tool_call_execute.

Production Checklist

Use this checklist before running the pattern in production traffic.

• Keep tool names stable. Subscribers and downstream exporters use names for filtering and dashboards.
• Keep tool arguments and results JSON-compatible.
• Register temporary debugging subscribers only in development or test environments.
• Pass the parent scope handle when the tool is part of a larger agent, request, or workflow.
• Use middleware names that describe ownership, such as search.redact_args or retrieval.timeout.

Common Issues

Check these symptoms first when the workflow does not behave as expected.

• No events appear: The application is still calling the tool directly.
• The tool appears outside the agent scope: Pass the current scope handle into the managed execute helper.
• The call fails before execution: A conditional-execution guardrail rejected the request.
• Subscribers see different data than the tool receives: Sanitize guardrails change event payloads, while request intercepts change the real arguments.

Next Steps

Use these links to continue from this workflow into the next related task.

• Add model-provider instrumentation with Instrument an LLM Call.
• Add policy or transformation with Add Middleware.
• Export events with Observability.
• Use Code Examples for manual lifecycle, streaming, scope, and partial middleware API examples.