@cursor/july 0.1.68 → 0.1.73

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (226) hide show
  1. package/AGENTS.md +4 -5
  2. package/README.md +23 -11
  3. package/dist/bin/agent-serve.js +3 -2
  4. package/dist/channels/github/api.d.ts +2 -0
  5. package/dist/channels/github/api.d.ts.map +1 -1
  6. package/dist/channels/github/api.js +2 -1
  7. package/dist/channels/github/binding.d.ts +7 -0
  8. package/dist/channels/github/binding.d.ts.map +1 -1
  9. package/dist/channels/github/binding.js +4 -0
  10. package/dist/channels/github/checks.d.ts +99 -0
  11. package/dist/channels/github/checks.d.ts.map +1 -0
  12. package/dist/channels/github/checks.js +108 -0
  13. package/dist/channels/github/cursor-account.d.ts +4 -4
  14. package/dist/channels/github/cursor-account.d.ts.map +1 -1
  15. package/dist/channels/github/cursor-account.js +7 -5
  16. package/dist/channels/github/index.d.ts +1 -0
  17. package/dist/channels/github/index.d.ts.map +1 -1
  18. package/dist/channels/github/index.js +1 -0
  19. package/dist/channels/github/types.d.ts +8 -0
  20. package/dist/channels/github/types.d.ts.map +1 -1
  21. package/dist/channels/slack/manifest.d.ts +2 -2
  22. package/dist/channels/slack/manifest.d.ts.map +1 -1
  23. package/dist/channels/slack/manifest.js +13 -11
  24. package/dist/channels/slack/types.d.ts +2 -2
  25. package/dist/channels/slack/types.d.ts.map +1 -1
  26. package/dist/connections.d.ts +17 -5
  27. package/dist/connections.d.ts.map +1 -1
  28. package/dist/connections.js +17 -5
  29. package/dist/docs/404.html +2 -2
  30. package/dist/docs/ab.html +3 -3
  31. package/dist/docs/assets/{app.C5XUTCw9.js → app.CdbcFD8T.js} +1 -1
  32. package/dist/docs/assets/chunks/@localSearchIndexroot.DQad--_z.js +1 -0
  33. package/dist/docs/assets/chunks/{VPLocalSearchBox.CGDTAYHY.js → VPLocalSearchBox.D_NKImM7.js} +1 -1
  34. package/dist/docs/assets/chunks/{theme.lPixh250.js → theme.CMvz7cu9.js} +2 -2
  35. package/dist/docs/assets/{concepts.md.CqOsxbMU.js → concepts.md.BXAm6G-C.js} +1 -1
  36. package/dist/docs/assets/{guides_mcp-oauth.md.C7G7IykG.js → guides_mcp-oauth.md.CzEB6RaG.js} +1 -1
  37. package/dist/docs/assets/{reference_agent-config.md.DHkkvcEZ.js → reference_agent-config.md.BZnEKfEc.js} +3 -4
  38. package/dist/docs/assets/{reference_agent-config.md.DHkkvcEZ.lean.js → reference_agent-config.md.BZnEKfEc.lean.js} +1 -1
  39. package/dist/docs/assets/{reference_connections.md.Bwswbm6H.js → reference_connections.md.Cu3N-S3Q.js} +18 -11
  40. package/dist/docs/assets/{reference_connections.md.Bwswbm6H.lean.js → reference_connections.md.Cu3N-S3Q.lean.js} +1 -1
  41. package/dist/docs/assets/{reference_sessions.md.DBVFi2Sx.js → reference_sessions.md.B0DdlM-K.js} +1 -1
  42. package/dist/docs/assets/{reference_tools.md.Wmvb7Lob.js → reference_tools.md.DTg_kEsx.js} +1 -1
  43. package/dist/docs/assets/troubleshooting.md.DQ-hYuZT.js +1 -0
  44. package/dist/docs/building-with-agents.html +3 -3
  45. package/dist/docs/concepts.html +5 -5
  46. package/dist/docs/deployment.html +3 -3
  47. package/dist/docs/evals.html +3 -3
  48. package/dist/docs/example-agents/approval-buddy.html +3 -3
  49. package/dist/docs/example-agents/benny.html +3 -3
  50. package/dist/docs/example-agents/bugbot.html +3 -3
  51. package/dist/docs/example-agents/codebase-wiki.html +3 -3
  52. package/dist/docs/example-agents/codeowners-review.html +3 -3
  53. package/dist/docs/example-agents/concierge.html +3 -3
  54. package/dist/docs/example-agents/fsd.html +3 -3
  55. package/dist/docs/example-agents/index.html +3 -3
  56. package/dist/docs/example-agents/knowledge-base.html +3 -3
  57. package/dist/docs/example-agents/oncall.html +3 -3
  58. package/dist/docs/example-agents/security-reviewer.html +3 -3
  59. package/dist/docs/example-agents/slack-agent.html +3 -3
  60. package/dist/docs/example-agents/weather-agent.html +3 -3
  61. package/dist/docs/guides/agent-to-agent.html +3 -3
  62. package/dist/docs/guides/cloud-runtime.html +3 -3
  63. package/dist/docs/guides/convert-automation.html +3 -3
  64. package/dist/docs/guides/github.html +3 -3
  65. package/dist/docs/guides/human-in-the-loop.html +3 -3
  66. package/dist/docs/guides/mcp-oauth.html +5 -5
  67. package/dist/docs/guides/opentelemetry.html +3 -3
  68. package/dist/docs/guides/slack.html +3 -3
  69. package/dist/docs/guides/webhooks.html +3 -3
  70. package/dist/docs/hashmap.json +1 -1
  71. package/dist/docs/hillclimbing.html +3 -3
  72. package/dist/docs/index.html +3 -3
  73. package/dist/docs/quickstart.html +3 -3
  74. package/dist/docs/reference/agent-config.html +5 -6
  75. package/dist/docs/reference/artifacts.html +3 -3
  76. package/dist/docs/reference/channels.html +3 -3
  77. package/dist/docs/reference/cli.html +3 -3
  78. package/dist/docs/reference/connections.html +20 -13
  79. package/dist/docs/reference/hooks.html +3 -3
  80. package/dist/docs/reference/http-api.html +3 -3
  81. package/dist/docs/reference/instructions.html +3 -3
  82. package/dist/docs/reference/playground.html +3 -3
  83. package/dist/docs/reference/project-layout.html +3 -3
  84. package/dist/docs/reference/prompt.html +3 -3
  85. package/dist/docs/reference/schedules.html +3 -3
  86. package/dist/docs/reference/sessions.html +5 -5
  87. package/dist/docs/reference/skills.html +3 -3
  88. package/dist/docs/reference/subagents.html +3 -3
  89. package/dist/docs/reference/tools.html +5 -5
  90. package/dist/docs/scaffolding-agents.html +3 -3
  91. package/dist/docs/storage.html +3 -3
  92. package/dist/docs/templates/agentic-owners.html +3 -3
  93. package/dist/docs/templates/demo.html +3 -3
  94. package/dist/docs/templates/pr-autofixer.html +3 -3
  95. package/dist/docs/templates/security-reviewer.html +3 -3
  96. package/dist/docs/templates/triage.html +3 -3
  97. package/dist/docs/troubleshooting.html +5 -5
  98. package/dist/internal/advertise-tools.d.ts +11 -6
  99. package/dist/internal/advertise-tools.d.ts.map +1 -1
  100. package/dist/internal/advertise-tools.js +63 -30
  101. package/dist/internal/cli-deploy.d.ts.map +1 -1
  102. package/dist/internal/cli-deploy.js +2 -4
  103. package/dist/internal/convert-automation/convert-workflow.d.ts.map +1 -1
  104. package/dist/internal/convert-automation/convert-workflow.js +2 -10
  105. package/dist/internal/cursor/account-mcp.d.ts +29 -3
  106. package/dist/internal/cursor/account-mcp.d.ts.map +1 -1
  107. package/dist/internal/cursor/account-mcp.js +147 -67
  108. package/dist/internal/cursor/backend-client.d.ts +11 -6
  109. package/dist/internal/cursor/backend-client.d.ts.map +1 -1
  110. package/dist/internal/cursor/backend-client.js +32 -10
  111. package/dist/internal/cursor-account-mcp-auth.d.ts +11 -0
  112. package/dist/internal/cursor-account-mcp-auth.d.ts.map +1 -1
  113. package/dist/internal/cursor-account-mcp-auth.js +69 -0
  114. package/dist/internal/deploy-client.d.ts +0 -7
  115. package/dist/internal/deploy-client.d.ts.map +1 -1
  116. package/dist/internal/deploy-client.js +2 -4
  117. package/dist/internal/deploy-manifest.d.ts +15 -24
  118. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  119. package/dist/internal/deploy-manifest.js +38 -27
  120. package/dist/internal/deployment-scm-event-stream.d.ts +4 -1
  121. package/dist/internal/deployment-scm-event-stream.d.ts.map +1 -1
  122. package/dist/internal/deployment-scm-event-stream.js +15 -1
  123. package/dist/internal/discovery.d.ts.map +1 -1
  124. package/dist/internal/discovery.js +42 -10
  125. package/dist/internal/init-project.d.ts.map +1 -1
  126. package/dist/internal/init-project.js +7 -106
  127. package/dist/internal/init-scaffold.d.ts +8 -0
  128. package/dist/internal/init-scaffold.d.ts.map +1 -0
  129. package/dist/internal/init-scaffold.js +168 -0
  130. package/dist/internal/inline-stdio-mcp.d.ts +2 -0
  131. package/dist/internal/inline-stdio-mcp.d.ts.map +1 -1
  132. package/dist/internal/inline-stdio-mcp.js +10 -8
  133. package/dist/internal/json-schema.d.ts +7 -0
  134. package/dist/internal/json-schema.d.ts.map +1 -1
  135. package/dist/internal/json-schema.js +18 -3
  136. package/dist/internal/mcp-endpoint.js +7 -7
  137. package/dist/internal/mcp-host.js +4 -2
  138. package/dist/internal/mcp-oauth.d.ts +22 -0
  139. package/dist/internal/mcp-oauth.d.ts.map +1 -1
  140. package/dist/internal/mcp-oauth.js +40 -1
  141. package/dist/internal/package-inline-stdio.d.ts.map +1 -1
  142. package/dist/internal/package-inline-stdio.js +5 -5
  143. package/dist/internal/review-comments.d.ts +97 -0
  144. package/dist/internal/review-comments.d.ts.map +1 -1
  145. package/dist/internal/review-comments.js +151 -0
  146. package/dist/internal/sanitize-mcp-tool-name.d.ts +20 -0
  147. package/dist/internal/sanitize-mcp-tool-name.d.ts.map +1 -0
  148. package/dist/internal/sanitize-mcp-tool-name.js +30 -0
  149. package/dist/internal/session-engine.d.ts.map +1 -1
  150. package/dist/internal/session-engine.js +4 -6
  151. package/dist/internal/shallow-clone.d.ts +94 -39
  152. package/dist/internal/shallow-clone.d.ts.map +1 -1
  153. package/dist/internal/shallow-clone.js +188 -68
  154. package/dist/internal/terminal-style.d.ts +18 -0
  155. package/dist/internal/terminal-style.d.ts.map +1 -1
  156. package/dist/internal/terminal-style.js +46 -1
  157. package/dist/internal/workspace.d.ts +2 -0
  158. package/dist/internal/workspace.d.ts.map +1 -1
  159. package/dist/internal/workspace.js +5 -0
  160. package/dist/playground/assets/index-77uhu5Kr.css +1 -0
  161. package/dist/playground/assets/{index-yxs1heea.js → index-D4buox4m.js} +42 -42
  162. package/dist/playground/index.html +2 -2
  163. package/dist/tools.d.ts +7 -0
  164. package/dist/tools.d.ts.map +1 -1
  165. package/dist/types.d.ts +28 -3
  166. package/dist/types.d.ts.map +1 -1
  167. package/docs/concepts.md +4 -4
  168. package/docs/guides/mcp-oauth.md +3 -1
  169. package/docs/reference/agent-config.md +11 -12
  170. package/docs/reference/connections.md +44 -26
  171. package/docs/reference/sessions.md +2 -2
  172. package/docs/reference/tools.md +1 -1
  173. package/docs/troubleshooting.md +3 -2
  174. package/package.json +4 -1
  175. package/skills/create-agent/SKILL.md +12 -9
  176. package/skills/debug/SKILL.md +2 -1
  177. package/skills/framework-map/SKILL.md +6 -6
  178. package/skills/mcp-auth/SKILL.md +8 -6
  179. package/src/bin/agent-serve.ts +3 -2
  180. package/src/channels/github/api.ts +6 -1
  181. package/src/channels/github/binding.ts +21 -0
  182. package/src/channels/github/checks.ts +179 -0
  183. package/src/channels/github/cursor-account.ts +9 -6
  184. package/src/channels/github/index.ts +1 -0
  185. package/src/channels/github/types.ts +8 -0
  186. package/src/channels/slack/manifest.ts +8 -10
  187. package/src/channels/slack/types.ts +2 -2
  188. package/src/connections.ts +17 -5
  189. package/src/internal/advertise-tools.ts +72 -23
  190. package/src/internal/cli-deploy.ts +4 -15
  191. package/src/internal/convert-automation/convert-workflow.ts +2 -11
  192. package/src/internal/cursor/account-mcp.ts +208 -73
  193. package/src/internal/cursor/backend-client.ts +45 -11
  194. package/src/internal/cursor-account-mcp-auth.ts +83 -0
  195. package/src/internal/deploy-client.ts +0 -10
  196. package/src/internal/deploy-manifest.ts +33 -39
  197. package/src/internal/deployment-scm-event-stream.ts +17 -1
  198. package/src/internal/discovery.ts +47 -3
  199. package/src/internal/init-project.ts +7 -133
  200. package/src/internal/init-scaffold.ts +176 -0
  201. package/src/internal/inline-stdio-mcp.ts +13 -0
  202. package/src/internal/json-schema.ts +24 -3
  203. package/src/internal/mcp-endpoint.ts +6 -0
  204. package/src/internal/mcp-host.ts +4 -0
  205. package/src/internal/mcp-oauth.ts +55 -1
  206. package/src/internal/package-inline-stdio.ts +5 -1
  207. package/src/internal/review-comments.ts +245 -0
  208. package/src/internal/sanitize-mcp-tool-name.ts +33 -0
  209. package/src/internal/session-engine.ts +7 -0
  210. package/src/internal/shallow-clone.ts +293 -105
  211. package/src/internal/terminal-style.ts +67 -1
  212. package/src/internal/workspace.ts +6 -0
  213. package/src/tools.ts +7 -0
  214. package/src/types.ts +32 -4
  215. package/templates/agentic-owners/agent/agent.ts +3 -0
  216. package/templates/demo/agent/agent.ts +3 -0
  217. package/templates/security-reviewer/agent/agent.ts +3 -0
  218. package/templates/triage/agent/agent.ts +3 -0
  219. package/dist/docs/assets/chunks/@localSearchIndexroot.DvUR3lv9.js +0 -1
  220. package/dist/docs/assets/troubleshooting.md.CuVztCKs.js +0 -1
  221. package/dist/playground/assets/index-CoL7xCJl.css +0 -1
  222. /package/dist/docs/assets/{concepts.md.CqOsxbMU.lean.js → concepts.md.BXAm6G-C.lean.js} +0 -0
  223. /package/dist/docs/assets/{guides_mcp-oauth.md.C7G7IykG.lean.js → guides_mcp-oauth.md.CzEB6RaG.lean.js} +0 -0
  224. /package/dist/docs/assets/{reference_sessions.md.DBVFi2Sx.lean.js → reference_sessions.md.B0DdlM-K.lean.js} +0 -0
  225. /package/dist/docs/assets/{reference_tools.md.Wmvb7Lob.lean.js → reference_tools.md.DTg_kEsx.lean.js} +0 -0
  226. /package/dist/docs/assets/{troubleshooting.md.CuVztCKs.lean.js → troubleshooting.md.DQ-hYuZT.lean.js} +0 -0
