Scalekit Tracing

Scalekit runs tools for an agent. Add the setup below to an existing app to send those tool calls to Phoenix.

Install

npm install @scalekit-sdk/node @arizeai/phoenix-otel

Configure Environment

First, start Phoenix:

Local
Container
Self-Host

uvx arize-phoenix serve

No uv? pip install arize-phoenix && phoenix serve does the same thing. See Terminal setup for customization.

docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest

Images are published to Docker Hub. See Docker for volumes, PostgreSQL, and other options.

Phoenix serves its UI and OTLP HTTP on port 6006, and OTLP gRPC on port 4317. For a local instance that’s http://localhost:6006. Leave it running while you work.

Then create a .env file that points your app at it:

PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
PHOENIX_API_KEY=your-api-key # Optional, only if auth is enabled
PHOENIX_PROJECT_NAME=scalekit-agentkit

PHOENIX_COLLECTOR_ENDPOINT is the Phoenix server URL. register() appends /v1/traces when that path is missing. Add the Scalekit credentials from Dashboard → Developers → API credentials to the same .env file:

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.com
SCALEKIT_CLIENT_ID=your-client-id
SCALEKIT_CLIENT_SECRET=your-client-secret

Setup

Call register() before the tool runs. It reads PHOENIX_COLLECTOR_ENDPOINT and PHOENIX_API_KEY. The run command loads .env with --env-file before the script starts. The project name is PHOENIX_PROJECT_NAME, or scalekit-agentkit when that variable is unset.

// instrumentation.ts
import { register } from "@arizeai/phoenix-otel";
import { ScalekitClient } from "@scalekit-sdk/node";

export const provider = register({
  projectName: process.env.PHOENIX_PROJECT_NAME ?? "scalekit-agentkit",
});

export const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENVIRONMENT_URL!,
  process.env.SCALEKIT_CLIENT_ID!,
  process.env.SCALEKIT_CLIENT_SECRET!,
);

Wrap client.actions.executeTool with traceTool from @arizeai/phoenix-otel. The span name is the tool name. The span records the call arguments and the result.

// traced-tools.ts
import { traceTool } from "@arizeai/phoenix-otel";
import type { ScalekitClient } from "@scalekit-sdk/node";

type ExecuteToolParams = Parameters<
  ScalekitClient["actions"]["executeTool"]
>[0];

export function createTracedToolExecutor(
  actions: Pick<ScalekitClient["actions"], "executeTool">
) {
  return (params: ExecuteToolParams) =>
    traceTool((toolParams: ExecuteToolParams) => actions.executeTool(toolParams), {
      name: params.toolName,
    })(params);
}

Then call a tool through it. identifier is the connected account the tool runs as.

// example.ts
import { provider, scalekit } from "./instrumentation.js";
import { createTracedToolExecutor } from "./traced-tools.js";

const executeTool = createTracedToolExecutor(scalekit.actions);

const result = await executeTool({
  toolName: "github_issue_get",
  connector: "github-connect",
  identifier: "test-user",
  toolInput: { owner: "octocat", repo: "Hello-World", issue_number: 1 },
});
console.log(result.data);

await provider.shutdown(); // flush batched spans before the script exits

A thrown error is recorded as status ERROR. A call that returns normally is status OK, including when the failure sits inside result.data. traceTool ends the span before the next line runs, so a later setStatus does not change it. The demo marks those resolved failures ERROR on a span it owns.

Running Your Application

The three files above are the example. From the directory that contains them:

npx tsx --env-file=.env example.ts

Observe

Phoenix lists the turn under PHOENIX_PROJECT_NAME. In this example the tool span is the root span. A thrown error shows status ERROR. In the demo, the tool span and the model span are siblings under the agent span run_agent.

Resources