> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `brain` CLI; `brain --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces.

# Use pi with Atlan

> Trace pi-agent-core runs, model calls, tool calls, and skills to Agent Registry by setting ATLAN_INSTRUMENT=pi and calling init() once.

atlanai SDK traces pi agents for you. With `ATLAN_INSTRUMENT=pi` set, `init()` wraps pi's public `Agent.prompt()` and `Agent.continue()`, so every run, model call, tool call, and skill appears in Agent Registry with its token usage. You don't change any agent code beyond one `init()` call. Use this guide when your TypeScript agent embeds `@mariozechner/pi-agent-core` (pi 0.67) or `@earendil-works/pi-agent-core` (pi 1.x).

## Before you begin

Before you start, make sure you have:

* **Project**: a Node.js app that embeds pi-agent-core 0.67 or 1.x. pi 1.x needs Node.js 22.19 or later. The pi command-line agent itself never calls `init()`, so this setup doesn't trace it.
* **Tracing**: atlanai SDK (`@atlanai/sdk`) installed, as in [Install atlanai SDK](/tools/sdk/how-tos/install), with `ATLAN_API_KEY`, `ATLAN_WORKSPACE_ID`, and `ATLAN_BASE_URL` set.
* **Credential**: the agent's own API key from its **Identity** tab. Runs sent with a personal key are filed under that person and do not appear on the agent's **Usage** tab.

## Trace runs

<Steps>
  <Step title="Turn on pi instrumentation">
    Set `ATLAN_INSTRUMENT` in the agent's environment. The value is a comma-separated list of frameworks, so `pi` is enough here.

    ```bash theme={null}
    export ATLAN_INSTRUMENT=pi
    ```

    To keep prompts and responses out of the trace and send only structure and token usage, also set `ATLAN_TRACE_CONTENT=false`. See [Control trace privacy](/tools/sdk/how-tos/privacy).
  </Step>

  <Step title="Call init before the first prompt">
    Keep your existing `init()` call, or add one at startup before the agent sends its first prompt.

    ```typescript theme={null}
    import { init } from "@atlanai/sdk/tracing";

    const client = init({ serviceName: "support-agent" });
    ```

    Instead of the environment variable, you can pass `instrument: ["pi"]` to `init()`. On startup the SDK logs `pi instrumentation on for <package>@<version> at <path> (content capture on)` to stderr. Agents created before or after `init()` are traced from their next prompt.
  </Step>

  <Step title="Name skills, if you use your own skill tool">
    By default, a call to a tool named `skill` with a string `args.name` is recorded as that skill, in `atlan.skill.name`. If your agent uses skills under a different tool, pass your own rule. It replaces the default, so return `args.name` for a `skill` tool too if you still use one.

    ```typescript theme={null}
    init({
      serviceName: "support-agent",
      instrument: ["pi"],
      instrumentation: {
        pi: {
          skillName: (toolName, args) =>
            toolName === "load_skill" ? (args as { id?: string }).id : undefined,
        },
      },
    });
    ```
  </Step>

  <Step title="Verify trace">
    Run one prompt with synthetic input, then `await client.flush()` before the process exits. Open the agent in Agent Registry, select **Usage**, then the run in **Recent runs**, and select **Full trace**. Confirm the run step, one model call per turn with token usage, and tool calls with their arguments and results.

    If the startup line is missing, see [Troubleshooting](#troubleshooting). If no traces arrive at all, see [`init()` disables tracing and no traces are exported](/tools/sdk/troubleshooting/install-and-setup-errors#init-disables-tracing-and-no-traces-are-exported).
  </Step>
</Steps>

## What a run looks like

Each `prompt()` or `continue()` call is one run. Span names and attributes follow the OpenTelemetry GenAI conventions.

| Span | Name | Key attributes |
| - | - | - |
| Run | `invoke_agent <service name>` | `gen_ai.operation.name`, `gen_ai.agent.name`, `gen_ai.conversation.id` (pi's `sessionId`, when the agent has one and the run is the trace root), `atlan.run.retry` |
| Model call | `chat <model>` | Model and provider, input and output tokens, cache read and cache write tokens, and the LiteLLM deployment and call ids when pi calls through a LiteLLM proxy and `ATLAN_CAPTURE_MODEL_REF` is not `false` |
| Tool call | `execute_tool` | Tool name, call id, arguments and result, `atlan.skill.name` for a skill |

Input tokens are sent with the cached part included, as the GenAI conventions define them, and cache reads and writes are sent separately, so Agent Registry prices cached tokens once. A run that pi ends with an error or an abort, or whose call throws, is marked as failed. A `continue()` with no active span is recorded as a child of the same agent's last `prompt()` run. When that agent's previous run failed, it also carries `atlan.run.retry` set to `true`.

## Join runs across processes

A run joins the trace that is active when it starts. To continue a trace in a worker process, pass the parent's W3C trace context in the `TRACEPARENT` environment variable. Without either, each `prompt()` starts its own trace, and a `continue()` joins the agent's last `prompt()`. Runs of agents created with the same `sessionId` are grouped by `gen_ai.conversation.id`.

## Limitations

* Zero-code tracing needs pi to load synchronously during `init()`. That means compiled JavaScript on Node.js 20.19 or later in the 20 line, or 22.12 or later, with no loader hooks such as `tsx`. Under a loader, pi is wrapped once it loads, and prompts that start before then are not traced. The SDK logs a warning that names the reason.
* pi instrumentation runs on Node.js only. On other runtimes the SDK logs a warning and traces nothing.
* `prompt()` and `continue()` return a new promise that settles with the same value or error as pi's own, so code that compares the returned promise object to pi's sees a different one. A rejection you don't handle still raises `unhandledRejection`.
* Only `prompt()` and `continue()` are traced. For work outside them, create your own spans, as in [Create spans for agent run](/tools/sdk/how-tos/tracing).
* In short-lived processes, flush before exit, as in [Export traces from serverless](/tools/sdk/how-tos/serverless).

## Troubleshooting

| Log message | Cause | Fix |
| - | - | - |
| No `pi instrumentation on` line and no pi warning | `ATLAN_INSTRUMENT` is not set in the process, or tracing is disabled (an earlier warning from `init()` names why) | Set the variable where the agent runs, and fix the warning `init()` logged |
| `unknown instrumentation "<name>" ignored` | A typo in `ATLAN_INSTRUMENT` | Set it to `pi` |
| `no @mariozechner/pi-agent-core or @earendil-works/pi-agent-core found` | pi is not installed where the SDK can resolve it from the app entry, the working directory, or the SDK | Install pi in the agent's own package |
| `unsupported runtime, pi could not be loaded synchronously` | Node.js older than 20.19 or 22.12, a loader such as `tsx`, or top-level await in pi | Run compiled JavaScript on a supported Node.js version |
| `has no Agent.prototype.prompt/continue/subscribe` | A pi version this SDK release doesn't know | Use pi 0.67 or 1.x, or upgrade atlanai SDK |

For other setup problems, see [Install and setup errors](/tools/sdk/troubleshooting/install-and-setup-errors).

## Next steps

* [Control trace privacy](/tools/sdk/how-tos/privacy): mask or suppress content before you trace production runs.

## See also

* [Framework coverage](/frameworks/coverage)
* [Agent frameworks](/frameworks/index)
* [Configuration](/tools/sdk/references/configuration)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.