Python Quick Start

This quick start shows the smallest Python workflow that emits scope, tool, and LLM events.

LangChain, LangGraph, and Deep Agents users should start with the LangChain integration, LangGraph integration, and Deep Agents integration guides for the best experience in those frameworks.

Choose an Install Path

Pick the installation path that matches whether you are using a published package or a local checkout.

Install from a Package Manager

Use this path when you want the published package for application development.

$ uv add nemo-relay@0.4.0

Run uv add from an application project that has a pyproject.toml; it records nemo-relay as a dependency. If you are only installing into an active virtual environment, use uv pip install nemo-relay. If you are not using uv, install the published package with pip install nemo-relay.

Install from the Repository

Use this path when you are working from a local checkout and need editable source behavior.

$ uv sync

This is the right path when you are working from a local checkout and want the editable package plus the native extension build.

If you are consuming the local checkout from another uv project, add the source path from that application’s directory instead:

$ uv add --editable ../NeMo-Relay

This records the local source in the application’s pyproject.toml through [tool.uv.sources].

Run One Scope, One Tool Call, and One LLM Call

The example below runs one minimal instrumented workflow through the binding.

1 import asyncio
2 
3 import nemo_relay
4 
5 def on_event(event) -> None:
6     print(f"event={event.kind} name={event.name}")
7 
8 async def search(args):
9     return {"echo": args["query"]}
10 
11 async def model(request):
12     return {
13         "messages": request.content["messages"],
14         "ok": True,
15     }
16 
17 async def main():
18     nemo_relay.subscribers.register("quickstart-printer", on_event)
19 
20     with nemo_relay.scope.scope("demo-agent", nemo_relay.ScopeType.Agent) as handle:
21         nemo_relay.scope.event("initialized", handle=handle, data={"binding": "python"})
22 
23         tool_result = await nemo_relay.tools.execute("search", {"query": "hello"}, search, handle=handle)
24         llm_result = await nemo_relay.llm.execute(
25             "demo-provider",
26             nemo_relay.LLMRequest({}, {"messages": [{"role": "user", "content": "hi"}]}),
27             model,
28             handle=handle,
29         )
30 
31         print(tool_result)
32         print(llm_result)
33 
34     nemo_relay.subscribers.flush()
35     nemo_relay.subscribers.deregister("quickstart-printer")
36 
37 asyncio.run(main())

What Success Looks Like

You should see:

Event lines for the scope, tool, LLM, and mark lifecycle
{'echo': 'hello'} from the tool call
A final object containing ok: True and the echoed message payload from the LLM callback

Native subscriber delivery is asynchronous, so flush before checking subscriber output. If you only see the returned values and no event lines, the callbacks ran but you did not verify instrumentation. The subscriber output is the fast check that NeMo Relay actually emitted lifecycle events.

Where the Python Surface Lives

These modules are the main Python APIs to use from applications and integrations.

nemo_relay.scope
nemo_relay.tools
nemo_relay.llm
nemo_relay.guardrails
nemo_relay.intercepts
nemo_relay.subscribers
nemo_relay.plugin
nemo_relay.adaptive
nemo_relay.typed
nemo_relay.codecs

What to Learn Next

Use these links to continue from the quick start into the core runtime concepts.

1	import asyncio
2
3	import nemo_relay
4
5	def on_event(event) -> None:
6	print(f"event={event.kind} name={event.name}")
7
8	async def search(args):
9	return {"echo": args["query"]}
10
11	async def model(request):
12	return {
13	"messages": request.content["messages"],
14	"ok": True,
15	}
16
17	async def main():
18	nemo_relay.subscribers.register("quickstart-printer", on_event)
19
20	with nemo_relay.scope.scope("demo-agent", nemo_relay.ScopeType.Agent) as handle:
21	nemo_relay.scope.event("initialized", handle=handle, data={"binding": "python"})
22
23	tool_result = await nemo_relay.tools.execute("search", {"query": "hello"}, search, handle=handle)
24	llm_result = await nemo_relay.llm.execute(
25	"demo-provider",
26	nemo_relay.LLMRequest({}, {"messages": [{"role": "user", "content": "hi"}]}),
27	model,
28	handle=handle,
29	)
30
31	print(tool_result)
32	print(llm_result)
33
34	nemo_relay.subscribers.flush()
35	nemo_relay.subscribers.deregister("quickstart-printer")
36
37	asyncio.run(main())