Start an AI Agent Project, Not Just an Agent

Starting an AI agent is easy. The hard part is what comes after: iterating on it in production without the whole thing turning into a mess.

Requirements that belong in code leak into prompts. Shared types get copied between files. And when something breaks, debugging is rough, because nothing separates what the model decided from what your code actually did.

Atlas Eve Starter is a public GitHub template that hands you a project shape before any of that sets in. The short version: the default Eve scaffold helps you start an agent; this starter helps you start an agent project.

It keeps the Eve app small and replaceable, then wraps it in the engineering defaults you would add yourself a week later anyway: a pnpm monorepo, formatting and linting, tests, dependency maintenance, and Atlas AI context for the people and coding agents working in the repo.

What is Eve?

Eve is Vercel's open-source, filesystem-first framework for durable backend AI agents. Instead of one large configuration object, you describe an agent as a directory of files: instructions in Markdown, deterministic behavior in typed tools, ingress surfaces in channels, and evals next to the code they check. Eve discovers those files and compiles them into an app.

That layout is the point. Real agents have to be inspected, reviewed, tested, and changed over time, and a folder of small files is much easier to reason about than a monolithic config.

What you get from Eve is more than a chat loop:

Durable sessions. Every conversation is a checkpointed workflow, so a run can pause, survive a crash or a deploy, and pick up where it left off.
Per-agent sandboxes. Shell commands, scripts, and file access run in an isolated environment, away from your app runtime.
One agent, many channels. Slack, Discord, Teams, Telegram, Twilio, GitHub, and Linear are adapters you opt into, and the same agent serves all of them.

In practice, that means ops bots that live in Slack, GitHub and Linear automations, and webhook-driven backend agents: long-running work where "it crashed halfway through" is not an acceptable outcome.

The default scaffold is deliberately minimal: an agent file, a channel, instructions, and TypeScript setup. That's the right way to learn the framework. Atlas Eve Starter picks up at the next step, when you already suspect the agent will end up inside a real product.

From a scaffold to a project

Here is the shape the starter gives you:

atlas-eve-starter/
├─ apps/
│  └─ example-agent/
│     ├─ agent/
│     │  ├─ agent.ts            # root agent config
│     │  ├─ instructions.md     # system prompt
│     │  ├─ tools/echo.ts       # typed tool
│     │  └─ channels/http.ts    # custom HTTP ingress with input validation
│     ├─ evals/example.eval.ts  # opt-in smoke eval
│     └─ tests/echo.test.ts     # plain unit test for the tool
├─ packages/
│  └─ example/                  # shared Zod contracts (no Eve dependency)
└─ .ai/                         # Atlas: memory, skills, decisions, plans, vocabulary

The example app is intentionally domain-neutral and not meant to be a finished product.

The boundary between model-guided behavior and deterministic code is already in place. The app is a shell, but it hands you the structure and building blocks to expand into something functional.

Shared contracts live in their own package, with no dependency on Eve:

// packages/example/src/index.ts
export const exampleRequestSchema = z.object({
  message: z.string().trim().min(1, "Message must not be empty."),
});

export type ExampleRequest = z.infer<typeof exampleRequestSchema>;

A tool imports that contract and stays an ordinary, testable function, with no model in the loop:

// apps/example-agent/agent/tools/echo.ts
export function createEchoResponse(request: ExampleRequest): ExampleResponse {
  return {
    echoedMessage: request.message,
    messageLength: request.message.length,
  };
}

export default defineTool({
  inputSchema: exampleRequestSchema,
  execute(input) {
    return createEchoResponse(input);
  },
});

And the channel validates input at the edge, before anything reaches the agent:

// apps/example-agent/agent/channels/http.ts
POST("/echo", async (req, { send }) => {
  const body = await req.json().catch(() => ({}));
  const parsed = exampleRequestSchema.safeParse(body);

  if (!parsed.success) {
    return Response.json(
      { error: "Invalid example request.", issues: parsed.error.issues },
      { status: 400 },
    );
  }

  // valid input → hand the message off to the agent
});

The same Zod schema backs the package, the tool, and the channel. You can unit-test the deterministic parts directly while the model handles only the model-shaped work. That is what makes the project easier to review, and to debug when something goes wrong.

What the starter adds on top of Eve

The default Eve scaffold covers the essentials. Atlas Eve Starter adds what teams reach for once a project gets serious:

a pnpm and Turborepo monorepo for apps and shared packages
Biome for formatting and linting, with a pre-commit hook and lint-staged
Vitest tests for the deterministic tool and the shared contracts
an opt-in Eve eval
Renovate for dependency updates
a reusable package pattern for schemas and types
a custom HTTP channel with validation at the boundary
Atlas .ai project context, present from the start

Atlas context from the first commit

Atlas is Blazity's framework-agnostic AI engineering scaffold. In this starter it gives the repo a shared memory layer that people and coding agents both read from: project vocabulary, architecture and stack notes, artifact paths, and repo-local skills for creating or auditing Eve agent changes.

The practical effect is that a coding agent dropped into the project does not have to guess from filenames. It can read the rules first: what the starter is for, which files define agent behavior, where shared contracts belong, which checks are safe to run, and which model-backed checks are opt-in. If your team works with AI coding tools, that context takes a lot of ambiguity out of review.

When to reach for it

Use Atlas Eve Starter when you want to evaluate Eve with a clean project structure, keep prompt behavior separate from deterministic code, and give reviewers and coding agents clear boundaries from the start. It is more structure than a throwaway demo needs. If the agent might become part of a product, that structure pays for itself quickly.

Get started

The template is on GitHub: github.com/Blazity/atlas-eve-starter. Create a repo from the template, then:

pnpm install
pnpm --filter @repo/example-agent dev
pnpm check && pnpm typecheck && pnpm test

From there, replace the example app with your own behavior and keep the boundaries explicit from the first commit. That's how we build Eve agents at Blazity: clear structure, typed contracts, reviewable behavior, and AI context that helps the next contributor, human or otherwise, get up to speed faster.

推荐订阅源

DEV Community