diff --git a/apps/docs/lib/geistdocs/llms-index.ts b/apps/docs/lib/geistdocs/llms-index.ts index 31cbc9095..cc82dadf8 100644 --- a/apps/docs/lib/geistdocs/llms-index.ts +++ b/apps/docs/lib/geistdocs/llms-index.ts @@ -12,7 +12,8 @@ Documentation links below point directly to Markdown. Remove the \`.md\` suffix ## Introduction -- [Getting Started](${EVE_ORIGIN}/docs/getting-started.md): Create a project, configure a model, understand its layout, and run it locally. +- [Getting Started](${EVE_ORIGIN}/docs/getting-started.md): Create a project, configure model credentials, and run your first agent. +- [Project Structure](${EVE_ORIGIN}/docs/concepts/project-structure.md): Choose a layout for agents and application code, add specialist subagents, and grow into an agent workspace. ## Core Concepts @@ -79,6 +80,7 @@ Documentation links below point directly to Markdown. Remove the \`.md\` suffix ## API Reference and Discovery +- [Agent Files](${EVE_ORIGIN}/docs/reference/agent-files.md): Look up filesystem slots, path-derived names, and discovery rules. - [TypeScript API Reference](${EVE_ORIGIN}/docs/reference/typescript-api.md): Find public \`define*\` helpers, runtime context, and import paths. - [CLI Reference](${EVE_ORIGIN}/docs/reference/cli.md): Find every eve command and option. - [Responsible Use](${EVE_ORIGIN}/docs/responsible-use.md): Review deployer responsibilities and safeguards. diff --git a/apps/docs/lib/geistdocs/redirects.test.ts b/apps/docs/lib/geistdocs/redirects.test.ts index e40eeeced..c08a5def5 100644 --- a/apps/docs/lib/geistdocs/redirects.test.ts +++ b/apps/docs/lib/geistdocs/redirects.test.ts @@ -104,11 +104,16 @@ describe("docsRedirects", () => { it.each([ ["/docs/channels", "/docs/channels/overview"], ["/docs/guides/deployment.md", "/docs/guides/deployment/overview.md"], + ["/docs/guides/frontend/add-a-web-app", "/docs/guides/frontend/nextjs"], + ["/docs/guides/frontend/add-a-web-app.mdx", "/docs/guides/frontend/nextjs.mdx"], ["/docs/introduction.md", "/docs/getting-started.md"], ["/docs/installation", "/docs/getting-started"], ["/docs/installation.md", "/docs/getting-started.md"], - ["/docs/project-structure", "/docs/getting-started"], - ["/docs/project-structure.md", "/docs/getting-started.md"], + ["/docs/project-structure", "/docs/concepts/project-structure"], + ["/docs/project-structure.md", "/docs/concepts/project-structure.md"], + ["/docs/getting-started/multiple-root-agents", "/docs/concepts/project-structure"], + ["/docs/multi-agent-projects", "/docs/concepts/project-structure"], + ["/docs/multi-agent-projects.mdx", "/docs/concepts/project-structure.mdx"], ["/docs/reference/http-api", "/docs/channels/eve"], ["/docs/project-layout", "/docs/getting-started"], ["/docs/reference/project-layout", "/docs/getting-started"], @@ -131,11 +136,23 @@ describe("docsRedirects", () => { }); }); +describe("project structure redirects", () => { + it.each(["", ".md", ".mdx"])("preserves the %s representation at both old paths", (extension) => { + for (const prefix of ["/docs", "/en/docs"]) { + expect(docsRedirects).toContainEqual({ + source: `${prefix}/getting-started/project-structure${extension}`, + destination: `/docs/concepts/project-structure${extension}`, + permanent: true, + }); + } + }); +}); + describe("rootMarkdownRedirects", () => { it.each([ ["/getting-started.mdx", "/docs/getting-started.mdx"], ["/installation.md", "/docs/getting-started.md"], - ["/project-structure.mdx", "/docs/getting-started.mdx"], + ["/project-structure.mdx", "/docs/concepts/project-structure.mdx"], ["/tools/overview.md", "/docs/tools.md"], ["/channels/eve.mdx", "/docs/channels/eve.mdx"], ])("redirects observed root Markdown alias %s to %s", (source, destination) => { diff --git a/apps/docs/lib/geistdocs/redirects.ts b/apps/docs/lib/geistdocs/redirects.ts index caf9bb498..f41b8cf3c 100644 --- a/apps/docs/lib/geistdocs/redirects.ts +++ b/apps/docs/lib/geistdocs/redirects.ts @@ -47,7 +47,8 @@ export const createIntegrationRedirects = (source: string, destination: string): export const docsRedirects: DocsRedirect[] = [ ...createDocsRedirects("/introduction", "/getting-started"), ...createDocsRedirects("/installation", "/getting-started"), - ...createDocsRedirects("/project-structure", "/getting-started"), + ...createDocsRedirects("/project-structure", "/concepts/project-structure"), + ...createDocsRedirects("/getting-started/project-structure", "/concepts/project-structure"), ...createDocsRedirects("/channels", "/channels/overview"), ...createDocsRedirects("/channels/http", "/channels/eve"), ...createDocsRedirects("/reference/http-api", "/channels/eve"), @@ -63,6 +64,7 @@ export const docsRedirects: DocsRedirect[] = [ ...createDocsRedirects("/guides/acp", "/protocols/acp"), ...createDocsRedirects("/guides/ucp", "/protocols/ucp"), ...createDocsRedirects("/guides/deployment", "/guides/deployment/overview"), + ...createDocsRedirects("/guides/frontend/add-a-web-app", "/guides/frontend/nextjs"), ...createDocsRedirects("/deployment", "/guides/deployment/overview"), ...createDocsRedirects("/deployment/overview", "/guides/deployment/overview"), ...createDocsRedirects("/deployment/vercel", "/guides/deployment/vercel"), @@ -78,7 +80,8 @@ export const docsRedirects: DocsRedirect[] = [ ...createDocsRedirects("/evals", "/evals/overview"), ...createDocsRedirects("/advanced/evals", "/evals/overview"), ...createDocsRedirects("/getting-started/installation", "/getting-started"), - ...createDocsRedirects("/getting-started/project-structure", "/getting-started"), + ...createDocsRedirects("/getting-started/multiple-root-agents", "/concepts/project-structure"), + ...createDocsRedirects("/multi-agent-projects", "/concepts/project-structure"), ...createDocsRedirects("/getting-started/first-agent", "/tutorial/first-agent"), ]; @@ -86,7 +89,7 @@ export const rootMarkdownRedirects: DocsRedirect[] = [ ["/getting-started", "/getting-started"], ["/install-integrations", "/install-integrations"], ["/installation", "/getting-started"], - ["/project-structure", "/getting-started"], + ["/project-structure", "/concepts/project-structure"], ["/instructions", "/instructions"], ["/tools/overview", "/tools"], ["/skills", "/skills"], diff --git a/docs/README.md b/docs/README.md index 32e59d507..3f1811550 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,28 +12,31 @@ Important naming note: ## Find the page for your task -| To do this | Read this | -| -------------------------------------------------------- | -------------------------------------------------------------------------------------- | -| Create a project, or understand the file layout | [Getting Started](./getting-started.mdx) | -| Set the model, reasoning, or other agent-wide config | [Agents](./agent-config.md) | -| Change what the agent does and how it behaves | [Instructions](./instructions.mdx) | -| Give the agent a typed capability it can call | [Tools](./tools/overview.mdx) | -| Require approval, or ask the user something mid-turn | [Human in the Loop](./tools/human-in-the-loop.md) | -| Call an external HTTP API or MCP server | [Connections](./connections/overview.mdx) | -| Add a messaging surface (Slack, Discord, iMessage, …) | [Channels](./channels/overview.mdx) | -| Expose your own HTTP route as a conversation surface | [Custom Channels](./channels/custom.mdx) | -| Package a procedure the agent loads only when it applies | [Skills](./skills.mdx) | -| Carry state across turns, or shape what the model sees | [State](./concepts/state.md), [Context Control](./concepts/context-control.md) | -| Run commands or untrusted code in isolation | [Sandboxes](./sandbox.mdx) | -| Delegate work to a specialist child agent | [Subagents](./subagents/index.mdx) | -| Run work on a recurring schedule | [Schedules](./schedules.mdx) | -| Install an existing integration instead of writing one | [Add Integrations](./install-integrations.mdx) | -| Link a Vercel project and deploy to production | [Deploy to Vercel](./guides/deployment/vercel.mdx) | -| Self-host, or compare hosting strategies | [Deployment](./guides/deployment/overview.md) | -| Authorize routes, sessions, and per-user access | [Authentication](./guides/auth-and-route-protection.md) | -| Build a web UI, or stream a session to a client | [Client SDK](./guides/client/overview.mdx), [Frontend](./guides/frontend/overview.mdx) | -| Test the agent's behavior | [Evals](./evals/overview.mdx) | -| Look up a CLI command or an exported type | [CLI](./reference/cli.md), [TypeScript API](./reference/typescript-api.md) | +| To do this | Read this | +| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| Organize agents, subagents, and browser application code | [Project Structure](./concepts/project-structure.mdx) | +| Create a project and run your first agent | [Getting Started](./getting-started.mdx) | +| Look up agent files and discovery rules | [Agent Files](./reference/agent-files.md) | +| Set the model, reasoning, or other agent-wide config | [Agents](./agent-config.md) | +| Change what the agent does and how it behaves | [Instructions](./instructions.mdx) | +| Give the agent a typed capability it can call | [Tools](./tools/overview.mdx) | +| Require approval, or ask the user something mid-turn | [Human in the Loop](./tools/human-in-the-loop.md) | +| Call an external HTTP API or MCP server | [Connections](./connections/overview.mdx) | +| Add a messaging surface (Slack, Discord, iMessage, …) | [Channels](./channels/overview.mdx) | +| Expose your own HTTP route as a conversation surface | [Custom Channels](./channels/custom.mdx) | +| Package a procedure the agent loads only when it applies | [Skills](./skills.mdx) | +| Carry state across turns, or shape what the model sees | [State](./concepts/state.md), [Context Control](./concepts/context-control.md) | +| Run commands or untrusted code in isolation | [Sandboxes](./sandbox.mdx) | +| Delegate work to a specialist child agent | [Subagents](./subagents/index.mdx) | +| Run work on a recurring schedule | [Schedules](./schedules.mdx) | +| Install an existing integration instead of writing one | [Add Integrations](./install-integrations.mdx) | +| Link a Vercel project and deploy to production | [Deploy to Vercel](./guides/deployment/vercel.mdx) | +| Self-host, or compare hosting strategies | [Deployment](./guides/deployment/overview.md) | +| Authorize routes, sessions, and per-user access | [Authentication](./guides/auth-and-route-protection.md) | +| Add a browser application | [Next.js](./guides/frontend/nextjs.mdx), [Nuxt](./guides/frontend/nuxt.mdx), or [SvelteKit](./guides/frontend/sveltekit.mdx) | +| Build a custom web UI, or stream a session to a client | [Client SDK](./guides/client/overview.mdx), [Frontend](./guides/frontend/overview.mdx) | +| Test the agent's behavior | [Evals](./evals/overview.mdx) | +| Look up a CLI command or an exported type | [CLI](./reference/cli.md), [TypeScript API](./reference/typescript-api.md) | ## Legal and safeguards @@ -54,24 +57,25 @@ Unless you configure stricter controls, eve agents may operate with permissive s For a full picture rather than a single task, read in this order: 1. [Getting Started](./getting-started.mdx) -2. [Tutorial](./tutorial/first-agent.mdx) -3. [Agents](./agent-config.md) -4. [TypeScript API Reference](./reference/typescript-api.md) -5. [Context Control](./concepts/context-control.md) -6. [Skills](./skills.mdx) -7. [Tools](./tools/overview.mdx) -8. [Connections](./connections/overview.mdx) -9. [Sandboxes](./sandbox.mdx) -10. [Channels](./channels/overview.mdx) -11. [Session Context](./guides/session-context.md) -12. [Sessions and Streaming](./concepts/sessions-runs-and-streaming.md) -13. [Client SDK](./guides/client/overview.mdx) -14. [Subagents](./subagents/index.mdx) -15. [Schedules](./schedules.mdx) -16. [Evals](./evals/overview.mdx) -17. [Authentication](./guides/auth-and-route-protection.md) -18. [Deployment](./guides/deployment/overview.md) -19. [CLI](./reference/cli.md) +2. [Project Structure](./concepts/project-structure.mdx) +3. [Tutorial](./tutorial/first-agent.mdx) +4. [Agents](./agent-config.md) +5. [TypeScript API Reference](./reference/typescript-api.md) +6. [Context Control](./concepts/context-control.md) +7. [Skills](./skills.mdx) +8. [Tools](./tools/overview.mdx) +9. [Connections](./connections/overview.mdx) +10. [Sandboxes](./sandbox.mdx) +11. [Channels](./channels/overview.mdx) +12. [Session Context](./guides/session-context.md) +13. [Sessions and Streaming](./concepts/sessions-runs-and-streaming.md) +14. [Client SDK](./guides/client/overview.mdx) +15. [Subagents](./subagents/index.mdx) +16. [Schedules](./schedules.mdx) +17. [Evals](./evals/overview.mdx) +18. [Authentication](./guides/auth-and-route-protection.md) +19. [Deployment](./guides/deployment/overview.md) +20. [CLI](./reference/cli.md) ## The public mental model diff --git a/docs/concepts/meta.json b/docs/concepts/meta.json index bbb4110d0..b553dbea6 100644 --- a/docs/concepts/meta.json +++ b/docs/concepts/meta.json @@ -2,6 +2,7 @@ "title": "Core Concepts", "defaultOpen": false, "pages": [ + "project-structure", "execution-model-and-durability", "sessions-runs-and-streaming", "state", diff --git a/docs/concepts/project-structure.mdx b/docs/concepts/project-structure.mdx new file mode 100644 index 000000000..3495bd9e9 --- /dev/null +++ b/docs/concepts/project-structure.mdx @@ -0,0 +1,111 @@ +--- +title: "Project Structure" +description: "Start with one agent, keep application code beside it, and split into a workspace only when you need separately addressable agents." +--- + +Start with one root agent in `agent/`. A root agent accepts requests through its own HTTP API or channels; it can have many tools, skills, and subagents. Keep browser application files outside `agent/`. + +| When you need… | Structure | +| ---------------------------------------------------------------------- | ------------------------------------------------ | +| One agent, with or without a browser app | `agent/` beside your application code | +| A specialist that an agent delegates to | `agent/subagents//` inside that agent | +| Several separately addressable agents sharing a package and deployment | `agents//agent/` in an eve agent workspace | +| Separate dependencies, versions, or release schedules | Separate agent packages or projects | + +Every root agent can have [declared subagents](/docs/subagents#declared-subagents) with their own prompts, tools, and sandboxes. These specialists have no separate channel endpoint and do not inherit the parent's authored capabilities. Use a [skill](/docs/skills) instead when you only need an optional procedure. + +## One agent + +Use this layout for a standalone agent or an agent inside a web application: + +```text +project/ +├── package.json +├── agent/ +│ ├── instructions.md +│ ├── tools/ +│ └── subagents/ +├── evals/ +├── app/ # optional Next.js browser application +└── next.config.ts # optional Next.js integration +``` + +Create the agent with [Getting Started](/docs/getting-started). The [Agent Files reference](/docs/reference/agent-files) lists supported paths. Keep agent-only helpers in `agent/lib/`; share reusable capabilities through [extensions](/docs/extensions). + +For a generated Next.js chat UI, run `eve add channel/web` from the project root. For an existing browser app, follow your [framework integration guide](/docs/guides/frontend/overview#per-framework-integration). + +## Several root agents + +Use an eve agent workspace when, for example, clients need to address support and research separately: + +```text +project/ +├── package.json +├── agents/ +│ ├── support/ +│ │ ├── agent/ +│ │ └── evals/ +│ └── research/ +│ ├── agent/ +│ └── evals/ +└── apps/ # optional peer applications, not eve workspace members + └── web/ +``` + +Members share the root package, dependencies, scripts, and Vercel deployment. Their directory names identify them in the CLI and public routes. Members have no `package.json` of their own: adding one excludes that directory from eve workspace discovery. Unlike a package-manager workspace, this layout does not give members separate dependency or version boundaries. + +Create a workspace, then select an agent to run: + +```bash +npx eve@latest init operations --agents support,research +cd operations +npx eve dev --agent support +``` + +Run agent commands such as `dev`, `info`, and `eval` from `agents//`, or pass `--agent ` from the workspace root. `eve dev --agent support` runs the selected agent, not peer applications. Start other agents separately when needed; local [workspace-peer calls](/docs/subagents#vercel-workspace-peers) require an explicit transport. + +On Vercel, run `eve link` and `eve deploy` from the root; deployment includes all members. No frontend is required. For self-hosting, [build and run each member separately](/docs/guides/deployment/self-hosting#run-workspace-members). + +## Independent releases + +Use separate packages or projects when agents need independent dependencies or releases, even within the same monorepo. These are not eve agent-workspace members. Share capabilities through [workspace extensions](/docs/extensions#use-an-extension-in-a-workspace); delegate across deployments with [remote agents](/docs/guides/remote-agents). + +## Configure a web deployment + +Choose how the frontend and agents run together independently of how many agents you have: + +- **Add agents to a Next.js application:** use [`eve/next`](/docs/guides/frontend/nextjs) in `next.config.ts`. Next.js owns the application lifecycle; the integration starts agent processes and proxies requests locally, and contributes separate agent services on Vercel. A root Next.js app can sit beside either `agent/` or `agents/`; workspace members are discovered automatically. +- **Add a frontend to an agent workspace:** keep the frontend as a peer application, for example under `apps/web/`. On Vercel, use [`eve/vercel` in root `vercel.ts`](/docs/guides/deployment/vercel#compose-agents-with-other-vercel-services) to contribute the agents alongside the frontend service. For [self-hosting](/docs/guides/deployment/self-hosting#run-workspace-members), run the services with your process manager and configure a reverse proxy. The frontend does not need `eve/next`. + +`apps/web/` is an organizational convention, not an eve filesystem slot. Deployment configuration owns peer services; eve discovers only the agents. Both Vercel integrations deploy the services together, not as independent releases. + +The generated Web Chat installer does not support agent workspaces. Create the frontend and its agent-selection UI yourself, using the [React chat example](/docs/guides/frontend/overview#basic-chat-react). Develop a peer Next.js frontend with `next dev` separately from the agents. For an authored Vercel service graph, use `vercel dev --local` to run the composition without linking a Vercel project. + +For a single `agent/` project, `eve add channel/web` currently generates a root Next.js app using `eve/next`. `eve/vercel` currently requires an `agents/` workspace; it cannot compose a standalone root `agent/`. + +## Add a second root agent + +To convert a single-agent project into a workspace, move the original agent from the project root: + +```bash +mkdir -p agents/support +mv agent agents/support/agent +``` + +Move its `evals/` directory, if present, to `agents/support/evals/`. Keep `package.json`, dependencies, environment files, and any browser application at the project root. Do not leave a root `agent/` directory: eve treats a project with `agent/` as single-agent even when `agents/` also exists. + +Before adding the next agent: + +- Update `tsconfig.json` to include `agents/**/*.ts`, preserving any application includes. Update moved-file imports and path aliases, including scaffolded `package.json#imports` entries that point at `./agent/*` or `./evals/*`. +- Update scripts that assume one agent. Use `--agent support` for agent-scoped commands; build an agent-only Vercel workspace with root `eve build`. For a Next.js app, keep the framework scripts and follow its [build instructions](/docs/guides/frontend/nextjs#dev-vs-deploy-topology). +- Update HTTP clients and webhook registrations for the named agent's public routes. In a root Next.js app, remove a single-agent `eveRoot` override to enable workspace discovery, and select `support` in the client hook. Store the agent name alongside durable-session links. + +Then add the second agent and check discovery: + +```bash +npx eve init research +npx eve info --agent support +npx eve info --agent research +``` + +Run the moved agent's evals with `npx eve eval --agent support`. Add later agents with `npx eve init ` from the workspace root. diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx index 4a03412fd..74e984b45 100644 --- a/docs/getting-started.mdx +++ b/docs/getting-started.mdx @@ -1,6 +1,6 @@ --- title: "Getting Started" -description: "Create an eve project, configure a model, understand its filesystem layout, and run your first agent." +description: "Create an eve project, configure model credentials, and run your first agent." contentType: "How-to" --- @@ -18,6 +18,8 @@ Choose a model, provider, and channel that meet your data-processing and complia ## Create a project +Start with one agent in `agent/`. + Run `eve init` with a project name: ```bash @@ -48,119 +50,29 @@ npx eve@latest init my-agent --model openai/gpt-5.6-terra --reasoning high ## Run the agent -The terminal UI opens after interactive initialization. To return later, run this from the project root: +The terminal UI opens after interactive initialization. To return later, enter the project and run: ```bash +cd my-agent npm run dev ``` -This starts an interactive session where you can send messages to your agent. +This starts an interactive session where you can send messages to your agent. Edit `agent/instructions.md` to change its behavior and `agent/agent.ts` to configure its model. eve reloads your changes as you work. -## Project layout + + + + + + + + + + -eve builds an agent by walking the filesystem under `agent/`. Each directory is an authored slot, and the slot a file lands in determines how eve loads it. +## Organize your project -### Naming from paths - -eve derives names from file paths, so you do not configure them separately. - -| 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` | - -The root agent uses its `package.json` `name`, or its app directory name if none is set. A subagent uses its directory name. - -### Recommended layout - -A minimal agent needs `instructions.md`; `agent.ts` is optional when the default config is sufficient. Framework defaults occupy ordinary agent slots, so authoring the same path replaces the default before eve compiles the agent. Add other slots as the agent needs them: - -```text -my-agent/ -├── README.md -├── package.json -├── tsconfig.json -├── agent/ -│ ├── agent.ts -│ ├── instructions.md -│ ├── instrumentation.ts -│ ├── channels/ -│ ├── connections/ -│ ├── hooks/ -│ ├── skills/ -│ ├── lib/ -│ ├── sandbox/ -│ ├── tools/ -│ ├── schedules/ -│ └── subagents/ -└── evals/ -``` - -Evals live beside `agent/`, not inside it. - -### Agent files and directories - -Each path under `agent/` has a specific purpose. Root agents can use every path below. A subagent has its own files and can use only the paths marked **Yes**. - -| Path | Use | Available to subagents | Notes | -| ------------------------------------------------------- | ----------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `agent.ts` | Runtime config | Yes | Model, model options, compaction, build, and experimental settings. See [Agents](./agent-config). | -| `instructions.md` / `instructions.ts` / `instructions/` | Base system prompt | Optional | A flat file or directory of `.md` and `.ts` files. Static sources compose at build time. Dynamic sources resolve at runtime. Required on the root, optional on subagents. | -| `instrumentation.ts` | Telemetry config | No | OTel exporter and AI SDK span settings, auto-discovered and run before agent code. Root-only. | -| `channels/` | HTTP and messaging entry points | No | Root-only. | -| `connections/` | External MCP and OpenAPI services | Yes | Static files define one path-named connection. Dynamic files can resolve a caller-specific connection set at runtime. | -| `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. Runtime files are seeded under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. | -| `lib/` | Shared authored helper code | Yes | Import-only; not mounted into the workspace. | -| `sandbox.ts` or `sandbox/sandbox.ts` | The agent's single sandbox | Yes | Use `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` with `sandbox/workspace/**` to also seed files. 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 | Each schedule is a default-exported `defineSchedule` module or a markdown prompt with `cron` frontmatter. Recursive nesting is supported. Root-only. | -| `subagents/` | Specialist child agents | Yes | Each child is a local package under `subagents//`. Nested subagents are supported. | - -### Files available in the sandbox - -Files under `agent/` define your agent; only files in `agent/sandbox/workspace/` are copied to `/workspace/` when a session starts. - -### Local subagents - -A local subagent uses the same `agent.ts` shape as the root: - -```text -agent/subagents/researcher/ -├── agent.ts -├── instructions.md -├── connections/ -├── hooks/ -├── skills/ -├── lib/ -├── sandbox/ -├── tools/ -└── subagents/ -``` - -A subagent's `agent.ts` is required and must provide a description, while its instructions are optional. Connections, hooks, skills, shared code, sandboxes, tools, and nested subagents are supported. Channels and schedules remain root-only. See [Subagents](./subagents) for inheritance and isolation behavior. - -### Flat layout - -When the app root is also the agent root, eve supports this layout: - -```text -my-agent/ -├── package.json -├── agent.ts -├── instructions.md -├── tools/ -└── skills/ -``` - -Prefer the nested layout because it keeps application files separate from the authored agent surface. - -### Debug file discovery - -Run `eve info` when eve does not discover a file. It lists the discovered surface and diagnostics so you can check the authored slot and root-versus-subagent boundary. eve also writes inspectable artifacts under `.eve/`; see [Instrumentation](./observability/instrumentation) and the [CLI](./reference/cli) reference. +See [Project Structure](/docs/concepts/project-structure) when adding another root agent or deciding where a frontend belongs. The [Agent Files reference](/docs/reference/agent-files) lists supported files and discovery rules. ## Install manually diff --git a/docs/guides/deployment/self-hosting.md b/docs/guides/deployment/self-hosting.md index f54728fc9..71792125b 100644 --- a/docs/guides/deployment/self-hosting.md +++ b/docs/guides/deployment/self-hosting.md @@ -61,6 +61,46 @@ Forward both runtime route prefixes through your reverse proxy or ingress: A proxy restricted to `/eve/` lets a session start, but the run stalls when its callback can’t reach eve. Preserve both prefixes without rewriting their paths. +## Run workspace members + +An [agent workspace](../../concepts/project-structure#several-root-agents) does not require Vercel or a frontend at runtime. Build each member from its own directory: root `eve build` produces a Vercel workspace deployment, not a group of self-hosted Node servers. + +For a workspace containing `support` and `research`, run these from the workspace root, outside a Vercel build environment: + +```bash +(cd agents/support && npx eve build) +(cd agents/research && npx eve build) +``` + +Start each built agent in a separate terminal, or configure these commands in your process manager: + +```bash +(cd agents/support && npx eve start --host 127.0.0.1 --port 3001) +(cd agents/research && npx eve start --host 127.0.0.1 --port 3002) +``` + +For example, this Caddy configuration gives each agent its own origin and forwards both `/eve/` and `/.well-known/workflow/` without changing their paths. Point the example hostnames at your server and run Caddy on the same machine: + +```text +support.example.com { + reverse_proxy 127.0.0.1:3001 +} + +research.example.com { + reverse_proxy 127.0.0.1:3002 +} +``` + +Apply the authentication, persistent storage, and sandbox configuration above to each member. With the default local Workflow world, persist each member's own `.eve/.workflow-data` directory. If agents delegate to one another, configure an explicit [workspace-peer transport](../../subagents#vercel-workspace-peers) with the peer's URL and credentials; the default transport requires Vercel. Ensure callback URLs are reachable from the services that call them. + +### Add a peer frontend + +A frontend under `apps/web/` is another service managed by your host, not by `eve start`. Build and start it using its framework commands. A browser client can use `useEveAgent({ host: "https://support.example.com" })`; configure [CORS](../../channels/eve#cors) and browser credentials for that deployment. Alternatively, mount each agent on the frontend's origin through your reverse proxy. + +For path-based mounts, strip the public prefix before forwarding requests to the agent and set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments. Forward its workflow callback routes as well as its eve routes. Keep the browser client, callback URLs, and peer transports consistent with the public mounts. + +You can instead use [`eve/next`](../frontend/nextjs#dev-vs-deploy-topology) if you want Next.js to start built agent processes and provide the browser-facing proxy routes. That integration is optional; `eve/vercel` configuration is not used by a self-hosted process manager. + ## Run schedules The standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler. diff --git a/docs/guides/deployment/vercel.mdx b/docs/guides/deployment/vercel.mdx index c13aeb48e..78d504681 100644 --- a/docs/guides/deployment/vercel.mdx +++ b/docs/guides/deployment/vercel.mdx @@ -7,7 +7,7 @@ Deploy eve to Vercel when you want the framework’s managed build and runtime i ## Prepare the Vercel project -Link the agent directory to a Vercel project: +Run this from the project root to link it to a Vercel project. For an eve agent workspace, use the workspace root, not a member directory: ```bash eve link @@ -51,27 +51,17 @@ See [Sandbox](../../sandbox) for resource limits, network policy, and lifecycle ## Deploy the agent -A project containing only several independently addressed root agents can use eve's hostless workspace layout: +For a single-agent project without a frontend, use `eve build`. For an agent-only workspace, run it from the workspace root: eve generates a separately built service and a `//eve/v1/*` transport route for each member. All members deploy together in one Vercel project. See [Project Structure](../../concepts/project-structure) for workspace membership and layout rules. -```text -my-project/ -├── package.json -└── agents/ - ├── support/ - │ └── agent/ - └── research/ - └── agent/ -``` - -In an eve workspace, eve discovers direct `agents//` children that contain nested or flat agent files and do not have their own `package.json`. Their directory names become their public identities, exposed at `//eve/v1/*`. A child with its own `package.json` is a separate package rather than a member of the parent eve workspace. Run an agent-specific command from a member directory or pass `--agent ` at the workspace root; interactive commands open a picker when the name is omitted. Run project-level build, link, and deploy commands from the workspace root. Workspace members share the root package, dependencies, and build scripts. - -Create this layout with `eve init my-project --agents support,research`, or add one agent to an existing workspace with `eve init billing`. - -For an agent-only workspace, run `eve build`. eve owns the Vercel Build Output and generates one independently built service and a `//eve/v1/*` transport route for each workspace member. +A Next.js-centered project uses [`withEve` in `next.config.ts`](../frontend/nextjs) and its Next.js build command. If you author the project's broader service graph in `vercel.ts`, use the configuration below instead. ### Compose agents with other Vercel services -Use Vercel's programmatic configuration when a workspace also deploys a frontend, private API, or another non-eve service. Replace `vercel.json` with a root `vercel.ts` and compose the authored graph with `withEve`: +Use `withEve` from `eve/vercel` when the agents and other applications are peer services. The helper contributes workspace agents to a Vercel service graph; it does not manage or require a particular frontend framework. Unlike `eve/next`, this keeps the project lifecycle separate from Next.js. Both integrations deploy the agent services together in one Vercel project. + +`eve/vercel` currently requires an `agents/` workspace, even if it has only one member. It does not support a standalone root `agent/`. + +For a workspace with a peer Next.js frontend under `apps/web/`, replace `vercel.json` with a root `vercel.ts`. The frontend uses an ordinary Next.js config without `eve/next`: ```typescript title="vercel.ts" import { withEve } from "eve/vercel"; @@ -92,7 +82,11 @@ export default await withEve({ }); ``` -Vercel evaluates `vercel.ts` before resolving the service graph. `withEve` discovers direct workspace members, adds their services and transport routes, and returns a plain Vercel configuration. Vercel can then build `web` and every eve agent independently. The frontend does not need `withEve` in its framework configuration or a build script that builds the agents. +Vercel evaluates `vercel.ts` before resolving the service graph. `withEve` discovers direct workspace members, adds their services and transport routes, and returns a plain Vercel configuration. Vercel then builds `web` and each eve agent separately. The frontend does not need a build script that builds the agents. + +The Web Chat installer does not support agent workspaces. Create the frontend using the [React chat example](../frontend/overview#basic-chat-react), and configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own [process and proxy configuration](./self-hosting#run-workspace-members). + +Workspace agents use `//eve/v1/*` routes. A same-origin React client calls support with `useEveAgent({ host: "/support" })`; the hook's `agent: "support"` shorthand targets the different `/eve/agents/support` mount used by frontend framework integrations. Generated transport routes are inserted before a filesystem handler or, when no filesystem handler exists, before authored routes. `withEve` throws instead of overwriting an authored service key or exact transport route that belongs to a generated agent. Remove the authored route, and remove or rename the authored service; `withEve` adds both automatically. Names in the array form of `services` must also be unique. Other service names, routes, bindings, and Cron Jobs remain authored in `vercel.ts`. @@ -122,7 +116,9 @@ A Vercel project can use only one configuration source, so remove `vercel.json` An authored eve service routed at `/eve/v1` already uses the protocol path; callbacks remain at `/eve/v1/callback/*`. A named mount such as `/support` adds that mount before the protocol path, giving `/support/eve/v1/callback/*`. -Deploy the linked project to production: +### Deploy the project + +Deploy the linked project to production from its root: ```bash eve deploy @@ -145,7 +141,14 @@ Vercel uses the generated output to configure these services: ## Verify the deployment -Check the health route and connect the development TUI: +For a single unnamed agent, check the health route and connect the development TUI: + +```bash +curl https://your_agent.vercel.app/eve/v1/health +eve dev https://your_agent.vercel.app +``` + +For a workspace agent, include its public mount: `/support` with `eve/vercel` or an agent-only workspace, or `/eve/agents/support` with `eve/next`. For example: ```bash curl https://your_agent.vercel.app/support/eve/v1/health diff --git a/docs/guides/frontend/nextjs.mdx b/docs/guides/frontend/nextjs.mdx index cd58ff5e0..36b9e2cde 100644 --- a/docs/guides/frontend/nextjs.mdx +++ b/docs/guides/frontend/nextjs.mdx @@ -3,13 +3,29 @@ title: "Next.js" description: "Run an eve agent and a Next.js app as one project with withEve." --- -`eve/next` ships a Next.js frontend and an eve agent as a single project. Wrap your config with `withEve()` to run both from one dev server and one Vercel deploy. [`useEveAgent`](./overview) finds the mounted routes on its own, so there's no CORS to configure and no URL env vars to keep in sync. +`eve/next` connects a Next.js app to one or more eve agents. Wrap your Next.js config with `withEve(nextConfig)` to run the app and agents with one development command and deploy them as one Vercel project. Browser requests use same-origin routes; the agent runtimes remain separate services. + +Use this integration when Next.js owns the application's development and deployment lifecycle. If the frontend is a peer of an agent workspace, compose the services with [`eve/vercel`](../deployment/vercel#compose-agents-with-other-vercel-services) on Vercel or your [self-hosted process manager and proxy](../deployment/self-hosting#run-workspace-members). A peer frontend can use `eve/react` without `eve/next`. See [Project Structure](/docs/concepts/project-structure#configure-a-web-deployment) for the choice. ## Prerequisites - The `eve` package installed in your project (`npm install eve@latest`). -- An existing eve agent directory. If you don't have one, start from [Getting started](../../getting-started). -- A Next.js app to mount the agent in. +- An existing eve agent directory. If you don't have one, start from [Getting Started](../../getting-started). +- A Next.js app, or a single-agent project where you want to generate one below. + +## Add the generated Web Chat app + +For a single-agent project, install the generated Next.js Web Chat app: + +```bash +eve add channel/web +``` + +The installer adds a Next.js application and wraps `next.config.ts` with `withEve()`. The generated chat calls the unnamed agent through same-origin `/eve/v1/*` routes. + +Before accepting production browser traffic, replace the generated placeholder authorization policy. See [Authenticate browser requests](./overview#authenticate-browser-requests). + +The Web Chat installer does not support eve agent workspaces. If you want Next.js to host the integration, create a root Next.js application and follow the steps below; `withEve(nextConfig)` discovers workspace members but does not generate a chat UI. To keep the frontend as a peer application instead, follow the [workspace layout guidance](/docs/concepts/project-structure#configure-a-web-deployment). ## Wrap the Next.js config @@ -22,7 +38,7 @@ const nextConfig: NextConfig = {}; export default withEve(nextConfig); ``` -By default `withEve()` looks for an `agent/` folder inside your Next.js project root. When the project root is an eve workspace with `agents//` members, it discovers every member and mounts each at `/eve/agents//eve/v1/*` instead. +By default `withEve(nextConfig)` looks for an `agent/` folder inside your Next.js project root and mounts its API at `/eve/v1/*`. When the project root is an eve workspace with `agents//` members, it discovers every member and mounts each at `/eve/agents//eve/v1/*` instead. You do not need an explicit `agents` map for this layout. If one agent lives somewhere else, point at it with `eveRoot`: @@ -32,14 +48,16 @@ export default withEve(nextConfig, { }); ``` +## Mount agents outside a workspace + To mount agents that are not members of the project-level `agents/` workspace, use `agents`. String values are agent roots; object values can override the build command or private production service prefix for that agent: ```ts export default withEve(nextConfig, { agents: { - support: "./agents/support", + support: "./apps/support-agent", billing: { - root: "./agents/billing", + root: "./apps/billing-agent", buildCommand: "pnpm build:billing-agent", servicePrefix: "/_eve_internal/billing", }, @@ -47,13 +65,6 @@ export default withEve(nextConfig, { }); ``` -Named agents mount under `/eve/agents//eve/v1/*`. Call the matching agent from React with `agent`: - -```tsx -const support = useEveAgent({ agent: "support" }); -const billing = useEveAgent({ agent: "billing" }); -``` - Use either `eveRoot` or `agents`, not both. `eveRoot` remains the shorthand for a single unnamed agent mounted at `/eve/v1/*`. Generated agent services build with `EVE_PUBLIC_ROUTE_PREFIX` set to the agent's public mount (for example `/eve/agents/support`) so framework-minted callback URLs — OAuth connection callbacks and remote-subagent session callbacks — resolve to the public per-agent path. If you configure eve services manually in `vercel.json` instead, export that variable in each named agent's build command. @@ -80,7 +91,24 @@ export default withEve(nextConfig, { ## Call the hook -With `withEve()` in `next.config.ts`, the eve routes are same-origin, so client code can call [`useEveAgent`](./overview) without naming a host. Cookie-based auth (Auth.js or any session cookie) needs no extra wiring, since the browser already sends those cookies on every eve request. For non-cookie schemes, attach the credentials yourself: +For a single unnamed agent, call [`useEveAgent`](./overview) without `agent` or `host`. For named agents, whether discovered from a workspace or configured explicitly, pass the name: + +```tsx +"use client"; + +import { useEveAgent } from "eve/react"; + +export function SupportStatus() { + const support = useEveAgent({ agent: "support" }); + return

