@cursor/july 0.1.42 → 0.1.45

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 (223) hide show
  1. package/AGENTS.md +1 -0
  2. package/dist/bin/agent-serve.js +3 -1
  3. package/dist/channels/github/api.d.ts +5 -0
  4. package/dist/channels/github/api.d.ts.map +1 -1
  5. package/dist/channels/github/api.js +18 -0
  6. package/dist/channels/github/defaults.d.ts +4 -5
  7. package/dist/channels/github/defaults.d.ts.map +1 -1
  8. package/dist/channels/github/defaults.js +27 -1
  9. package/dist/channels/github/github-channel.d.ts.map +1 -1
  10. package/dist/channels/github/github-channel.js +41 -10
  11. package/dist/channels/github/index.d.ts +1 -0
  12. package/dist/channels/github/index.d.ts.map +1 -1
  13. package/dist/channels/github/index.js +1 -0
  14. package/dist/channels/github/progress.d.ts +54 -0
  15. package/dist/channels/github/progress.d.ts.map +1 -0
  16. package/dist/channels/github/progress.js +168 -0
  17. package/dist/channels/github/state.d.ts +2 -0
  18. package/dist/channels/github/state.d.ts.map +1 -1
  19. package/dist/channels/github/state.js +1 -1
  20. package/dist/channels/github/types.d.ts +16 -4
  21. package/dist/channels/github/types.d.ts.map +1 -1
  22. package/dist/channels/slack/slack-channel.d.ts +4 -0
  23. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  24. package/dist/channels/slack/slack-channel.js +4 -0
  25. package/dist/channels.d.ts +17 -0
  26. package/dist/channels.d.ts.map +1 -1
  27. package/dist/channels.js +31 -0
  28. package/dist/docs/404.html +2 -2
  29. package/dist/docs/ab.html +4 -4
  30. package/dist/docs/assets/{app.C4-Gwi7g.js → app.fHnNXEJ6.js} +1 -1
  31. package/dist/docs/assets/chunks/@localSearchIndexroot.BMT0xM4I.js +1 -0
  32. package/dist/docs/assets/chunks/{VPLocalSearchBox.DDoLm843.js → VPLocalSearchBox.Cf6ghfFY.js} +1 -1
  33. package/dist/docs/assets/chunks/{theme.SbjGIiM0.js → theme.B_5-VLe8.js} +2 -2
  34. package/dist/docs/assets/{deployment.md.BHVjVqRa.js → deployment.md.Cdp4rTE4.js} +1 -1
  35. package/dist/docs/assets/{guides_github.md.R2QlpR75.js → guides_github.md.DSg0j9qj.js} +29 -3
  36. package/dist/docs/assets/{guides_github.md.R2QlpR75.lean.js → guides_github.md.DSg0j9qj.lean.js} +1 -1
  37. package/dist/docs/assets/guides_opentelemetry.md.Csn7ZI25.js +27 -0
  38. package/dist/docs/assets/guides_opentelemetry.md.Csn7ZI25.lean.js +1 -0
  39. package/dist/docs/assets/index.md.COeoSkcF.js +5 -0
  40. package/dist/docs/assets/index.md.COeoSkcF.lean.js +1 -0
  41. package/dist/docs/assets/{quickstart.md.rIbfahJM.js → quickstart.md.DZxBu44y.js} +18 -49
  42. package/dist/docs/assets/quickstart.md.DZxBu44y.lean.js +1 -0
  43. package/dist/docs/assets/{reference_agent-config.md.CRmkoxd6.js → reference_agent-config.md.XRpxctsA.js} +9 -4
  44. package/dist/docs/assets/{reference_agent-config.md.CRmkoxd6.lean.js → reference_agent-config.md.XRpxctsA.lean.js} +1 -1
  45. package/dist/docs/assets/{reference_channels.md.BIabFUAI.js → reference_channels.md.MN8iDy8V.js} +1 -1
  46. package/dist/docs/assets/{reference_cli.md.DqEqQpGn.js → reference_cli.md.BDmjPPAm.js} +2 -2
  47. package/dist/docs/assets/{reference_hooks.md.B40QAG6m.js → reference_hooks.md.4cbRRIIu.js} +2 -2
  48. package/dist/docs/assets/{reference_hooks.md.B40QAG6m.lean.js → reference_hooks.md.4cbRRIIu.lean.js} +1 -1
  49. package/dist/docs/assets/{reference_project-layout.md._XdeMahr.js → reference_project-layout.md.D3MdHM2z.js} +2 -1
  50. package/dist/docs/assets/{reference_tools.md.lSrsTxYJ.js → reference_tools.md.kJfJAP2m.js} +1 -1
  51. package/dist/docs/assets/templates_triage.md.CConZt1z.js +11 -0
  52. package/dist/docs/assets/templates_triage.md.CConZt1z.lean.js +1 -0
  53. package/dist/docs/building-with-agents.html +5 -5
  54. package/dist/docs/concepts.html +5 -5
  55. package/dist/docs/deployment.html +6 -6
  56. package/dist/docs/evals.html +4 -4
  57. package/dist/docs/example-agents/approval-buddy.html +4 -4
  58. package/dist/docs/example-agents/benny.html +4 -4
  59. package/dist/docs/example-agents/bugbot.html +4 -4
  60. package/dist/docs/example-agents/codebase-wiki.html +4 -4
  61. package/dist/docs/example-agents/codeowners-review.html +4 -4
  62. package/dist/docs/example-agents/concierge.html +4 -4
  63. package/dist/docs/example-agents/fsd.html +4 -4
  64. package/dist/docs/example-agents/index.html +5 -5
  65. package/dist/docs/example-agents/knowledge-base.html +4 -4
  66. package/dist/docs/example-agents/oncall.html +4 -4
  67. package/dist/docs/example-agents/security-reviewer.html +4 -4
  68. package/dist/docs/example-agents/slack-agent.html +4 -4
  69. package/dist/docs/example-agents/weather-agent.html +4 -4
  70. package/dist/docs/guides/agent-to-agent.html +4 -4
  71. package/dist/docs/guides/cloud-runtime.html +5 -5
  72. package/dist/docs/guides/github.html +33 -7
  73. package/dist/docs/guides/human-in-the-loop.html +4 -4
  74. package/dist/docs/guides/mcp-oauth.html +4 -4
  75. package/dist/docs/guides/opentelemetry.html +51 -0
  76. package/dist/docs/guides/slack.html +4 -4
  77. package/dist/docs/guides/webhooks.html +4 -4
  78. package/dist/docs/hashmap.json +1 -1
  79. package/dist/docs/hillclimbing.html +4 -4
  80. package/dist/docs/index.html +8 -27
  81. package/dist/docs/quickstart.html +24 -55
  82. package/dist/docs/reference/agent-config.html +12 -7
  83. package/dist/docs/reference/artifacts.html +4 -4
  84. package/dist/docs/reference/channels.html +6 -6
  85. package/dist/docs/reference/cli.html +7 -7
  86. package/dist/docs/reference/connections.html +4 -4
  87. package/dist/docs/reference/hooks.html +6 -6
  88. package/dist/docs/reference/http-api.html +4 -4
  89. package/dist/docs/reference/instructions.html +4 -4
  90. package/dist/docs/reference/playground.html +4 -4
  91. package/dist/docs/reference/project-layout.html +7 -6
  92. package/dist/docs/reference/prompt.html +4 -4
  93. package/dist/docs/reference/schedules.html +4 -4
  94. package/dist/docs/reference/sessions.html +4 -4
  95. package/dist/docs/reference/skills.html +4 -4
  96. package/dist/docs/reference/subagents.html +4 -4
  97. package/dist/docs/reference/tools.html +6 -6
  98. package/dist/docs/scaffolding-agents.html +4 -4
  99. package/dist/docs/storage.html +4 -4
  100. package/dist/docs/templates/triage.html +35 -0
  101. package/dist/docs/troubleshooting.html +4 -4
  102. package/dist/index.d.ts +3 -1
  103. package/dist/index.d.ts.map +1 -1
  104. package/dist/index.js +2 -1
  105. package/dist/internal/cli-ax.d.ts +1 -0
  106. package/dist/internal/cli-ax.d.ts.map +1 -1
  107. package/dist/internal/cli-ax.js +20 -5
  108. package/dist/internal/cli-deploy.d.ts.map +1 -1
  109. package/dist/internal/cli-deploy.js +38 -7
  110. package/dist/internal/deploy-client.d.ts +8 -0
  111. package/dist/internal/deploy-client.d.ts.map +1 -1
  112. package/dist/internal/deploy-client.js +5 -2
  113. package/dist/internal/discovery.d.ts.map +1 -1
  114. package/dist/internal/discovery.js +82 -13
  115. package/dist/internal/distribution.d.ts.map +1 -1
  116. package/dist/internal/distribution.js +1 -0
  117. package/dist/internal/host-otel.d.ts +25 -0
  118. package/dist/internal/host-otel.d.ts.map +1 -0
  119. package/dist/internal/host-otel.js +162 -0
  120. package/dist/internal/init-project.d.ts +24 -0
  121. package/dist/internal/init-project.d.ts.map +1 -1
  122. package/dist/internal/init-project.js +136 -17
  123. package/dist/internal/otel/attrs.d.ts +7 -0
  124. package/dist/internal/otel/attrs.d.ts.map +1 -0
  125. package/dist/internal/otel/attrs.js +13 -0
  126. package/dist/internal/otel/collector.d.ts +21 -0
  127. package/dist/internal/otel/collector.d.ts.map +1 -0
  128. package/dist/internal/otel/collector.js +605 -0
  129. package/dist/internal/otel/config.d.ts +42 -0
  130. package/dist/internal/otel/config.d.ts.map +1 -0
  131. package/dist/internal/otel/config.js +236 -0
  132. package/dist/internal/otel/http.d.ts +11 -0
  133. package/dist/internal/otel/http.d.ts.map +1 -0
  134. package/dist/internal/otel/http.js +97 -0
  135. package/dist/internal/otel/runtime.d.ts +21 -0
  136. package/dist/internal/otel/runtime.d.ts.map +1 -0
  137. package/dist/internal/otel/runtime.js +188 -0
  138. package/dist/internal/sdk-runner.d.ts +1 -1
  139. package/dist/internal/sdk-runner.d.ts.map +1 -1
  140. package/dist/internal/sdk-runner.js +1 -1
  141. package/dist/internal/server.d.ts.map +1 -1
  142. package/dist/internal/server.js +26 -1
  143. package/dist/internal/session-engine.d.ts +15 -2
  144. package/dist/internal/session-engine.d.ts.map +1 -1
  145. package/dist/internal/session-engine.js +58 -7
  146. package/dist/memory.d.ts +4 -0
  147. package/dist/memory.d.ts.map +1 -1
  148. package/dist/memory.js +4 -0
  149. package/dist/otel.d.ts +88 -0
  150. package/dist/otel.d.ts.map +1 -0
  151. package/dist/otel.js +64 -0
  152. package/dist/playground/assets/index-CZH9EFvO.css +1 -0
  153. package/dist/playground/assets/{index-B3HBneZZ.js → index-Dces8BDp.js} +34 -34
  154. package/dist/playground/index.html +2 -2
  155. package/dist/types.d.ts +103 -3
  156. package/dist/types.d.ts.map +1 -1
  157. package/docs/README.md +35 -105
  158. package/docs/deployment.md +2 -1
  159. package/docs/guides/github.md +79 -6
  160. package/docs/guides/opentelemetry.md +214 -0
  161. package/docs/quickstart.md +89 -227
  162. package/docs/reference/agent-config.md +52 -0
  163. package/docs/reference/channels.md +3 -1
  164. package/docs/reference/cli.md +2 -2
  165. package/docs/reference/hooks.md +21 -4
  166. package/docs/reference/project-layout.md +2 -0
  167. package/docs/reference/tools.md +5 -4
  168. package/docs/templates/triage.md +147 -0
  169. package/package.json +24 -2
  170. package/skills/create-agent/SKILL.md +2 -2
  171. package/skills/framework-map/SKILL.md +2 -0
  172. package/skills/otel/SKILL.md +98 -0
  173. package/src/bin/agent-serve.ts +3 -1
  174. package/src/channels/github/api.ts +22 -0
  175. package/src/channels/github/defaults.ts +27 -6
  176. package/src/channels/github/github-channel.ts +36 -1
  177. package/src/channels/github/index.ts +1 -0
  178. package/src/channels/github/progress.ts +243 -0
  179. package/src/channels/github/state.ts +3 -0
  180. package/src/channels/github/types.ts +12 -4
  181. package/src/channels/slack/slack-channel.ts +4 -0
  182. package/src/channels.ts +38 -0
  183. package/src/index.ts +7 -0
  184. package/src/internal/cli-ax.ts +21 -3
  185. package/src/internal/cli-deploy.ts +58 -3
  186. package/src/internal/deploy-client.ts +11 -0
  187. package/src/internal/discovery.ts +108 -4
  188. package/src/internal/distribution.ts +1 -0
  189. package/src/internal/host-otel.ts +252 -0
  190. package/src/internal/init-project.ts +160 -17
  191. package/src/internal/otel/attrs.ts +18 -0
  192. package/src/internal/otel/collector.ts +881 -0
  193. package/src/internal/otel/config.ts +307 -0
  194. package/src/internal/otel/http.ts +126 -0
  195. package/src/internal/otel/runtime.ts +271 -0
  196. package/src/internal/sdk-runner.ts +6 -0
  197. package/src/internal/server.ts +39 -1
  198. package/src/internal/session-engine.ts +83 -2
  199. package/src/memory.ts +4 -0
  200. package/src/otel.ts +155 -0
  201. package/src/types.ts +109 -3
  202. package/templates/triage/README.md +48 -0
  203. package/templates/triage/agent/agent.ts +14 -0
  204. package/templates/triage/agent/channels/intake.ts +20 -0
  205. package/templates/triage/agent/channels/slack.ts +3 -0
  206. package/templates/triage/agent/hooks/memory.ts +3 -0
  207. package/templates/triage/agent/instructions.md +27 -0
  208. package/templates/triage/agent/skills/triage-rubric.md +43 -0
  209. package/templates/triage/agent/tools/record_triage.ts +23 -0
  210. package/templates/triage/evals/evals.config.ts +5 -0
  211. package/templates/triage/evals/triage.eval.ts +43 -0
  212. package/templates/triage/package.json +18 -0
  213. package/templates/triage/tsconfig.json +12 -0
  214. package/dist/docs/assets/chunks/@localSearchIndexroot.BlU3A8EB.js +0 -1
  215. package/dist/docs/assets/index.md.BKpbkCa6.js +0 -24
  216. package/dist/docs/assets/index.md.BKpbkCa6.lean.js +0 -1
  217. package/dist/docs/assets/quickstart.md.rIbfahJM.lean.js +0 -1
  218. package/dist/playground/assets/index-Bqk9nplh.css +0 -1
  219. /package/dist/docs/assets/{deployment.md.BHVjVqRa.lean.js → deployment.md.Cdp4rTE4.lean.js} +0 -0
  220. /package/dist/docs/assets/{reference_channels.md.BIabFUAI.lean.js → reference_channels.md.MN8iDy8V.lean.js} +0 -0
  221. /package/dist/docs/assets/{reference_cli.md.DqEqQpGn.lean.js → reference_cli.md.BDmjPPAm.lean.js} +0 -0
  222. /package/dist/docs/assets/{reference_project-layout.md._XdeMahr.lean.js → reference_project-layout.md.D3MdHM2z.lean.js} +0 -0
  223. /package/dist/docs/assets/{reference_tools.md.lSrsTxYJ.lean.js → reference_tools.md.kJfJAP2m.lean.js} +0 -0
