Integrating a Custom AI Provider with Vercel Eve

We built a minimal SpringForAll content‑operation assistant that uses a single Agent, model configuration, persistent instructions, and the Eve CLI chat. To use a third‑party OpenAI‑compatible provider instead of Vercel AI Gateway, the model configuration is made switchable.

If you don’t want to rely solely on Vercel AI Gateway, or you wish to use your own OpenAI‑compatible provider, how should Eve Agent’s model configuration be implemented?

Sample Project Structure

example/02-custom-provider/
  package.json
  tsconfig.json
  .env.example
  scripts/
    check-custom-gateway.mjs
  agent/
    agent.ts
    instructions.md
    channels/
      eve.ts

Compared with the first version, two items are added: agent/agent.ts now supports both Vercel AI Gateway and a custom provider. scripts/check-custom-gateway.mjs validates the custom gateway before development.

Install Dependencies

Add the OpenAI‑compatible SDK and other required packages:

{
  "dependencies": {
    "@ai-sdk/openai-compatible": "^2.0.51",
    "@vercel/connect": "0.2.2",
    "ai": "7.0.0-beta.178",
    "eve": "^0.12.0",
    "zod": "4.4.3"
  }
}

Include a script for gateway checking:

{
  "scripts": {
    "build": "eve build",
    "dev": "eve dev",
    "start": "eve start",
    "typecheck": "tsc",
    "check:gateway": "node scripts/check-custom-gateway.mjs"
  }
}

Design Environment Variables

Two groups of variables are defined. The default path remains Vercel AI Gateway:

EVE_GATEWAY_MODEL_ID=minimax/minimax-m3
AI_GATEWAY_API_KEY=

For a custom OpenAI‑compatible provider, set:

EVE_MODEL_BASE_URL=https://api.example.com/v1
EVE_MODEL_API_KEY=your-api-key
EVE_MODEL_ID=your-model-id
EVE_MODEL_CONTEXT_WINDOW_TOKENS=128000

The switch rule is simple: if EVE_MODEL_BASE_URL is non‑empty, use the custom provider; otherwise continue with Vercel AI Gateway.

Agent Code Modification

The updated agent/agent.ts performs three tasks:

Determine whether EVE_MODEL_BASE_URL exists to choose the gateway.

When using a custom provider, enforce that EVE_MODEL_ID is supplied.

Parse EVE_MODEL_CONTEXT_WINDOW_TOKENS, throwing an error for invalid values.

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

const defaultGatewayModelId = "minimax/minimax-m3";
const customBaseURL = process.env.EVE_MODEL_BASE_URL;
const usesCustomGateway = customBaseURL !== undefined && customBaseURL.trim() !== "";

function parseContextWindowTokens(value: string | undefined) {
  if (value === undefined || value.trim() === "") {
    return 128000;
  }
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new Error("EVE_MODEL_CONTEXT_WINDOW_TOKENS must be a positive integer.");
  }
  return parsed;
}

function requireCustomModelId() {
  const modelId = process.env.EVE_MODEL_ID;
  if (modelId === undefined || modelId.trim() === "") {
    throw new Error("EVE_MODEL_ID is required when EVE_MODEL_BASE_URL is set.");
  }
  return modelId;
}

const model = usesCustomGateway
  ? createOpenAICompatible({
      name: "custom",
      baseURL: customBaseURL,
      apiKey: process.env.EVE_MODEL_API_KEY,
      includeUsage: true,
    }).chatModel(requireCustomModelId())
  : (process.env.EVE_GATEWAY_MODEL_ID ?? defaultGatewayModelId);

const modelContextWindowTokens = parseContextWindowTokens(process.env.EVE_MODEL_CONTEXT_WINDOW_TOKENS);

export default defineAgent({
  model,
  modelContextWindowTokens,
});

modelContextWindowTokens

defines the agent’s context capacity and cost boundary; using a value larger than the model’s supported window (e.g., 200 000 for a 32 K model) would cause failures.

Validate Custom Gateway

The scripts/check-custom-gateway.mjs script performs:

Read .env.local.

Verify EVE_MODEL_BASE_URL and EVE_MODEL_ID are set.

Send a minimal POST request to ${baseURL}/chat/completions with the message "Say OK.".

Optionally check streaming output and usage.

Running the script with npm run check:gateway (or with --stream and --include-usage) ensures the gateway is reachable before invoking eve dev. If the script cannot return "OK", subsequent agent errors are likely due to gateway misconfiguration rather than agent logic.

Start Chat Verification

After installing dependencies, launch the agent:

npm run dev

In the CLI chat, ask a simple question such as:

你现在是什么角色？能帮 SpringForAll 做什么？

If the configuration is correct, the agent responds according to agent/instructions.md, confirming its role as a SpringForAll content‑operation assistant without claiming capabilities it does not have.

When using a custom provider, run npm run check:gateway first to validate the endpoint, then start the chat with npm run dev.

Summary

Default continues to use Vercel AI Gateway.

Setting EVE_MODEL_BASE_URL switches to a custom OpenAI‑compatible provider.

Explicitly declare the context window via EVE_MODEL_CONTEXT_WINDOW_TOKENS.

Use check-custom-gateway.mjs to validate the custom model entry before development.

Run eve dev and interact via CLI chat to confirm correct behavior.

Example repository: https://github.com/dyc87112/vercel-eve-content-team-tutorial/tree/main/example/02-custom-provider