Agent SDK0.2.29

Appearance

Build with a coding agent ​

Agent SDK projects live in files and expose structured CLI commands. 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 edit-and-test loop.

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.

Create an agent from a goal ​

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, post one review comment per pull request, and include one smoke eval.

Ask it to read 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.

Add one capability ​

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.

Examples:

Add Slack mentions and DMs to this agent. Follow the setup-slack skill, keep replies in the source thread, and verify one local mention.

Connect the private inventory MCP server with host OAuth. Keep its write tools behind a narrow server-tool wrapper.

Add a GitHub ready-for-review trigger and replay PR 42 before posting anything live.

The companion skills live under skills/: Slack, MCP OAuth, and GitHub. 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.

text
agent-sdk validate --dir .
agent-sdk info --dir . --json

agent-sdk tool 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. tool 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 and tool trajectory before declaring the capability complete.

text
agent-sdk run --dir . \
  --message "Is https://github.com/acme/checkout/pull/42 ready to approve?"

run prints the saved trace path. Use that exact path instead of constructing one from the session ID:

text
agent-sdk session get --file <trace-path-printed-by-run>
agent-sdk eval --dir . --tag smoke

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.

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:

text
agent-sdk run --dir . --message "<fixture prompt>"
agent-sdk serve --dir . --dev
agent-sdk eval --dir . --tag smoke

Missing access is a handoff boundary, not a reason to skip verification or invent a substitute result.

Improve a working agent ​

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.

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.

Ask it to read 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.