package/dist/docs/concepts.html CHANGED
@@ -9,20 +9,20 @@
9
9
  <link rel="preload stylesheet" href="/docs/assets/style.kTsvp4pE.css" as="style">
10
10
  <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/docs/assets/app.C5XUTCw9.js"></script>
12
+ <script type="module" src="/docs/assets/app.CdbcFD8T.js"></script>
13
13
  <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/docs/assets/chunks/theme.lPixh250.js">
14
+ <link rel="modulepreload" href="/docs/assets/chunks/theme.CMvz7cu9.js">
15
15
  <link rel="modulepreload" href="/docs/assets/chunks/framework.CAZyNGu9.js">
16
- <link rel="modulepreload" href="/docs/assets/concepts.md.CqOsxbMU.lean.js">
16
+ <link rel="modulepreload" href="/docs/assets/concepts.md.BXAm6G-C.lean.js">
17
17
  <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>
18
18
  <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
19
19
  </head>
20
20
  <body>
21
- <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><!--[--><!--]--></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 and seeded files</td><td>Added to the session workspace</td><td>Must exist in the cloud repository</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. If your agent lives inside a large monorepo, set <code>defineAgent({ local: { cwd } })</code> to a clean directory or pass a separate <code>--state-root</code>. The <code>run</code> and <code>eval</code> commands already use temporary state.</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>
21
+ <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><!--[--><!--]--></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 and seeded files</td><td>Added to the session workspace</td><td>Must exist in the cloud repository</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>
22
22
  <span class="line"><span> sessions/&lt;id&gt;/events.ndjson</span></span>
