@cursor/july 0.1.111 → 0.1.113

package/dist/docs/building-with-agents.md

@@ -1,69 +1,56 @@
-# Building agents with agents
+# Build with a coding agent
 
-Give a coding agent the goal. The built-in skills guide it through
-scaffolding, channels, verification, deployment, evals, and measured
-improvement.
+Agent SDK projects live in files and expose structured CLI commands, so
+a coding agent can create the project, exercise its tools, run a real
+turn, and inspect the result. You approve the plan and side effects
+while the coding agent owns the implementation loop.
 
-## What can a coding agent build for me?
+This page covers a coding agent working inside a checkout. To let a
+running agent propose changes to its own source, use the separate
+[self-improvement extension](/docs/guides/improve.md).
 
-A coding agent can take an Agent SDK project from an idea to a
-verified first version. It can:
+## Create an agent from a goal
 
-- Create the project and choose the smallest useful surface
-- Add tools, skills, channels, MCP connections, and approval gates
-- Run a real turn and inspect its trace
-- Add evals for the behavior you want to keep
-- Improve the agent against fixed inputs
-
-This works because the project surface lives in files. The CLI also
-returns structured JSON and records each run as an NDJSON trace. Your
-coding agent can inspect what the framework discovered, run the agent,
-and verify the result without reading terminal prose.
-
-## How do I create an agent with the built-in skill?
-
-Have the coding agent read
-[`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) and
-follow it.
-
-The skill asks about your agent's purpose, runtime, model, channels, MCP
-connections, and capabilities. It then shows you a plan, writes the
-project, and verifies the result.
-
-For example:
+Give the coding agent a purpose and the surfaces people will use. The
+`create-agent` skill asks only for missing decisions, shows a file plan,
+then scaffolds and verifies a small first version.
 
 > Use the Agent SDK create-agent skill to build a PR triage agent
 > reachable through GitHub. It should summarize failed checks, require
 > approval before posting a review, and include one smoke eval.
 
-The skill starts with a small surface: short instructions, one or two
-tools, the channels you chose, and a smoke eval. You can add more after
-the first end-to-end turn works.
+Ask it to read
+[`skills/create-agent/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md). The
+first version should stay narrow: instructions, one or two tools, the
+chosen channels or connections, and a smoke eval.
 
-## Which built-in skill should I use?
+## Add one capability
 
-The package ships task-specific guides under `skills/`:
+For an existing project, name the user-visible outcome and point the
+coding agent at the matching procedure. It should inspect the current
+agent first, make the smallest change, then exercise the new path.
 
-| What you want to do | Skill |
-| --- | --- |
-| Understand the project layout and runtimes | [`framework-map`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/framework-map/SKILL.md) |
-| Create and verify a new agent | [`create-agent`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/create-agent/SKILL.md) |
-| Write fixtures and regression checks | [`evals`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) |
-| Export OpenTelemetry traces | [`otel`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/otel/SKILL.md) |
-| Improve an agent against fixed inputs | [`hillclimb`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md) |
-| Add GitHub webhooks and replay events | [`github`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/github/SKILL.md) |
-| Connect an agent to Slack | [`setup-slack`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md) |
-| Authorize host MCP OAuth | [`mcp-auth`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md) |
-| Deploy with an attached service account | [`deploy`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/deploy/SKILL.md) |
-| Diagnose a local run | [`debug`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/debug/SKILL.md) |
+Examples:
 
-Point your coding agent at the matching `SKILL.md`. The guide contains
-the workflow, commands, and common mistakes for that task.
+> Add Slack mentions and DMs to this agent. Follow the setup-slack
+> skill, keep replies in the source thread, and verify one local mention.
 
-## How does a coding agent verify its work?
+> Connect the private inventory MCP server with host OAuth. Keep its
+> write tools behind an approved server-tool wrapper.
 
-The coding agent should discover the project, test each server tool,
-run a real turn, and finish with evals:
+> Add a GitHub ready-for-review trigger and replay PR 42 before posting
+> anything live.
+
+The companion skills live under `skills/`: [Slack](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/setup-slack/SKILL.md),
+[MCP OAuth](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md), and
+[GitHub](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/github/SKILL.md). Use the capability guide for the
+reader experience and the skill for the coding procedure.
+
+## Verify tools before tuning the prompt
+
+Start with discovery, then call deterministic server tools without a
+model turn. If a tool returns the wrong evidence, fix the tool before
+changing instructions.
 
 ```bash
 agent-sdk validate --dir .
@@ -71,50 +58,75 @@ agent-sdk info --dir . --json
 
 agent-sdk call inspect_pr --dir . \
   --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
+```
+
+`validate` confirms the discovered project shape. `info` shows what the
+serve host will mount. `call` runs the authored tool with schema
+validation and exposes its real output.
 
