Run your eve agent in AX

The eve agent runs your own agent, built with eve, as the agent in an experiment. Instead of a coding CLI, each variant starts your eve project in the sandbox, sends it the prompt, and records what it did. The rest of the experiment works as usual: setup, environment variables, tests and results.

What you need

• An eve project: an agent/ directory with agent/agent.ts (defineAgent(...)) and an instructions file such as agent/instructions.md.
• eve 0.71.3 as the project's dependency. The sandbox runs Node 24, which eve 0.71.3 requires. The dependency must be locked in package-lock.json or pnpm-lock.yaml. AX runs the eve your project installs (the nearest node_modules/.bin/eve between the project and the workspace root), and refuses the run unless it is 0.71.3 and the lockfile resolves it to the registered package.
• Your agent reads its model from EVE_AGENT_MODEL: see Choose the model. Nothing else in your project changes for AX.
• A setup script that puts the project in /workspace and leaves it ready to start: dependencies installed, and any build or codegen steps your project needs before eve dev already run.

Point the experiment at your project

Name the agent eve, and set project to the project's directory inside the workspace. project defaults to the workspace root.

agents:
  - name: eve
    project: acme-agents/agents/my-agent
models: [anthropic/claude-sonnet-5.5]

environments:
  - name: main
    setup:
      name: checkout
      script: |
        git clone --depth 1 --branch v1.4.0 https://github.com/acme/agents.git /workspace/acme-agents
        cd /workspace/acme-agents/agents/my-agent && npm ci

project is a plain workspace-relative path: no absolute path, .. or . component, backslash, : or %. It must hold the agent/ directory, and a symlink that leads outside the workspace is refused. It is part of the variant identity, so two projects in one experiment are two variants, and you can compare projects or refs side by side.

To run another ref, change the setup script. For a private repository, pass the token to the setup only, with script_environment_variables, so the agent never sees it.

eve dev can install packages into your project while it runs. When the run ends, AX restores the project's package.json files and lockfiles as setup left them, removes packages the run added under node_modules, and removes a .eve/ directory the run created. A file inside an already-installed package that the run rewrites is not restored.

Environment variables and secrets

Variables in environment_variables reach your agent's process when it starts. Use them for your agent's own configuration and service credentials, with ax://secrets/<slug> references for secret values:

environment_variables:
  - name: ORDERS_API_URL
    value: https://staging.acme.dev
  - name: ORDERS_API_TOKEN
    value: ax://secrets/orders-staging

AX sets these names itself for an eve variant, so ax experiment validate rejects them in environment_variables (top level or in a setup): AI_GATEWAY_API_KEY, EVE_AGENT_MODEL, EVE_GATEWAY_BASE_URL, EVE_TELEMETRY_DISABLED and HOME. A setup's script_environment_variables may still use them, because only setup scripts see those.

Model access

eve runs use Fiveonefour's AI gateway, like the other agents: AX meters your agent's model calls and bills them from Usage Credits, and no provider key enters the sandbox. Bring-your-own provider keys don't serve eve runs.

You don't change your project for this: AX sends your agent's model calls, its subagents' included, to Fiveonefour's gateway with a credential scoped to the run. If you set NODE_OPTIONS in environment_variables, AX keeps your options.

Choose the model

eve has no way to override a project's model from outside, so the project opts in once: read the model from EVE_AGENT_MODEL, with your default as the fallback.

import { defineAgent } from "eve";

export default defineAgent({
  model: process.env.EVE_AGENT_MODEL ?? "anthropic/claude-sonnet-5.5",
});

Every eve variant needs a model from the models axis: AX sets EVE_AGENT_MODEL to it, and a variant without one fails with exit reason driver_error before your agent starts. If your agent's own steps (not its subagents') run a different model, AX stops the run with exit reason model_unsupported_by_harness rather than recording results under the wrong model.

models entries for eve are exact AI Gateway ids such as anthropic/claude-sonnet-5.5, with no lab. ax experiment validate rejects ids AX can't price for eve, and rejects the effort, thinking, fast and context_window_size controls, because eve offers no way to pass them to the project. In agents: [claude, eve], a model only the other agent runs is pruned from the eve variants.

Check that eve runs your model

ax agent version eve 0.71.3 lists every model eve offers, with its compatibility status. A variant runs only a verified model. After AX registers a new eve version, it checks each listed model with a short run, retries once a check that couldn't decide, and saves the answer, verified or unsupported. A model whose checks still couldn't decide, for example because the AI Gateway was unavailable, stays unknown. For such a model, ax experiment validate fails with No runnable compatibility pairing remains and prints the command that tests it:

ax agent test eve@0.71.3 --model <MODEL>

The check runs at Fiveonefour's expense. When the model replies, the pair is saved as verified for everyone, and validation accepts it from then on.

Subagents on other models

Your agent's subagents can run other models. A subagent may call any model that ax agent version eve 0.71.3 lists, whatever its status, and each call is billed from Usage Credits under the model it names, at that model's price. A call for a model outside that list is refused.

Limits

A failed tool call doesn't fail the run: the agent sees the error and continues, as it would in production.