23
23
  <span class="line"><span> sessions/&lt;id&gt;/workspace/</span></span>
24
24
  <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>
25
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"ZeGEpAw_\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"DBL1TwtP\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_convert-automation.md\":\"BhMzTkE5\",\"guides_github.md\":\"CLLQJKRB\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"DP4H75WP\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"DhRHS_-L\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"DHkkvcEZ\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"Cl14Jfo3\",\"reference_connections.md\":\"Bwswbm6H\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"Wmvb7Lob\",\"scaffolding-agents.md\":\"CrWSA0Ko\",\"storage.md\":\"D8NQ389l\",\"templates_agentic-owners.md\":\"BkTLORaU\",\"templates_demo.md\":\"Bgd6MBaZ\",\"templates_pr-autofixer.md\":\"DcmoeUNZ\",\"templates_security-reviewer.md\":\"C0yIUaYs\",\"templates_triage.md\":\"DWuQ1bZz\",\"troubleshooting.md\":\"CuVztCKs\"}");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\":{\"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>
25
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"BXAm6G-C\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"ZeGEpAw_\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"DBL1TwtP\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_convert-automation.md\":\"BhMzTkE5\",\"guides_github.md\":\"CLLQJKRB\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"CzEB6RaG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"DP4H75WP\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"DhRHS_-L\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"BZnEKfEc\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"Cl14Jfo3\",\"reference_connections.md\":\"Cu3N-S3Q\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"B0DdlM-K\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"DTg_kEsx\",\"scaffolding-agents.md\":\"CrWSA0Ko\",\"storage.md\":\"D8NQ389l\",\"templates_agentic-owners.md\":\"BkTLORaU\",\"templates_demo.md\":\"Bgd6MBaZ\",\"templates_pr-autofixer.md\":\"DcmoeUNZ\",\"templates_security-reviewer.md\":\"C0yIUaYs\",\"templates_triage.md\":\"DWuQ1bZz\",\"troubleshooting.md\":\"DQ-hYuZT\"}");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\":{\"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>
26
26
 
