@cursor/july 0.1.90 → 0.1.92

package/dist/docs/ab.md

@@ -0,0 +1,338 @@
+# Live A/B metrics
+
+Use `defineAB` to compare variants on live agent sessions. New sessions
+receive a sticky assignment in each enrolled experiment. The Agent SDK folds
+their durable event streams into tool, token, failure, and wall-time
+metrics. You can send cumulative samples to your metrics backend and
+inspect aggregates in the playground.
+
+`defineAB` compares live variants through sticky assignment,
+instruction overlays, optional tool branches, and cumulative metrics.
+Metric callbacks observe the result without approving, rejecting, or
+failing a turn. Use [evals](/docs/evals.md) for pass/fail regression checks
+on fixed inputs.
+
+> [!NOTE]
+> Import paths here use `@cursor/july/ab`. On projects still
+> using `@anysphere/agent-serve`, swap the import. See
+> [Run the CLI](/docs/index.md#run-the-cli) for the full rename table.
+
+## Choose live A/B metrics or evals
+
+Both features read the session event stream, but they answer different
+questions.
+
+| | Live A/B metrics | Evals |
+| --- | --- | --- |
+| Question | How do variants compare on live sessions? | Does the agent still meet a fixed contract? |
+| Location | `agent/ab.ts` or `agent/ab/<name>.ts` | `evals/**/*.eval.ts` |
+| Input | Dev or production traffic | Frozen prompts and fixtures |
+| Output | Cumulative metrics by session and arm | Pass/fail assertions |
+| How it runs | Automatically on new live sessions | `agent-sdk eval` |
+
+There is no `agent-sdk ab` command or assertion API.
+
+## Define an experiment
+
+Author one experiment in `agent/ab.ts`, add more under
+`agent/ab/<name>.ts`, or use both forms. Each file defines one
+experiment. The experiment name comes from `name` when set. Otherwise,
+The Agent SDK uses `ab` for `agent/ab.ts` and the file stem for files under
+`agent/ab/`.
+
+```ts
+// agent/ab/concise-weather.ts
+import {
+  defineAB,
+  splitBySessionHash,
+} from "@cursor/july/ab";
+
+export default defineAB({
+  name: "concise-weather",
+  variants: {
+    control: {
+      label: "Baseline",
+    },
+    treatment: {
+      label: "Short replies",
+      description: "Adds a one-paragraph response limit.",
+      instructions: "Keep weather replies to one short paragraph.",
+    },
+  },
+  split: splitBySessionHash({
+    weights: { control: 1, treatment: 1 },
+    holdout: 0.1,
+  }),
+  derive: {
+    weatherCalls: (event) =>
+      event.type === "action.result" &&
+      event.data.toolName === "get_weather"
+        ? 1
+        : null,
+  },
+  onSample(sample) {
+    console.log(
+      sample.experiment,
+      sample.variant,
+      sample.metrics.toolCalls,
+      sample.metrics.wallTimeMs
+    );
+  },
+});
+```
+
+Every definition needs:
+
+- At least two variants. Variant keys cannot be empty or contain `/` or
+  `\`.
+- A `split` function that returns a variant key or `null`.
+- An `onSample` callback for completed or failed turns.
+
+`label` and `description` appear with the arm in result surfaces.
+`instructions` changes the prompt for sessions in that arm. `derive`
+adds custom counters.
+
+Duplicate experiment names are validation errors. Check discovery
+before you serve:
+
+```bash
+agent-sdk validate --dir .
+agent-sdk info --dir . --json
+```
+
+The `abs` field in `info` lists the discovered experiment names.
+
+## Assign sticky variants
+
+Enrollment happens once, when a live session is created and before its
+first turn:
+
+1. The Agent SDK records `session.started`.
+2. Each experiment runs its `split` function.
+3. The Agent SDK records one durable `ab.assigned` event per experiment.
+4. The selected arms become available on `session.abs`.
+5. Variant instruction overlays reach the first model turn.
+
+A split can return a variant key or `null`. A null assignment is a
+sticky skip for that experiment. It increments the experiment's
+`skipped` total, still appears in the snapshot's `sessions` list with
+`variant: null`, and does not collect arm metrics or call `onSample`.
+
+Use the split helper that matches your rollout:
+
+| Helper | Behavior |
+| --- | --- |
+| `splitBySessionHash({ weights?, holdout?, salt? })` | Hashes the session id into a reproducible arm; the recommended default |
+| `splitByRandom({ weights?, holdout? })` | Draws once when the session starts, then persists the result |
+| `splitAlways("control")` | Pins every new session to one arm |
+| `splitNone()` | Skips every new session without deleting the experiment |
+| `splitIf(predicate, inner)` | Runs `inner` only when the predicate passes |
+| Custom `split(ctx)` | Returns a declared variant key or `null` |
+
+The split context includes the agent name, channel id, session info,
+experiment name, and declared variant keys. For example, enroll only
+Slack sessions:
+
+```ts
+split: splitIf(
+  (ctx) => ctx.channel.id === "slack",
+  splitBySessionHash()
+),
+```
+
+Weights default to equal. Non-positive weights leave an arm out of the
+draw, and at least one arm must have a positive weight. `holdout` is the
+fraction of sessions assigned `null`, from `0` through `1`. Change
+`salt` to reshuffle future hash assignments without renaming the
+experiment.
+
+If a custom split throws or returns an unknown variant, the Agent SDK logs
+the error and records `variant: null`. The failed decision becomes a
+sticky skip instead of breaking the session.
+
+Enrollment only applies to new sessions. Adding an experiment does not
+assign existing conversations. Follow-ups keep the session's original
+arms. Keep experiment names and variant keys stable while you collect
+and compare results.
+
+## Change behavior by variant
+
+Variant instructions are appended to the agent's base instructions.
+Local sessions receive the merged instructions in `AGENTS.md` before
+every turn. Cloud sessions receive them in the first-turn preamble
+only. For cloud follow-ups, branch through `session.abs` when the arm
+must remain visible to deterministic behavior.
+
+Tools can branch on the assignment through `ctx.session.abs`. Hooks can
+read the same field for logging or export:
+
+```ts
+const treatment =
+  ctx.session.abs?.["concise-weather"] === "treatment";
+
+if (treatment) {
+  return conciseWeatherResult;
+}
+
+return baselineWeatherResult;
+```
+
+This makes the assignment available to deterministic code as well as
+the model prompt. Use both patterns together when one experiment must
+steer the prompt and host code at once.
+
+`defineAB` does not select a different model or runtime for each arm.
+Keep those settings in `agent/agent.ts`, or write explicit host logic
+when your experiment needs another behavior lever.
+
+The split and selected arm can affect agent behavior. `derive` and
+`onSample` only observe the resulting event stream. Errors in either
+callback are logged and never fail the turn.
+
+## Collect built-in and custom metrics
+
+Metrics accumulate for each session and experiment. When one session
+joins several experiments, every enrolled experiment folds the same
+turn and tool events into its own counters.
+
+| Metric | How the Agent SDK calculates it |
+| --- | --- |
+| `turns` | Adds one on `turn.completed` or `turn.failed` |
+| `turnFailures` | Adds one on `turn.failed` |
+| `toolCalls` | Adds one for each `action.result` |
+| `toolErrors` | Adds one when `action.result.data.isError` is true |
+| `inputTokens`, `outputTokens` | Adds usage from completed turns |
+| `cacheReadTokens`, `cacheWriteTokens` | Adds cache usage from completed turns |
+| `costUsd` | Sums the estimated turn cost recorded on `turn.completed` (turns whose model has no known rates contribute 0) |
+| `wallTimeMs` | Sums the time from `turn.started` to its completed or failed event |
+| `custom` | Sums finite numeric deltas returned by `derive` |
+
+`onSample` fires after every `turn.completed` and `turn.failed` event
+for an enrolled arm. The sample contains:
+
+| Field | Value |
+| --- | --- |
+| `experiment` | Experiment name |
+| `variant`, `variantLabel?` | Sticky arm and optional display label |
+| `sessionId`, `channelId` | Source session |
+| `metrics` | Cumulative metrics through this turn |
+| `reason` | `turn.completed` or `turn.failed` |
+| `at` | Terminal event timestamp |
+
+The metrics are cumulative, not per-turn deltas. A second sample from
+the same session includes the first turn's counts.
+
+Each `derive` extractor runs on every session event for its enrolled
+experiment, including streamed `message.appended` events. Keep it
+synchronous and cheap. Return a finite number to add a delta, or
+`null` to skip the event. Send samples to your metrics service from
+`onSample`; do not perform network or disk work in `derive`.
+
+Skipped sessions never call `onSample`. Errors from `derive` or
+`onSample` are logged, then metric collection continues.
+
+## Inspect assignments and results
+
+Open the playground's **A/Bs** tab to see aggregate arm totals and
+per-session assignments. The tab reads `GET /v1/abs`.
+
+The response has two views of the same durable data:
+
+| Field | Contents |
+| --- | --- |
+| `experiments` | Declared variants, skipped-session count, arm session counts, and aggregate metrics |
+| `sessions` | Visible sessions with their assignments and cumulative metrics |
+
+`GET /v1/abs` returns sessions visible to the current principal by
+default. In `--dev`, loopback requests include every session. Add
+`--allow-anonymous` to include every session from non-loopback callers
+too. This include-all behavior can still apply to `GET /v1/abs` in dev
+when bearer or custom auth keeps `GET /v1/sessions` owner-scoped.
+
+Session `events.ndjson` is the source of truth for assignment + fold.
+`GET /v1/abs` recomputes aggregates from those logs. Any
+`agent/storage.ts` exports samples and snapshots durably: an authored
+`abs` table when the backend has a native shape for it, or the table
+derived over the KV core otherwise. See
+[Storage](/docs/storage.md#eval-and-a-b-tables).
+
+## Configure the playground fold window
+
+Assignments and foldable metrics already persist in each session's
+`events.ndjson` under `--state-root`. The optional `agent/ab.config.ts`
+only caps how many sessions the playground and `GET /v1/abs` fold:
+
+```ts
+import { defineABConfig } from "@cursor/july/ab";
+
+export default defineABConfig({
+  // Optional — defaults to 200. Only affects GET /v1/abs / A/Bs tab.
+  maxPlaygroundSessions: 500,
+});
+```
+
+`maxPlaygroundSessions` keeps the newest sessions in the fold. It does
+not prune session logs or change assignment. For export to S3, a DB, or
+your metrics vendor, send samples from `onSample` or declare a storage
+`abs` table.
+
+## Keep assignments durable
+
+The append-only `events.ndjson` stream is the source of truth. Each
+`ab.assigned` event persists a variant key or null skip. Built-in
+metrics come from the turn and tool events that follow it.
+
+After a server restart or a parked session resumes, the live collector
+replays the stream to rebuild cumulative counters. Replay does not call
+`onSample` (or write to the storage `abs` table) for historical turns.
+Only a new completed or failed turn emits another sample.
+
+The snapshot API also replays `derive` across the full stream, so
+custom totals match the current extractor. Changing a derive function
+can change historical snapshot totals. Treat metric definitions as
+versioned experiment code.
+
+## Keep eval traffic separate
+
+Sessions created by `agent-sdk eval` and the playground Evals runner use
+`purpose: "eval"`. They skip A/B enrollment entirely:
+
+- No split function runs.
+- No `ab.assigned` event is recorded.
+- No `onSample` callback fires.
+- The session is omitted from `GET /v1/abs`.
+
+Ordinary chat, `agent-sdk run`, Slack, GitHub, and other channel sessions
+use the live purpose. You do not need `splitIf` to exclude eval traffic.
+
+## Know the boundaries
+
+`defineAB` provides sticky assignment, variant instructions,
+`session.abs` for tools, cumulative metrics, and local inspection. It
+does not provide:
+
+- A test command, assertion API, or pass/fail result
+- Statistical significance calculations
+- An experiment rollout or lifecycle service
+- Per-variant model or runtime configuration
+- A built-in analytics warehouse (bring your own via `onSample` or the
+  storage `abs` table)
+
+Use [evals](/docs/evals.md) to protect known behavior. Use `onSample` or a
+storage `abs` table when you need sample/snapshot exports beyond the
+session event log.
+
+## What's next
+
+Continue with these pages:
+
+- [Evals](/docs/evals.md): pass/fail regression checks on fixed inputs
+- [Hillclimbing](/docs/hillclimbing.md): improve an agent against fixed
+  fixtures
+- [Hooks](/docs/reference/hooks.md): other event-stream consumers
+- [Sessions and streaming](/docs/reference/sessions.md): the
+  `ab.assigned` event and durable log
+- [Playground](/docs/reference/playground.md): the A/Bs tab
+- [HTTP API](/docs/reference/http-api.md): `GET /v1/abs`
+- [Live A/B metrics skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/ab/SKILL.md): have a coding agent
+  wire an experiment

package/dist/docs/assets/{ab.md.DYjwREAP.js → ab.md.CVzWxLoB.js}

@@ -1,4 +1,4 @@
-import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Live A/B metrics","description":"Assign sticky variants with defineAB, collect live performance metrics, and inspect per-arm results.","frontmatter":{"title":"Live A/B metrics","description":"Assign sticky variants with defineAB, collect live performance metrics, and inspect per-arm results."},"headers":[],"relativePath":"ab.md","filePath":"ab.md"}'),n={name:"ab.md"};function o(l,e,r,d,h,p){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="live-a-b-metrics" tabindex="-1">Live A/B metrics <a class="header-anchor" href="#live-a-b-metrics" aria-label="Permalink to &quot;Live A/B metrics&quot;">​</a></h1><p>Use <code>defineAB</code> to compare variants on live agent sessions. New sessions receive a sticky assignment in each enrolled experiment. The Agent SDK folds their durable event streams into tool, token, failure, and wall-time metrics. You can send cumulative samples to your metrics backend and inspect aggregates in the playground.</p><p><code>defineAB</code> compares live variants through sticky assignment, instruction overlays, optional tool branches, and cumulative metrics. Metric callbacks observe the result without approving, rejecting, or failing a turn. Use <a href="./evals.html">evals</a> for pass/fail regression checks on fixed inputs.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>Import paths here use <code>@cursor/july/ab</code>. On projects still using <code>@anysphere/agent-serve</code>, swap the import. See <a href="/docs/#run-the-cli">Run the CLI</a> for the full rename table.</p></div><h2 id="choose-live-a-b-metrics-or-evals" tabindex="-1">Choose live A/B metrics or evals <a class="header-anchor" href="#choose-live-a-b-metrics-or-evals" aria-label="Permalink to &quot;Choose live A/B metrics or evals&quot;">​</a></h2><p>Both features read the session event stream, but they answer different questions.</p><table tabindex="0"><thead><tr><th></th><th>Live A/B metrics</th><th>Evals</th></tr></thead><tbody><tr><td>Question</td><td>How do variants compare on live sessions?</td><td>Does the agent still meet a fixed contract?</td></tr><tr><td>Location</td><td><code>agent/ab.ts</code> or <code>agent/ab/&lt;name&gt;.ts</code></td><td><code>evals/**/*.eval.ts</code></td></tr><tr><td>Input</td><td>Dev or production traffic</td><td>Frozen prompts and fixtures</td></tr><tr><td>Output</td><td>Cumulative metrics by session and arm</td><td>Pass/fail assertions</td></tr><tr><td>How it runs</td><td>Automatically on new live sessions</td><td><code>agent-sdk eval</code></td></tr></tbody></table><p>There is no <code>agent-sdk ab</code> command or assertion API.</p><h2 id="define-an-experiment" tabindex="-1">Define an experiment <a class="header-anchor" href="#define-an-experiment" aria-label="Permalink to &quot;Define an experiment&quot;">​</a></h2><p>Author one experiment in <code>agent/ab.ts</code>, add more under <code>agent/ab/&lt;name&gt;.ts</code>, or use both forms. Each file defines one experiment. The experiment name comes from <code>name</code> when set. Otherwise, The Agent SDK uses <code>ab</code> for <code>agent/ab.ts</code> and the file stem for files under <code>agent/ab/</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/ab/concise-weather.ts</span></span>
+import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Live A/B metrics","description":"Assign sticky variants with defineAB, collect live performance metrics, and inspect per-arm results.","frontmatter":{"title":"Live A/B metrics","description":"Assign sticky variants with defineAB, collect live performance metrics, and inspect per-arm results."},"headers":[],"relativePath":"ab.md","filePath":"ab.md"}'),n={name:"ab.md"};function o(l,e,r,d,h,p){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="live-a-b-metrics" tabindex="-1">Live A/B metrics <a class="header-anchor" href="#live-a-b-metrics" aria-label="Permalink to &quot;Live A/B metrics&quot;">​</a></h1><p>Use <code>defineAB</code> to compare variants on live agent sessions. New sessions receive a sticky assignment in each enrolled experiment. The Agent SDK folds their durable event streams into tool, token, failure, and wall-time metrics. You can send cumulative samples to your metrics backend and inspect aggregates in the playground.</p><p><code>defineAB</code> compares live variants through sticky assignment, instruction overlays, optional tool branches, and cumulative metrics. Metric callbacks observe the result without approving, rejecting, or failing a turn. Use <a href="./evals.html">evals</a> for pass/fail regression checks on fixed inputs.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>Import paths here use <code>@cursor/july/ab</code>. On projects still using <code>@anysphere/agent-serve</code>, swap the import. See <a href="/docs/#run-the-cli">Run the CLI</a> for the full rename table.</p></div><h2 id="choose-live-a-b-metrics-or-evals" tabindex="-1">Choose live A/B metrics or evals <a class="header-anchor" href="#choose-live-a-b-metrics-or-evals" aria-label="Permalink to &quot;Choose live A/B metrics or evals&quot;">​</a></h2><p>Both features read the session event stream, but they answer different questions.</p><table tabindex="0"><thead><tr><th></th><th>Live A/B metrics</th><th>Evals</th></tr></thead><tbody><tr><td>Question</td><td>How do variants compare on live sessions?</td><td>Does the agent still meet a fixed contract?</td></tr><tr><td>Location</td><td><code>agent/ab.ts</code> or <code>agent/ab/&lt;name&gt;.ts</code></td><td><code>evals/**/*.eval.ts</code></td></tr><tr><td>Input</td><td>Dev or production traffic</td><td>Frozen prompts and fixtures</td></tr><tr><td>Output</td><td>Cumulative metrics by session and arm</td><td>Pass/fail assertions</td></tr><tr><td>How it runs</td><td>Automatically on new live sessions</td><td><code>agent-sdk eval</code></td></tr></tbody></table><p>There is no <code>agent-sdk ab</code> command or assertion API.</p><h2 id="define-an-experiment" tabindex="-1">Define an experiment <a class="header-anchor" href="#define-an-experiment" aria-label="Permalink to &quot;Define an experiment&quot;">​</a></h2><p>Author one experiment in <code>agent/ab.ts</code>, add more under <code>agent/ab/&lt;name&gt;.ts</code>, or use both forms. Each file defines one experiment. The experiment name comes from <code>name</code> when set. Otherwise, The Agent SDK uses <code>ab</code> for <code>agent/ab.ts</code> and the file stem for files under <code>agent/ab/</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// agent/ab/concise-weather.ts</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  defineAB,</span></span>
 <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  splitBySessionHash,</span></span>

package/dist/docs/assets/{ab.md.DYjwREAP.lean.js → ab.md.CVzWxLoB.lean.js}

@@ -1 +1 @@
-import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Live A/B metrics","description":"Assign sticky variants with defineAB, collect live performance metrics, and inspect per-arm results.","frontmatter":{"title":"Live A/B metrics","description":"Assign sticky variants with defineAB, collect live performance metrics, and inspect per-arm results."},"headers":[],"relativePath":"ab.md","filePath":"ab.md"}'),n={name:"ab.md"};function o(l,e,r,d,h,p){return a(),t("div",null,[...e[0]||(e[0]=[i("",68)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};
+import{_ as s,c as t,o as a,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Live A/B metrics","description":"Assign sticky variants with defineAB, collect live performance metrics, and inspect per-arm results.","frontmatter":{"title":"Live A/B metrics","description":"Assign sticky variants with defineAB, collect live performance metrics, and inspect per-arm results."},"headers":[],"relativePath":"ab.md","filePath":"ab.md"}'),n={name:"ab.md"};function o(l,e,r,d,h,p){return a(),t("div",null,[...e[0]||(e[0]=[i("",68)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/{app.wiNkt6G7.js → app.Bci6CM9E.js}

@@ -1 +1 @@
-import{t as p}from"./chunks/theme.Dx7j_-0n.js";import{R as s,a2 as i,a3 as u,a4 as c,a5 as l,a6 as f,a7 as d,a8 as m,a9 as h,aa as g,ab as A,d as v,u as y,v as C,s as P,ac as b,ad as w,ae as R,af as E}from"./chunks/framework.CAZyNGu9.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=y();return C(()=>{P(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&b(),w(),R(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=_(),a=D();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function D(){return A(S)}function _(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};
+import{R as p}from"./chunks/theme.BEA8BF3c.js";import{R as s,a3 as i,a4 as u,a5 as c,a6 as l,a7 as f,a8 as d,a9 as m,aa as h,ab as g,ac as A,d as v,u as R,v as w,s as y,ad as C,ae as P,af as b,a2 as E}from"./chunks/framework.BCISBCiQ.js";function r(e){if(e.extends){const a=r(e.extends);return{...a,...e,async enhanceApp(t){a.enhanceApp&&await a.enhanceApp(t),e.enhanceApp&&await e.enhanceApp(t)}}}return e}const n=r(p),S=v({name:"VitePressApp",setup(){const{site:e,lang:a,dir:t}=R();return w(()=>{y(()=>{document.documentElement.lang=a.value,document.documentElement.dir=t.value})}),e.value.router.prefetchLinks&&C(),P(),b(),n.setup&&n.setup(),()=>E(n.Layout)}});async function T(){globalThis.__VITEPRESS__=!0;const e=_(),a=D();a.provide(u,e);const t=c(e.route);return a.provide(l,t),a.component("Content",f),a.component("ClientOnly",d),Object.defineProperties(a.config.globalProperties,{$frontmatter:{get(){return t.frontmatter.value}},$params:{get(){return t.page.value.params}}}),n.enhanceApp&&await n.enhanceApp({app:a,router:e,siteData:m}),{app:a,router:e,data:t}}function D(){return A(S)}function _(){let e=s;return h(a=>{let t=g(a),o=null;return t&&(e&&(t=t.replace(/\.js$/,".lean.js")),o=import(t)),s&&(e=!1),o},n.NotFound)}s&&T().then(({app:e,router:a,data:t})=>{a.go().then(()=>{i(a.route,t.site),e.mount("#app")})});export{T as createApp};

package/dist/docs/assets/{building-with-agents.md.PeZaZA1P.js → building-with-agents.md.DH8A_cHA.js}

@@ -1,4 +1,4 @@
-import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent.","frontmatter":{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),n={name:"building-with-agents.md"};function l(h,e,r,o,d,c){return s(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="building-agents-with-agents" tabindex="-1">Building agents with agents <a class="header-anchor" href="#building-agents-with-agents" aria-label="Permalink to &quot;Building agents with agents&quot;">​</a></h1><p>Give a coding agent the goal. The built-in skills guide it through scaffolding, channels, verification, evals, and measured improvement.</p><h2 id="what-can-a-coding-agent-build-for-me" tabindex="-1">What can a coding agent build for me? <a class="header-anchor" href="#what-can-a-coding-agent-build-for-me" aria-label="Permalink to &quot;What can a coding agent build for me?&quot;">​</a></h2><p>A coding agent can take an Agent SDK project from an idea to a verified first version. It can:</p><ul><li>Create the project and choose the smallest useful surface</li><li>Add tools, skills, channels, MCP connections, and approval gates</li><li>Run a real turn and inspect its trace</li><li>Add evals for the behavior you want to keep</li><li>Improve the agent against fixed inputs</li></ul><p>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.</p><h2 id="how-do-i-create-an-agent-with-the-built-in-skill" tabindex="-1">How do I create an agent with the built-in skill? <a class="header-anchor" href="#how-do-i-create-an-agent-with-the-built-in-skill" aria-label="Permalink to &quot;How do I create an agent with the built-in skill?&quot;">​</a></h2><p>Have the coding agent read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a> (in the monorepo: <code>packages/agent-serve/skills/create-agent/SKILL.md</code>) and follow it.</p><p>The skill asks about your agent&#39;s purpose, runtime, model, channels, MCP connections, and capabilities. It then shows you a plan, writes the project, and verifies the result.</p><p>For example:</p><blockquote><p>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.</p></blockquote><p>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.</p><h2 id="which-built-in-skill-should-i-use" tabindex="-1">Which built-in skill should I use? <a class="header-anchor" href="#which-built-in-skill-should-i-use" aria-label="Permalink to &quot;Which built-in skill should I use?&quot;">​</a></h2><p>The package ships task-specific guides under <a href="./../skills/"><code>skills/</code></a>:</p><table tabindex="0"><thead><tr><th>What you want to do</th><th>Skill</th></tr></thead><tbody><tr><td>Understand the project layout and runtimes</td><td><a href="./../skills/framework-map/SKILL.html"><code>framework-map</code></a></td></tr><tr><td>Create and verify a new agent</td><td><a href="./../skills/create-agent/SKILL.html"><code>create-agent</code></a></td></tr><tr><td>Write fixtures and regression checks</td><td><a href="./../skills/evals/SKILL.html"><code>evals</code></a></td></tr><tr><td>Live A/B metrics on traffic (<code>defineAB</code>)</td><td><a href="./../skills/ab/SKILL.html"><code>ab</code></a></td></tr><tr><td>Improve an agent against fixed inputs</td><td><a href="./../skills/hillclimb/SKILL.html"><code>hillclimb</code></a></td></tr><tr><td>Add GitHub webhooks and replay events</td><td><a href="./../skills/github/SKILL.html"><code>github</code></a></td></tr><tr><td>Connect an agent to Slack</td><td><a href="./../skills/setup-slack/SKILL.html"><code>setup-slack</code></a></td></tr><tr><td>Diagnose a local run</td><td><a href="./../skills/debug/SKILL.html"><code>debug</code></a></td></tr></tbody></table><p>Point your coding agent at the matching <code>SKILL.md</code>. The guide contains the workflow, commands, and common mistakes for that task.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>The skill bodies use the current <code>agent-serve</code> CLI names. This guide uses the upcoming <code>agent-sdk</code> names. See <a href="/docs/#run-the-cli">Run the CLI</a> for the full rename table.</p></div><h2 id="how-does-a-coding-agent-verify-its-work" tabindex="-1">How does a coding agent verify its work? <a class="header-anchor" href="#how-does-a-coding-agent-verify-its-work" aria-label="Permalink to &quot;How does a coding agent verify its work?&quot;">​</a></h2><p>The coding agent should discover the project, test each server tool, run a real turn, and finish with evals:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
+import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent.","frontmatter":{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),n={name:"building-with-agents.md"};function l(h,e,r,o,d,c){return s(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="building-agents-with-agents" tabindex="-1">Building agents with agents <a class="header-anchor" href="#building-agents-with-agents" aria-label="Permalink to &quot;Building agents with agents&quot;">​</a></h1><p>Give a coding agent the goal. The built-in skills guide it through scaffolding, channels, verification, evals, and measured improvement.</p><h2 id="what-can-a-coding-agent-build-for-me" tabindex="-1">What can a coding agent build for me? <a class="header-anchor" href="#what-can-a-coding-agent-build-for-me" aria-label="Permalink to &quot;What can a coding agent build for me?&quot;">​</a></h2><p>A coding agent can take an Agent SDK project from an idea to a verified first version. It can:</p><ul><li>Create the project and choose the smallest useful surface</li><li>Add tools, skills, channels, MCP connections, and approval gates</li><li>Run a real turn and inspect its trace</li><li>Add evals for the behavior you want to keep</li><li>Improve the agent against fixed inputs</li></ul><p>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.</p><h2 id="how-do-i-create-an-agent-with-the-built-in-skill" tabindex="-1">How do I create an agent with the built-in skill? <a class="header-anchor" href="#how-do-i-create-an-agent-with-the-built-in-skill" aria-label="Permalink to &quot;How do I create an agent with the built-in skill?&quot;">​</a></h2><p>Have the coding agent read <a href="./../skills/create-agent/SKILL.html"><code>skills/create-agent/SKILL.md</code></a> (in the monorepo: <code>packages/agent-serve/skills/create-agent/SKILL.md</code>) and follow it.</p><p>The skill asks about your agent&#39;s purpose, runtime, model, channels, MCP connections, and capabilities. It then shows you a plan, writes the project, and verifies the result.</p><p>For example:</p><blockquote><p>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.</p></blockquote><p>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.</p><h2 id="which-built-in-skill-should-i-use" tabindex="-1">Which built-in skill should I use? <a class="header-anchor" href="#which-built-in-skill-should-i-use" aria-label="Permalink to &quot;Which built-in skill should I use?&quot;">​</a></h2><p>The package ships task-specific guides under <a href="./../skills/"><code>skills/</code></a>:</p><table tabindex="0"><thead><tr><th>What you want to do</th><th>Skill</th></tr></thead><tbody><tr><td>Understand the project layout and runtimes</td><td><a href="./../skills/framework-map/SKILL.html"><code>framework-map</code></a></td></tr><tr><td>Create and verify a new agent</td><td><a href="./../skills/create-agent/SKILL.html"><code>create-agent</code></a></td></tr><tr><td>Write fixtures and regression checks</td><td><a href="./../skills/evals/SKILL.html"><code>evals</code></a></td></tr><tr><td>Live A/B metrics on traffic (<code>defineAB</code>)</td><td><a href="./../skills/ab/SKILL.html"><code>ab</code></a></td></tr><tr><td>Improve an agent against fixed inputs</td><td><a href="./../skills/hillclimb/SKILL.html"><code>hillclimb</code></a></td></tr><tr><td>Add GitHub webhooks and replay events</td><td><a href="./../skills/github/SKILL.html"><code>github</code></a></td></tr><tr><td>Connect an agent to Slack</td><td><a href="./../skills/setup-slack/SKILL.html"><code>setup-slack</code></a></td></tr><tr><td>Diagnose a local run</td><td><a href="./../skills/debug/SKILL.html"><code>debug</code></a></td></tr></tbody></table><p>Point your coding agent at the matching <code>SKILL.md</code>. The guide contains the workflow, commands, and common mistakes for that task.</p><div class="note custom-block github-alert"><p class="custom-block-title">NOTE</p><p>The skill bodies use the current <code>agent-serve</code> CLI names. This guide uses the upcoming <code>agent-sdk</code> names. See <a href="/docs/#run-the-cli">Run the CLI</a> for the full rename table.</p></div><h2 id="how-does-a-coding-agent-verify-its-work" tabindex="-1">How does a coding agent verify its work? <a class="header-anchor" href="#how-does-a-coding-agent-verify-its-work" aria-label="Permalink to &quot;How does a coding agent verify its work?&quot;">​</a></h2><p>The coding agent should discover the project, test each server tool, run a real turn, and finish with evals:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> info</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --json</span></span>
 <span class="line"></span>
 <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> call</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>

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

@@ -1 +1 @@
-import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.CAZyNGu9.js";const k=JSON.parse('{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent.","frontmatter":{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),n={name:"building-with-agents.md"};function l(h,e,r,o,d,c){return s(),t("div",null,[...e[0]||(e[0]=[i("",29)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};
+import{_ as a,c as t,o as s,ag as i}from"./chunks/framework.BCISBCiQ.js";const k=JSON.parse('{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent.","frontmatter":{"title":"Building agents with agents","description":"Use the built-in skills to have a coding agent create, verify, and improve your agent."},"headers":[],"relativePath":"building-with-agents.md","filePath":"building-with-agents.md"}'),n={name:"building-with-agents.md"};function l(h,e,r,o,d,c){return s(),t("div",null,[...e[0]||(e[0]=[i("",29)])])}const g=a(n,[["render",l]]);export{k as __pageData,g as default};