# Project layout

An Agent SDK project keeps agent files under `bot/`, and each file's
path determines how Agent SDK loads it. [Evals](https://cursor.com/docs/agent-sdk/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](https://cursor.com/docs/agent-sdk/reference/agent-config.md)                 |
| `instructions.md`                          | Always-on system prompt, required on the root agent                       | [Instructions](https://cursor.com/docs/agent-sdk/reference/instructions.md)                 |
| `tools/<name>.ts`                          | One typed tool named after the file                                       | [Tools](https://cursor.com/docs/agent-sdk/reference/tools.md)                               |
| `skills/*`                                 | Procedures loaded on demand                                               | [Skills](https://cursor.com/docs/agent-sdk/reference/skills.md)                             |
| `mcp-connections/<name>.ts`                | MCP servers for the model, server tools, and handlers                     | [MCP connections](https://cursor.com/docs/agent-sdk/reference/connections.md)               |
| `host-connections/<name>.ts`               | MCP servers for host code and `mcp oauth`. The model never sees them      | [MCP connections](https://cursor.com/docs/agent-sdk/reference/connections.md)               |
| `subagents/<id>/`                          | Child agent directory with a required `description`                       | [Subagents](https://cursor.com/docs/agent-sdk/reference/subagents.md)                       |
| `extensions/<ns>.ts` or `extensions/<ns>/` | Extension or Cursor plugin mount. Its contributions become `<ns>__<name>` | [Extensions](https://cursor.com/docs/agent-sdk/reference/extensions.md)                     |
| `channels/<name>.ts`                       | HTTP routes under `/v1/channels/<name>`                                   | [Channels](https://cursor.com/docs/agent-sdk/reference/channels.md)                         |
| `hooks/*.ts`                               | Observe-only event subscribers                                            | [Hooks](https://cursor.com/docs/agent-sdk/reference/hooks.md)                               |
| `artifacts.ts`                             | Artifact kinds, the `tag_artifact` opt-in, and retention                  | [Artifacts](https://cursor.com/docs/agent-sdk/reference/artifacts.md)                       |
| `schedules/*`                              | Cron-driven runs                                                          | [Schedules](https://cursor.com/docs/agent-sdk/reference/schedules.md)                       |
| `reminders/*.ts`                           | Named reminder handlers                                                   | [Reminders](https://cursor.com/docs/agent-sdk/reference/schedules.md#reminders)             |
| `sandbox/workspace/**`                     | Seed files copied into each local session workspace                       | [Sessions](https://cursor.com/docs/agent-sdk/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.


---

## Sitemap

[Overview of all docs pages](/llms.txt)