27
27
  </body>
28
28
  </html>
package/dist/docs/deployment.html CHANGED
@@ -9,9 +9,9 @@
9
9
  <link rel="preload stylesheet" href="/docs/assets/style.kTsvp4pE.css" as="style">
10
10
  <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/docs/assets/app.C5XUTCw9.js"></script>
12
+ <script type="module" src="/docs/assets/app.CdbcFD8T.js"></script>
13
13
  <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/docs/assets/chunks/theme.lPixh250.js">
14
+ <link rel="modulepreload" href="/docs/assets/chunks/theme.CMvz7cu9.js">
15
15
  <link rel="modulepreload" href="/docs/assets/chunks/framework.CAZyNGu9.js">
16
16
  <link rel="modulepreload" href="/docs/assets/deployment.md.B8kW-h7P.lean.js">
17
17
  <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>
@@ -73,7 +73,7 @@
73
73
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --state-root</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /var/lib/agent-serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \</span></span>
74
74
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --bearer-token</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_SDK_BEARER_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span></span></code></pre></div><p>Mount the state root as a persistent volume and inject secrets at startup. Install <code>git</code> and <code>gh</code> when channels need host-side GitHub work. Don&#39;t put secrets in the image.</p><h3 id="serve-many-agents-from-one-process" tabindex="-1">Serve many agents from one process <a class="header-anchor" href="#serve-many-agents-from-one-process" aria-label="Permalink to &quot;Serve many agents from one process&quot;">​</a></h3><p>Point <code>serve</code> at a folder of agent projects and every child mounts under its directory name on one port. One process, one state root, one credential:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> /srv/agents</span></span>
75
75
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># index at /, each agent at /&lt;slug&gt;/v1/*, /&lt;slug&gt;/playground</span></span></code></pre></div><p>Only mount what you mean to run. Every mounted agent&#39;s channels are live, and webhook-driven agents spend model budget on every wake. <code>--mode single</code> serves exactly one agent at the unslugged <code>/v1/*</code> when the agent is the whole host. See the <a href="./reference/http-api.html">HTTP API</a> for route layout and the <a href="./guides/slack.html">Slack guide</a> for multi-agent token setup.</p><h3 id="the-production-flags" tabindex="-1">The production flags <a class="header-anchor" href="#the-production-flags" aria-label="Permalink to &quot;The production flags&quot;">​</a></h3><p>Use these settings in production:</p><table tabindex="0"><thead><tr><th>Flag</th><th>In production</th></tr></thead><tbody><tr><td><code>--dev</code></td><td>Leave off. Dev mode admits unsigned loopback GitHub deliveries, widens playground session listing on loopback, and never auto-fires schedules.</td></tr><tr><td><code>--bearer-token</code></td><td>Set on shared hosts unless an authenticating proxy is the trust boundary and you use <code>--allow-anonymous</code> instead.</td></tr><tr><td><code>--allow-anonymous</code></td><td>Use only behind an authenticating network boundary. It also widens playground session access so Slack and webhook sessions appear.</td></tr><tr><td><code>--state-root</code></td><td>Place on a persistent volume outside any repo.</td></tr><tr><td><code>--public-url</code></td><td>Set when cloud-runtime turns must call back into peers on this host.</td></tr><tr><td><code>--no-playground</code></td><td>Set when no human needs the UI.</td></tr><tr><td><code>--no-docs</code></td><td>Set to remove the documentation site at <code>/docs</code>.</td></tr><tr><td><code>--no-schedules</code></td><td>Set on secondary hosts so schedules run exactly once.</td></tr></tbody></table><p>Schedules fire on their cron cadence (UTC) in production mode. They have no cross-host coordination, so enable them on exactly one serving process per project.</p><h3 id="restarts-and-upgrades" tabindex="-1">Restarts and upgrades <a class="header-anchor" href="#restarts-and-upgrades" aria-label="Permalink to &quot;Restarts and upgrades&quot;">​</a></h3><p>Restarts preserve sessions, event streams, and SDK conversation state under the state root. Parked approvals and in-memory reminders don&#39;t survive a restart; re-run or recreate them afterward.</p><h3 id="observability" tabindex="-1">Observability <a class="header-anchor" href="#observability" aria-label="Permalink to &quot;Observability&quot;">​</a></h3><p>Use <a href="./reference/cli.html#logs"><code>agent-sdk logs</code></a> for runtime output, <a href="./guides/opentelemetry.html">OpenTelemetry</a> for OTLP traces and metrics, <a href="./reference/hooks.html">hooks</a> for in-process subscribers, and <a href="./reference/sessions.html#how-do-i-inspect-a-saved-event-stream">session traces</a> for incident review.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./reference/cli.html#deploy">CLI reference</a>: deploy, inspect, stop, and rotate hosted agents</li><li><a href="./storage.html">Storage</a>: preserve supported records across engine replacements</li><li><a href="./reference/channels.html#auth-policies">Channels</a>: the auth policies in detail</li><li><a href="./guides/github.html">GitHub guide</a>: delivery paths without a public URL</li><li><a href="./troubleshooting.html">Troubleshooting</a>: the symptom table for when a deploy misbehaves</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/example-agents/codeowners-review.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Previous page</span><span class="title" data-v-574f06fa>Codeowners review</span><!--]--></a></div><div class="pager" data-v-574f06fa><a class="VPLink link pager-link next" href="/docs/troubleshooting.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Next page</span><span class="title" data-v-574f06fa>Fix common problems</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
76
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"ZeGEpAw_\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"DBL1TwtP\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_convert-automation.md\":\"BhMzTkE5\",\"guides_github.md\":\"CLLQJKRB\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"DP4H75WP\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"DhRHS_-L\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"DHkkvcEZ\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"Cl14Jfo3\",\"reference_connections.md\":\"Bwswbm6H\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"Wmvb7Lob\",\"scaffolding-agents.md\":\"CrWSA0Ko\",\"storage.md\":\"D8NQ389l\",\"templates_agentic-owners.md\":\"BkTLORaU\",\"templates_demo.md\":\"Bgd6MBaZ\",\"templates_pr-autofixer.md\":\"DcmoeUNZ\",\"templates_security-reviewer.md\":\"C0yIUaYs\",\"templates_triage.md\":\"DWuQ1bZz\",\"troubleshooting.md\":\"CuVztCKs\"}");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\":{\"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>
76
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"BXAm6G-C\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"ZeGEpAw_\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"DBL1TwtP\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_convert-automation.md\":\"BhMzTkE5\",\"guides_github.md\":\"CLLQJKRB\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"CzEB6RaG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"DP4H75WP\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"DhRHS_-L\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"BZnEKfEc\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"Cl14Jfo3\",\"reference_connections.md\":\"Cu3N-S3Q\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"B0DdlM-K\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"DTg_kEsx\",\"scaffolding-agents.md\":\"CrWSA0Ko\",\"storage.md\":\"D8NQ389l\",\"templates_agentic-owners.md\":\"BkTLORaU\",\"templates_demo.md\":\"Bgd6MBaZ\",\"templates_pr-autofixer.md\":\"DcmoeUNZ\",\"templates_security-reviewer.md\":\"C0yIUaYs\",\"templates_triage.md\":\"DWuQ1bZz\",\"troubleshooting.md\":\"DQ-hYuZT\"}");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\":{\"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>
77
77
 
