@cursor/july 0.1.109 → 0.1.112

package/dist/docs/index.md

@@ -1,166 +1,99 @@
-# Agent SDK documentation
+# Agent SDK
 
-Use the Agent SDK to define Cursor agents in TypeScript and Markdown.
-See [Project layout](/docs/reference/project-layout.md) for the directory
-structure.
+The Agent SDK is how Cursor builds agents. It's the open-source version
+of the engine behind Bugbot, Security Review, and Approval Bot.
 
-Use Node 22.13 or newer. Bun isn't supported.
+Agents are folders containing markdown and typescript, Cursor provides
+abstractions to give you the building blocks you need to make your agents available where you
+work: Source Control, Slack, Issue Tracking, and the Cursor apps.
 
-Create a project:
+Use any model and make each agent unique by building custom harnessses that combine the
+flexibility of deterministic TypeScript, and the expressiveness of agents.
 
+## Why use it
+
+- **Agent live in your repo.** Instructions, tools, and evals are
+  files you review, version, and ship like the rest of your code.
+
+- **Cursor runs the agent loop.** You write the instructions and tools.
+  Your agent gets Cursor's models, tool calling, skills, MCP, and
+  subagents. Each turn runs on your host or on a Cursor cloud agent.
+
+- **Agents are available where you work.** Trigger it from Source Control events, Slack threads, or write your own Webhooks and custom schedules.
+
+- **Easily testable and extendable.** Write your evals, unit tests in normal TypeScript code.
+
+- **Easy to host.** your Agents can be hosted and eval'd on Cursor's battle tested infrastructure.
+
+## When to use the Agent SDK
+
+| | Cursor Automations | Grok Bot | Agent SDK |
+| --- | --- | --- | --- |
+| **Use for** | Repeatable jobs driven by a prompt and a trigger | Interactive agents that work with you in Cursor | Agents that need custom code, integrations, tests, or deployment choices |
+| **You define** | A prompt, model, and trigger in the dashboard | Instructions, skills, and connected tools in the app | A versioned Markdown and TypeScript project |
+| **Where it runs** | Cursor-managed | Cursor-managed | Cursor-managed hosting or your infrastructure |
+| **Choose it when** | The job fits a schedule or event trigger | You want an agent you can configure and talk to without creating a software project | You want deterministic code around model judgment and a project your team can review and test |
+
+## Architecture
+
+Agents are defined as code in your source control of choice, execution, inference and sandboxing
+runs on Cursor infrastructure or self-hosted.
+
+![Agent SDK architecture: you bring the agent as code, the platform provides triggers, runtime, integrations, and operations](/docs/architecture.svg)
+
+
+The next steps in this guide will help you build your first agent, or choose from one of the templates we offer.
+
+## Get started
+
+1. Install the Agent SDK
 ```bash
-npx @cursor/july init ./my-agent
+npx @cursor/agent-sdk init ./my-agent
 cd my-agent
 agent-sdk dev
 ```
 
-If `agent-sdk` isn't on `PATH`, use `npx @cursor/july <command>`.
+2. Open Cursor
+
+```text
+my-agent/
+├── package.json
+├── agent/
+│   ├── agent.ts               # model and runtime
+│   ├── instructions.md        # the system prompt
+│   ├── tools/
+│   │   └── approve_pr.ts      # one typed tool per file
+│   ├── skills/
+│   │   └── pr-review.md       # procedures the model loads on demand
+│   ├── mcp-connections/
+│   │   └── linear.ts          # tools from an MCP server
+│   └── channels/
+│       └── github.ts          # wake on pull requests, CI, and comments
+└── evals/
+    └── readiness.eval.ts      # regression checks
+```
 
-Open the docs locally:
+3. Describe your Agent
+Describe your Agent in the Cursor app, or edit the code yourself.
 
-```bash
-npx @cursor/july docs
-```
+## Next steps
 
