Vercel Eve

Eve is Vercel’s filesystem-first TypeScript framework for durable backend AI agents. You define an agent as files under an agent/ directory, and Eve compiles it into an app that runs on Vercel Functions. Eve emits OpenTelemetry GenAI spans for every turn, model step, model call, and tool execution. Arize AX captures them through the @arizeai/openinference-vercel span processor, which you register as an OpenTelemetry destination in Eve’s agent/instrumentation/ directory.

This guide requires Eve 0.62 or later. Eve 0.62 replaced the single agent/instrumentation.ts file with the agent/instrumentation/ directory. If you’re upgrading an agent that still has agent/instrumentation.ts, see Eve’s instrumentation migration guide.

Prerequisites

Node.js 24+ (Eve’s CLI requires it)
An Eve agent project (npx eve@latest init my-agent)
An Arize AX account (sign up)
An AI Gateway credential for Eve’s model routing: an AI_GATEWAY_API_KEY, or a VERCEL_OIDC_TOKEN pulled with vercel link

Launch Arize AX

Sign in to your Arize AX account.
From Space Settings, copy your Space ID and API Key. You will set them as ARIZE_SPACE_ID and ARIZE_API_KEY below.

Install

In your Eve project, add the Arize OpenInference span processor, the OpenTelemetry trace SDK it builds on, and the OTLP exporter it sends spans through:

npm install @arizeai/openinference-vercel@^3.2.3 \
  @opentelemetry/sdk-trace-base \
  @opentelemetry/exporter-trace-otlp-proto

Eve registers the OpenTelemetry pipeline itself, so you don’t install @vercel/otel or call registerOTel.

Configure credentials

export ARIZE_SPACE_ID="<your-space-id>"
export ARIZE_API_KEY="<your-api-key>"
export ARIZE_PROJECT_NAME="my-eve-agent"
export AI_GATEWAY_API_KEY="<your-ai-gateway-key>"

Setup tracing

Eve discovers every file in agent/instrumentation/ and loads them at server startup, before any agent code runs. Each file exports one piece of the tracing setup, and the file names are yours to choose. You don’t set experimental_telemetry on individual calls; Eve manages telemetry internally. Add two files. The first, otel.ts, holds the process-wide OpenTelemetry settings. It sets the model_id resource attribute, which Arize uses to route spans to a project:

agent/instrumentation/otel.ts

import { otel } from "eve/instrumentation/otel";

export default otel({
  // Arize routes spans to the project named by the model_id resource attribute.
  resource: { model_id: process.env.ARIZE_PROJECT_NAME ?? "my-eve-agent" },
});

The second, arize.ts, declares Arize AX as a trace destination. It registers the OpenInference span processor with an OTLP exporter pointed at Arize. The processor’s spanFilter and reparentOrphanedSpans options control which spans reach Arize; see Span filter:

agent/instrumentation/arize.ts

import { otelIntegration } from "eve/instrumentation/otel";
import {
  isOpenInferenceSpan,
  OpenInferenceSimpleSpanProcessor,
} from "@arizeai/openinference-vercel";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";

export default otelIntegration({
  spanProcessors: [
    new OpenInferenceSimpleSpanProcessor({
      exporter: new OTLPTraceExporter({
        url: "https://otlp.arize.com/v1/traces",
        headers: {
          "arize-space-id": process.env.ARIZE_SPACE_ID ?? "",
          "arize-api-key": process.env.ARIZE_API_KEY ?? "",
        },
      }),
      spanFilter: isOpenInferenceSpan,
      reparentOrphanedSpans: true,
    }),
  ],
});

OpenInferenceSimpleSpanProcessor exports each span synchronously as it ends, so it’s safe on the short-lived serverless functions Eve runs on, with no process-exit forceFlush to call. @arizeai/openinference-vercel translates Eve’s GenAI spans into OpenInference before export.

Control what content is captured

By default, Eve records model and tool inputs and outputs on spans only in development and for public conversations. Everywhere else, spans carry metadata (span structure, models, token counts, and timing) without prompts, responses, or tool arguments. To capture content in production, set tracePolicy in otel.ts:

agent/instrumentation/otel.ts

