# Project layout

An Agent SDK project keeps agent files under `bot/`, and each file's
path determines how Agent SDK loads it. [Evals](/docs/evals.md) live in
`evals/` at the project root, beside `bot/`.

```text
my-agent/
├── package.json
├── bot/
│   ├── agent.ts
│   ├── instructions.md
│   ├── tools/
│   │   └── approve_pr.ts
│   ├── skills/
│   │   └── pr-review.md
│   ├── mcp-connections/
│   │   └── linear.ts
│   ├── subagents/
│   │   └── reviewer/
│   │       ├── agent.ts
│   │       └── instructions.md
│   ├── extensions/
│   │   └── ci.ts
│   ├── channels/
│   │   └── github.ts
│   └── hooks/
│       └── audit.ts
└── evals/
    ├── evals.config.ts
    └── readiness.eval.ts
```

The root agent's name is the `name` in `package.json`, or else the directory name. When one server hosts multiple agents, each slug is the agent's directory name, and it must match `[A-Za-z0-9][A-Za-z0-9_-]*` and can't be `v1`, `playground`, or `docs`.

## Folder reference

| Path under `bot/` | What it is | Reference |
| --- | --- | --- |
| `agent.ts` | `defineAgent({ model?, local? })` | [Agent config](/docs/reference/agent-config.md) |
| `instructions.md` | Always-on system prompt, required on the root agent | [Instructions](/docs/reference/instructions.md) |
| `tools/<name>.ts` | One typed tool named after the file | [Tools](/docs/reference/tools.md) |
| `skills/*` | Procedures loaded on demand | [Skills](/docs/reference/skills.md) |
| `mcp-connections/<name>.ts` | MCP servers for the model, server tools, and handlers | [MCP connections](/docs/reference/connections.md) |
| `host-connections/<name>.ts` | MCP servers for host code and `mcp oauth`. The model never sees them | [MCP connections](/docs/reference/connections.md) |
| `subagents/<id>/` | Child agent directory with a required `description` | [Subagents](/docs/reference/subagents.md) |
| `extensions/<ns>.ts` or `extensions/<ns>/` | Extension or Cursor plugin mount. Its contributions become `<ns>__<name>` | [Extensions](/docs/reference/extensions.md) |
| `channels/<name>.ts` | HTTP routes under `/v1/channels/<name>` | [Channels](/docs/reference/channels.md) |
| `hooks/*.ts` | Observe-only event subscribers | [Hooks](/docs/reference/hooks.md) |
| `artifacts.ts` | Artifact kinds, the `tag_artifact` opt-in, and retention | [Artifacts](/docs/reference/artifacts.md) |
| `schedules/*` | Cron-driven runs | [Schedules](/docs/reference/schedules.md) |
| `reminders/*.ts` | Named reminder handlers | [Reminders](/docs/reference/schedules.md#reminders) |
| `sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](/docs/reference/sessions.md#local-session-workspace) |
| `lib/` | Shared imports, never discovered | None |

Every eval project needs `evals/evals.config.ts`. Each
`evals/**/*.eval.ts` file is a suite whose case IDs come from its path.

A `.ts` file in a discovery folder loads as a definition, and an
unrecognized directory produces a validation warning. Agent SDK still
loads existing projects rooted at `agent/`.

## Inspect discovery

```text
agent-sdk validate --dir .    # diagnostics, non-zero exit on errors
agent-sdk info --dir .        # discovered surface
agent-sdk info --dir . --json # same shape as GET /v1/info
```

`serve` refuses to start on errors. Warnings do not block startup. When `info` omits a tool or channel, the file is in the wrong directory or has the wrong extension.
