@cursor/bdk 0.2.3 → 0.2.5

package/dist/docs/assets/{building-with-agents.md.-fcjCmJU.js → building-with-agents.md.BPjPFxFg.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as t,o as n,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Build with a coding agent","description":"Delegate BDK creation, capability work, verification, and measured improvement to a coding agent.","frontmatter":{"title":"Build with a coding agent","description":"Delegate BDK creation, capability work, verification, and measured improvement to a coding agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),o={name:"building-with-agents.md"};function s(r,e,l,c,d,p){return n(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="build-with-a-coding-agent" tabindex="-1">Build with a coding agent <a class="header-anchor" href="#build-with-a-coding-agent" aria-label="Permalink to &quot;Build with a coding agent&quot;">​</a></h1><p>Grok Bot Development Kit (BDK) 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.</p><p>The <code>@cursor/bdk</code> imports and <code>bdk</code> commands on this page are docs-ahead until publication; see <a href="/docs/#bdk-package-availability">BDK package availability</a>.</p><p>This page covers a coding agent working inside a checkout. To let a running agent propose changes to its own source, use the separate <a href="./guides/improve.html">self-improvement extension</a>.</p><h2 id="create-an-agent-from-a-goal" tabindex="-1">Create an agent from a goal <a class="header-anchor" href="#create-an-agent-from-a-goal" aria-label="Permalink to &quot;Create an agent from a goal&quot;">​</a></h2><p>Give the coding agent a purpose and the surfaces people will use. The <code>create-agent</code> skill asks only for missing decisions, shows a file plan, then scaffolds and verifies a small first version.</p><blockquote><p>Use the BDK 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.</p></blockquote><p>Ask it to read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a>. The first version should stay narrow: instructions, one or two tools, the chosen channels or connections, and a smoke eval.</p><h2 id="add-one-capability" tabindex="-1">Add one capability <a class="header-anchor" href="#add-one-capability" aria-label="Permalink to &quot;Add one capability&quot;">​</a></h2><p>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.</p><p>Examples:</p><blockquote><p>Add Slack mentions and DMs to this agent. Follow the setup-slack skill, keep replies in the source thread, and verify one local mention.</p></blockquote><blockquote><p>Connect the private inventory MCP server with host OAuth. Keep its write tools behind an approved server-tool wrapper.</p></blockquote><blockquote><p>Add a GitHub ready-for-review trigger and replay PR 42 before posting anything live.</p></blockquote><p>The companion skills live under <code>skills/</code>: <a href="./../skills/setup-slack/SKILL.html">Slack</a>, <a href="./../skills/mcp-auth/SKILL.html">MCP OAuth</a>, and <a href="./../skills/github/SKILL.html">GitHub</a>. Use the capability guide for the reader experience and the skill for the coding procedure.</p><h2 id="verify-tools-before-tuning-the-prompt" tabindex="-1">Verify tools before tuning the prompt <a class="header-anchor" href="#verify-tools-before-tuning-the-prompt" aria-label="Permalink to &quot;Verify tools before tuning the prompt&quot;">​</a></h2><p>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.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk validate --dir .</span></span>
+import{_ as a,c as t,o as n,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Build with a coding agent","description":"Delegate BDK creation, capability work, verification, and measured improvement to a coding agent.","frontmatter":{"title":"Build with a coding agent","description":"Delegate BDK creation, capability work, verification, and measured improvement to a coding agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),o={name:"building-with-agents.md"};function s(r,e,l,c,d,p){return n(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="build-with-a-coding-agent" tabindex="-1">Build with a coding agent <a class="header-anchor" href="#build-with-a-coding-agent" aria-label="Permalink to &quot;Build with a coding agent&quot;">​</a></h1><p>Grok Bot Development Kit (BDK) 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.</p><p>This page covers a coding agent working inside a checkout. To let a running agent propose changes to its own source, use the separate <a href="./guides/improve.html">self-improvement extension</a>.</p><h2 id="create-an-agent-from-a-goal" tabindex="-1">Create an agent from a goal <a class="header-anchor" href="#create-an-agent-from-a-goal" aria-label="Permalink to &quot;Create an agent from a goal&quot;">​</a></h2><p>Give the coding agent a purpose and the surfaces people will use. The <code>create-agent</code> skill asks only for missing decisions, shows a file plan, then scaffolds and verifies a small first version.</p><blockquote><p>Use the BDK 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.</p></blockquote><p>Ask it to read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a>. The first version should stay narrow: instructions, one or two tools, the chosen channels or connections, and a smoke eval.</p><h2 id="add-one-capability" tabindex="-1">Add one capability <a class="header-anchor" href="#add-one-capability" aria-label="Permalink to &quot;Add one capability&quot;">​</a></h2><p>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.</p><p>Examples:</p><blockquote><p>Add Slack mentions and DMs to this agent. Follow the setup-slack skill, keep replies in the source thread, and verify one local mention.</p></blockquote><blockquote><p>Connect the private inventory MCP server with host OAuth. Keep its write tools behind an approved server-tool wrapper.</p></blockquote><blockquote><p>Add a GitHub ready-for-review trigger and replay PR 42 before posting anything live.</p></blockquote><p>The companion skills live under <code>skills/</code>: <a href="./../skills/setup-slack/SKILL.html">Slack</a>, <a href="./../skills/mcp-auth/SKILL.html">MCP OAuth</a>, and <a href="./../skills/github/SKILL.html">GitHub</a>. Use the capability guide for the reader experience and the skill for the coding procedure.</p><h2 id="verify-tools-before-tuning-the-prompt" tabindex="-1">Verify tools before tuning the prompt <a class="header-anchor" href="#verify-tools-before-tuning-the-prompt" aria-label="Permalink to &quot;Verify tools before tuning the prompt&quot;">​</a></h2><p>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.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk validate --dir .</span></span>
 <span class="line"><span>bdk info --dir . --json</span></span>
 <span class="line"><span></span></span>
 <span class="line"><span>bdk call inspect_pr --dir . \\</span></span>
@@ -6,4 +6,4 @@ import{_ as a,c as t,o as n,a3 as i}from"./chunks/framework.BNw1pucY.js";const u
 <span class="line"><span>  --message &quot;Is https://github.com/acme/checkout/pull/42 ready to approve?&quot;</span></span></code></pre></div><p><code>run</code> prints the saved trace path. Use that exact path instead of constructing one from the session ID:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk trajectory --events &lt;trace-path-printed-by-run&gt;</span></span>
 <span class="line"><span>bdk eval --dir . --tag smoke</span></span></code></pre></div><p>Finish with the project&#39;s TypeScript check. BDK executes TypeScript through type stripping, so a successful turn does not prove the project type-checks.</p><h2 id="hand-off-credential-dependent-checks" tabindex="-1">Hand off credential-dependent checks <a class="header-anchor" href="#hand-off-credential-dependent-checks" aria-label="Permalink to &quot;Hand off credential-dependent checks&quot;">​</a></h2><p>Project discovery, <code>info</code>, server-tool calls, and serve bring-up do not need a model credential. Model turns and evals resolve <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then <code>bdk login</code>.</p><p>When the coding environment has none, it should complete every key-free check and hand you the exact remaining commands:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk run --dir . --message &quot;&lt;fixture prompt&gt;&quot;</span></span>
 <span class="line"><span>bdk serve --dir . --dev</span></span>
-<span class="line"><span>bdk eval --dir . --tag smoke</span></span></code></pre></div><p>Missing access is a handoff boundary, not a reason to skip verification or invent a substitute result.</p><h2 id="improve-a-working-agent" tabindex="-1">Improve a working agent <a class="header-anchor" href="#improve-a-working-agent" aria-label="Permalink to &quot;Improve a working agent&quot;">​</a></h2><p>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.</p><blockquote><p>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.</p></blockquote><p>Ask it to read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>. Keep creation and improvement separate: a smoke turn proves the surface works; a measured climb proves it works better on fixed inputs.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Quickstart</a>: build the first agent manually</li><li><a href="./evals.html">Evals</a>: protect behavior with regression cases</li><li><a href="./hillclimbing.html">Hillclimbing</a>: run one measured improvement round</li><li><a href="./guides/improve.html">Self-improvement</a>: let a running agent propose a source change through a pull request</li><li><a href="./reference/cli.html">CLI reference</a>: command contracts and flags</li></ul>`,36)])])}const g=a(o,[["render",s]]);export{u as __pageData,g as default};
+<span class="line"><span>bdk eval --dir . --tag smoke</span></span></code></pre></div><p>Missing access is a handoff boundary, not a reason to skip verification or invent a substitute result.</p><h2 id="improve-a-working-agent" tabindex="-1">Improve a working agent <a class="header-anchor" href="#improve-a-working-agent" aria-label="Permalink to &quot;Improve a working agent&quot;">​</a></h2><p>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.</p><blockquote><p>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.</p></blockquote><p>Ask it to read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>. Keep creation and improvement separate: a smoke turn proves the surface works; a measured climb proves it works better on fixed inputs.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./quickstart.html">Quickstart</a>: build the first agent manually</li><li><a href="./evals.html">Evals</a>: protect behavior with regression cases</li><li><a href="./hillclimbing.html">Hillclimbing</a>: run one measured improvement round</li><li><a href="./guides/improve.html">Self-improvement</a>: let a running agent propose a source change through a pull request</li><li><a href="./reference/cli.html">CLI reference</a>: command contracts and flags</li></ul>`,35)])])}const g=a(o,[["render",s]]);export{u as __pageData,g as default};

package/dist/docs/assets/{building-with-agents.md.-fcjCmJU.lean.js → building-with-agents.md.BPjPFxFg.lean.js}

@@ -1 +1 @@
-import{_ as a,c as t,o as n,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Build with a coding agent","description":"Delegate BDK creation, capability work, verification, and measured improvement to a coding agent.","frontmatter":{"title":"Build with a coding agent","description":"Delegate BDK creation, capability work, verification, and measured improvement to a coding agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),o={name:"building-with-agents.md"};function s(r,e,l,c,d,p){return n(),t("div",null,[...e[0]||(e[0]=[i("",36)])])}const g=a(o,[["render",s]]);export{u as __pageData,g as default};
+import{_ as a,c as t,o as n,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Build with a coding agent","description":"Delegate BDK creation, capability work, verification, and measured improvement to a coding agent.","frontmatter":{"title":"Build with a coding agent","description":"Delegate BDK creation, capability work, verification, and measured improvement to a coding agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),o={name:"building-with-agents.md"};function s(r,e,l,c,d,p){return n(),t("div",null,[...e[0]||(e[0]=[i("",35)])])}const g=a(o,[["render",s]]);export{u as __pageData,g as default};