Vercel Eve Traces - Inference.net Documentation

Catalyst traces Eve through Eve’s native agent/instrumentation.ts hook. Eve already emits OpenTelemetry spans for agent turns, model calls, sub-agent invocations, and tools; Catalyst installs its OpenTelemetry provider from that hook and enriches the exported spans with OpenInference attributes and $eve.* workflow tags. Use this guide for TypeScript Eve agents. If your app calls the Vercel AI SDK directly outside Eve, use Vercel AI SDK traces for those direct generateText or streamText calls.

Eve uses the presence of agent/instrumentation.ts as the telemetry enablement signal. For Eve apps, export defineCatalystEveInstrumentation() from that file instead of calling setup() in your agent code.

What Is Captured

Eve turn spans such as ai.eve.turn as OpenInference CHAIN spans
Eve invoke_agent spans as AGENT spans
AI SDK v7 model spans inside Eve as LLM spans, including model, provider, input/output messages, finish reason, and token usage when the provider returns them
Eve execute_tool spans as TOOL spans, including tool name, call ID, arguments, result, and errors when available
Eve session, turn, parent, root, and trigger metadata
$eve.* aggregate fields such as model, input tokens, output tokens, cache tokens, and tool count
Custom runtime metadata added from defineCatalystEveInstrumentation()

Catalyst sets recordInputs and recordOutputs to true by default so the dashboard can show model and tool IO. Set either option to false when a deployment should avoid exporting full prompts, responses, tool arguments, or tool results.

Install

Install Catalyst tracing in the same package where your Eve agent runs.

TypeScript

bun add @inference/tracing eve

Install the AI SDK provider package your Eve agent uses. For Catalyst Gateway or another OpenAI-compatible endpoint:

TypeScript

bun add @ai-sdk/openai-compatible

Configure Export

Set the Catalyst traces endpoint and token before the Eve process starts.

export CATALYST_OTLP_ENDPOINT="https://telemetry.inference.net"
export CATALYST_OTLP_TOKEN="<your-token>"
export CATALYST_SERVICE_NAME="eve-weather-agent"
export CATALYST_SERVICE_VERSION="2026.06.17"

If your Eve model calls go through Catalyst Gateway, configure that provider separately:

export INFERENCE_API_KEY="<your-api-key>"
export INFERENCE_BASE_URL="https://api.inference.net/v1"
export INFERENCE_MODEL="claude-haiku-4-5"

Add Eve Instrumentation

Create agent/instrumentation.ts at the root of your Eve agent. Eve loads this file during agent startup.

TypeScript

import { defineCatalystEveInstrumentation } from "@inference/tracing/eve";

export default defineCatalystEveInstrumentation({
  functionId: "weather-agent",
  serviceName: "eve-weather-agent",
  metadata: {
    "deployment.environment": process.env.NODE_ENV ?? "development",
  },
});

functionId becomes Eve’s AI SDK telemetry function ID. Use a stable value for the logical agent or workflow. serviceName becomes the OpenTelemetry service.name resource attribute; when omitted, Catalyst uses Eve’s agent name.

Agent Provider Example

Your agent/agent.ts keeps using Eve normally. This example uses an OpenAI-compatible AI SDK provider pointed at Catalyst Gateway.

TypeScript

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { defineAgent } from "eve";

const inference = createOpenAICompatible({
  name: "inference.net",
  baseURL: process.env.INFERENCE_BASE_URL ?? "https://api.inference.net/v1",
  apiKey: process.env.INFERENCE_API_KEY!,
  includeUsage: true,
});

export default defineAgent({
  model: inference(process.env.INFERENCE_MODEL ?? "claude-haiku-4-5"),
  modelContextWindowTokens: 200_000,
});

includeUsage: true lets the provider return token counts for Catalyst columns. modelContextWindowTokens is useful when Eve cannot infer context-window metadata from a custom AI SDK provider model.

Tool Spans

Eve tools are captured automatically when the runtime emits execute_tool spans. You do not need to wrap the tool manually.

TypeScript

import { defineTool } from "eve/tools";
import { never } from "eve/tools/approval";
import { z } from "zod";

export default defineTool({
  needsApproval: never(),
  description: "Get the current weather for a city.",
  inputSchema: z.object({
    city: z.string(),
  }),
  async execute(input) {
    return {
      city: input.city,
      temperatureF: 72,
      condition: "Sunny",
      summary: `Sunny in ${input.city} with a light breeze.`,
    };
  },
});

When this tool runs, Catalyst records a TOOL span with tool.name, tool_call.id, input.value, and output.value.

Existing Eve Hooks

If you already use Eve instrumentation events, pass them into defineCatalystEveInstrumentation(). Catalyst composes your step.started handler with its own handler and merges the returned runtime context.

TypeScript

import { defineCatalystEveInstrumentation } from "@inference/tracing/eve";

export default defineCatalystEveInstrumentation({
  functionId: "support-agent",
  serviceName: "eve-support-agent",
  recordInputs: false,
  recordOutputs: false,
  metadata: {
    "deployment.environment": "production",
  },
  events: {
    "step.started": (input) => ({
      runtimeContext: {
        "customer.channel": input.channel.kind ?? "unknown",
      },
    }),
  },
});

Only primitive metadata values are exported as attributes. Use strings, numbers, or booleans for custom runtime context.

Options

Option	Purpose
`functionId`	Stable Eve/AI SDK telemetry function ID. Defaults to Eve’s agent name when omitted.
`serviceName`	OpenTelemetry `service.name`. Defaults to Eve’s agent name when omitted.
`recordInputs`	Whether Eve/AI SDK records full inputs. Defaults to `true`.
`recordOutputs`	Whether Eve/AI SDK records full outputs. Defaults to `true`.
`metadata`	Primitive values merged into Eve’s AI SDK runtime context and exported as attributes.
`events`	Eve instrumentation event hooks. Catalyst composes `step.started` with your hook.
`setup`	Optional callback invoked from Eve’s startup hook after Catalyst tracing setup is requested.

Other Catalyst setup() options, such as batching and resourceAttributes, can also be passed through. autoInstrument and modules are intentionally managed by the Eve integration.

Verify In Catalyst

Run your Eve agent, trigger a turn, then open Catalyst and filter by your service.name, for example eve-weather-agent. A successful Eve trace should include:

An ai.eve.turn CHAIN span with $eve.parent, $eve.root, and $eve.trigger
An invoke_agent AGENT span with agent.name and gen_ai.system=eve
One or more LLM spans for the nested AI SDK model calls
TOOL spans for any executed Eve tools
Token usage and model fields when the provider returns usage metadata

For local one-off smoke tests, batching: "simple" can make spans export as soon as they end. For long-lived Eve processes, the default batch exporter is usually the better fit.

Troubleshooting

If Eve traces do not appear:

Confirm the file is named agent/instrumentation.ts and is inside the Eve agent root.
Confirm CATALYST_OTLP_ENDPOINT and CATALYST_OTLP_TOKEN are available to the Eve process.
Use a stable serviceName and filter by that value in Catalyst.
Run Eve in a Node-compatible runtime. Catalyst configures the Node OpenTelemetry tracer provider for this integration.
If model spans appear without token counts, set includeUsage: true on the AI SDK provider when the provider supports it.
If Eve cannot resolve model context metadata for a custom provider, set modelContextWindowTokens in defineAgent().

​What Is Captured

​Install

​Configure Export

​Add Eve Instrumentation

​Agent Provider Example

​Tool Spans

​Existing Eve Hooks

​Options

​Verify In Catalyst

​Troubleshooting

What Is Captured

Install

Configure Export

Add Eve Instrumentation

Agent Provider Example

Tool Spans

Existing Eve Hooks

Options

Verify In Catalyst

Troubleshooting