TypeScript API Reference
Purpose and Scope
This reference explains the public TypeScript surface that eve expects application authors to import. In eve, the important distinction is between authored APIs and framework internals. Authored APIs are the define* helpers, channel constructors, connection helpers, and runtime context objects that appear in project files under agent/. Internals may exist elsewhere in the package, but the reference page explicitly frames the public contract as the surface exported by the package for agent authors rather than every implementation module in the repository.
Sources: docs/reference/typescript-api.md
The core rule behind the API design is that identity comes from the filesystem. A developer does not pass a name or id into a tool, connection, skill, or channel definition. Instead, eve derives identity from where the file lives. A tool authored at agent/tools/get_weather.ts becomes get_weather, and a connection authored at agent/connections/linear.ts becomes linear. This keeps definitions small, makes projects inspectable, and lets the directory layout act as the contract between authored code and the runtime.
Most authored files therefore follow a repeatable pattern: import the helper from the correct eve subpath, call it with the definition object, and default-export the result. The reference examples show defineAgent imported from eve in agent/agent.ts, and defineTool imported from eve/tools in agent/tools/get_weather.ts. The tool example also demonstrates the normal typed-tool shape: a human-readable description, a Zod input schema, and an asynchronous execute function that receives validated input plus runtime context.
Relevant Source Files
docs/reference/typescript-api.md- First-party reference page for the public TypeScript API, including the filesystem identity rule, example authored files, helper import paths, and the helper-to-location mapping table.
Authoring Model
The most important thing to understand before reading individual helper names is the authoring model. Eve treats an agent as a directory on disk, and the TypeScript helpers are how executable or typed pieces of that directory declare their contract. Markdown can carry human-readable instructions or procedures, while TypeScript is used where the runtime needs schemas, callbacks, adapters, or integration configuration. The helper call is not an imperative registration step; it is a typed declaration that eve can discover through the project layout.
Sources: docs/reference/typescript-api.md
This also explains why there is no central registry file in the public API. A tool does not become available because it is appended to an array in agent/agent.ts; it becomes available because a definition exists in agent/tools/<name>.ts. A channel does not need a separate identifier; the channel file location supplies the integration identity. This convention reduces duplication and avoids mismatches between a filename, exported name, and configured id.
Because identity is filesystem-derived, the exported value in each authored file should be a default export of the relevant helper result. The reference shows this explicitly for both the agent config and a tool. A concise agent file can be only defineAgent({ model: "anthropic/claude-opus-4.8" }), while a tool can provide a Zod schema and implementation without separately naming itself. Readers should carry that pattern into skills, connections, hooks, schedules, and channels unless a guide for that capability documents a more specific shape.
Public Helper Reference
The helper table is the quickest way to choose the right import path. defineAgent is imported from eve and authored at agent/agent.ts. It describes top-level agent configuration such as the model in the reference example. defineTool is imported from eve/tools and authored at agent/tools/<name>.ts. A tool definition describes what the model may call and how eve should validate and execute that call.
Sources: docs/reference/typescript-api.md
defineDynamic appears across eve/tools, eve/skills, and eve/instructions, and is authored under the corresponding capability directories. Use it when the set of available capabilities is not fixed entirely at build time and needs to be resolved dynamically. Dynamic capabilities still fit the same filesystem model: the authored file declares the resolver, and eve uses the directory location to understand which kind of capability is being resolved.
Connections are represented by specialized helpers from eve/connections. The reference names defineMcpClientConnection for Model Context Protocol integrations and defineOpenAPIConnection for OpenAPI integrations, both authored at agent/connections/<name>.ts. These are different from local tools: a local tool is code you implement directly in the agent project, while a connection adapts an external system or API into agent-accessible capabilities. The file location still supplies the connection identity.
Channels have two layers in the public API. defineChannel is imported from eve/channels for custom channel adapters authored at agent/channels/<name>.ts. First-party channel constructors, including eveChannel, slackChannel, and other platform-specific helpers, are imported from eve/channels/<platform> and conventionally live at agent/channels/<platform>.ts. The built-in eve channel is the HTTP-facing channel used by the TUI, SDK clients, browser integrations, and direct API calls, so many projects only add a channel file when overriding defaults such as authentication.
Other authored helpers map directly to their directories. defineSkill comes from eve/skills for agent/skills/<name>.ts; defineInstructions comes from eve/instructions for agent/instructions.ts; defineHook comes from eve/hooks for lifecycle and stream-event subscribers under agent/hooks/<slug>.ts; defineSchedule comes from eve/schedules for recurring jobs under agent/schedules/<name>.ts; and defineState comes from eve/context for state used by tools, hooks, and lifecycle code.
Compact Import and Location Matrix
| Public API | Import path | Authored location | Use it for |
|---|---|---|---|
defineAgent | eve | agent/agent.ts | Agent runtime configuration such as model selection. |
defineTool | eve/tools | agent/tools/<name>.ts | Typed functions the model can call. |
defineDynamic | eve/tools, eve/skills, eve/instructions | agent/{tools,skills,instructions}/ | Runtime-resolved tools, skills, or instructions. |
defineMcpClientConnection | eve/connections | agent/connections/<name>.ts | MCP-backed external capabilities. |
defineOpenAPIConnection | eve/connections | agent/connections/<name>.ts | OpenAPI-backed external capabilities. |
defineChannel | eve/channels | agent/channels/<name>.ts | Custom message ingress and delivery adapters. |
eveChannel, slackChannel, and platform helpers | eve/channels/<platform> | agent/channels/<platform>.ts | First-party channel integrations. |
defineSkill | eve/skills | agent/skills/<name>.ts | Reusable named procedures. |
defineInstructions | eve/instructions | agent/instructions.ts | Typed instruction definitions when not using plain markdown. |
defineHook | eve/hooks | agent/hooks/<slug>.ts | Lifecycle and stream-event subscribers. |
defineSchedule | eve/schedules | agent/schedules/<name>.ts | Recurring scheduled agent work. |
defineState | eve/context | tools, hooks, lifecycle | Session context state shared by runtime code. |
Runtime Context and Execution Callbacks
The reference describes the public surface as both helpers and the ctx they receive at runtime. The visible tool example shows this in the execute({ city }, ctx) signature. The first argument is the validated input produced from the tool schema. The second argument is the runtime context that eve supplies while the agent run is executing. This separation matters because authored code should keep request-specific state, session information, approvals, or runtime services in ctx rather than in module-level globals.
Sources: docs/reference/typescript-api.md
For tool authors, the practical contract is that validation and execution are separate concerns. The inputSchema defines what the model may provide, and execute operates on the parsed input. The example returns structured data rather than prose, which lets the agent consume tool results as data and decide how to respond. This pattern is also safer for integrations because the input schema becomes the boundary between model-generated arguments and side-effecting code.
Hooks, schedules, dynamic resolvers, and state definitions follow the same general API philosophy even though their individual callback signatures differ by capability. Use the helper for the authored file type, put the file in the conventional location, and treat runtime context as the bridge from declarative configuration into an actual session or run. If a value is not exported by the public package entrypoint or documented import path, treat it as an implementation detail rather than a stable application dependency.
Framework and Frontend Entry Points
The TypeScript API reference is primarily about authoring agents, but the same package also exposes framework-facing entry points for applications that talk to an agent. Official frontend documentation names browser bindings such as useEveAgent from eve/svelte, and channel documentation identifies the eve channel as the default HTTP API used by the terminal UI, SDK clients, browser frontends, curl, and other API clients. Those application-facing APIs connect to the same session and streaming model as the authored backend.
For backend authors, the key integration point is still the channel definition. The eve channel can be used implicitly, or explicitly authored with eveChannel() from eve/channels/eve when a project needs to customize defaults such as route authentication. Custom channels use defineChannel when a team needs an adapter that is not one of the first-party platforms. In either case, channel files are separate from tools and connections: channels deliver messages into the agent, while tools and connections provide capabilities the agent can use during a turn.
Connections deserve similar separation in application design. MCP and OpenAPI helpers are not frontend clients and are not message channels. They configure external capability surfaces that the agent can call during execution. A browser or Next.js application may send a user message through the eve HTTP channel, but the agent may answer by invoking a local tool, resolving a dynamic skill, or using an MCP or OpenAPI connection behind the scenes. Keeping those roles distinct makes authorization, approvals, and debugging easier.
Implementation Guidance and Next Steps
When adding a new capability, start from the file path, then choose the helper. If the capability is a local function callable by the model, create agent/tools/<name>.ts and import defineTool from eve/tools. If it is a reusable procedure, create a skill file and use defineSkill. If it exposes an external MCP server or OpenAPI description, put it under agent/connections/<name>.ts and choose the matching connection helper. If it controls how messages enter the agent, use a channel helper under agent/channels/.
Sources: docs/reference/typescript-api.md
The next useful pages depend on what you are building. For backend behavior, read Agent Config, Instructions, Tools and Approvals, Skills, Dynamic Capabilities, Connections Overview, MCP Connections, and OpenAPI Connections. For delivery surfaces, read Channels Overview and Eve Channel. For application integration, continue with Client Overview, Messages and Streaming, and the framework-specific frontend pages. In all cases, prefer documented import paths over internal source modules, and let the filesystem provide identity instead of duplicating names in configuration.