Skip to navigation
Getting StartedQuick StartsAgent Harnesses

pi Quick Start

View as Markdown

Goal

Run one local pi task through NeMo Relay and write its agent, model, and tool lifecycle to a local Agent Trajectory Observability Format (ATOF) file.

The pi integration is a proof of concept. This guide pins pi 0.84.0. pi can introduce breaking hook changes in minor releases, so this quick start installs that exact version.

Trial configuration

This guide uses disposable local files and wrapped execution to try Relay for one run. It is a trial configuration, not an ongoing deployment setup.

For regular use

For personal use, configure user or system settings and follow the agent’s persistent integration setup.

For administrator-managed deployments, use daemon mode for a shared service and centrally managed configuration.

Use the event relationships to follow model and tool work through a run and check where the expected activity occurred.

Prerequisites

Before you start, make sure you have:

  • Node.js 24 or newer and npm (the selected runtime for this guide)
  • A configured pi model with inference access: a provider API key or a supported authenticated session
  • A supported NeMo Relay CLI platform

On Unix, the verification step also uses jq 1.6 or newer; check your version with jq --version. PowerShell uses its built-in JSON parser. pi itself supports Node.js 22.19 or newer; this guide uses Node.js 24.

Relay does not require a particular model or an OpenAI account. The pinned pi release supports NVIDIA NIM through NVIDIA_API_KEY, as well as other providers. For an NVIDIA example, choose an available model from build.nvidia.com in pi’s model selector. Use a provider speaking OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages; Gemini and Vertex APIs are not supported by this Relay gateway.

1

Install

Install the pinned pi release and the NeMo Relay version for these docs:

npm install --global @earendil-works/pi-coding-agent@0.84.0
curl -fsSL https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.sh | NEMO_RELAY_VERSION=0.11.0 sh
export PATH="$HOME/.local/bin:$PATH"

Confirm that pi --version reports 0.84.0 before continuing.

pi hooks must originate inside the process, so install the Relay extension once and verify that pi can load it:

nemo-relay install pi
nemo-relay doctor pi

A local gateway reachability warning can occur before step 3 starts the temporary gateway. Resolve any other installation or extension-loading problems before continuing.

2

Configure

Create a disposable working directory and make sure the agent can write files there:

mkdir relay-pi-quickstart
cd relay-pi-quickstart

Save the following files and run the remaining commands from this directory.

Keep your existing pi model and provider configuration. If you have not configured a provider, use pi’s /login and /model selectors first. For an NVIDIA provider, set its inference key in the same terminal used to run pi:

export NVIDIA_API_KEY="your-nvidia-api-key"

If your provider is already authenticated, skip the key example. For another provider, use its own credential rather than NVIDIA_API_KEY. Use the key issued for your endpoint; keys are not interchangeable between inference services.

Save this file as config.toml in the directory where you will run the agent:

config.toml
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
[agents.pi]
command = "pi"

The agent entry in config.toml tells Relay which executable to launch. Save this sibling file as plugins.toml to enable ATOF export to logs/events.jsonl:

plugins.toml
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
version = 1
[policy]
unknown_component = "error"
unknown_field = "error"
unsupported_value = "error"
[[components]]
kind = "observability"
enabled = true
[components.config]
version = 4
enable_full_payloads = false
[components.config.atof]
enabled = true
[[components.config.atof.sinks]]
type = "file"
output_directory = "logs"
filename = "events.jsonl"
mode = "overwrite"

ATOF output can contain sensitive prompts, responses, tool arguments, and tool results. Protect logs/events.jsonl even when full payload export is disabled.

3

Run

From the directory containing both files, run the common validation prompt:

rm -f -- relay-check.txt logs/events.jsonl &&
nemo-relay --config "$PWD/config.toml" pi -- -p "Use a file-writing tool to create relay-check.txt in the current working directory containing exactly RELAY_QUICKSTART_TOOL_OK. Then reply with RELAY_QUICKSTART_RESPONSE_OK."

pi uses its configured model. To select another model for this invocation, add --model PROVIDER/MODEL_ID after --, using the full reference shown by pi --list-models; these are pi options, not Relay requirements. Relay starts a temporary local gateway and loads the installed extension for this run.

For a custom endpoint, use a distinct provider name in pi’s custom model configuration. This avoids ambiguity when a model ID itself begins with a built-in provider name. A 403 can indicate that the selected model is not allowed by your key; confirm the endpoint and exact model ID before changing credentials.

4

Verify

The tool marker proves that the agent created the requested file. The event marker proves that Relay recorded matching start/end records for the required turn or agent, tool, and model work. The response marker is the agent’s reply; it is checked separately from the captured lifecycle.

The verification command prints RELAY_QUICKSTART_TOOL_OK and RELAY_QUICKSTART_EVENTS_OK.

Run the verification checks

After the task exits, confirm that Relay wrote the local event stream:

jq -eRs 'gsub("^\\s+|\\s+$"; "") == "RELAY_QUICKSTART_TOOL_OK"' relay-check.txt > /dev/null &&
jq -se '
  . as $events |
  def closed($category):
    any($events[]; . as $end_event |
      .kind == "scope" and .scope_category == "end" and
      .category == $category and
      any($events[]; .kind == "scope" and .scope_category == "start" and
        .uuid == $end_event.uuid and .name == $end_event.name and
        .category == $end_event.category and .parent_uuid == $end_event.parent_uuid));
  length > 0 and
  all(.[]; .atof_version == "0.1" and (.kind == "scope" or .kind == "mark")) and
  closed("agent") and closed("tool") and closed("llm")
' logs/events.jsonl > /dev/null &&
printf 'RELAY_QUICKSTART_TOOL_OK\nRELAY_QUICKSTART_EVENTS_OK\n'

The verification command prints the following output when its checks pass:

RELAY_QUICKSTART_TOOL_OK
RELAY_QUICKSTART_EVENTS_OK

The agent’s final reply should include RELAY_QUICKSTART_RESPONSE_OK; its surrounding wording can vary.

The verification markers confirm the tool-created file and matching start/end records for agent, tool, and LLM work.

Inspect the Recorded Activity

Read the completed model calls from the same event file:

jq 'select(.kind == "scope" and .scope_category == "end" and .category == "llm") |
  {name, category, category_profile, uuid, parent_uuid, timestamp, metadata}' logs/events.jsonl

category and name identify the recorded work. The same uuid pairs its start and end records; parent_uuid connects it to its enclosing scope. timestamp records when this event occurred. For model calls, category_profile and metadata can include the model identity and completion status, depending on the integration. These fields let you follow a call through the run without requiring full prompt or response capture.

This run captured pi’s agent, model, and tool activity in logs/events.jsonl. The temporary gateway ends with this invocation; repeat the wrapped command when you want to observe another run.

For More Details

For more details, refer to: