Skip to main content
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

OptionPurpose
functionIdStable Eve/AI SDK telemetry function ID. Defaults to Eve’s agent name when omitted.
serviceNameOpenTelemetry service.name. Defaults to Eve’s agent name when omitted.
recordInputsWhether Eve/AI SDK records full inputs. Defaults to true.
recordOutputsWhether Eve/AI SDK records full outputs. Defaults to true.
metadataPrimitive values merged into Eve’s AI SDK runtime context and exported as attributes.
eventsEve instrumentation event hooks. Catalyst composes step.started with your hook.
setupOptional 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().