import { otel } from "eve/instrumentation/otel";

export default otel({
  resource: { model_id: process.env.ARIZE_PROJECT_NAME ?? "my-eve-agent" },
  tracePolicy: () => ({ emit: true, recordInputs: true, recordOutputs: true }),
});

Captured content includes user messages, model responses, and tool arguments and results. Before you enable it in production, confirm that your Arize AX space’s access controls and retention fit that data. tracePolicy receives the conversation’s audience and environment, so you can capture content selectively.

Run Eve

Start the Eve agent:

npm run dev

You can then ask the agent questions.

❯ npm run dev
 eve My Agent
 Use /channels to add more ways to reach your agent.

▌ hello

▲ Hi there! How can I help you today?

Verify in Arize AX

Open your Arize AX space and select the project named by ARIZE_PROJECT_NAME.

Within ~30 seconds you should see one trace per turn. Each trace is rooted at an invoke_agent agent span. Under it, each model step is an agent.step chain span that holds the chat LLM span (prompt, response, and token counts). Each tool call is an agent.action chain span over an execute_tool tool span (arguments and result):

invoke_agent                    AGENT   turn
  ├─ agent.step                 CHAIN   step 0
  │    ├─ chat <model>          LLM     prompt, response, token counts
  │    └─ agent.action          CHAIN   tool call
  │         └─ execute_tool <tool>  TOOL    tool.name, arguments, result
  └─ agent.step                 CHAIN   step 1
       └─ chat <model>          LLM     final reply

Open the Sessions tab. Turns from the same Eve session share a session.id, taken from Eve’s gen_ai.conversation.id, so they group into one session. Traces from subagents join their caller’s session.
If no traces appear, see Troubleshooting.

Other Eve features add their own spans to the turn:

Eve feature	Spans in the trace
Tool approval	An `agent.approval` span (`CHAIN`) under the tool’s `agent.action`, with the decision in `agent.approval.outcome`
Declared subagent or remote agent	An `agent.action` span (`CHAIN`) with the subagent’s name in `agent.action.name`. The subagent’s own turn is a separate trace rooted at `invoke_agent`, with the subagent’s name in `gen_ai.agent.name`, in the same session
Workflow tool	An `agent.action` span (`CHAIN`) with the tool’s name in `agent.action.name`. Each agent session the workflow opens with `ctx.agent()` is a separate `invoke_agent` trace in the same session

The table describes Eve 0.69 and later. In Eve 0.62 through 0.68, a subagent call is an agent.action agent span over an execute_tool span, and a workflow tool that calls agents is an invoke_workflow chain span.

Check from the skill, CLI, or SDK

Confirm spans are actually reaching your Arize AX project. Use whichever fits your workflow — the skill and CLI work for any framework; the SDK check is shown for each language.

Arize skill (agent)
AX CLI
SDK

Install the Arize Skills plugin and let your coding agent check for you:

npx skills add Arize-ai/arize-skills

Then prompt your agent:

Use the arize-trace skill to export and analyze recent traces from my project. Confirm spans are arriving, and summarize any errors or latency issues.

Export recent spans for your project — any rows mean traces are landing:

ax spans export "$ARIZE_PROJECT_NAME" --space "$ARIZE_SPACE_ID" \
  --limit 5 --stdout | jq 'length'

A non-zero count confirms spans reached Arize AX. Run ax auth login first if you have not authenticated. See the ax spans reference.

Query the project’s spans and check that at least one came back.

import os
from arize import ArizeClient

client = ArizeClient(api_key=os.environ["ARIZE_API_KEY"])
resp = client.spans.list(
    project=os.environ["ARIZE_PROJECT_NAME"],
    space=os.environ["ARIZE_SPACE_ID"],
    limit=5,
)
count = len(resp.spans)
print(
    f"{count} span(s) found" if count else "No spans yet — recheck setup"
)

// Reads ARIZE_API_KEY from the environment.
import { listSpans } from "@arizeai/ax-client";

const { data: spans } = await listSpans({
  project: process.env.ARIZE_PROJECT_NAME!,
  space: process.env.ARIZE_SPACE_ID!,
  limit: 5,
});
const count = spans.length;
console.log(
  count ? `${count} span(s) found` : "No spans yet — recheck setup",
);