-## Where to start
-
-| You are... | Start with |
-| --- | --- |
-| New to the Agent SDK | [Quickstart](/docs/quickstart.md) (PR reviewer), then [Concepts](/docs/concepts.md) |
-| Building a new agent with Cursor | [Scaffold an agent with Cursor](/docs/scaffolding-agents.md) |
-| Turning a Cursor Automation into a project | [Convert a Cursor Automation](/docs/guides/convert-automation.md) |
-| Wiring an agent to Slack | [Slack guide](/docs/guides/slack.md) |
-| Starting from a packaged template | [Demo](/docs/templates/demo.md), [Grok Bot agents](/docs/templates/grokbot-agents.md), [Code wiki](/docs/templates/code-wiki.md), [Living AGENTS.md](/docs/templates/agents-md.md), [Security reviewer](/docs/templates/security-reviewer.md), [Security help](/docs/templates/security-help.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
-| Wiring an agent to GitHub or GitHub Enterprise Server | [GitHub guide](/docs/guides/github.md) |
-| Wiring an agent to GitLab | [GitLab guide](/docs/guides/gitlab.md) |
-| Wiring an agent to Bitbucket | [Bitbucket guide](/docs/guides/bitbucket.md) |
-| Driving PRs from a cloud VM | [PR autofixer template](/docs/templates/pr-autofixer.md) |
-| Handing coding work to Cursor cloud agents | [Cursor cloud agents](/docs/guides/cloud-agents.md) |
-| Talking to your Grok Bot agents | [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md) |
-| Letting an agent change its own source | [Self-improvement](/docs/guides/improve.md) |
-| Driving an agent from Linear (or another tracker) | [Webhooks guide: Linear example](/docs/guides/webhooks.md#example-linear-as-the-control-plane) |
-| Making an existing agent measurably better | [Evals](/docs/evals.md), then [Hillclimbing](/docs/hillclimbing.md) |
-| Gating agent behavior in CI | [Run evals in CI](/docs/evals.md#run-evals-in-ci) |
-| Deploying with Cursor or on your own infrastructure | [Deployment](/docs/deployment.md) |
-| Debugging something that misbehaves | [Fix common agent problems](/docs/troubleshooting.md) |
-
-## Documentation
-
-**Core**
-
-- [Quickstart](/docs/quickstart.md): build a PR reviewer that classifies
-  changes by complexity and handles GitHub webhook events.
-- [Scaffold an agent with Cursor](/docs/scaffolding-agents.md): use the
-  bundled skill for a guided build.
-- [Convert a Cursor Automation](/docs/guides/convert-automation.md): export
-  a dashboard Automation into an Agent SDK project.
-- [Concepts](/docs/concepts.md): agent discovery, sessions, channels,
-  runtimes, and observability.
-
-**Templates**
-
-- [Record a walkthrough from a collected PR](/docs/templates/demo.md): host
-  collects the PR, the model records, then comments.
-- [Talk to your Grok Bot agents](/docs/templates/grokbot-agents.md): name
-  the bots, then consult them from this agent's own conversation.
-- [Keep a code wiki current after merge](/docs/templates/code-wiki.md):
-  update in-repo `wiki/` pages when a pull request merges.
-- [Keep AGENTS.md current from last week's work](/docs/templates/agents-md.md):
-  pull rules out of merged PRs and Slack, then open a follow-up PR.
-- [Security reviewer](/docs/templates/security-reviewer.md): review pull
-  requests for exploitable bugs and post one comment.
-- [Answer security questions in Slack](/docs/templates/security-help.md):
-  answer from your skills, or take a first look at a pasted PR.
-- [Triage Linear or Jira issues in place](/docs/templates/triage.md): classify
-  existing tickets and comment on them.
-- [Review pull requests with owners policies](/docs/templates/agentic-owners.md):
-  request owners and approve changes allowed by repository policy.
-- [Fix pull requests on a Cursor cloud VM](/docs/templates/pr-autofixer.md)
-
-**Self-improving Agents**
-
-- [Building agents with agents](/docs/building-with-agents.md): use a coding
-  agent to scaffold, run, and iterate on your agent.
-- [Evals](/docs/evals.md): author `defineEval` cases, assert over the
-  trajectory, and run them locally and in CI.
-- [Storage](/docs/storage.md): point durable storage at a backend you own
-  with `defineStorage`.
-- [Hillclimbing](/docs/hillclimbing.md): measure and improve an agent
-  iteratively.
-
-**Guides**
-
-- [Webhooks and custom channels](/docs/guides/webhooks.md): give the agent
-  its own HTTP surface.
-- [GitHub](/docs/guides/github.md): trigger the agent from pull requests,
-  CI, and comments.
-- [GitLab](/docs/guides/gitlab.md): trigger the agent from merge requests,
-  notes, pipelines, and pushes.
-- [Bitbucket](/docs/guides/bitbucket.md): trigger the agent from pull requests,
-  comments, and pushes.
-- [Slack](/docs/guides/slack.md): put the agent in Slack over Socket Mode.
-- [Human-in-the-loop approvals](/docs/guides/human-in-the-loop.md): park a
-  tool call until a person signs off.
-- [Host MCP OAuth](/docs/guides/mcp-oauth.md): authorize
-  `oauth: true` connections, store tokens locally, and persist them
-  on hosted deployments (`--store`).
-- [Agent-to-agent](/docs/guides/agent-to-agent.md): every agent is an MCP
-  server; agents can delegate to each other.
-- [Cursor cloud agents](/docs/guides/cloud-agents.md): let the agent launch
-  and steer cloud agents through the `cursor-cloud-agents` extension.
-- [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): let the agent
-  talk to Grok Bot agents through the `cursor-grokbot-agents` extension.
-- [Self-improvement](/docs/guides/improve.md): let the agent change its own
-  source through a one-off cloud agent and a pull request with the
-  `improve` extension.
-- [OpenTelemetry](/docs/guides/opentelemetry.md): push session, turn, and
-  tool traces to an OTLP collector you run.
-
-**Operating**
-
-- [Deployment](/docs/deployment.md): Cursor-managed hosting, self-hosting,
-  auth, state, and operations.
-- [Fix common agent problems](/docs/troubleshooting.md): diagnose common
-  failures by symptom.
-
-**Reference**
-
-- [Project layout](/docs/reference/project-layout.md): the full folder structure.
-- [Agent config](/docs/reference/agent-config.md) ·
-  [Instructions](/docs/reference/instructions.md) ·
-  [Tools](/docs/reference/tools.md) ·
-  [`prompt`](/docs/reference/prompt.md) ·
-  [Skills](/docs/reference/skills.md) ·
-  [MCP connections](/docs/reference/connections.md) ·
-  [Subagents](/docs/reference/subagents.md) ·
-  [Extensions](/docs/reference/extensions.md)
-- [Channels](/docs/reference/channels.md) ·
-  [Schedules and reminders](/docs/reference/schedules.md) ·
-  [Hooks](/docs/reference/hooks.md) ·
-  [Artifacts](/docs/reference/artifacts.md) ·
-  [Turn result](/docs/reference/result.md) ·
-  [Sessions and streaming](/docs/reference/sessions.md) ·
-  [Playground](/docs/reference/playground.md)
-- [CLI](/docs/reference/cli.md) · [HTTP API](/docs/reference/http-api.md)
-
-## Run the CLI
-
-Docs use `agent-sdk <command>`. If it isn't on `PATH`, use
-`npx @cursor/july <command>`.
-
-## Credentials
-
-Sign in to Cursor or set `CURSOR_API_KEY`:
+- [Build your first PR reviewer](/docs/quickstart.md): a working GitHub
+  reviewer, one step at a time.
 
-```bash
-agent-sdk login
-# or: export CURSOR_API_KEY=key_...
-agent-sdk whoami
-```
+- Start from a template with `init --template`:
+  [security reviewer](/docs/templates/security-reviewer.md),
+  [thermo reviewer](/docs/templates/thermo-review.md),
+  [thermo quality reviewer](/docs/templates/thermo-quality-review.md),
+  [owners-policy approver](/docs/templates/agentic-owners.md),
+  [PR autofixer](/docs/templates/pr-autofixer.md), or
+  [issue triager](/docs/templates/triage.md).
 
-Confirm `agent-sdk whoami` shows the expected account.
+- [Convert a Cursor Automation](/docs/guides/convert-automation.md): export
+  an Automation from the dashboard into a project you own.
 
-## Related documentation
+- [Build agents with agents](/docs/building-with-agents.md): hand the build
+  to a coding agent with the package's bundled skills.
 
-- Package reference: [`README.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/README.md)
-- Coding-agent workflows: [`skills/`](/docs/skills/index.md)
+- [Project layout](/docs/reference/project-layout.md) and
+  [CLI](/docs/reference/cli.md): every folder and every command.