eve

--- title: "TypeScript API" description: "The define* helpers, the runtime ctx, and where each one is imported from." --- 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. ```ts title="agent/agent.ts" import { defineAgent } from "eve"; export default defineAgent({ model: "anthropic/claude-opus-4.8" }); ``` ```ts title="agent/tools/get_weather.ts" 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 | Helper | Import from | Authored at | Guide | | ----------------------------------------------------- | --------------------------------------------- | ------------------------------------ | ------------------------------------------------------ | | `defineAgent` | `eve` | `agent/agent.ts` | [agent.ts](../agent-config) | | `defineTool` | `eve/tools` | `agent/tools/<name>.ts` | [Tools](../tools) | | `defineDynamic` | `eve/tools`, `eve/skills`, `eve/instructions` | `agent/{tools,skills,instructions}/` | [Dynamic capabilities](../guides/dynamic-capabilities) | | `defineMcpClientConnection` | `eve/connections` | `agent/connections/<name>.ts` | [MCP connections](../connections/mcp) | | `defineOpenAPIConnection` | `eve/connections` | `agent/connections/<name>.ts` | [OpenAPI connections](../connections/openapi) | | `defineChannel` | `eve/channels` | `agent/channels/<name>.ts` | [Custom channels](../channels/custom) | | `eveChannel`, `slackChannel`, and the other platforms | `eve/channels/<platform>` | `agent/channels/<platform>.ts` | [Channels](../channels/overview) | | `defineSkill` | `eve/skills` | `agent/skills/<name>.ts` | [Skills](../skills) | | `defineInstructions` | `eve/instructions` | `agent/instructions.ts` | [Instructions](../instructions) | | `defineHook` | `eve/hooks` | `agent/hooks/<slug>.ts` | [Hooks](../guides/hooks) | | `defineSchedule` | `eve/schedules` | `agent/schedules/<name>.ts` | [Schedules](../schedules) | | `defineState` | `eve/context` | tools, hooks, lifecycle | [Session context](../guides/session-context) | | `defineSandbox` | `eve/sandbox` | `agent/sandbox.ts` | [Sandbox](../sandbox) | | `defineInstrumentation` | `eve/instrumentation` | `agent/instrumentation.ts` | [instrumentation.ts](../guides/instrumentation) | | `defineRemoteAgent` | `eve` | `agent/subagents/<id>/agent.ts` | [Remote agents](../guides/remote-agents) | | `defineEval` | `eve/evals` | `evals/*.eval.ts` | [Evals](../evals/overview) | | `defineEvalConfig` | `eve/evals` | `evals/evals.config.ts` | [Evals](../evals/overview) | | `mockModel` | `eve/evals` | Deterministic fixture agent models | [Evals](../evals/overview) | | `useEveAgent` | `eve/react`, `eve/vue`, `eve/svelte` | frontend | [Frontend](../guides/frontend/overview) | A few non-`define*` helpers round out the set: `disableTool` and `experimental_workflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), 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 built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `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` is exported from `eve/tools` for the `experimental_workflow(...)` config shape. ## 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](../guides/session-context) for the full model. | Member | Use | | --------------------------- | ---------------------------------------------------------------------------- | | `ctx.session` | Current session, turn, auth, and optional parent lineage (read-only) | | `ctx.getSandbox()` | Live sandbox handle for the current agent | | `ctx.getSkill(identifier)` | Handle for a named skill visible to the current agent | | `ctx.getToken(provider)` | Resolve a bearer token for an inline auth provider such as `connect("...")` | | `ctx.requireAuth(provider)` | Evict and re-authorize an inline provider, commonly after a downstream `401` | ## Imports at a glance | Import | Holds | | ----------------------------------------------------------- | --------------------------------------------------------------------- | | `eve` | `defineAgent`, `defineRemoteAgent`, agent config types | | `eve/tools` | `defineTool`, `defineDynamic`, `disableTool`, `experimental_workflow` | | `eve/tools/defaults` | the built-in tools as plain values | | `eve/tools/approval` | `always`, `once`, `never` | | `eve/connections` | `defineMcpClientConnection`, `defineOpenAPIConnection` | | `eve/channels` | `defineChannel`, route verbs | | `eve/channels/eve` | `eveChannel` | | `eve/channels/auth` | `localDev`, `vercelOidc`, `placeholderAuth` | | `eve/channels/{slack,discord,teams,telegram,twilio,github}` | platform channel factories | | `eve/hooks` | `defineHook` | | `eve/schedules` | `defineSchedule` | | `eve/skills` | `defineSkill`, `defineDynamic` | | `eve/instructions` | `defineInstructions`, `defineDynamic` | | `eve/context` | `defineState`, session and state types | | `eve/sandbox` | `defineSandbox`, backends | | `eve/instrumentation` | `defineInstrumentation`, `isChannel` | | `eve/models/openai` | `experimental_chatgpt` | | `eve/evals` | `defineEval`, `defineEvalConfig`, `mockModel`, eval types | | `eve/evals/expect` | `includes`, `equals`, `matches`, `similarity` | | `eve/evals/reporters` | `Braintrust`, `JUnit`, `EvalReporter` | | `eve/evals/loaders` | `loadJson`, `loadYaml` | | `eve/react`, `eve/vue`, `eve/svelte` | `useEveAgent` | | `eve/next`, `eve/nuxt`, `eve/sveltekit` | framework bundler plugins | | [`eve/client`](../guides/client/overview) | `Client`, `ClientSession` | 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`: ```ts title="agent/agent.ts" 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`](../agent-config): the agent config these helpers configure - [Tools](../tools): `defineTool`, the most-used helper - [Project layout](./project-layout): where each define\* lives on disk