client, err := arize.NewClient(
    arize.Config{APIKey: os.Getenv("ARIZE_API_KEY")},
)
if err != nil {
    log.Fatal(err)
}
resp, err := client.Spans.List(ctx, spans.ListRequest{
    Project: os.Getenv("ARIZE_PROJECT_NAME"),
    Space:   os.Getenv("ARIZE_SPACE_ID"),
    Limit:   5,
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%d span(s) found\n", len(resp.Spans))

SDK span references: Python · TypeScript · Go.

Span filter

Two options on the processor control which spans reach Arize and how they’re rooted:

spanFilter: isOpenInferenceSpan keeps only the AI spans and drops the rest. A single turn produces well over a hundred spans from Eve’s Vercel Workflow runtime (workflow.* and step.*), plus queue and HTTP spans. The filter drops them, leaving the agent, chain, LLM, and tool spans shown above.
reparentOrphanedSpans: true re-roots any AI span whose parent the filter dropped, so it doesn’t point at a parent that was never exported. Eve already roots each turn at invoke_agent, so nothing is orphaned in local development. Keep the option on as a safeguard for hosts or other instrumentation that wrap the turn in their own non-AI span.

new OpenInferenceSimpleSpanProcessor({
  exporter,
  spanFilter: isOpenInferenceSpan,
  reparentOrphanedSpans: true, // default: false
});

Troubleshooting

No traces in Arize AX. Confirm the files are in the agent/instrumentation/ directory. Eve 0.62 and later ignore a single agent/instrumentation.ts file, and eve build fails if one is present. Check that ARIZE_SPACE_ID and ARIZE_API_KEY are set in the shell running npm run dev. Enable OpenTelemetry debug logs with export OTEL_LOG_LEVEL=debug and run again.
No prompts or responses on spans. Eve’s default trace policy records content only in development and for public conversations. Set tracePolicy as shown in Control what content is captured.
Every step shows up as an LLM span. @arizeai/openinference-vercel versions before 3.2.3 classify Eve’s agent.step, agent.action, and agent.approval spans as LLM spans, so a turn appears to make more model calls than it did. Upgrade to 3.2.3 or later.
No traces from a Vercel deployment. Projects created with eve deploy sample 100% of traces. Existing Vercel projects need a sampling rule; see Eve’s Enable tracing on Vercel.
Model auth errors. Eve routes models through AI Gateway. Set AI_GATEWAY_API_KEY, or run vercel link to use a VERCEL_OIDC_TOKEN. To skip the gateway, switch the agent to a direct provider model (for example @ai-sdk/openai with OPENAI_API_KEY). A brand-new AI Gateway key also fails until you add a payment method: the turn errors with GatewayInternalServerError: AI Gateway requires a valid credit card on file to service requests, even if you only plan to use the free credits. Add a card in your Vercel AI Gateway dashboard to unlock them.

OpenTelemetry

LLM Providers

Agent Frameworks

Coding Agents

Platforms

Orchestration

Evaluation

Prerequisites

Launch Arize AX

Install

Configure credentials

Setup tracing

Control what content is captured

Run Eve

Verify in Arize AX

Check from the skill, CLI, or SDK

Span filter

Troubleshooting

Resources

Cookbook: Tracing a Vercel Eve Agent

Eve OpenTelemetry Docs

Eve Instrumentation Migration Guide

OpenInference Vercel Span Processor

Eve Getting Started

​Prerequisites

​Launch Arize AX

​Install

​Configure credentials

​Setup tracing

​Control what content is captured

​Run Eve

​Verify in Arize AX

​Check from the skill, CLI, or SDK

​Span filter

​Troubleshooting

​Resources

Cookbook: Tracing a Vercel Eve Agent

Eve OpenTelemetry Docs

Eve Instrumentation Migration Guide

OpenInference Vercel Span Processor

Eve Getting Started

Prerequisites

Launch Arize AX

Install

Configure credentials

Setup tracing

Control what content is captured

Run Eve

Verify in Arize AX

Check from the skill, CLI, or SDK

Span filter

Troubleshooting

Resources