package/dist/docs/reference/agent-config.html CHANGED
@@ -9,16 +9,16 @@
9
9
  <link rel="preload stylesheet" href="/docs/assets/style.CK3hwt6q.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.C4-Gwi7g.js"></script>
12
+ <script type="module" src="/docs/assets/app.fHnNXEJ6.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.SbjGIiM0.js">
14
+ <link rel="modulepreload" href="/docs/assets/chunks/theme.B_5-VLe8.js">
15
15
  <link rel="modulepreload" href="/docs/assets/chunks/framework.CAZyNGu9.js">
16
- <link rel="modulepreload" href="/docs/assets/reference_agent-config.md.CRmkoxd6.lean.js">
16
+ <link rel="modulepreload" href="/docs/assets/reference_agent-config.md.XRpxctsA.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-41df81ff><!--[--><!--]--><!--[--><span tabindex="-1" data-v-c792f8ce></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-c792f8ce>Skip to content</a><!--]--><!----><header class="VPNav" data-v-41df81ff data-v-ecf0170c><div class="VPNavBar" data-v-ecf0170c data-v-74fc79fd><div class="wrapper" data-v-74fc79fd><div class="container" data-v-74fc79fd><div class="title" data-v-74fc79fd><div class="VPNavBarTitle has-sidebar" data-v-74fc79fd data-v-38e78292><a class="title" href="/docs/" data-v-38e78292><!--[--><!--]--><!----><span data-v-38e78292>Agent SDK</span><!--[--><!--]--></a></div></div><div class="content" data-v-74fc79fd><div class="content-body" data-v-74fc79fd><!--[--><!--]--><div class="VPNavBarSearch search" data-v-74fc79fd><!--[--><!----><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-74fc79fd data-v-6bcb02d4><span id="main-nav-aria-label" class="visually-hidden" data-v-6bcb02d4> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/example-agents/" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Examples</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-74fc79fd data-v-106703d3><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-106703d3 data-v-2881b93b data-v-5009fed8><span class="check" data-v-5009fed8><span class="icon" data-v-5009fed8><!--[--><span class="vpi-sun sun" data-v-2881b93b></span><span class="vpi-moon moon" data-v-2881b93b></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-74fc79fd data-v-53eccc99 data-v-f6ef69a3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-f6ef69a3><span class="vpi-more-horizontal icon" data-v-f6ef69a3></span></button><div class="menu" data-v-f6ef69a3><div class="VPMenu" data-v-f6ef69a3 data-v-00ea3a5e><!----><!--[--><!--[--><!----><div class="group" data-v-53eccc99><div class="item appearance" data-v-53eccc99><p class="label" data-v-53eccc99>Appearance</p><div class="appearance-action" data-v-53eccc99><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-53eccc99 data-v-2881b93b data-v-5009fed8><span class="check" data-v-5009fed8><span class="icon" data-v-5009fed8><!--[--><span class="vpi-sun sun" data-v-2881b93b></span><span class="vpi-moon moon" data-v-2881b93b></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-74fc79fd data-v-1d6d00d8><span class="container" data-v-1d6d00d8><span class="top" data-v-1d6d00d8></span><span class="middle" data-v-1d6d00d8></span><span class="bottom" data-v-1d6d00d8></span></span></button></div></div></div></div><div class="divider" data-v-74fc79fd><div class="divider-line" data-v-74fc79fd></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-41df81ff data-v-fac38a7d><div class="container" data-v-fac38a7d><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-fac38a7d><span class="vpi-align-left menu-icon" data-v-fac38a7d></span><span class="menu-text" data-v-fac38a7d>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-fac38a7d data-v-3829176f><button data-v-3829176f>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-41df81ff data-v-78b202de><div class="curtain" data-v-78b202de></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-78b202de><span class="visually-hidden" id="sidebar-aria-label" data-v-78b202de> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Getting started</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/concepts.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Improving agents</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/evals.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/ab.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/storage.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Guides</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Cloud runtime</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Example agents</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Choose an example</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/weather-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Weather agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/slack-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Slack agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/concierge.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Concierge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/benny.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Playbook router</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/oncall.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Alert investigator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/bugbot.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>PR evidence reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/approval-buddy.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Approval Buddy</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/security-reviewer.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Security Reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/fsd.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Remote PR coordinator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/knowledge-base.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Knowledge base</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/codebase-wiki.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Codebase wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/codeowners-review.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Codeowners review</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Operating</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/deployment.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0 collapsible has-active" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-29a50a33><span class="vpi-chevron-right caret-icon" data-v-29a50a33></span></div></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-41df81ff data-v-9d9adfa7><div class="VPDoc has-sidebar has-aside" data-v-9d9adfa7 data-v-d5d7ccd1><!--[--><!--]--><div class="container" data-v-d5d7ccd1><div class="aside" data-v-d5d7ccd1><div class="aside-curtain" data-v-d5d7ccd1></div><div class="aside-container" data-v-d5d7ccd1><div class="aside-content" data-v-d5d7ccd1><div class="VPDocAside" data-v-d5d7ccd1 data-v-83378aaf><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-83378aaf data-v-5d36b21a><div class="content" data-v-5d36b21a><div class="outline-marker" data-v-5d36b21a></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-5d36b21a>On this page</div><ul class="VPDocOutlineItem root" data-v-5d36b21a data-v-537d09da><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-83378aaf></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-d5d7ccd1><div class="content-container" data-v-d5d7ccd1><!--[--><!--]--><main class="main" data-v-d5d7ccd1><div style="position:relative;" class="vp-doc _docs_reference_agent-config" data-v-d5d7ccd1><div><h1 id="agent-config-agent-agent-ts" tabindex="-1">Agent config (<code>agent/agent.ts</code>) <a class="header-anchor" href="#agent-config-agent-agent-ts" aria-label="Permalink to &quot;Agent config (`agent/agent.ts`)&quot;">​</a></h1><p><code>agent/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent, where turns execute, and runtime-specific defaults. Everything is optional on the root agent.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
21
+ <div id="app"><div class="Layout" data-v-41df81ff><!--[--><!--]--><!--[--><span tabindex="-1" data-v-c792f8ce></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-c792f8ce>Skip to content</a><!--]--><!----><header class="VPNav" data-v-41df81ff data-v-ecf0170c><div class="VPNavBar" data-v-ecf0170c data-v-74fc79fd><div class="wrapper" data-v-74fc79fd><div class="container" data-v-74fc79fd><div class="title" data-v-74fc79fd><div class="VPNavBarTitle has-sidebar" data-v-74fc79fd data-v-38e78292><a class="title" href="/docs/" data-v-38e78292><!--[--><!--]--><!----><span data-v-38e78292>Agent SDK</span><!--[--><!--]--></a></div></div><div class="content" data-v-74fc79fd><div class="content-body" data-v-74fc79fd><!--[--><!--]--><div class="VPNavBarSearch search" data-v-74fc79fd><!--[--><!----><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-74fc79fd data-v-6bcb02d4><span id="main-nav-aria-label" class="visually-hidden" data-v-6bcb02d4> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/webhooks.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/example-agents/" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Examples</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-6bcb02d4 data-v-40a52867><!--[--><span data-v-40a52867>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-74fc79fd data-v-106703d3><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-106703d3 data-v-2881b93b data-v-5009fed8><span class="check" data-v-5009fed8><span class="icon" data-v-5009fed8><!--[--><span class="vpi-sun sun" data-v-2881b93b></span><span class="vpi-moon moon" data-v-2881b93b></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-74fc79fd data-v-53eccc99 data-v-f6ef69a3><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-f6ef69a3><span class="vpi-more-horizontal icon" data-v-f6ef69a3></span></button><div class="menu" data-v-f6ef69a3><div class="VPMenu" data-v-f6ef69a3 data-v-00ea3a5e><!----><!--[--><!--[--><!----><div class="group" data-v-53eccc99><div class="item appearance" data-v-53eccc99><p class="label" data-v-53eccc99>Appearance</p><div class="appearance-action" data-v-53eccc99><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-53eccc99 data-v-2881b93b data-v-5009fed8><span class="check" data-v-5009fed8><span class="icon" data-v-5009fed8><!--[--><span class="vpi-sun sun" data-v-2881b93b></span><span class="vpi-moon moon" data-v-2881b93b></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-74fc79fd data-v-1d6d00d8><span class="container" data-v-1d6d00d8><span class="top" data-v-1d6d00d8></span><span class="middle" data-v-1d6d00d8></span><span class="bottom" data-v-1d6d00d8></span></span></button></div></div></div></div><div class="divider" data-v-74fc79fd><div class="divider-line" data-v-74fc79fd></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-41df81ff data-v-fac38a7d><div class="container" data-v-fac38a7d><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-fac38a7d><span class="vpi-align-left menu-icon" data-v-fac38a7d></span><span class="menu-text" data-v-fac38a7d>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-fac38a7d data-v-3829176f><button data-v-3829176f>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-41df81ff data-v-78b202de><div class="curtain" data-v-78b202de></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-78b202de><span class="visually-hidden" id="sidebar-aria-label" data-v-78b202de> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Getting started</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Quickstart</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/scaffolding-agents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Scaffold an agent with Cursor</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/concepts.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Concepts</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Templates</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Improving agents</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Building agents with agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/evals.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/ab.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Live A/B metrics</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/storage.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Storage</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Hillclimbing</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Guides</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Webhooks & custom channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/human-in-the-loop.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Human-in-the-loop approvals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Agent-to-agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Host MCP OAuth</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/cloud-runtime.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Cloud runtime</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>OpenTelemetry</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Example agents</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Choose an example</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/weather-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Weather agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/slack-agent.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Slack agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/concierge.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Concierge</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/benny.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Playbook router</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/oncall.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Alert investigator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/bugbot.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>PR evidence reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/approval-buddy.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Approval Buddy</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/security-reviewer.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Security Reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/fsd.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Remote PR coordinator</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/knowledge-base.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Knowledge base</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/codebase-wiki.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Codebase wiki</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/example-agents/codeowners-review.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Codeowners review</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Operating</h2><!----></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/deployment.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Fix common problems</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9195cb0b><section class="VPSidebarItem level-0 collapsible has-active" data-v-9195cb0b data-v-29a50a33><div class="item" role="button" tabindex="0" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><h2 class="text" data-v-29a50a33>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-29a50a33><span class="vpi-chevron-right caret-icon" data-v-29a50a33></span></div></div><div class="items" data-v-29a50a33><!--[--><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-29a50a33><div class="item" data-v-29a50a33><div class="indicator" data-v-29a50a33></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-29a50a33><!--[--><p class="text" data-v-29a50a33>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-41df81ff data-v-9d9adfa7><div class="VPDoc has-sidebar has-aside" data-v-9d9adfa7 data-v-d5d7ccd1><!--[--><!--]--><div class="container" data-v-d5d7ccd1><div class="aside" data-v-d5d7ccd1><div class="aside-curtain" data-v-d5d7ccd1></div><div class="aside-container" data-v-d5d7ccd1><div class="aside-content" data-v-d5d7ccd1><div class="VPDocAside" data-v-d5d7ccd1 data-v-83378aaf><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-83378aaf data-v-5d36b21a><div class="content" data-v-5d36b21a><div class="outline-marker" data-v-5d36b21a></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-5d36b21a>On this page</div><ul class="VPDocOutlineItem root" data-v-5d36b21a data-v-537d09da><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-83378aaf></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-d5d7ccd1><div class="content-container" data-v-d5d7ccd1><!--[--><!--]--><main class="main" data-v-d5d7ccd1><div style="position:relative;" class="vp-doc _docs_reference_agent-config" data-v-d5d7ccd1><div><h1 id="agent-config-agent-agent-ts" tabindex="-1">Agent config (<code>agent/agent.ts</code>) <a class="header-anchor" href="#agent-config-agent-agent-ts" aria-label="Permalink to &quot;Agent config (`agent/agent.ts`)&quot;">​</a></h1><p><code>agent/agent.ts</code> default-exports <code>defineAgent(config)</code>: which model runs the agent, where turns execute, and runtime-specific defaults. Everything is optional on the root agent.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
22
22
  <span class="line"></span>
23
23
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
24
24
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> model: {</span></span>
@@ -33,13 +33,18 @@
33
33
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // repos: [{ url: &quot;https://github.com/org/repo&quot;, startingRef: &quot;main&quot; }],</span></span>
34
34
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // },</span></span>
35
35
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // local: { cwd: &quot;../harness&quot; },</span></span>
36
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="fields-on-defineagent" tabindex="-1">Fields on <code>defineAgent</code> <a class="header-anchor" href="#fields-on-defineagent" aria-label="Permalink to &quot;Fields on `defineAgent`&quot;">​</a></h2><p><code>defineAgent</code> accepts these fields.</p><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code> on the root agent. Subagents omit it to inherit.</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name override. Defaults to the package name or directory name.</td></tr><tr><td><code>description</code></td><td>string</td><td>What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root.</td></tr><tr><td><code>instructions</code></td><td>string</td><td>Inline instructions. Prefer <code>instructions.md</code>; this exists for subagents and generated configs.</td></tr><tr><td><code>runtime</code></td><td><code>&quot;local&quot;</code> or <code>&quot;cloud&quot;</code></td><td>Where turns execute. Default <code>&quot;local&quot;</code>.</td></tr><tr><td><code>cloud</code></td><td>object</td><td>Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when <code>runtime</code> is <code>&quot;cloud&quot;</code>, and as the base merged under per-session <code>cloud</code> send options.</td></tr><tr><td><code>local</code></td><td><code>{ cwd?, workspaceDir?, sandbox? }</code></td><td>Local harness defaults; ignored for cloud turns. See <a href="#local-options">Local options</a>.</td></tr><tr><td><code>hosting</code></td><td><code>{ egressDomains?, secretNames? }</code></td><td>Managed-hosting declarations read by <code>agent-sdk deploy</code>: the pod&#39;s egress allowlist and the secret names the agent expects. Ignored by local serving.</td></tr><tr><td><code>concurrency</code></td><td><code>{ maxRunningTurns? }</code></td><td>Engine-wide turn admission limit. See <a href="#concurrency">Concurrency</a>.</td></tr><tr><td><code>builtinTools</code></td><td><code>{ reminders? }</code></td><td>Framework-provided model-facing tools, opted in per capability. See <a href="#built-in-tools">Built-in tools</a>.</td></tr></tbody></table><h2 id="choose-a-model" tabindex="-1">Choose a model <a class="header-anchor" href="#choose-a-model" aria-label="Permalink to &quot;Choose a model&quot;">​</a></h2><p><code>model</code> is a Cursor model id string, or <code>{ id, params }</code>. Effort and speed are params, not id suffixes. The SDK rejects suffix-style ids like <code>grok-4.5-fast</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
36
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="fields-on-defineagent" tabindex="-1">Fields on <code>defineAgent</code> <a class="header-anchor" href="#fields-on-defineagent" aria-label="Permalink to &quot;Fields on `defineAgent`&quot;">​</a></h2><p><code>defineAgent</code> accepts these fields.</p><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.5</code> with <code>effort=high</code>, <code>fast=true</code> on the root agent. Subagents omit it to inherit.</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name override. Defaults to the package name or directory name.</td></tr><tr><td><code>description</code></td><td>string</td><td>What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root.</td></tr><tr><td><code>instructions</code></td><td>string</td><td>Inline instructions. Prefer <code>instructions.md</code>; this exists for subagents and generated configs.</td></tr><tr><td><code>runtime</code></td><td><code>&quot;local&quot;</code> or <code>&quot;cloud&quot;</code></td><td>Where turns execute. Default <code>&quot;local&quot;</code>.</td></tr><tr><td><code>cloud</code></td><td>object</td><td>Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when <code>runtime</code> is <code>&quot;cloud&quot;</code>, and as the base merged under per-session <code>cloud</code> send options.</td></tr><tr><td><code>local</code></td><td><code>{ cwd?, workspaceDir?, sandbox? }</code></td><td>Local harness defaults; ignored for cloud turns. See <a href="#local-options">Local options</a>.</td></tr><tr><td><code>hosting</code></td><td><code>{ egressDomains?, secretNames? }</code></td><td>Managed-hosting declarations read by <code>agent-sdk deploy</code>: the pod&#39;s egress allowlist and the secret names the agent expects. Ignored by local serving.</td></tr><tr><td><code>concurrency</code></td><td><code>{ maxRunningTurns? }</code></td><td>Engine-wide turn admission limit. See <a href="#concurrency">Concurrency</a>.</td></tr><tr><td><code>builtinTools</code></td><td><code>{ reminders? }</code></td><td>Framework-provided model-facing tools, opted in per capability. See <a href="#built-in-tools">Built-in tools</a>.</td></tr><tr><td><code>tools</code></td><td><code>ToolName[]</code></td><td>Allowlist of built-in harness tools offered to the model. Unset = the model&#39;s full standard toolset. See <a href="#allowlist-built-in-harness-tools">Allowlist built-in harness tools</a>.</td></tr></tbody></table><h2 id="choose-a-model" tabindex="-1">Choose a model <a class="header-anchor" href="#choose-a-model" aria-label="Permalink to &quot;Choose a model&quot;">​</a></h2><p><code>model</code> is a Cursor model id string, or <code>{ id, params }</code>. Effort and speed are params, not id suffixes. The SDK rejects suffix-style ids like <code>grok-4.5-fast</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
37
37
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> id</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;grok-4.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
38
38
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> params</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
39
39
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;effort&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;high&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
40
40
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;fast&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;true&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
41
41
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
42
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>A plain string works when you don&#39;t need params:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span></code></pre></div><h2 id="choose-a-runtime" tabindex="-1">Choose a runtime <a class="header-anchor" href="#choose-a-runtime" aria-label="Permalink to &quot;Choose a runtime&quot;">​</a></h2><p><code>runtime: &quot;local&quot;</code> (the default) runs turns on the Cursor SDK harness on this machine. The session id doubles as the SDK agent id, and server tools, skills, sandbox seeds, and tool approvals all apply.</p><p><code>runtime: &quot;cloud&quot;</code> runs turns on Cursor cloud agents (<code>bc-…</code> ids). Pass a <code>cloud</code> block with the repos the VM carries. Server tools stay reachable over authenticated HTTP MCP back to the serve host when <code>--public-url</code> or <code>--cloud-tools-url</code> is set (omitted with a warning otherwise), and instructions and agent-tool catalogs are prepended to the first prompt, because the local session workspace is not the cloud VM.</p><p><code>validate</code> warns when <code>runtime: &quot;cloud&quot;</code> is combined with agent tools, skills, or sandbox seeds, which only materialize into local session workspaces, and when the <code>cloud</code> block is missing. The full capability matrix and the patterns that hold up are in the <a href="./../guides/cloud-runtime.html">Cloud runtime guide</a>.</p><h2 id="local-options" tabindex="-1">Local options <a class="header-anchor" href="#local-options" aria-label="Permalink to &quot;Local options&quot;">​</a></h2><p><code>local</code> sets local-harness defaults, all ignored for cloud turns.</p><p><code>local.workspaceDir</code> points every session at one shared harness cwd, for agents that work inside an existing checkout. It takes precedence over <code>cwd</code>, and a per-send <code>workspaceDir</code> still wins over both. The SDK keys its local executor (rules, skills, MCP, ignore mappings) on the harness cwd, so a shared directory resolves the workspace once per serve process instead of once per session. The trade: sessions share a working tree, so a file one turn writes is visible to the next.</p><p><code>local.sandbox</code> runs the harness inside Cursor&#39;s local sandbox. It&#39;s off by default, matching the SDK: shell then auto-approves and inherits the serve process environment, including any credentials the host holds. Turn it on for agents whose turns read untrusted input (webhook payloads, PR diffs, inbound chat); it&#39;s a real tool boundary rather than a prompt-level one.</p><h3 id="local-cwd" tabindex="-1">Local cwd <a class="header-anchor" href="#local-cwd" aria-label="Permalink to &quot;Local cwd&quot;">​</a></h3><p><code>local.cwd</code> sets the default parent directory for local harness workspaces. Each session uses <code>&lt;cwd&gt;/&lt;sessionId&gt;</code> (absolute, or relative to the project root) unless a per-send <code>workspaceDir</code> overrides it.</p><p>This is your control over ambient context. Session workspaces are real Cursor project directories, so the harness loads <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. An agent inside a big monorepo that must not inherit the monorepo&#39;s rules points <code>cwd</code> outside it (or runs with <code>--state-root</code> under <code>/tmp</code>). An agent that <em>needs</em> a specific checkout&#39;s skills and rules points <code>cwd</code> inside that checkout.</p><h2 id="the-cloud-block" tabindex="-1">The <code>cloud</code> block <a class="header-anchor" href="#the-cloud-block" aria-label="Permalink to &quot;The `cloud` block&quot;">​</a></h2><p>Cloud agent defaults forwarded to the Cursor SDK: <code>repos</code> (each <code>{ url, startingRef? }</code>), environment selection, <code>envVars</code>, and the rest. A local agent uses the same block as the base config when a channel opens a cloud-attached session per send. That hybrid pattern is covered in <a href="./../guides/cloud-runtime.html#hybrid-local-agent-cloud-sessions">Cloud runtime</a>.</p><h2 id="concurrency" tabindex="-1">Concurrency <a class="header-anchor" href="#concurrency" aria-label="Permalink to &quot;Concurrency&quot;">​</a></h2><p><code>concurrency.maxRunningTurns</code> caps how many model turns run at once across all of the agent&#39;s sessions (positive integer, hard cap 200). When every slot is busy, newly admitted turns queue FIFO instead of failing: the stream records a durable <code>turn.queued</code> event with the queue position, <code>GET /v1/sessions</code> reports <code>queued: true</code>, and each queued turn starts as soon as a slot frees. A queued turn still counts as running for busy semantics: follow-ups preempt it, and direct tool calls get <code>409 session_busy</code>. Omit for unlimited.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
42
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>A plain string works when you don&#39;t need params:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span></code></pre></div><h2 id="choose-a-runtime" tabindex="-1">Choose a runtime <a class="header-anchor" href="#choose-a-runtime" aria-label="Permalink to &quot;Choose a runtime&quot;">​</a></h2><p><code>runtime: &quot;local&quot;</code> (the default) runs turns on the Cursor SDK harness on this machine. The session id doubles as the SDK agent id, and server tools, skills, sandbox seeds, and tool approvals all apply.</p><p><code>runtime: &quot;cloud&quot;</code> runs turns on Cursor cloud agents (<code>bc-…</code> ids). Pass a <code>cloud</code> block with the repos the VM carries. Server tools stay reachable over authenticated HTTP MCP back to the serve host when <code>--public-url</code> or <code>--cloud-tools-url</code> is set (omitted with a warning otherwise), and instructions and agent-tool catalogs are prepended to the first prompt, because the local session workspace is not the cloud VM.</p><p><code>validate</code> warns when <code>runtime: &quot;cloud&quot;</code> is combined with agent tools, skills, or sandbox seeds, which only materialize into local session workspaces, and when the <code>cloud</code> block is missing. The full capability matrix and the patterns that hold up are in the <a href="./../guides/cloud-runtime.html">Cloud runtime guide</a>.</p><h2 id="local-options" tabindex="-1">Local options <a class="header-anchor" href="#local-options" aria-label="Permalink to &quot;Local options&quot;">​</a></h2><p><code>local</code> sets local-harness defaults, all ignored for cloud turns.</p><p><code>local.workspaceDir</code> points every session at one shared harness cwd, for agents that work inside an existing checkout. It takes precedence over <code>cwd</code>, and a per-send <code>workspaceDir</code> still wins over both. The SDK keys its local executor (rules, skills, MCP, ignore mappings) on the harness cwd, so a shared directory resolves the workspace once per serve process instead of once per session. The trade: sessions share a working tree, so a file one turn writes is visible to the next.</p><p><code>local.sandbox</code> runs the harness inside Cursor&#39;s local sandbox. It&#39;s off by default, matching the SDK: shell then auto-approves and inherits the serve process environment, including any credentials the host holds. Turn it on for agents whose turns read untrusted input (webhook payloads, PR diffs, inbound chat); it&#39;s a real tool boundary rather than a prompt-level one.</p><h3 id="local-cwd" tabindex="-1">Local cwd <a class="header-anchor" href="#local-cwd" aria-label="Permalink to &quot;Local cwd&quot;">​</a></h3><p><code>local.cwd</code> sets the default parent directory for local harness workspaces. Each session uses <code>&lt;cwd&gt;/&lt;sessionId&gt;</code> (absolute, or relative to the project root) unless a per-send <code>workspaceDir</code> overrides it.</p><p>This is your control over ambient context. Session workspaces are real Cursor project directories, so the harness loads <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. An agent inside a big monorepo that must not inherit the monorepo&#39;s rules points <code>cwd</code> outside it (or runs with <code>--state-root</code> under <code>/tmp</code>). An agent that <em>needs</em> a specific checkout&#39;s skills and rules points <code>cwd</code> inside that checkout.</p><h2 id="allowlist-built-in-harness-tools" tabindex="-1">Allowlist built-in harness tools <a class="header-anchor" href="#allowlist-built-in-harness-tools" aria-label="Permalink to &quot;Allowlist built-in harness tools&quot;">​</a></h2><p><code>tools</code> names which of the Cursor harness&#39;s built-in tools the model is offered, riding the SDK&#39;s <code>AgentOptions.tools</code>. It is opt-in by design: unset keeps the model&#39;s full standard toolset, and once set the agent gets exactly what it names — nothing more. <code>[]</code> removes every native built-in tool. There is deliberately no exclusion form: an agent that restricts tools states what it keeps, so tools the platform adds later stay off until someone opts in.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
43
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> model: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;composer-2.5&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
44
+ <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Read-only triage agent: search and read only.</span></span>
45
+ <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // No shell, no edits, no subagents.</span></span>
46
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tools: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;read&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;grep&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;glob&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ls&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
47
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>One name is injected for you: <strong><code>&quot;mcp&quot;</code> is always granted alongside a configured allowlist</strong>. It is transport, not capability — this kit&#39;s authored server tools reach the model over the SDK custom-tool MCP path, so omitting it would silently strand <code>agent/tools/</code>. What MCP actually exposes stays governed by the second layer: the tools you author, the connections you declare, and the harness cwd&#39;s ambient <code>.cursor</code> config. An agent that must not see a checkout&#39;s MCP servers points <code>local.cwd</code> outside it (see <a href="#local-cwd">Local cwd</a>), and <code>local.sandbox</code> makes MCP tool calls fail closed.</p><p>The other names use the SDK&#39;s public tool vocabulary (<code>&quot;shell&quot;</code>, <code>&quot;read&quot;</code>, <code>&quot;edit&quot;</code>, <code>&quot;grep&quot;</code>, <code>&quot;glob&quot;</code>, <code>&quot;ls&quot;</code>, <code>&quot;task&quot;</code>, ...); unknown names fail the turn with a <code>ConfigurationError</code>. Two deserve care: <code>&quot;shell&quot;</code> is a capability group that also grants shell stdin writes — and is what <code>execution: &quot;agent&quot;</code> tool scripts run through, so an allowlist without it strands them (discovery warns about that combination). <code>&quot;task&quot;</code> gates subagents (which otherwise keep their own curated toolsets).</p><p>The allowlist states runtime-agnostic intent, but the SDK cannot enforce tool restrictions on cloud agents yet — and a restriction must never silently not apply. A <code>runtime: &quot;cloud&quot;</code> agent that sets <code>tools</code> fails at serve start with an error diagnostic, and a hybrid agent&#39;s per-send cloud sessions are refused (the turn errors) rather than run unrestricted. When the SDK lifts the limitation, the same field will simply start applying to cloud turns.</p><p>Not a security boundary against the serve host: like <code>local.sandbox</code>, the allowlist only shapes what the model can call; pair with <code>sandbox: true</code> when the concern is untrusted input steering the model.</p><h2 id="the-cloud-block" tabindex="-1">The <code>cloud</code> block <a class="header-anchor" href="#the-cloud-block" aria-label="Permalink to &quot;The `cloud` block&quot;">​</a></h2><p>Cloud agent defaults forwarded to the Cursor SDK: <code>repos</code> (each <code>{ url, startingRef? }</code>), environment selection, <code>envVars</code>, and the rest. A local agent uses the same block as the base config when a channel opens a cloud-attached session per send. That hybrid pattern is covered in <a href="./../guides/cloud-runtime.html#hybrid-local-agent-cloud-sessions">Cloud runtime</a>.</p><h2 id="concurrency" tabindex="-1">Concurrency <a class="header-anchor" href="#concurrency" aria-label="Permalink to &quot;Concurrency&quot;">​</a></h2><p><code>concurrency.maxRunningTurns</code> caps how many model turns run at once across all of the agent&#39;s sessions (positive integer, hard cap 200). When every slot is busy, newly admitted turns queue FIFO instead of failing: the stream records a durable <code>turn.queued</code> event with the queue position, <code>GET /v1/sessions</code> reports <code>queued: true</code>, and each queued turn starts as soon as a slot frees. A queued turn still counts as running for busy semantics: follow-ups preempt it, and direct tool calls get <code>409 session_busy</code>. Omit for unlimited.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
43
48
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> concurrency: { maxRunningTurns: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">3</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
44
49
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="built-in-tools" tabindex="-1">Built-in tools <a class="header-anchor" href="#built-in-tools" aria-label="Permalink to &quot;Built-in tools&quot;">​</a></h2><p><code>builtinTools</code> opts into framework-provided model-facing tools. Each enabled capability materializes as ordinary server tools at discovery time, so turns, direct calls, <code>info</code>, and the playground treat them like authored tools. Authored tools with the same name win, with a warning, and like all server tools they run on the local runtime.</p><p><code>builtinTools: { reminders: true }</code> adds three tools bound to the current conversation over <code>host.reminders</code>: <code>reminders_create</code>, <code>reminders_list</code>, and <code>reminders_cancel</code>. Sessions without a continuation key can&#39;t arm reminders. See <a href="./schedules.html#reminders">Schedules and reminders</a>.</p><h2 id="generate-instructions" tabindex="-1">Generate instructions <a class="header-anchor" href="#generate-instructions" aria-label="Permalink to &quot;Generate instructions&quot;">​</a></h2><p>When the system prompt must be computed, author <code>agent/instructions.ts</code> instead of markdown:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineInstructions } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
45
50
  <span class="line"></span>
@@ -54,7 +59,7 @@
54
59
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`listening on ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">handle</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
55
60
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.callTool(...), handle.dispatchSchedule(&quot;heartbeat&quot;),</span></span>
56
61
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// handle.createReminder(...), handle.project, await handle.close()</span></span></code></pre></div><p><code>ServeOptions</code> mirrors the CLI flags: <code>port</code>, <code>host</code>, <code>dev</code>, <code>stateRoot</code>, <code>apiKey</code>, <code>schedules</code>, <code>reminders</code>, <code>noControlPlane</code>, <code>playground</code>, <code>docs</code>, <code>authToken</code> (the <code>--bearer-token</code> equivalent), <code>allowAnonymous</code>, <code>allowAnonymousCursorGithub</code>, <code>allowAnonymousCursorAccountMcp</code>, <code>cursorGithubProxy</code>, <code>publicUrl</code>, <code>cloudToolsUrl</code>, <code>cursorEvents</code>, and <code>logger</code>. <code>serve()</code> additionally accepts <code>discovery</code> (project-loading options) and <code>mode: &quot;single&quot; | &quot;multi&quot;</code>. The Cursor credential resolves in one order everywhere: explicit <code>apiKey</code>, then <code>CURSOR_API_KEY</code>, then the key stored by <code>agent-sdk login</code>.</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="./instructions.html">Instructions</a>: the required half of a minimal agent</li><li><a href="./../guides/cloud-runtime.html">Cloud runtime</a>: when and how to leave the host</li><li><a href="./cli.html">CLI</a>: the flags <code>ServeOptions</code> mirrors</li></ul></div></div></main><footer class="VPDocFooter" data-v-d5d7ccd1 data-v-a5908b0f><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-a5908b0f><span class="visually-hidden" id="doc-footer-aria-label" data-v-a5908b0f>Pager</span><div class="pager" data-v-a5908b0f><a class="VPLink link pager-link prev" href="/docs/reference/project-layout.html" data-v-a5908b0f><!--[--><span class="desc" data-v-a5908b0f>Previous page</span><span class="title" data-v-a5908b0f>Project layout</span><!--]--></a></div><div class="pager" data-v-a5908b0f><a class="VPLink link pager-link next" href="/docs/reference/instructions.html" data-v-a5908b0f><!--[--><span class="desc" data-v-a5908b0f>Next page</span><span class="title" data-v-a5908b0f>Instructions</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
57
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"hdxsvX5M\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"BHVjVqRa\",\"evals.md\":\"qeoGgPw0\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"l7JTmm8X\",\"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\":\"DPz9ezO4\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"ZE0n6ZFN\",\"example-agents_security-reviewer.md\":\"Dkf1gyo6\",\"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_github.md\":\"R2QlpR75\",\"guides_human-in-the-loop.md\":\"BWvT7UqY\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_slack.md\":\"zriQpU_9\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"BKpbkCa6\",\"quickstart.md\":\"rIbfahJM\",\"reference_agent-config.md\":\"CRmkoxd6\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"BIabFUAI\",\"reference_cli.md\":\"DqEqQpGn\",\"reference_connections.md\":\"CSQiNzre\",\"reference_hooks.md\":\"B40QAG6m\",\"reference_http-api.md\":\"DGrw_wOu\",\"reference_instructions.md\":\"CgoV-YEb\",\"reference_playground.md\":\"CPZhfYaO\",\"reference_project-layout.md\":\"_XdeMahr\",\"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\":\"lSrsTxYJ\",\"scaffolding-agents.md\":\"mkc3B_ZW\",\"storage.md\":\"DcGSnIxX\",\"troubleshooting.md\":\"CkgwmVI0\"}");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\":\"Concepts\",\"link\":\"/concepts\"}]},{\"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\":\"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>
62
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"ab.md\":\"hdxsvX5M\",\"building-with-agents.md\":\"PeZaZA1P\",\"concepts.md\":\"CqOsxbMU\",\"deployment.md\":\"Cdp4rTE4\",\"evals.md\":\"qeoGgPw0\",\"example-agents_approval-buddy.md\":\"CIiZ9coo\",\"example-agents_benny.md\":\"l7JTmm8X\",\"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\":\"DPz9ezO4\",\"example-agents_index.md\":\"xmJ87d_3\",\"example-agents_knowledge-base.md\":\"IneynQSR\",\"example-agents_oncall.md\":\"ZE0n6ZFN\",\"example-agents_security-reviewer.md\":\"Dkf1gyo6\",\"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_github.md\":\"DSg0j9qj\",\"guides_human-in-the-loop.md\":\"BWvT7UqY\",\"guides_mcp-oauth.md\":\"C7G7IykG\",\"guides_opentelemetry.md\":\"Csn7ZI25\",\"guides_slack.md\":\"zriQpU_9\",\"guides_webhooks.md\":\"DB-r_er9\",\"hillclimbing.md\":\"yXqdlv2R\",\"index.md\":\"COeoSkcF\",\"quickstart.md\":\"DZxBu44y\",\"reference_agent-config.md\":\"XRpxctsA\",\"reference_artifacts.md\":\"BGG4bZo-\",\"reference_channels.md\":\"MN8iDy8V\",\"reference_cli.md\":\"BDmjPPAm\",\"reference_connections.md\":\"CSQiNzre\",\"reference_hooks.md\":\"4cbRRIIu\",\"reference_http-api.md\":\"DGrw_wOu\",\"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\":\"kJfJAP2m\",\"scaffolding-agents.md\":\"mkc3B_ZW\",\"storage.md\":\"DcGSnIxX\",\"templates_triage.md\":\"CConZt1z\",\"troubleshooting.md\":\"CkgwmVI0\"}");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\":\"Concepts\",\"link\":\"/concepts\"}]},{\"text\":\"Templates\",\"items\":[{\"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>
58
63
 
59
64
  </body>
60
65
  </html>