@cursor/july 0.1.91 → 0.1.92

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

@@ -0,0 +1,124 @@
+# Building agents with agents
+
+Give a coding agent the goal. The built-in skills guide it through
+scaffolding, channels, verification, evals, and measured improvement.
+
+## What can a coding agent build for me?
+
+A coding agent can take an Agent SDK project from an idea to a
+verified first version. It can:
+
+- 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) (in the
+monorepo: `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:
+
+> 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.
+
+## Which built-in skill should I use?
+
+The package ships task-specific guides under [`skills/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/skills/):
+
+| 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) |
+| Live A/B metrics on traffic (`defineAB`) | [`ab`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/ab/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) |
+| Diagnose a local run | [`debug`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/debug/SKILL.md) |
+
+Point your coding agent at the matching `SKILL.md`. The guide contains
+the workflow, commands, and common mistakes for that task.
+
+> [!NOTE]
+> The skill bodies use the current `agent-serve` CLI names. This guide
+> uses the upcoming `agent-sdk` names. See
+> [Run the CLI](/docs/index.md#run-the-cli) for the full rename table.
+
+## How does a coding agent verify its work?
+
+The coding agent should discover the project, test each server tool,
+run a real turn, and finish with evals:
+
+```bash
+agent-sdk validate --dir .
+agent-sdk info --dir . --json
+
+agent-sdk call inspect_pr --dir . \
+  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
+
+agent-sdk run --dir . \
+  --message "Is https://github.com/acme/checkout/pull/42 ready to approve?"
+
+agent-sdk trajectory --events .agent-serve/traces/<sessionId>.ndjson
+
+agent-sdk eval --dir . --list
+agent-sdk eval --dir . --json
+```
+
+`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.
+
+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.
+
+`validate` and `run` don't type-check the project because tsx strips
+types. 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.
+
+## How do I improve the agent after its first run?
+
+Scaffolding proves the agent runs. It says nothing about quality. Once a
+smoke turn passes, give the hillclimb skill:
+
+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
+
+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.
+
+## Related
+
+- [Create your first agent](/docs/quickstart.md)
+- [Scaffold an agent with Cursor](/docs/scaffolding-agents.md)
+- [Evals](/docs/evals.md)
+- [Hillclimbing](/docs/hillclimbing.md)
+- [CLI reference](/docs/reference/cli.md)

package/dist/docs/concepts.html

@@ -16,13 +16,15 @@
     <link rel="modulepreload" href="/docs/assets/concepts.md.CRfU3bVg.lean.js">
     <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
     <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
+    <link rel="alternate" type="text/plain" href="/docs/llms.txt">
+    <link rel="alternate" type="text/markdown" href="/docs/concepts.md">
   </head>
   <body>
-    <div id="app"><div class="Layout" data-v-282c430e><!--[--><!--]--><!--[--><span tabindex="-1" data-v-af8643bc></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-af8643bc>Skip to content</a><!--]--><!----><header class="VPNav" data-v-282c430e data-v-4751689a><div class="VPNavBar" data-v-4751689a data-v-d2a336f3><div class="wrapper" data-v-d2a336f3><div class="container" data-v-d2a336f3><div class="title" data-v-d2a336f3><div class="VPNavBarTitle has-sidebar" data-v-d2a336f3 data-v-3a787a7b><a class="title" href="/docs/" data-v-3a787a7b><!--[--><!--]--><!----><span data-v-3a787a7b>Agent SDK</span><!--[--><!--[--><!--[--><!--[--><span class="agent-sdk-version" title="@cursor/july 0.1.91" data-v-c26a5f4f>0.1.91</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-d2a336f3><div class="content-body" data-v-d2a336f3><!--[--><!--]--><div class="VPNavBarSearch search" data-v-d2a336f3><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-d2a336f3 data-v-b60c0a58><span id="main-nav-aria-label" class="visually-hidden" data-v-b60c0a58> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/example-agents/" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Examples</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-d2a336f3 data-v-d559fc20><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-d559fc20 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-d2a336f3 data-v-75b97eb1 data-v-ed271fd4><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-ed271fd4><span class="vpi-more-horizontal icon" data-v-ed271fd4></span></button><div class="menu" data-v-ed271fd4><div class="VPMenu" data-v-ed271fd4 data-v-505057d2><!----><!--[--><!--[--><!----><div class="group" data-v-75b97eb1><div class="item appearance" data-v-75b97eb1><p class="label" data-v-75b97eb1>Appearance</p><div class="appearance-action" data-v-75b97eb1><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-75b97eb1 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-d2a336f3 data-v-966f1ac7><span class="container" data-v-966f1ac7><span class="top" data-v-966f1ac7></span><span class="middle" data-v-966f1ac7></span><span class="bottom" data-v-966f1ac7></span></span></button></div></div></div></div><div class="divider" data-v-d2a336f3><div class="divider-line" data-v-d2a336f3></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-282c430e data-v-f96f8409><div class="container" data-v-f96f8409><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-f96f8409><span class="vpi-align-left menu-icon" data-v-f96f8409></span><span class="menu-text" data-v-f96f8409>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-f96f8409 data-v-1bc67f4b><button data-v-1bc67f4b>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-282c430e data-v-3d1258d2><div class="curtain" data-v-3d1258d2></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-3d1258d2><span class="visually-hidden" id="sidebar-aria-label" data-v-3d1258d2> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 has-active" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Getting started</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Convert a Cursor Automation</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/concepts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Templates</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/demo.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Demo agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agentic Owners</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/pr-autofixer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR autofixer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Improving agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/evals.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/ab.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/storage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Guides</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Cloud runtime</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Example agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Choose an example</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/weather-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Weather agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/slack-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/concierge.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concierge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/benny.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playbook router</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/oncall.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Alert investigator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/bugbot.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR evidence reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/approval-buddy.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Approval Buddy</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security Reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/fsd.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Remote PR coordinator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/knowledge-base.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Knowledge base</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/codebase-wiki.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Codebase wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/codeowners-review.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Codeowners review</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Operating</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 collapsible" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-61fcdc7c><span class="vpi-chevron-right caret-icon" data-v-61fcdc7c></span></div></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-282c430e data-v-3b8d81ee><div class="VPDoc has-sidebar has-aside" data-v-3b8d81ee data-v-2e506a34><!--[--><!--]--><div class="container" data-v-2e506a34><div class="aside" data-v-2e506a34><div class="aside-curtain" data-v-2e506a34></div><div class="aside-container" data-v-2e506a34><div class="aside-content" data-v-2e506a34><div class="VPDocAside" data-v-2e506a34 data-v-b485a79e><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-b485a79e data-v-cc6b345c><div class="content" data-v-cc6b345c><div class="outline-marker" data-v-cc6b345c></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-cc6b345c>On this page</div><ul class="VPDocOutlineItem root" data-v-cc6b345c data-v-4f0215bf><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-b485a79e></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-2e506a34><div class="content-container" data-v-2e506a34><!--[--><!--]--><main class="main" data-v-2e506a34><div style="position:relative;" class="vp-doc _docs_concepts" data-v-2e506a34><div><h1 id="how-the-agent-sdk-works" tabindex="-1">How the Agent SDK works <a class="header-anchor" href="#how-the-agent-sdk-works" aria-label="Permalink to &quot;How the Agent SDK works&quot;">​</a></h1><p>An agent is a folder of instructions and capabilities. The Agent SDK discovers those files, runs conversations, and records what happened.</p><h2 id="what-happens-when-someone-sends-a-message" tabindex="-1">What happens when someone sends a message? <a class="header-anchor" href="#what-happens-when-someone-sends-a-message" aria-label="Permalink to &quot;What happens when someone sends a message?&quot;">​</a></h2><p>Follow one message through the system:</p><ol><li>A channel receives the message from HTTP, Slack, GitHub, or another webhook.</li><li>The channel starts a session or continues an existing one.</li><li>The runtime gives the model its instructions, tools, and workspace.</li><li>The model replies and can call tools along the way.</li><li>The Agent SDK appends every message and tool call to the session&#39;s event stream.</li></ol><p>The channel is the front door. The runtime does the work. The event stream is the record you inspect later.</p><h2 id="how-do-files-become-an-agent" tabindex="-1">How do files become an agent? <a class="header-anchor" href="#how-do-files-become-an-agent" aria-label="Permalink to &quot;How do files become an agent?&quot;">​</a></h2><p>Each capability has a home in the project. The path tells the Agent SDK what to load. The filename becomes the capability&#39;s name. For example, <code>agent/tools/get_weather.ts</code> creates a tool named <code>get_weather</code>.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td>Model and runtime settings</td></tr><tr><td><code>agent/instructions.md</code></td><td>The always-on system prompt</td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>Typed actions the model can call</td></tr><tr><td><code>agent/skills/*</code></td><td>Procedures loaded when needed</td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>Tools from external MCP servers</td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP, Slack, and GitHub entry points</td></tr><tr><td><code>agent/ab.ts</code> or <code>agent/ab/*.ts</code></td><td>Sticky variants and live performance metrics</td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Repeatable checks at the project root</td></tr></tbody></table><p>Other folders add subagents, hooks, schedules, and workspace files. You don&#39;t register them elsewhere. Run <code>agent-sdk validate</code> to catch invalid files before serving the project.</p><p>See <a href="./reference/project-layout.html">Project layout</a> for every supported path.</p><h2 id="how-does-the-agent-sdk-identify-a-conversation" tabindex="-1">How does the Agent SDK identify a conversation? <a class="header-anchor" href="#how-does-the-agent-sdk-identify-a-conversation" aria-label="Permalink to &quot;How does the Agent SDK identify a conversation?&quot;">​</a></h2><p>A session is one durable conversation. It has two identifiers:</p><ul><li><strong><code>continuationToken</code></strong> tells a channel which conversation to resume. A Slack channel can use its thread ID. A GitHub channel can use the pull request. The built-in HTTP API returns an opaque token and rotates it after each accepted follow-up.</li><li><strong><code>sessionId</code></strong> identifies the stored session. Use it to stream events, inspect the session, resolve approvals, or bind a tool call to the session.</li></ul><p>Use the continuation token to keep talking. Use the session ID to observe or manage the conversation.</p><h2 id="how-do-i-see-what-an-agent-did" tabindex="-1">How do I see what an agent did? <a class="header-anchor" href="#how-do-i-see-what-an-agent-did" aria-label="Permalink to &quot;How do I see what an agent did?&quot;">​</a></h2><p>Each session writes an append-only NDJSON file: <code>sessions/&lt;id&gt;/events.ndjson</code>. It includes:</p><ul><li>Messages and streamed text</li><li>Requested tool calls and their results</li><li>Approval requests and decisions</li><li>Turn completion and token usage</li></ul><p>Sessions and their event streams survive server restarts. The playground renders the stream. Evals assert against it. The <code>agent-sdk trajectory</code> command turns a saved stream into a short summary.</p><p>When a run surprises you, inspect its event stream first. See <a href="./reference/sessions.html">Sessions and streaming</a> for every event.</p><h2 id="what-does-a-channel-control" tabindex="-1">What does a channel control? <a class="header-anchor" href="#what-does-a-channel-control" aria-label="Permalink to &quot;What does a channel control?&quot;">​</a></h2><p>A channel connects the agent to a surface such as HTTP, Slack, GitHub, or a custom webhook. It controls:</p><ul><li>Routes and input schemas</li><li>Authentication</li><li>Conversation identity</li><li>How replies return to the user</li></ul><p>The built-in HTTP session API is always available. Custom routes accept loopback callers by default. Add an auth policy before sharing them over a network.</p><p>Channels should also prepare deterministic input for the model. For example, a GitHub channel can fetch the pull request, collect the diff, and seed the workspace before the turn starts. The model can then focus on the review instead of gathering files.</p><p>See <a href="./reference/channels.html">Channels</a> for route and authentication details.</p><h2 id="where-does-a-turn-run" tabindex="-1">Where does a turn run? <a class="header-anchor" href="#where-does-a-turn-run" aria-label="Permalink to &quot;Where does a turn run?&quot;">​</a></h2><p>Choose a runtime in <code>agent/agent.ts</code>:</p><table tabindex="0"><thead><tr><th></th><th>Local (default)</th><th>Cloud</th></tr></thead><tbody><tr><td>Turn runs on</td><td>The server host</td><td>A Cursor cloud agent</td></tr><tr><td>Server tools</td><td>Supported</td><td>Supported when the server has <code>--public-url</code> or <code>--cloud-tools-url</code>; the cloud turn reaches them over authenticated HTTP MCP. Without one of those flags, the server warns and cloud turns omit them.</td></tr><tr><td>Approvals (<code>needsApproval</code>)</td><td>Supported</td><td>Not supported (local runtime only)</td></tr><tr><td>Agent tool scripts</td><td>Supported</td><td>Supported</td></tr><tr><td>Skills</td><td>Added to the session workspace</td><td>Available automatically</td></tr><tr><td>Seeded files</td><td>Added to the session workspace</td><td>Ignored</td></tr><tr><td>Repository</td><td>You provide it</td><td>The cloud agent checks it out</td></tr></tbody></table><p>Use the local runtime when the host has the tools and files the agent needs. Use the cloud runtime when each turn needs an isolated repository checkout. <code>agent-sdk validate</code> warns when a cloud agent uses a local-only capability.</p><p>See <a href="./guides/cloud-runtime.html">Cloud runtime</a> for setup and trade-offs.</p><h2 id="what-files-can-a-local-session-access" tabindex="-1">What files can a local session access? <a class="header-anchor" href="#what-files-can-a-local-session-access" aria-label="Permalink to &quot;What files can a local session access?&quot;">​</a></h2><p>Each local session gets its own workspace. The Agent SDK writes the instructions as <code>AGENTS.md</code>, installs authored skills, copies sandbox files, and adds agent tool scripts.</p><p>The workspace is a real Cursor project. It can inherit <code>AGENTS.md</code> and <code>.cursor</code> settings from parent directories. Nested git checkouts default <code>local.cwd</code> to <code>~/.cache/agent-serve/&lt;dir&gt;</code>. Point <code>cwd</code> at a checkout only when the agent should inherit that tree. <code>run</code> and <code>eval</code> already use a temporary state root.</p><p>Durable local state uses this shape:</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>&lt;project&gt;/.agent-serve/</span></span>
+    <div id="app"><div class="Layout" data-v-282c430e><!--[--><!--]--><!--[--><span tabindex="-1" data-v-af8643bc></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-af8643bc>Skip to content</a><!--]--><!----><header class="VPNav" data-v-282c430e data-v-4751689a><div class="VPNavBar" data-v-4751689a data-v-d2a336f3><div class="wrapper" data-v-d2a336f3><div class="container" data-v-d2a336f3><div class="title" data-v-d2a336f3><div class="VPNavBarTitle has-sidebar" data-v-d2a336f3 data-v-3a787a7b><a class="title" href="/docs/" data-v-3a787a7b><!--[--><!--]--><!----><span data-v-3a787a7b>Agent SDK</span><!--[--><!--[--><!--[--><!--[--><span class="agent-sdk-version" title="@cursor/july 0.1.92" data-v-c26a5f4f>0.1.92</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-d2a336f3><div class="content-body" data-v-d2a336f3><!--[--><!--]--><div class="VPNavBarSearch search" data-v-d2a336f3><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-d2a336f3 data-v-b60c0a58><span id="main-nav-aria-label" class="visually-hidden" data-v-b60c0a58> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/example-agents/" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Examples</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-b60c0a58 data-v-74de87b9><!--[--><span data-v-74de87b9>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-d2a336f3 data-v-d559fc20><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-d559fc20 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-d2a336f3 data-v-75b97eb1 data-v-ed271fd4><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-ed271fd4><span class="vpi-more-horizontal icon" data-v-ed271fd4></span></button><div class="menu" data-v-ed271fd4><div class="VPMenu" data-v-ed271fd4 data-v-505057d2><!----><!--[--><!--[--><!----><div class="group" data-v-75b97eb1><div class="item appearance" data-v-75b97eb1><p class="label" data-v-75b97eb1>Appearance</p><div class="appearance-action" data-v-75b97eb1><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-75b97eb1 data-v-deaafa36 data-v-88da49d2><span class="check" data-v-88da49d2><span class="icon" data-v-88da49d2><!--[--><span class="vpi-sun sun" data-v-deaafa36></span><span class="vpi-moon moon" data-v-deaafa36></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-d2a336f3 data-v-966f1ac7><span class="container" data-v-966f1ac7><span class="top" data-v-966f1ac7></span><span class="middle" data-v-966f1ac7></span><span class="bottom" data-v-966f1ac7></span></span></button></div></div></div></div><div class="divider" data-v-d2a336f3><div class="divider-line" data-v-d2a336f3></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-282c430e data-v-f96f8409><div class="container" data-v-f96f8409><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-f96f8409><span class="vpi-align-left menu-icon" data-v-f96f8409></span><span class="menu-text" data-v-f96f8409>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-f96f8409 data-v-1bc67f4b><button data-v-1bc67f4b>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-282c430e data-v-3d1258d2><div class="curtain" data-v-3d1258d2></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-3d1258d2><span class="visually-hidden" id="sidebar-aria-label" data-v-3d1258d2> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 has-active" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Getting started</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Convert a Cursor Automation</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/concepts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Templates</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/demo.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Demo agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agentic Owners</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/pr-autofixer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR autofixer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Improving agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/evals.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/ab.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/storage.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Guides</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Cloud runtime</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Example agents</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Choose an example</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/weather-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Weather agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/slack-agent.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Slack agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/concierge.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Concierge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/benny.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playbook router</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/oncall.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Alert investigator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/bugbot.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>PR evidence reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/approval-buddy.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Approval Buddy</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/security-reviewer.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Security Reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/fsd.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Remote PR coordinator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/knowledge-base.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Knowledge base</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/codebase-wiki.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Codebase wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/example-agents/codeowners-review.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Codeowners review</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Operating</h2><!----></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-f2306e18><section class="VPSidebarItem level-0 collapsible" data-v-f2306e18 data-v-61fcdc7c><div class="item" role="button" tabindex="0" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><h2 class="text" data-v-61fcdc7c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-61fcdc7c><span class="vpi-chevron-right caret-icon" data-v-61fcdc7c></span></div></div><div class="items" data-v-61fcdc7c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-61fcdc7c><div class="item" data-v-61fcdc7c><div class="indicator" data-v-61fcdc7c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-61fcdc7c><!--[--><p class="text" data-v-61fcdc7c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-282c430e data-v-3b8d81ee><div class="VPDoc has-sidebar has-aside" data-v-3b8d81ee data-v-2e506a34><!--[--><!--]--><div class="container" data-v-2e506a34><div class="aside" data-v-2e506a34><div class="aside-curtain" data-v-2e506a34></div><div class="aside-container" data-v-2e506a34><div class="aside-content" data-v-2e506a34><div class="VPDocAside" data-v-2e506a34 data-v-b485a79e><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-b485a79e data-v-cc6b345c><div class="content" data-v-cc6b345c><div class="outline-marker" data-v-cc6b345c></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-cc6b345c>On this page</div><ul class="VPDocOutlineItem root" data-v-cc6b345c data-v-4f0215bf><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-b485a79e></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-2e506a34><div class="content-container" data-v-2e506a34><!--[--><!--]--><main class="main" data-v-2e506a34><div style="position:relative;" class="vp-doc _docs_concepts" data-v-2e506a34><div><h1 id="how-the-agent-sdk-works" tabindex="-1">How the Agent SDK works <a class="header-anchor" href="#how-the-agent-sdk-works" aria-label="Permalink to &quot;How the Agent SDK works&quot;">​</a></h1><p>An agent is a folder of instructions and capabilities. The Agent SDK discovers those files, runs conversations, and records what happened.</p><h2 id="what-happens-when-someone-sends-a-message" tabindex="-1">What happens when someone sends a message? <a class="header-anchor" href="#what-happens-when-someone-sends-a-message" aria-label="Permalink to &quot;What happens when someone sends a message?&quot;">​</a></h2><p>Follow one message through the system:</p><ol><li>A channel receives the message from HTTP, Slack, GitHub, or another webhook.</li><li>The channel starts a session or continues an existing one.</li><li>The runtime gives the model its instructions, tools, and workspace.</li><li>The model replies and can call tools along the way.</li><li>The Agent SDK appends every message and tool call to the session&#39;s event stream.</li></ol><p>The channel is the front door. The runtime does the work. The event stream is the record you inspect later.</p><h2 id="how-do-files-become-an-agent" tabindex="-1">How do files become an agent? <a class="header-anchor" href="#how-do-files-become-an-agent" aria-label="Permalink to &quot;How do files become an agent?&quot;">​</a></h2><p>Each capability has a home in the project. The path tells the Agent SDK what to load. The filename becomes the capability&#39;s name. For example, <code>agent/tools/get_weather.ts</code> creates a tool named <code>get_weather</code>.</p><table tabindex="0"><thead><tr><th>Path</th><th>What it is</th></tr></thead><tbody><tr><td><code>agent/agent.ts</code></td><td>Model and runtime settings</td></tr><tr><td><code>agent/instructions.md</code></td><td>The always-on system prompt</td></tr><tr><td><code>agent/tools/&lt;name&gt;.ts</code></td><td>Typed actions the model can call</td></tr><tr><td><code>agent/skills/*</code></td><td>Procedures loaded when needed</td></tr><tr><td><code>agent/mcp-connections/&lt;name&gt;.ts</code></td><td>Tools from external MCP servers</td></tr><tr><td><code>agent/channels/*.ts</code></td><td>HTTP, Slack, and GitHub entry points</td></tr><tr><td><code>agent/ab.ts</code> or <code>agent/ab/*.ts</code></td><td>Sticky variants and live performance metrics</td></tr><tr><td><code>evals/**/*.eval.ts</code></td><td>Repeatable checks at the project root</td></tr></tbody></table><p>Other folders add subagents, hooks, schedules, and workspace files. You don&#39;t register them elsewhere. Run <code>agent-sdk validate</code> to catch invalid files before serving the project.</p><p>See <a href="./reference/project-layout.html">Project layout</a> for every supported path.</p><h2 id="how-does-the-agent-sdk-identify-a-conversation" tabindex="-1">How does the Agent SDK identify a conversation? <a class="header-anchor" href="#how-does-the-agent-sdk-identify-a-conversation" aria-label="Permalink to &quot;How does the Agent SDK identify a conversation?&quot;">​</a></h2><p>A session is one durable conversation. It has two identifiers:</p><ul><li><strong><code>continuationToken</code></strong> tells a channel which conversation to resume. A Slack channel can use its thread ID. A GitHub channel can use the pull request. The built-in HTTP API returns an opaque token and rotates it after each accepted follow-up.</li><li><strong><code>sessionId</code></strong> identifies the stored session. Use it to stream events, inspect the session, resolve approvals, or bind a tool call to the session.</li></ul><p>Use the continuation token to keep talking. Use the session ID to observe or manage the conversation.</p><h2 id="how-do-i-see-what-an-agent-did" tabindex="-1">How do I see what an agent did? <a class="header-anchor" href="#how-do-i-see-what-an-agent-did" aria-label="Permalink to &quot;How do I see what an agent did?&quot;">​</a></h2><p>Each session writes an append-only NDJSON file: <code>sessions/&lt;id&gt;/events.ndjson</code>. It includes:</p><ul><li>Messages and streamed text</li><li>Requested tool calls and their results</li><li>Approval requests and decisions</li><li>Turn completion and token usage</li></ul><p>Sessions and their event streams survive server restarts. The playground renders the stream. Evals assert against it. The <code>agent-sdk trajectory</code> command turns a saved stream into a short summary.</p><p>When a run surprises you, inspect its event stream first. See <a href="./reference/sessions.html">Sessions and streaming</a> for every event.</p><h2 id="what-does-a-channel-control" tabindex="-1">What does a channel control? <a class="header-anchor" href="#what-does-a-channel-control" aria-label="Permalink to &quot;What does a channel control?&quot;">​</a></h2><p>A channel connects the agent to a surface such as HTTP, Slack, GitHub, or a custom webhook. It controls:</p><ul><li>Routes and input schemas</li><li>Authentication</li><li>Conversation identity</li><li>How replies return to the user</li></ul><p>The built-in HTTP session API is always available. Custom routes accept loopback callers by default. Add an auth policy before sharing them over a network.</p><p>Channels should also prepare deterministic input for the model. For example, a GitHub channel can fetch the pull request, collect the diff, and seed the workspace before the turn starts. The model can then focus on the review instead of gathering files.</p><p>See <a href="./reference/channels.html">Channels</a> for route and authentication details.</p><h2 id="where-does-a-turn-run" tabindex="-1">Where does a turn run? <a class="header-anchor" href="#where-does-a-turn-run" aria-label="Permalink to &quot;Where does a turn run?&quot;">​</a></h2><p>Choose a runtime in <code>agent/agent.ts</code>:</p><table tabindex="0"><thead><tr><th></th><th>Local (default)</th><th>Cloud</th></tr></thead><tbody><tr><td>Turn runs on</td><td>The server host</td><td>A Cursor cloud agent</td></tr><tr><td>Server tools</td><td>Supported</td><td>Supported when the server has <code>--public-url</code> or <code>--cloud-tools-url</code>; the cloud turn reaches them over authenticated HTTP MCP. Without one of those flags, the server warns and cloud turns omit them.</td></tr><tr><td>Approvals (<code>needsApproval</code>)</td><td>Supported</td><td>Not supported (local runtime only)</td></tr><tr><td>Agent tool scripts</td><td>Supported</td><td>Supported</td></tr><tr><td>Skills</td><td>Added to the session workspace</td><td>Available automatically</td></tr><tr><td>Seeded files</td><td>Added to the session workspace</td><td>Ignored</td></tr><tr><td>Repository</td><td>You provide it</td><td>The cloud agent checks it out</td></tr></tbody></table><p>Use the local runtime when the host has the tools and files the agent needs. Use the cloud runtime when each turn needs an isolated repository checkout. <code>agent-sdk validate</code> warns when a cloud agent uses a local-only capability.</p><p>See <a href="./guides/cloud-runtime.html">Cloud runtime</a> for setup and trade-offs.</p><h2 id="what-files-can-a-local-session-access" tabindex="-1">What files can a local session access? <a class="header-anchor" href="#what-files-can-a-local-session-access" aria-label="Permalink to &quot;What files can a local session access?&quot;">​</a></h2><p>Each local session gets its own workspace. The Agent SDK writes the instructions as <code>AGENTS.md</code>, installs authored skills, copies sandbox files, and adds agent tool scripts.</p><p>The workspace is a real Cursor project. It can inherit <code>AGENTS.md</code> and <code>.cursor</code> settings from parent directories. Nested git checkouts default <code>local.cwd</code> to <code>~/.cache/agent-serve/&lt;dir&gt;</code>. Point <code>cwd</code> at a checkout only when the agent should inherit that tree. <code>run</code> and <code>eval</code> already use a temporary state root.</p><p>Durable local state uses this shape:</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>&lt;project&gt;/.agent-serve/</span></span>
 <span class="line"><span>  sessions/&lt;id&gt;/events.ndjson</span></span>
 <span class="line"><span>  sessions/&lt;id&gt;/workspace/</span></span>
 <span class="line"><span>  traces/&lt;sessionId&gt;.ndjson</span></span></code></pre></div><h2 id="how-can-one-agent-call-another" tabindex="-1">How can one agent call another? <a class="header-anchor" href="#how-can-one-agent-call-another" aria-label="Permalink to &quot;How can one agent call another?&quot;">​</a></h2><p>Every mounted agent also serves MCP at <code>/&lt;slug&gt;/v1/mcp</code>. Another agent or MCP client can use <code>ask</code>, <code>check</code>, and <code>call_tool</code> to delegate work. A peer MCP connection such as <code>defineConnection({ agent: &quot;weather-agent&quot; })</code> adds those tools to the calling agent.</p><p>See <a href="./guides/agent-to-agent.html">Agent-to-agent</a> for a complete example.</p><h2 id="which-rules-prevent-common-setup-problems" tabindex="-1">Which rules prevent common setup problems? <a class="header-anchor" href="#which-rules-prevent-common-setup-problems" aria-label="Permalink to &quot;Which rules prevent common setup problems?&quot;">​</a></h2><ul><li>Use Node 22.13 or newer. Bun isn&#39;t supported.</li><li>Put evals under the project-root <code>evals/</code> directory, not <code>agent/evals/</code>.</li><li>Run a TypeScript check before shipping. <code>validate</code> and <code>run</code> execute TypeScript but don&#39;t type-check it.</li><li>Return JSON-shaped values from tool <code>execute</code> functions.</li><li>Keep local session workspaces away from parent rules you don&#39;t want the agent to inherit.</li><li>Sign in or set <code>CURSOR_API_KEY</code> before starting a model turn. Discovery, validation, direct tool calls, and server startup work without a credential.</li></ul><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></li><li><a href="./reference/project-layout.html">Project layout</a></li><li><a href="./reference/sessions.html">Sessions and streaming</a></li><li><a href="./reference/channels.html">Channels</a></li><li><a href="./ab.html">Live A/B metrics</a></li><li><a href="./guides/cloud-runtime.html">Cloud runtime</a></li></ul></div></div></main><footer class="VPDocFooter" data-v-2e506a34 data-v-574f06fa><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-574f06fa><span class="visually-hidden" id="doc-footer-aria-label" data-v-574f06fa>Pager</span><div class="pager" data-v-574f06fa><a class="VPLink link pager-link prev" href="/docs/guides/convert-automation.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Previous page</span><span class="title" data-v-574f06fa>Convert a Cursor Automation</span><!--]--></a></div><div class="pager" data-v-574f06fa><a class="VPLink link pager-link next" href="/docs/templates/demo.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Next page</span><span class="title" data-v-574f06fa>Demo agent</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
-    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"CVzWxLoB\",\"building-with-agents.md\":\"DH8A_cHA\",\"concepts.md\":\"CRfU3bVg\",\"deployment.md\":\"DX_hc3ze\",\"evals.md\":\"a0SMN6r9\",\"example-agents_approval-buddy.md\":\"DNL83puR\",\"example-agents_benny.md\":\"C40vHRLc\",\"example-agents_bugbot.md\":\"BRGMi9O2\",\"example-agents_codebase-wiki.md\":\"Dftj_tPp\",\"example-agents_codeowners-review.md\":\"Bfta-lBU\",\"example-agents_concierge.md\":\"MrKpQndp\",\"example-agents_fsd.md\":\"ZWHWWZPE\",\"example-agents_index.md\":\"QZ8mhr6n\",\"example-agents_knowledge-base.md\":\"DqKqHQ9u\",\"example-agents_oncall.md\":\"DK4XkYTd\",\"example-agents_security-reviewer.md\":\"Bai6D0Ee\",\"example-agents_slack-agent.md\":\"D7Kdj5BV\",\"example-agents_weather-agent.md\":\"lVEAbWFf\",\"guides_agent-to-agent.md\":\"BCeVdJRJ\",\"guides_cloud-runtime.md\":\"BSMLIBHr\",\"guides_convert-automation.md\":\"D06eIzea\",\"guides_github.md\":\"Cdt1s2QC\",\"guides_human-in-the-loop.md\":\"By1G2T3_\",\"guides_mcp-oauth.md\":\"Du0f7pGU\",\"guides_opentelemetry.md\":\"bmPmkvJu\",\"guides_slack.md\":\"DiUmk_Oi\",\"guides_webhooks.md\":\"BpnIdO0i\",\"hillclimbing.md\":\"ywF3yDAd\",\"index.md\":\"BAaMXLFd\",\"quickstart.md\":\"DsrarzEg\",\"reference_agent-config.md\":\"Bqylgw50\",\"reference_artifacts.md\":\"Dior32Qw\",\"reference_channels.md\":\"DQZjCnyh\",\"reference_cli.md\":\"B7GkAJRC\",\"reference_connections.md\":\"DYidrb-j\",\"reference_hooks.md\":\"B9FSgdDe\",\"reference_http-api.md\":\"CSHVobzG\",\"reference_instructions.md\":\"DhNCOl7r\",\"reference_playground.md\":\"Dfb92yQf\",\"reference_project-layout.md\":\"CwkSbEWT\",\"reference_prompt.md\":\"DZUMtLPD\",\"reference_schedules.md\":\"DNipebiG\",\"reference_sessions.md\":\"tUFzz98S\",\"reference_skills.md\":\"B5ZEuHfG\",\"reference_subagents.md\":\"Xoav0AII\",\"reference_tools.md\":\"wpaJtHn6\",\"scaffolding-agents.md\":\"CRDDUtYJ\",\"storage.md\":\"JbjlHWZ6\",\"templates_agentic-owners.md\":\"DSJSIpWU\",\"templates_demo.md\":\"DhFcWN6j\",\"templates_pr-autofixer.md\":\"1HAR3RXE\",\"templates_security-reviewer.md\":\"ByFyRta2\",\"templates_triage.md\":\"CVlpctKS\",\"troubleshooting.md\":\"DYECCZiJ\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.1.91\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Convert a Cursor Automation\",\"link\":\"/guides/convert-automation\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Demo agent\",\"link\":\"/templates/demo\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Agentic Owners\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"PR autofixer\",\"link\":\"/templates/pr-autofixer\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
+    <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"CVzWxLoB\",\"building-with-agents.md\":\"DH8A_cHA\",\"concepts.md\":\"CRfU3bVg\",\"deployment.md\":\"DX_hc3ze\",\"evals.md\":\"a0SMN6r9\",\"example-agents_approval-buddy.md\":\"DNL83puR\",\"example-agents_benny.md\":\"C40vHRLc\",\"example-agents_bugbot.md\":\"BRGMi9O2\",\"example-agents_codebase-wiki.md\":\"Dftj_tPp\",\"example-agents_codeowners-review.md\":\"Bfta-lBU\",\"example-agents_concierge.md\":\"MrKpQndp\",\"example-agents_fsd.md\":\"ZWHWWZPE\",\"example-agents_index.md\":\"QZ8mhr6n\",\"example-agents_knowledge-base.md\":\"DqKqHQ9u\",\"example-agents_oncall.md\":\"DK4XkYTd\",\"example-agents_security-reviewer.md\":\"Bai6D0Ee\",\"example-agents_slack-agent.md\":\"D7Kdj5BV\",\"example-agents_weather-agent.md\":\"lVEAbWFf\",\"guides_agent-to-agent.md\":\"BCeVdJRJ\",\"guides_cloud-runtime.md\":\"BSMLIBHr\",\"guides_convert-automation.md\":\"D06eIzea\",\"guides_github.md\":\"Cdt1s2QC\",\"guides_human-in-the-loop.md\":\"By1G2T3_\",\"guides_mcp-oauth.md\":\"Du0f7pGU\",\"guides_opentelemetry.md\":\"bmPmkvJu\",\"guides_slack.md\":\"DiUmk_Oi\",\"guides_webhooks.md\":\"BpnIdO0i\",\"hillclimbing.md\":\"ywF3yDAd\",\"index.md\":\"BAaMXLFd\",\"quickstart.md\":\"DsrarzEg\",\"reference_agent-config.md\":\"Bqylgw50\",\"reference_artifacts.md\":\"Dior32Qw\",\"reference_channels.md\":\"DQZjCnyh\",\"reference_cli.md\":\"B7GkAJRC\",\"reference_connections.md\":\"DYidrb-j\",\"reference_hooks.md\":\"B9FSgdDe\",\"reference_http-api.md\":\"CSHVobzG\",\"reference_instructions.md\":\"DhNCOl7r\",\"reference_playground.md\":\"Dfb92yQf\",\"reference_project-layout.md\":\"CwkSbEWT\",\"reference_prompt.md\":\"DZUMtLPD\",\"reference_schedules.md\":\"DNipebiG\",\"reference_sessions.md\":\"tUFzz98S\",\"reference_skills.md\":\"B5ZEuHfG\",\"reference_subagents.md\":\"Xoav0AII\",\"reference_tools.md\":\"wpaJtHn6\",\"scaffolding-agents.md\":\"CRDDUtYJ\",\"storage.md\":\"JbjlHWZ6\",\"templates_agentic-owners.md\":\"DSJSIpWU\",\"templates_demo.md\":\"DhFcWN6j\",\"templates_pr-autofixer.md\":\"1HAR3RXE\",\"templates_security-reviewer.md\":\"ByFyRta2\",\"templates_triage.md\":\"CVlpctKS\",\"troubleshooting.md\":\"DYECCZiJ\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Agent SDK\",\"description\":\"Filesystem-first framework for building and serving Cursor agents.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.1.92\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/webhooks\"},{\"text\":\"Examples\",\"link\":\"/example-agents/\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Scaffold an agent with Cursor\",\"link\":\"/scaffolding-agents\"},{\"text\":\"Convert a Cursor Automation\",\"link\":\"/guides/convert-automation\"},{\"text\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"text\":\"Demo agent\",\"link\":\"/templates/demo\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Agentic Owners\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"PR autofixer\",\"link\":\"/templates/pr-autofixer\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Improving agents\",\"items\":[{\"text\":\"Building agents with agents\",\"link\":\"/building-with-agents\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Live A/B metrics\",\"link\":\"/ab\"},{\"text\":\"Storage\",\"link\":\"/storage\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"}]},{\"text\":\"Guides\",\"items\":[{\"text\":\"Webhooks & custom channels\",\"link\":\"/guides/webhooks\"},{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Human-in-the-loop approvals\",\"link\":\"/guides/human-in-the-loop\"},{\"text\":\"Agent-to-agent\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Host MCP OAuth\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Cloud runtime\",\"link\":\"/guides/cloud-runtime\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"}]},{\"text\":\"Example agents\",\"items\":[{\"text\":\"Choose an example\",\"link\":\"/example-agents/\"},{\"text\":\"Weather agent\",\"link\":\"/example-agents/weather-agent\"},{\"text\":\"Slack agent\",\"link\":\"/example-agents/slack-agent\"},{\"text\":\"Concierge\",\"link\":\"/example-agents/concierge\"},{\"text\":\"Playbook router\",\"link\":\"/example-agents/benny\"},{\"text\":\"Alert investigator\",\"link\":\"/example-agents/oncall\"},{\"text\":\"PR evidence reviewer\",\"link\":\"/example-agents/bugbot\"},{\"text\":\"Approval Buddy\",\"link\":\"/example-agents/approval-buddy\"},{\"text\":\"Security Reviewer\",\"link\":\"/example-agents/security-reviewer\"},{\"text\":\"Remote PR coordinator\",\"link\":\"/example-agents/fsd\"},{\"text\":\"Knowledge base\",\"link\":\"/example-agents/knowledge-base\"},{\"text\":\"Codebase wiki\",\"link\":\"/example-agents/codebase-wiki\"},{\"text\":\"Codeowners review\",\"link\":\"/example-agents/codeowners-review\"}]},{\"text\":\"Operating\",\"items\":[{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Fix common problems\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
     
   </body>
 </html>

package/dist/docs/concepts.md

@@ -0,0 +1,174 @@
+# How the Agent SDK works
+
+An agent is a folder of instructions and capabilities. The Agent SDK
+discovers those files, runs conversations, and records what happened.
+
+## What happens when someone sends a message?
+
+Follow one message through the system:
+
+1. A channel receives the message from HTTP, Slack, GitHub, or another
+   webhook.
+2. The channel starts a session or continues an existing one.
+3. The runtime gives the model its instructions, tools, and workspace.
+4. The model replies and can call tools along the way.
+5. The Agent SDK appends every message and tool call to the session's
+   event stream.
+
+The channel is the front door. The runtime does the work. The event
+stream is the record you inspect later.
+
+## How do files become an agent?
+
+Each capability has a home in the project. The path tells
+the Agent SDK what to load. The filename becomes the capability's
+name. For example, `agent/tools/get_weather.ts` creates a tool named
+`get_weather`.
+
+| Path | What it is |
+| --- | --- |
+| `agent/agent.ts` | Model and runtime settings |
+| `agent/instructions.md` | The always-on system prompt |
+| `agent/tools/<name>.ts` | Typed actions the model can call |
+| `agent/skills/*` | Procedures loaded when needed |
+| `agent/mcp-connections/<name>.ts` | Tools from external MCP servers |
+| `agent/channels/*.ts` | HTTP, Slack, and GitHub entry points |
+| `agent/ab.ts` or `agent/ab/*.ts` | Sticky variants and live performance metrics |
+| `evals/**/*.eval.ts` | Repeatable checks at the project root |
+
+Other folders add subagents, hooks, schedules, and workspace files. You
+don't register them elsewhere. Run `agent-sdk validate` to catch
+invalid files before serving the project.
+
+See [Project layout](/docs/reference/project-layout.md) for every supported
+path.
+
+## How does the Agent SDK identify a conversation?
+
+A session is one durable conversation. It has two identifiers:
+
+- **`continuationToken`** tells a channel which conversation to resume.
+  A Slack channel can use its thread ID. A GitHub channel can use the
+  pull request. The built-in HTTP API returns an opaque token and
+  rotates it after each accepted follow-up.
+- **`sessionId`** identifies the stored session. Use it to stream
+  events, inspect the session, resolve approvals, or bind a tool call to
+  the session.
+
+Use the continuation token to keep talking. Use the session ID to
+observe or manage the conversation.
+
+## How do I see what an agent did?
+
+Each session writes an append-only NDJSON file:
+`sessions/<id>/events.ndjson`. It includes:
+
+- Messages and streamed text
+- Requested tool calls and their results
+- Approval requests and decisions
+- Turn completion and token usage
+
+Sessions and their event streams survive server restarts. The
+playground renders the stream. Evals assert against it. The
+`agent-sdk trajectory` command turns a saved stream into a short
+summary.
+
+When a run surprises you, inspect its event stream first. See
+[Sessions and streaming](/docs/reference/sessions.md) for every event.
+
+## What does a channel control?
+
+A channel connects the agent to a surface such as HTTP, Slack, GitHub,
+or a custom webhook. It controls:
+
+- Routes and input schemas
+- Authentication
+- Conversation identity
+- How replies return to the user
+
+The built-in HTTP session API is always available. Custom routes accept
+loopback callers by default. Add an auth policy before sharing them over
+a network.
+
+Channels should also prepare deterministic input for the model. For
+example, a GitHub channel can fetch the pull request, collect the diff,
+and seed the workspace before the turn starts. The model can then focus
+on the review instead of gathering files.
+
+See [Channels](/docs/reference/channels.md) for route and authentication
+details.
+
+## Where does a turn run?
+
+Choose a runtime in `agent/agent.ts`:
+
+| | Local (default) | Cloud |
+| --- | --- | --- |
+| Turn runs on | The server host | A Cursor cloud agent |
+| Server tools | Supported | Supported when the server has `--public-url` or `--cloud-tools-url`; the cloud turn reaches them over authenticated HTTP MCP. Without one of those flags, the server warns and cloud turns omit them. |
+| Approvals (`needsApproval`) | Supported | Not supported (local runtime only) |
+| Agent tool scripts | Supported | Supported |
+| Skills | Added to the session workspace | Available automatically |
+| Seeded files | Added to the session workspace | Ignored |
+| Repository | You provide it | The cloud agent checks it out |
+
+Use the local runtime when the host has the tools and files the agent
+needs. Use the cloud runtime when each turn needs an isolated repository
+checkout. `agent-sdk validate` warns when a cloud agent uses a
+local-only capability.
+
+See [Cloud runtime](/docs/guides/cloud-runtime.md) for setup and trade-offs.
+
+## What files can a local session access?
+
+Each local session gets its own workspace. The Agent SDK writes the
+instructions as `AGENTS.md`, installs authored skills, copies sandbox
+files, and adds agent tool scripts.
+
+The workspace is a real Cursor project. It can inherit `AGENTS.md` and
+`.cursor` settings from parent directories. Nested git checkouts default
+`local.cwd` to `~/.cache/agent-serve/<dir>`. Point `cwd` at a checkout
+only when the agent should inherit that tree. `run` and `eval` already
+use a temporary state root.
+
+Durable local state uses this shape:
+
+```text
+<project>/.agent-serve/
+  sessions/<id>/events.ndjson
+  sessions/<id>/workspace/
+  traces/<sessionId>.ndjson
+```
+
+## How can one agent call another?
+
+Every mounted agent also serves MCP at `/<slug>/v1/mcp`. Another agent
+or MCP client can use `ask`, `check`, and `call_tool` to delegate work.
+A peer MCP connection such as
+`defineConnection({ agent: "weather-agent" })` adds those tools to the
+calling agent.
+
+See [Agent-to-agent](/docs/guides/agent-to-agent.md) for a complete example.
+
+## Which rules prevent common setup problems?
+
+- Use Node 22.13 or newer. Bun isn't supported.
+- Put evals under the project-root `evals/` directory, not
+  `agent/evals/`.
+- Run a TypeScript check before shipping. `validate` and `run` execute
+  TypeScript but don't type-check it.
+- Return JSON-shaped values from tool `execute` functions.
+- Keep local session workspaces away from parent rules you don't want
+  the agent to inherit.
+- Sign in or set `CURSOR_API_KEY` before starting a model turn.
+  Discovery, validation, direct tool calls, and server startup work
+  without a credential.
+
+## Related
+
+- [Quickstart](/docs/quickstart.md)
+- [Project layout](/docs/reference/project-layout.md)
+- [Sessions and streaming](/docs/reference/sessions.md)
+- [Channels](/docs/reference/channels.md)
+- [Live A/B metrics](/docs/ab.md)
+- [Cloud runtime](/docs/guides/cloud-runtime.md)