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

# Vercel Eve Traces

> Trace Eve agent turns, model calls, tool execution, session lineage, and AI SDK v7 telemetry through Catalyst.

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](/integrations/traces/ai-sdk)
for those direct `generateText` or `streamText` calls.

<Info>
  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.
</Info>

## 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.

<Metadata text="integrations/traces/eve-install[series=eve_setup]" />

```bash TypeScript theme={"system"}
bun add @inference/tracing eve
```

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

<Metadata text="integrations/traces/eve-install-provider[series=eve_setup]" />

```bash TypeScript theme={"system"}
bun add @ai-sdk/openai-compatible
```

## Configure Export

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

<Metadata text="integrations/traces/eve-env[series=eve_setup]" />

```bash theme={"system"}
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:

<Metadata text="integrations/traces/eve-gateway-env[series=eve_setup]" />

```bash theme={"system"}
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.

<Metadata text="integrations/traces/eve-instrumentation[series=eve_setup]" />

```typescript TypeScript theme={"system"}
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.

<Metadata text="integrations/traces/eve-agent-provider[series=eve_setup]" />

```typescript TypeScript theme={"system"}
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.

<Metadata text="integrations/traces/eve-tool[series=eve_setup]" />

```typescript TypeScript theme={"system"}
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.

<Metadata text="integrations/traces/eve-existing-hooks[series=eve_setup]" />

```typescript TypeScript theme={"system"}
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()`.