Agent SDK documentation

Use the Agent SDK to define Cursor agents in TypeScript and Markdown. See Project layout for the directory structure.

Use Node 22.13 or newer. Bun isn't supported.

Create a project:

bash

npx @cursor/july init ./my-agent
cd my-agent
agent-sdk dev

If agent-sdk isn't on PATH, use npx @cursor/july <command>.

Open the docs locally:

bash

npx @cursor/july docs

Where to start

You are...	Start with
New to the Agent SDK	Quickstart (PR reviewer), then Concepts
Building a new agent with Cursor	Scaffold an agent with Cursor
Turning a Cursor Automation into a project	Convert a Cursor Automation
Learning from working agents	Example agents
Wiring an agent to Slack	Slack guide
Starting from a packaged template	Demo, Security reviewer, or Triage
Wiring an agent to GitHub webhooks	GitHub guide
Driving PRs from a cloud VM	PR autofixer template
Driving an agent from Linear (or another tracker)	Webhooks guide: Linear example
Making an existing agent measurably better	Evals, then Hillclimbing
Comparing variants on live traffic	Live A/B metrics
Deploying with Cursor or on your own infrastructure	Deployment
Debugging something that misbehaves	Fix common agent problems

Core

Quickstart: build a PR reviewer that classifies changes by complexity and handles GitHub webhook events.
Scaffold an agent with Cursor: use the bundled skill for a guided build.
Convert a Cursor Automation: export a dashboard Automation into an Agent SDK project.
Concepts: agent discovery, sessions, channels, runtimes, and observability.

Templates

Record a walkthrough from a collected PR: host collects the PR, the model records, then comments.
Security reviewer: review pull requests for exploitable bugs and post one comment.
Triage Linear or Jira issues in place: classify existing tickets and comment on them.
Fix pull requests on a Cursor cloud VM

Self-improving Agents

Building agents with agents: use a coding agent to scaffold, run, and iterate on your agent.
Evals: author defineEval cases, pick fixtures, and use evals as regression checks.
Live A/B metrics: assign sticky variants and compare cumulative metrics on live sessions.
Storage: point durable storage at a backend you own with defineStorage.
Hillclimbing: measure and improve an agent iteratively.

Guides

Webhooks and custom channels: give the agent its own HTTP surface.
GitHub: trigger the agent from pull requests, CI, and comments.
Slack: put the agent in Slack over Socket Mode.
Human-in-the-loop approvals: park a tool call until a person signs off.
Host MCP OAuth: authorize oauth: true connections, store tokens locally, and --store them on hosted deployments.
Agent-to-agent: every agent is an MCP server; agents can delegate to each other.
Cloud runtime: run turns on Cursor cloud agents instead of the local harness.
OpenTelemetry: push session, turn, and tool traces to an OTLP collector you run.

Example agents

Choose the right example: compare all twelve agents by runtime, channels, tools, state, and architecture.
Weather agent: explore tools, MCP, approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.
Slack agent: put a minimal agent in Slack through an account-linked transport.
Concierge: delegate work to a peer agent with its own context and sessions.
Playbook router: route Slack intake through inherited repository playbooks.
Alert investigator: watch a Slack alerts channel and pin a self-rechecking investigation to every alert thread.
PR evidence reviewer: review a host-prepared, diff-first pull-request evidence tree.
Approval Buddy: keep approval policy in code while subagents supply review findings.
Security Reviewer: run a staged, parallel security pipeline with live playground progress.
Remote PR coordinator: hand PR triage from local chat and webhooks to durable remote sessions.
Knowledge base: turn conversations about people, systems, decisions, and preferences into shared markdown.
Codebase wiki: ingest merged PRs into per-feature pages with a daily digest schedule.
Codeowners review: route PR reviews by ownership to per-area playbooks and aggregate verdicts.

Operating

Reference

Docs use agent-sdk <command>. If it isn't on PATH, use npx @cursor/july <command>.

From packages/agent-serve in a source checkout:

bash

alias agent-sdk="pnpm exec tsx $PWD/src/bin/agent-serve.ts"

bash

agent-sdk login
# or: export CURSOR_API_KEY=key_...
agent-sdk whoami

Confirm agent-sdk whoami shows the expected account.