--- title: Agent Files description: Look up agent directory slots, path-derived names, subagent files, and filesystem discovery rules. --- # Agent Files eve builds an agent from files under its agent directory. Each supported path determines how eve loads the file. For recommended project layouts and when to split agents, read [Project Structure](/docs/concepts/project-structure). ## Agent directory layout In a single-agent project, the agent directory is `agent/`. In an eve agent workspace, each member has an `agents//agent/` directory. A minimal root agent needs an instructions source; `agent.ts` is optional when the default configuration is sufficient. ```text agent/ ├── agent.ts ├── instructions.md ├── instrumentation.ts ├── channels/ ├── connections/ ├── extensions/ ├── hooks/ ├── skills/ ├── lib/ ├── memory/ ├── sandbox/ ├── tools/ ├── schedules/ └── subagents/ ``` Add only the files you need. Framework defaults use the same slots, so a file at the same path replaces the default when eve compiles the agent. Evals live beside `agent/`, not inside it. ## Naming from paths eve derives capability names from file paths: | Path | Resolves to | | ------------------------------------- | --------------------- | | `agent/tools/get_weather.ts` | tool `get_weather` | | `agent/connections/linear.ts` | connection `linear` | | `agent/skills/summarize.md` | skill `summarize` | | `agent/subagents/researcher/agent.ts` | subagent `researcher` | A standalone root agent uses its package name (without an npm scope), or its app directory name when no name is set. An eve workspace member uses its directory name under `agents/`. A local subagent uses its directory name under `subagents/`. ## Agent files and directories Paths below are relative to the agent directory. Root agents can use every path; subagents can use paths marked **Yes**. | Path | Purpose | Available to subagents | Notes | | ------------------------------------------------------- | ----------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `agent.ts` | Runtime config | Yes | Model, model options, compaction, build, and experimental settings. See [Agents](/docs/agent-config). | | `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Yes | A flat file or directory of `.md` and `.ts` files. Required on the root, optional on subagents. See [Instructions](/docs/instructions). | | `instrumentation.ts` | Telemetry config | No | Auto-discovered and run before agent code. See [Instrumentation](/docs/observability/instrumentation). | | `channels/` | HTTP and messaging entry points | No | See [Channels](/docs/channels/overview). | | `connections/` | External MCP and OpenAPI services | Yes | Static files define path-named connections; dynamic sources can resolve caller-specific connections. | | `extensions/` | Mounted reusable capabilities | Yes | File or directory mounts. See [Extensions](/docs/extensions). | | `hooks/` | Lifecycle and stream-event subscribers | Yes | Module-backed only; recursive directories are supported. | | `skills/` | On-demand procedures and capability packs | Yes | Flat Markdown, module-backed skills, or packaged skills. | | `lib/` | Shared authored helper code | Yes | Import-only; not copied into the sandbox. | | `memory.ts` or `memory/.ts` | Cross-session memory | Yes | Provider-backed slots. See [Memory](/docs/memory). | | `sandbox.ts` or `sandbox/sandbox.ts` | The agent's sandbox | Yes | The framework default applies when neither is authored. | | `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Mirrored into `/workspace/` when a session starts. | | `tools/` | Typed executable integrations | Yes | Module-backed only. | | `schedules/` | Recurring jobs | No | `defineSchedule` modules or Markdown prompts with `cron` frontmatter; recursive nesting is supported. | | `subagents/` | Specialist child agents | Yes | Local directories or remote-agent definitions; nested subagents are supported. | ## Files available in the sandbox Agent source files are not automatically available to shell commands. Put files to copy into the sandbox's `/workspace/` under `agent/sandbox/workspace/`. Skill runtime files are seeded separately under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. See [Sandboxes](/docs/sandbox) and [Skills](/docs/skills). ## Local subagents A local declared subagent lives at `agent/subagents//`: ```text agent/subagents/researcher/ ├── agent.ts # required; must include description ├── instructions.md # optional ├── tools/ └── subagents/ ``` It uses the same `defineAgent` helper as the root and supports the slots marked **Yes** above. Channels, schedules, and instrumentation are root-only. A declared subagent does not inherit its parent's authored slots; see [Subagents](/docs/subagents#the-isolation-boundary) for defaults and isolation behavior. ## Flat layout eve also supports agent files directly in the app root, without an `agent/` directory: ```text my-agent/ ├── package.json ├── agent.ts ├── instructions.md ├── tools/ └── skills/ ``` Workspace members can also use flat agent files directly under `agents//`. Prefer the nested layouts in [Project Structure](/docs/concepts/project-structure) to keep application files separate from agent definitions. ## Debug file discovery Run `eve info` from the agent's app directory, or `eve info --agent ` from an eve workspace root. It lists the discovered files and diagnostics. eve also writes inspectable artifacts under `.eve/`; see the [CLI reference](/docs/reference/cli#eve-info). Workspace discovery includes only direct `agents//` children with agent files and no `package.json` of their own. A root `agent/` directory takes precedence over `agents/` and makes the project single-agent. See [Add a second root agent](/docs/concepts/project-structure#add-a-second-root-agent) to convert that layout. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)