{support.status}

; +} +``` + +See [Basic chat](./overview#basic-chat-react) for rendering messages and sending turns. + +Bind each chat route to its agent, and include the agent identity in durable-session URLs so the UI does not restore a session through the wrong agent route. Remount the chat component when switching agents: the hook reads `agent` when it creates its store. + +Requests are same-origin, so the browser sends application cookies to the agent. Each agent must verify those credentials through its own channel authentication policy. For non-cookie schemes, attach the credentials yourself: ```tsx const agent = useEveAgent({ @@ -90,7 +118,7 @@ const agent = useEveAgent({ }); ``` -The browser still needs a production authentication policy. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration. +Configure authorization for every exposed agent before accepting production browser traffic. See [Authenticate browser requests](./overview#authenticate-browser-requests) for the default fail-closed behavior and channel configuration. ## Use the generated Web Chat routes @@ -129,15 +157,21 @@ See [Resumable sessions](./overview#resumable-sessions) for persistence and repl - **Local production build.** `next build && next start` serves the eve runtime from its built `.output/server/index.mjs` on a stable local port (`4274`) and proxies the eve routes to it. Run `eve build` first so that output exists. In an `agents/` workspace, build every member from its `agents//` directory before starting Next.js. Change the port with `EVE_NEXT_PRODUCTION_PORT`: ```bash - EVE_NEXT_PRODUCTION_PORT=5000 npm run build && npm start + export EVE_NEXT_PRODUCTION_PORT=5000 + npm run build && npm start ``` -- **Non-Vercel hosts.** When the eve service lives on a separate origin, tell Next.js where to find it with `EVE_NEXT_PRODUCTION_ORIGIN`: +- **Non-Vercel hosts.** `withEve()` provides both agent process startup and Next.js proxy rewrites; self-hosters using this path do not need to recreate the browser-facing routing. The Vercel service output is a separate integration, not a self-hosting requirement. By default, `next start` runs each built eve service on its derived loopback port. If your host supervises eve services itself, run each service separately and set `EVE_NEXT_PRODUCTION_ORIGIN` to the origin that serves its private route prefix: ```bash - EVE_NEXT_PRODUCTION_ORIGIN=https://agent.example.com npm run build + export EVE_NEXT_PRODUCTION_ORIGIN=https://agent.example.com + npm run build && npm start ``` + This setting disables automatic production agent startup. The destination includes `servicePrefix`: for named agents, the default is `/_eve_internal/eve//eve/v1/*`. Configure that routing on the destination host, and use the same origin setting when building and starting Next.js. + + If the public routing layer mounts an agent below a path, set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments so callback URLs use the public path. Process restarts, persistent workflow storage, sandbox configuration, and workflow callback routing remain hosting responsibilities; see [Self-host eve](../deployment/self-hosting). + ## What to read next - [Frontend overview](./overview): the `useEveAgent` API diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdx index d74070d93..a4c74cbd0 100644 --- a/docs/guides/frontend/overview.mdx +++ b/docs/guides/frontend/overview.mdx @@ -3,16 +3,16 @@ title: "Overview" description: "Put an eve agent behind a browser chat UI with useEveAgent." --- -The frontend helpers put a browser chat or agent UI on top of an eve agent. `useEveAgent()` opens a durable session, sends turns, streams the reply back, and turns the raw event stream into render-ready state. React is the reference implementation; [Vue](./use-eve-agent-vue) and [Svelte](./use-eve-agent-svelte) ship the same surface. +Use this guide when you already have a browser application and need to connect it to an eve agent. `useEveAgent()` opens a durable session, sends turns, streams the reply back, and turns the raw event stream into render-ready state. React is the reference implementation; [Vue](./use-eve-agent-vue) and [Svelte](./use-eve-agent-svelte) ship the same surface. ## The integration model A browser UI is a client of the agent's HTTP routes (the [eve channel](../../channels/overview)). Two layers wire it up: -- **The framework integration** mounts the eve routes on your app's origin, so the browser never crosses a CORS boundary or reads an env var to find the agent. Pick yours: [Next.js](./nextjs) (`withEve`), [Nuxt](./nuxt) (the `eve/nuxt` module), or [SvelteKit](./sveltekit) (the `eveSvelteKit` Vite plugin). On any other stack the hook talks to same-origin `/eve/v1/*` routes directly, or you pass an explicit `host`. +- **Routing** makes the agent reachable from the browser. A framework integration can mount eve on your app's origin: [Next.js](./nextjs) (`withEve`), [Nuxt](./nuxt) (the `eve/nuxt` module), or [SvelteKit](./sveltekit) (the `eveSvelteKit` Vite plugin). If the frontend and agents are peer services, use your deployment platform or reverse proxy instead. The hook works with either setup; pass `host` for a different origin or a named path mount. - **The hook** (`useEveAgent`) holds the session state, streaming, errors, and composer status. It defaults to same-origin eve routes such as `/eve/v1/session`. -The per-framework pages below walk through the wiring step by step: [Next.js](./nextjs), [Nuxt](./nuxt), and [SvelteKit](./sveltekit). +The framework pages walk through the wiring step by step: [Next.js](./nextjs), [Nuxt](./nuxt), and [SvelteKit](./sveltekit). See [Project Structure](../../concepts/project-structure#configure-a-web-deployment) to choose between a framework integration and peer services. For scripts, server-to-server calls, evals, tests, or custom clients that do not need framework UI state, use the [Client SDK](../client/overview) directly. diff --git a/docs/install-integrations.mdx b/docs/install-integrations.mdx index 5249df392..c669a147f 100644 --- a/docs/install-integrations.mdx +++ b/docs/install-integrations.mdx @@ -19,7 +19,7 @@ eve add memory/file If an item is not found, `eve add` searches the available catalogs and prints close matches without installing anything. -Web Chat installs a project-level Next.js application and cannot currently be added to a top-level `agents/` workspace. For that topology, create a root Next.js application and wrap its config with [`withEve()`](./guides/frontend/nextjs); eve discovers the workspace agents automatically. eve rejects `eve add channel/web` before writing files when the selected agent belongs to such a workspace. +Web Chat installs a project-level Next.js application. It cannot be added to an eve agent workspace; eve rejects the installation before writing files. See [Project Structure](./concepts/project-structure) for browser-app placement and [Next.js](./guides/frontend/nextjs) for manual integration. If you do not know an item name yet, run `eve add` without an argument. Its help output shows how to search the registry with `eve registry search `. diff --git a/docs/reference/agent-files.md b/docs/reference/agent-files.md new file mode 100644 index 000000000..e9b03670c --- /dev/null +++ b/docs/reference/agent-files.md @@ -0,0 +1,104 @@ +--- +title: "Agent Files" +description: "Look up agent directory slots, path-derived names, subagent files, and filesystem discovery rules." +--- + +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. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index fb4cfd8f7..bdbd91b22 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -399,10 +399,10 @@ Lists the user-authored channels in the current project. 4. `eve build` before shipping. 5. `eve start` to smoke-test the built output locally. -Related: [Project layout](../getting-started#project-layout) · [Instrumentation](../observability/instrumentation). +Related: [Agent Files](/docs/reference/agent-files) · [Instrumentation](../observability/instrumentation). ## What to read next -- [Project layout](../getting-started#project-layout): what `eve info` discovers +- [Agent Files](/docs/reference/agent-files): what `eve info` discovers - [Instrumentation](../observability/instrumentation): tracing and the error catalog - [Deployment](../guides/deployment/overview): `eve build` and `eve start` in production diff --git a/docs/reference/meta.json b/docs/reference/meta.json index 65d284e9f..8f4d25d0c 100644 --- a/docs/reference/meta.json +++ b/docs/reference/meta.json @@ -1 +1 @@ -{ "title": "Reference", "pages": ["typescript-api", "cli", "telemetry"] } +{ "title": "Reference", "pages": ["agent-files", "typescript-api", "cli", "telemetry"] } diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md index ecefa89b0..4cf18dd78 100644 --- a/docs/reference/typescript-api.md +++ b/docs/reference/typescript-api.md @@ -223,4 +223,4 @@ Troubleshooting: - [`agent.ts`](../agent-config): the agent config these helpers configure - [Tools](../tools): `defineTool`, the most-used helper -- [Project layout](../getting-started#project-layout): where each define\* lives on disk +- [Agent Files](/docs/reference/agent-files): where each define\* lives on disk