78
78
  </body>
79
79
  </html>
package/dist/docs/evals.html CHANGED
@@ -9,9 +9,9 @@
9
9
  <link rel="preload stylesheet" href="/docs/assets/style.kTsvp4pE.css" as="style">
10
10
  <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/docs/assets/app.C5XUTCw9.js"></script>
12
+ <script type="module" src="/docs/assets/app.CdbcFD8T.js"></script>
13
13
  <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
- <link rel="modulepreload" href="/docs/assets/chunks/theme.lPixh250.js">
14
+ <link rel="modulepreload" href="/docs/assets/chunks/theme.CMvz7cu9.js">
15
15
  <link rel="modulepreload" href="/docs/assets/chunks/framework.CAZyNGu9.js">
16
16
  <link rel="modulepreload" href="/docs/assets/evals.md.CVe_O75-.lean.js">
17
17
  <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>
@@ -103,7 +103,7 @@
103
103
  <span class="line"></span>
104
104
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> cancel</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> evalrun_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> vulnerability-scanner</span></span>
105
105
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> eval</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> status</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> evalrun_…</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> vulnerability-scanner</span></span></code></pre></div><p>The Evals tab prefers the server’s in-flight batch (<code>activeRunId</code>) over a stale tab-local remembered id, so CLI / Slack kicks show up without an incognito window.</p><h2 id="what-good-cases-assert" tabindex="-1">What good cases assert <a class="header-anchor" href="#what-good-cases-assert" aria-label="Permalink to &quot;What good cases assert&quot;">​</a></h2><p>Gate decisions and shape, not prose. Model wording varies run to run. Tool choice, tool avoidance, and output structure are the stable contract.</p><ol><li><code>t.succeeded()</code>: always, first.</li><li>The tool decision: <code>calledTool</code> for the intended path, <code>notCalledTool</code> for the likely wrong alternative. The pair is stronger than either alone.</li><li>Output shape: a regex for the contract (<code>/ready|blocked/i</code>, a JSON marker, a findings-block fence), never exact sentences.</li><li>For structured output, parse <code>t.reply</code> and check fields with <code>satisfies</code> instead of substring-matching JSON.</li></ol><p>The common failure modes: asserting exact phrasing, packing more than about five gates into one case (split it), and cases that depend on live external state that drifts (pin the input; see fixtures).</p><h2 id="pick-fixtures-by-agent-type" tabindex="-1">Pick fixtures by agent type <a class="header-anchor" href="#pick-fixtures-by-agent-type" aria-label="Permalink to &quot;Pick fixtures by agent type&quot;">​</a></h2><p>The right fixture depends on the surface under test.</p><table tabindex="0"><thead><tr><th>Agent surface</th><th>Fixture</th></tr></thead><tbody><tr><td>Chat / domain assistant</td><td>A canonical prompt string, chosen once and frozen</td></tr><tr><td>Tool-heavy</td><td>Run <code>agent-sdk call &lt;tool&gt;</code> first to pin what the tool returns, then freeze the prompt that triggers it</td></tr><tr><td>GitHub webhook</td><td><code>agent-sdk github replay &lt;pr&gt; --events &#39;*&#39; --dry-run --out fixtures/github</code> snapshots real payloads for offline replay (<a href="./guides/github.html">GitHub guide</a>)</td></tr><tr><td>PR reviewer with host preparation</td><td>Diff, metadata, and gold labels pinned to commit SHAs; keep any live PR matrix small</td></tr><tr><td>Workspace-dependent</td><td><code>workspaceFiles</code> in <code>t.send</code> options, never developer-machine paths</td></tr></tbody></table><p>Tag the fast, reliably passing core <code>smoke</code> and run <code>--tag smoke</code> in the inner loop. Leave slow or flaky-prone cases untagged for explicit runs.</p><h3 id="materialize-api-backed-fixtures" tabindex="-1">Materialize API-backed fixtures <a class="header-anchor" href="#materialize-api-backed-fixtures" aria-label="Permalink to &quot;Materialize API-backed fixtures&quot;">​</a></h3><p>An input that only points at external data, such as a pull request URL, snapshot id, or pair of commit SHAs, is not self-contained. Fetch it once and commit the rendered fixture before you expand the suite.</p><ol><li>Save the diff, metadata, and labels under <code>fixtures/</code> at pinned revisions.</li><li>Seed those files with <code>workspaceFiles</code>, or read them from the fixture directory.</li><li>Assert decisions and output shape against the saved evidence.</li><li>Keep a small <code>smoke</code> subset for any remaining live pipeline checks.</li></ol><p>Read committed fixtures with <code>@cursor/july/evals/loaders</code>: <code>loadJson</code>, <code>loadJsonl</code>, and <code>loadYaml</code> resolve relative paths against the project root the runner discovered, not the cwd the CLI was invoked from (<code>resolveFixturePath</code> and <code>evalFixtureRoot</code> expose the same resolution for other file formats).</p><p><code>maxConcurrency</code> limits parallel datapoints. It does not limit model or API fan-out inside one datapoint. Materialized fixtures prevent a large suite from exhausting provider and GitHub rate limits. The <a href="./../skills/evals/SKILL.html">evals skill</a> has the full fixture workflow.</p><h2 id="keep-improvements-with-regression-evals" tabindex="-1">Keep improvements with regression evals <a class="header-anchor" href="#keep-improvements-with-regression-evals" aria-label="Permalink to &quot;Keep improvements with regression evals&quot;">​</a></h2><p>Every <a href="./hillclimbing.html">hillclimb</a> round that keeps a change must land an eval that would have failed before the change. If you can&#39;t express the improvement as a gate (a <code>calledTool</code> shift, a bounded <code>action.result</code> count, an output-shape regex), the improvement is unverified, and it&#39;ll regress silently.</p><p>The rule cuts the other way too: never weaken an existing gate to make a round pass. That&#39;s the freeze line moving, and it turns your regression suite into a list of checks that no longer protect anything.</p><h2 id="compare-variants-on-live-traffic" tabindex="-1">Compare variants on live traffic <a class="header-anchor" href="#compare-variants-on-live-traffic" aria-label="Permalink to &quot;Compare variants on live traffic&quot;">​</a></h2><p>Use <code>defineAB</code> to compare variant metrics on live sessions. It is not a test runner and has no <code>agent-sdk ab</code> command. Keep <code>defineEval</code> as the regression ratchet. Eval sessions do not enroll or change live metrics. See <a href="./ab.html">Live A/B metrics</a> for assignment, behavior, collection, and inspection.</p><h2 id="what-s-next" tabindex="-1">What&#39;s next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to &quot;What&#39;s next&quot;">​</a></h2><p>Continue with these pages:</p><ul><li><a href="./ab.html">Live A/B metrics</a>: sticky variants and cumulative metrics on live sessions</li><li><a href="./hillclimbing.html">Hillclimbing</a>: the loop evals make trustworthy</li><li><a href="./building-with-agents.html">Building agents with agents</a>: have a coding agent write the first suite</li><li><a href="./guides/github.html">GitHub guide</a>: deterministic webhook fixtures with <code>github replay</code></li><li><a href="./reference/sessions.html">Sessions and streaming</a>: the events <code>t.events</code> contains</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/building-with-agents.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Previous page</span><span class="title" data-v-574f06fa>Building agents with agents</span><!--]--></a></div><div class="pager" data-v-574f06fa><a class="VPLink link pager-link next" href="/docs/ab.html" data-v-574f06fa><!--[--><span class="desc" data-v-574f06fa>Next page</span><span class="title" data-v-574f06fa>Live A/B metrics</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
106
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"ZeGEpAw_\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"DBL1TwtP\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_convert-automation.md\":\"BhMzTkE5\",\"guides_github.md\":\"CLLQJKRB\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"DP4H75WP\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"DhRHS_-L\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"DHkkvcEZ\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"Cl14Jfo3\",\"reference_connections.md\":\"Bwswbm6H\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"DBVFi2Sx\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"Wmvb7Lob\",\"scaffolding-agents.md\":\"CrWSA0Ko\",\"storage.md\":\"D8NQ389l\",\"templates_agentic-owners.md\":\"BkTLORaU\",\"templates_demo.md\":\"Bgd6MBaZ\",\"templates_pr-autofixer.md\":\"DcmoeUNZ\",\"templates_security-reviewer.md\":\"C0yIUaYs\",\"templates_triage.md\":\"DWuQ1bZz\",\"troubleshooting.md\":\"CuVztCKs\"}");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\":{\"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>
106
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"DYjwREAP\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"BXAm6G-C\",\"deployment.md\":\"B8kW-h7P\",\"evals.md\":\"CVe_O75-\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"B-LIDGja\",\"example-agents_bugbot.md\":\"Dp5JqHSQ\",\"example-agents_codebase-wiki.md\":\"D-lteFf0\",\"example-agents_codeowners-review.md\":\"BU2ZXLf-\",\"example-agents_concierge.md\":\"DA2al_NK\",\"example-agents_fsd.md\":\"ZeGEpAw_\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"CBmyuAKc\",\"example-agents_security-reviewer.md\":\"DBL1TwtP\",\"example-agents_slack-agent.md\":\"06jQXTAI\",\"example-agents_weather-agent.md\":\"DC3lINjo\",\"guides_agent-to-agent.md\":\"Bmbxy-FA\",\"guides_cloud-runtime.md\":\"V5igN4Sq\",\"guides_convert-automation.md\":\"BhMzTkE5\",\"guides_github.md\":\"CLLQJKRB\",\"guides_human-in-the-loop.md\":\"Cf8kIIqC\",\"guides_mcp-oauth.md\":\"CzEB6RaG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"DP4H75WP\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"DhRHS_-L\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"BZnEKfEc\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"Cl14Jfo3\",\"reference_connections.md\":\"Cu3N-S3Q\",\"reference_hooks.md\":\"DJE5DXcT\",\"reference_http-api.md\":\"DMbdFGVQ\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"D3MdHM2z\",\"reference_prompt.md\":\"BaiweQxE\",\"reference_schedules.md\":\"gmfYzf_I\",\"reference_sessions.md\":\"B0DdlM-K\",\"reference_skills.md\":\"B_jHN7JL\",\"reference_subagents.md\":\"DSrGLIuB\",\"reference_tools.md\":\"DTg_kEsx\",\"scaffolding-agents.md\":\"CrWSA0Ko\",\"storage.md\":\"D8NQ389l\",\"templates_agentic-owners.md\":\"BkTLORaU\",\"templates_demo.md\":\"Bgd6MBaZ\",\"templates_pr-autofixer.md\":\"DcmoeUNZ\",\"templates_security-reviewer.md\":\"C0yIUaYs\",\"templates_triage.md\":\"DWuQ1bZz\",\"troubleshooting.md\":\"DQ-hYuZT\"}");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\":{\"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>
107
107
 
108
108
  </body>
109
109
  </html>