Vercel Eve

​

Prerequisites

• Node.js 24+ (Eve’s CLI requires it)
• An Eve agent project (npx eve@latest init my-agent)
• A self-hosted Phoenix instance

​

Install

npm install @arizeai/phoenix-otel @arizeai/openinference-vercel

​

Connect to Phoenix

PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"

# optional; defaults to the agent name
PHOENIX_PROJECT_NAME="weather-agent"

# only if your Phoenix has auth enabled
# PHOENIX_API_KEY="<your-phoenix-api-key>"

​

Setup tracing

import {
  isOpenInferenceSpan,
  OpenInferenceSimpleSpanProcessor,
} from "@arizeai/openinference-vercel";
import { OTLPTraceExporter, register } from "@arizeai/phoenix-otel";
import { defineInstrumentation } from "eve/instrumentation";

export default defineInstrumentation({
  setup: ({ agentName }) => {
    register({
      projectName: process.env.PHOENIX_PROJECT_NAME ?? agentName,
      spanProcessors: [
        // The simple (non-batched) processor delivers each span as it ends,
        // which is safe on the short-lived serverless functions Eve deploys to.
        // Swap in OpenInferenceBatchSpanProcessor if you prefer batching.
        new OpenInferenceSimpleSpanProcessor({
          exporter: new OTLPTraceExporter({
            url: `${process.env.PHOENIX_COLLECTOR_ENDPOINT ?? "http://localhost:6006"}/v1/traces`,
            // Only needed when Phoenix has auth enabled.
            headers: process.env.PHOENIX_API_KEY
              ? { Authorization: `Bearer ${process.env.PHOENIX_API_KEY}` }
              : undefined,
          }),
          spanFilter: isOpenInferenceSpan,
          reparentOrphanedSpans: true,
        }),
      ],
    });
  },
});

​

Run Eve

npm run dev

curl -X POST http://127.0.0.1:2000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"What is the weather in Brooklyn?"}'

curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream

​

Expected output

{"type":"session.started","data":{"runtime":{"agentName":"weather-agent"}}}
{"type":"actions.requested","data":{"actions":[{"kind":"tool-call","toolName":"get_weather","input":{"city":"Brooklyn"}}]}}
{"type":"message.completed","data":{"message":"The weather in Brooklyn is **sunny** and **72°F**.","finishReason":"stop"}}

​

Observe in Phoenix

1. Open your project. Go to localhost:6006 and click the project named weather-agent (or whatever you set in PHOENIX_PROJECT_NAME). New spans show up within ~30 seconds of a turn.
2. Open a trace. Navigate to the “Traces” tab — each row is one full agent turn, from the incoming message to the final reply. Click a row to open the span tree; each span is one unit of work (a model call, a tool run), nested to show what ran inside what.
3. Read a span by its name and its kind. Eve registers the AI SDK’s @ai-sdk/otel telemetry adapter, which names spans per OpenTelemetry’s GenAI conventions — invoke_agent gpt-4o-mini, step 1, chat gpt-4o-mini, execute_tool get_weather — and the OpenInference span processor translates their attributes to OpenInference on export. Alongside the name, each span carries a span kind, a colored label Phoenix adds to denote what it is:
   • agent a step of the agent’s turn (its reasoning and orchestration).
   • llm a model request (the chat span). Open it to see the prompt, the response, and token usage.
   • tool a tool execution (the execute_tool span), carrying a tool.name attribute such as get_weather.
4. Find the session context. Click any span and open its Attributes panel. Eve attaches session identifiers under the ai.settings.context.eve.* prefix — ai.settings.context.eve.session.id, ai.settings.context.eve.turn.id, ai.settings.context.eve.step.index, and ai.settings.context.eve.channel.kind — so you can trace any span back to the session and turn it came from.
5. Read the tree top-down. At the top sits Eve’s ai.eve.turn span, an agent root, one per turn. Beneath it sits one invoke_agent span (kind agent) per step Eve took, each wrapping a step 1 span (kind chain) that holds the model request — a chat span of kind llm. If the step ran a tool, an execute_tool span of kind tool carries tool.name.
6. If no traces appear at all, see Troubleshooting.

​

Troubleshooting

• No traces in Phoenix. Confirm the file is exactly agent/instrumentation.ts (Eve discovers it by path), and that PHOENIX_COLLECTOR_ENDPOINT points at your Phoenix (it defaults to http://localhost:6006 in the snippet above). If your Phoenix has auth enabled, also set PHOENIX_API_KEY. Enable OpenTelemetry debug logs with export OTEL_LOG_LEVEL=debug and re-run.
• Traces land in the wrong project. Phoenix routes spans to a project by the project-name resource attribute. Set PHOENIX_PROJECT_NAME (or rely on the agent-name fallback above); without it, spans land in Phoenix’s default project.
• Model auth errors. Eve routes models through AI Gateway, so 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 (e.g. @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.

​

Resources