+## Verify one end-to-end turn
+
+Once deterministic inputs are correct, send the same request a user
+will. The coding agent should check the final answer, tool trajectory,
+and any parked approval before declaring the capability complete.
+
+```bash
 agent-sdk run --dir . \
   --message "Is https://github.com/acme/checkout/pull/42 ready to approve?"
+```
 
-agent-sdk trajectory --events <state-root>/traces/<sessionId>.ndjson
+`run` prints the saved trace path. Use that exact path instead of
+constructing one from the session ID:
 
-agent-sdk eval --dir . --list
-agent-sdk eval --dir . --json
+```bash
+agent-sdk trajectory --events <trace-path-printed-by-run>
+agent-sdk eval --dir . --tag smoke
 ```
 
-`serve` boots without an API key, which is enough to check channel
-mounts and the playground shell. Model turns need a credential. When the
-environment lacks one, finish every key-free check, then hand the `run`
-and `eval` commands to the operator.
+Finish with the project's TypeScript check. Agent SDK executes
+TypeScript through type stripping, so a successful turn does not prove
+the project type-checks.
 
-Test server tools with `call` before tuning the prompt. It runs a tool
-in-process with schema validation and no model turn. If the tool returns
-the wrong data, a prompt change won't fix it.
+## Hand off credential-dependent checks
+
+Project discovery, `info`, server-tool calls, and serve bring-up do not
+need a model credential. Model turns and evals resolve
+`CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
+`CURSOR_SERVICE_ACCOUNT_KEY`, then `agent-sdk login`.
+
+When the coding environment has none, it should complete every key-free
+check and hand you the exact remaining commands:
+
+```bash
+agent-sdk run --dir . --message "<fixture prompt>"
+agent-sdk serve --dir . --dev
+agent-sdk eval --dir . --tag smoke
+```
 
-`validate` and `run` do not type-check the project. Run the project's
-TypeScript check before shipping. Tool results
-must also be JSON-shaped. Use object literals or `type` aliases for
-`execute` return types instead of `interface` types.
+Missing access is a handoff boundary, not a reason to skip verification
+or invent a substitute result.
 
-## How do I improve the agent after its first run?
+## Improve a working agent
 
-Scaffolding proves the agent runs. It says nothing about quality. Once a
-smoke turn passes, give the hillclimb skill:
+After one smoke turn passes, give the coding agent fixed fixtures, one
+success criterion, and the behavior that must not change. The
+hillclimb skill measures the current run, changes one lever, remeasures,
+and adds an eval for every kept improvement.
 
-1. **Fixtures**: one to three fixed inputs, such as a PR URL, a
-   canonical question, or a saved webhook payload
-2. **Success criteria**: correct tool choice, fewer tool calls, lower
-   wall time, or better output
-3. **The freeze line**: the API contract, output shape, and existing
-   evals that must stay unchanged
+> Hillclimb the PR triage agent on these two saved PRs. Reduce repeated
+> reads without losing either gold finding. Keep the review JSON shape
+> and all existing evals unchanged.
 
-Have the coding agent read
-[`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md). It measures
-the current run, proposes one change, remeasures the same fixtures, and
-adds an eval for each kept improvement.
+Ask it to read
+[`skills/hillclimb/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/hillclimb/SKILL.md). Keep
+creation and improvement separate: a smoke turn proves the surface
+works; a measured climb proves it works better on fixed inputs.
 
 ## Related
 
-- [Create your first agent](/docs/quickstart.md)
-- [Evals](/docs/evals.md)
-- [Hillclimbing](/docs/hillclimbing.md)
-- [CLI reference](/docs/reference/cli.md)
+- [Quickstart](/docs/quickstart.md): build the first agent manually
+- [Evals](/docs/evals.md): protect behavior with regression cases
+- [Hillclimbing](/docs/hillclimbing.md): run one measured improvement round
+- [Self-improvement](/docs/guides/improve.md): let a running agent propose a
+  source change through a pull request
+- [CLI reference](/docs/reference/cli.md): command contracts and flags