TypeScript API Reference

This is the public surface of the eve package: the define* helpers you author with, the ctx they receive at runtime, and the import path for each. The full contract lives in packages/eve/src/public/index.ts; anything not exported there is a framework internal.

Identity comes from the filesystem, not a field you set. A tool at agent/tools/get_weather.ts is get_weather, and a connection at agent/connections/linear.ts is linear, so no definition carries a name or id.

Most files look the same: import a helper, default-export the result.

import { defineAgent } from "eve";

export default defineAgent({ model: "anthropic/claude-opus-4.8" });

import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Get the weather for a city.",
  inputSchema: z.object({ city: z.string() }),
  async execute({ city }, ctx) {
    return { city, condition: "Sunny" };
  },
});

The define* helpers

A few additional helpers round out the set: defineGlobTool, defineGrepTool, disableTool, experimental_workflow, and webSearch from eve/tools (see Built-in tools), sleep from eve/tools/sleep, the route verbs GET/POST/PUT/PATCH/DELETE/WS from eve/channels, the approval policies always/once/never from eve/tools/approval, and the channel auth helpers localDev/vercelOidc/placeholderAuth from eve/channels/auth. To wrap a framework-provided tool, import its definition from eve/tools/defaults (bash, readFile, writeFile, glob, grep, webFetch, todo, loadSkill). AgentReasoningDefinition is exported from eve for the top-level defineAgent({ reasoning }) setting. AgentLimitsDefinition is exported for defineAgent({ limits }). AgentWorkflowDefinition and AgentWorkflowWorldDefinition are exported from eve for the defineAgent({ experimental: { workflow } }) config shape. ExperimentalWorkflowToolInput, WebSearchToolInput, and WebSearchProvider are exported from eve/tools for their corresponding tool configuration helpers.

defineInstructions accepts { content: string, role?: "system" | "user" }; omitted role means "system". Its eve/instructions version of defineDynamic accepts only session.started and turn.started handlers returning defineInstructions(...) or null. The legacy { markdown: string } definition remains available as a deprecated system-role form.

Runtime context (ctx)

ctx is passed to your tool execute, hook handlers, channel event handlers, and connection auth/header resolvers. It is live only while authored code is running, so reaching for it at module top level throws. See Session context for the full model.

Imports at a glance

Exported types ship from the same entrypoint as the helper they describe (for example ToolDefinition and ToolContext from eve/tools). For the exhaustive list, read packages/eve/src/public/index.ts.

ChatGPT subscription models

experimental_chatgpt() from eve/models/openai serves an OpenAI model through the local Codex login and bills the ChatGPT subscription. With no argument, it selects gpt-5.6-sol:

import { defineAgent } from "eve";
import { experimental_chatgpt } from "eve/models/openai";

export default defineAgent({
  model: experimental_chatgpt(),
  modelContextWindowTokens: 200_000,
});

Pass another bare OpenAI model slug to override the default. The helper reads credentials from codex login, so use it only where that local login exists.

What to read next

• agent.ts: the agent config these helpers configure
• Tools: defineTool, the most-used helper
• Project layout: where each define* lives on disk