Project layout

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

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

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.