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.tsThe 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 errorsagent-sdk info --dir . # discovered surfaceagent-sdk info --dir . --json # same shape as GET /v1/infoserve 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.