Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vercel/eve/llms.txt

Use this file to discover all available pages before exploring further.

eve builds an agent by walking the filesystem under agent/. The directory structure is not just an organizational convention — it is the configuration. The slot a file lands in determines how eve loads it, and the path itself becomes the name the model sees. You never write a name or id field on a define* call; the filesystem provides both.

​
The naming rule

Identity comes from the path. Every define* helper picks up its name from the filename or directory, so there is no duplication between code and config.
PathResolves to
agent/tools/get_weather.tstool get_weather
agent/connections/linear.tsconnection linear
agent/skills/summarize.mdskill summarize
agent/subagents/researcher/agent.tssubagent researcher
The root agent takes its name from the enclosing package.json name field, falling back to the app-root directory name when package.json has no name. A subagent takes its name from its directory under subagents/. Tool files use snake_case slugs (e.g. get_weather.ts, refund_charge.ts). That slug is exactly what the model sees as the tool name, so keep it lowercase and underscore-separated. The standard project separates the app root from the authored surface under agent/. Evals live at the app root as a sibling of agent/, not inside it. 
my-agent/
├── package.json
├── tsconfig.json
├── agent/
│   ├── agent.ts
│   ├── instructions.md
│   ├── instrumentation.ts
│   ├── channels/
│   ├── connections/
│   ├── hooks/
│   ├── skills/
│   ├── lib/
│   ├── sandbox/
│   ├── tools/
│   ├── schedules/
│   └── subagents/
└── evals/
A flat layout is supported when the app root and agent root are the same directory, but the nested layout above is preferred because it keeps the app root clean.

​
Slot table

The table below lists every authored slot. The Subagents column indicates whether a declared subagent (subagents/<id>/) can use that slot. A declared subagent inherits nothing from the root — it discovers its own slots independently.
PathDescriptionSubagentsNotes
agent.tsRuntime configYesModel, modelOptions, compaction, build, experimental. See Agent Config.
instructions.md / instructions.ts / instructions/Base system promptOptionalA flat file, or a directory of .md and .ts files. Static sources compose at build time. Dynamic sources (defineDynamic + defineInstructions) resolve at runtime. Required on the root, optional on subagents.
instrumentation.tsTelemetry configNoOTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only.
channels/HTTP / messaging entrypointsNoRoot-only.
connections/External service connections (MCP, OpenAPI)YesOne connection per file; name derived from filename.
hooks/Lifecycle and stream-event subscribersYesModule-backed only. Recursive directories supported.
skills/On-demand procedures and capability packsYesFlat markdown, module-backed skills, or packaged skills. Seeded into /workspace/skills/....
lib/Shared authored helper codeYesImport-only; not mounted into the workspace.
sandbox.ts or sandbox/sandbox.tsThe agent’s single sandboxYesUse top-level sandbox.ts for a definition-only override; use sandbox/sandbox.ts + sandbox/workspace/** to also seed files. Framework default applies when neither is authored.
sandbox/workspace/**Files seeded into the sandboxYesMirrored into /workspace/... at session bootstrap.
tools/Typed executable integrationsYesModule-backed only.
schedules/Recurring jobsNoEach schedule is <name>.ts (default-exported defineSchedule) or <name>.md (frontmatter cron: + prompt body). Recursive nesting supported. Root-only.
subagents/Specialist child agentsYesEach child is its own local package under subagents/<id>/. Nested subagents are supported.

​
What reaches the runtime workspace

eve does not mount the whole agent/ tree into the sandbox. Only two sources land in /workspace:
  • skills/ files → /workspace/skills/...
  • agent/sandbox/workspace/** → /workspace/... at session bootstrap
Everything under lib/ stays as import-only source code and never reaches the workspace.

​
Local subagent layout

A local subagent lives under subagents/<id>/ and uses the same agent.ts shape as the root agent. It has its own full authored surface, but channels and schedules are not supported inside subagents. 
agent/subagents/researcher/
├── agent.ts
├── instructions.md
├── connections/
├── hooks/
├── skills/
├── lib/
├── sandbox/
├── tools/
└── subagents/
agent.ts is required for every declared subagent and must export a description. The parent reads that description to decide when to delegate to the child.

​
Flat layout

When the app root is also the agent root, a flat layout is valid: 
my-agent/
├── package.json
├── agent.ts
├── instructions.md
├── tools/
└── skills/
Prefer the nested layout above. It keeps the app root separate from the authored surface and scales better as the project grows.

​
Troubleshooting discovery

Run eve info to list the discovered surface and print discovery diagnostics. If a file was not picked up, verify that it sits in the correct authored slot per the table above and that the root-vs-subagent boundary is valid. eve also writes inspectable artifacts under .eve/.

Build docs developers (and LLMs) love

Get started for freeTalk to us