> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/relay/llms.txt.
> For full documentation content, see https://docs.nvidia.com/nemo/relay/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/relay/_mcp/server.

# Python Quick Start

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

[LangChain](https://www.langchain.com/langchain), [LangGraph](https://www.langchain.com/langgraph), and [Deep Agents](https://www.langchain.com/deep-agents) users should start with the [LangChain integration](/supported-integrations/langchain), [LangGraph integration](/supported-integrations/langgraph), and [Deep Agents integration](/supported-integrations/deepagents) 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.

```bash
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.

```bash
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:

```bash
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.

```python
import asyncio

import nemo_relay

def on_event(event) -> None:
    print(f"event={event.kind} name={event.name}")

async def search(args):
    return {"echo": args["query"]}

async def model(request):
    return {
        "messages": request.content["messages"],
        "ok": True,
    }

async def main():
    nemo_relay.subscribers.register("quickstart-printer", on_event)

    with nemo_relay.scope.scope("demo-agent", nemo_relay.ScopeType.Agent) as handle:
        nemo_relay.scope.event("initialized", handle=handle, data={"binding": "python"})

        tool_result = await nemo_relay.tools.execute("search", {"query": "hello"}, search, handle=handle)
        llm_result = await nemo_relay.llm.execute(
            "demo-provider",
            nemo_relay.LLMRequest({}, {"messages": [{"role": "user", "content": "hi"}]}),
            model,
            handle=handle,
        )

        print(tool_result)
        print(llm_result)

    nemo_relay.subscribers.flush()
    nemo_relay.subscribers.deregister("quickstart-printer")

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.

* [Supported Integrations](/supported-integrations/about)
* [Scopes](/about-nemo-relay/concepts/scopes)
* [Middleware](/about-nemo-relay/concepts/middleware)
* [Plugins](/about-nemo-relay/concepts/plugins)