@grok/agent-sdk 0.2.28 → 0.2.29

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 (339) hide show
  1. package/AGENTS.md +29 -29
  2. package/dist/bin/agent-serve.d.ts +2 -2
  3. package/dist/bin/agent-serve.js +3 -3
  4. package/dist/channels/pagerduty/api.js +1 -1
  5. package/dist/channels/pagerduty/pagerduty-channel.d.ts +1 -1
  6. package/dist/channels/pagerduty/pagerduty-channel.d.ts.map +1 -1
  7. package/dist/channels/pagerduty/pagerduty-channel.js +1 -1
  8. package/dist/channels/pagerduty/replay.d.ts +1 -1
  9. package/dist/channels/pagerduty/replay.js +4 -4
  10. package/dist/docs/404.html +2 -2
  11. package/dist/docs/assets/{app.DF9vlcdn.js → app.DMrZKFjI.js} +4 -4
  12. package/dist/docs/assets/changelog.md.DrLFQUlu.js +1 -0
  13. package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +1 -0
  14. package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +1 -0
  15. package/dist/docs/assets/chunks/{VPLocalSearchBox.D8OuwKO0.js → VPLocalSearchBox.DQvuw1KA.js} +1 -1
  16. package/dist/docs/assets/chunks/{arc.DCq_TCYV.js → arc.ahOG-Qza.js} +1 -1
  17. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.PWRNTPbk.js → architectureDiagram-Q4EWVU46.BcgfYNO_.js} +1 -1
  18. package/dist/docs/assets/chunks/{baseUniq.BeRPvRUL.js → baseUniq.DeIYZrWh.js} +1 -1
  19. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.BuRmZVSo.js → blockDiagram-DXYQGD6D.HjJ2goMX.js} +1 -1
  20. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.7DKSMwuv.js → c4Diagram-AHTNJAMY.C1QTb9GM.js} +1 -1
  21. package/dist/docs/assets/chunks/channel._fZX_hvU.js +1 -0
  22. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.7VrO9-9i.js → chunk-4BX2VUAB.UuZiDiVp.js} +1 -1
  23. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.CHystNE2.js → chunk-4TB4RGXK.5A3YmkhI.js} +1 -1
  24. package/dist/docs/assets/chunks/{chunk-55IACEB6.Nuh9TbTq.js → chunk-55IACEB6.B4uf1yYV.js} +1 -1
  25. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CA0EKugm.js → chunk-EDXVE4YY.CoXBce8t.js} +1 -1
  26. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.F9_mp7U8.js → chunk-FMBD7UC4.DnC5NO4e.js} +1 -1
  27. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CEU4QfE1.js → chunk-OYMX7WX6.CzfHCeIi.js} +1 -1
  28. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.B8h_x9_i.js → chunk-QZHKN3VN.C6tcwkVd.js} +1 -1
  29. package/dist/docs/assets/chunks/{chunk-YZCP3GAM.Btfb-rKg.js → chunk-YZCP3GAM._oboyZ1A.js} +1 -1
  30. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +1 -0
  31. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +1 -0
  32. package/dist/docs/assets/chunks/clone.W1Phdw9P.js +1 -0
  33. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.DKvc96Wa.js → cose-bilkent-S5V4N54A.BfPVKeId.js} +1 -1
  34. package/dist/docs/assets/chunks/{dagre-KV5264BT.CMo0cy1b.js → dagre-KV5264BT.CLMLc0lD.js} +1 -1
  35. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.DDgMOQhB.js → diagram-5BDNPKRD.C7OF7UfH.js} +1 -1
  36. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.BdJnoIsU.js → diagram-G4DWMVQ6.Dpao0Bl1.js} +1 -1
  37. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.oSvhAZaL.js → diagram-MMDJMWI5.DLnM9eLp.js} +1 -1
  38. package/dist/docs/assets/chunks/{diagram-TYMM5635.C9zZLIE-.js → diagram-TYMM5635.BcpVgA_M.js} +1 -1
  39. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.BNhVyccy.js → erDiagram-SMLLAGMA.CsL5JuCV.js} +1 -1
  40. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.BEFLLBiU.js → flowDiagram-DWJPFMVM.MFihq9AF.js} +1 -1
  41. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.BdUzXBgY.js → ganttDiagram-T4ZO3ILL.CJeLodyG.js} +1 -1
  42. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.Rd3LlOIJ.js → gitGraphDiagram-UUTBAWPF.1HhlE45Z.js} +1 -1
  43. package/dist/docs/assets/chunks/{graph.DnJC1GpG.js → graph.BS02KkWA.js} +1 -1
  44. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.xv0xntDJ.js → infoDiagram-42DDH7IO.fp5gvytQ.js} +1 -1
  45. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.BaGIlviU.js → ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js} +1 -1
  46. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.Cof_h0fp.js → journeyDiagram-VCZTEJTY.qJt4uJ_H.js} +1 -1
  47. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.C5GozFuU.js → kanban-definition-6JOO6SKY.z2tG9kly.js} +1 -1
  48. package/dist/docs/assets/chunks/{layout.zc9UShLc.js → layout.BPCkdejr.js} +1 -1
  49. package/dist/docs/assets/chunks/{linear.BoqrFVcJ.js → linear.CL3TC3u7.js} +1 -1
  50. package/dist/docs/assets/chunks/{min.DwIfr8hG.js → min.SPrSp704.js} +1 -1
  51. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.Dkq2yTtp.js → mindmap-definition-QFDTVHPH.DgrQRFZW.js} +1 -1
  52. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.B4CpTmHK.js → pieDiagram-DEJITSTG.Ba7yxiW2.js} +1 -1
  53. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.BqXnFC9C.js → quadrantDiagram-34T5L4WZ.Bvskad4p.js} +1 -1
  54. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.DhIN2z-E.js → requirementDiagram-MS252O5E.Ce70ugV9.js} +1 -1
  55. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BhxUAmg2.js → sankeyDiagram-XADWPNL6.BJ5OEULO.js} +1 -1
  56. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.BqgU7HU-.js → sequenceDiagram-FGHM5R23.C8a1hDs6.js} +1 -1
  57. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.B1BCO18N.js → stateDiagram-FHFEXIEX.D2D8A5CK.js} +1 -1
  58. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +1 -0
  59. package/dist/docs/assets/chunks/{theme.oV7rddEz.js → theme.DRciHmS1.js} +2 -2
  60. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.oRI8UwMC.js → timeline-definition-GMOUNBTQ.C4ePrY8-.js} +1 -1
  61. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.DmuWrIxN.js → vennDiagram-DHZGUBPP.Dzso6dEA.js} +1 -1
  62. package/dist/docs/assets/chunks/{wardley-RL74JXVD.CEBjM5ov.js → wardley-RL74JXVD.djgXR0ar.js} +1 -1
  63. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.m5zsCOF9.js → wardleyDiagram-NUSXRM2D.Bf2ICxjh.js} +1 -1
  64. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.cPN-587n.js → xychartDiagram-5P7HB3ND.DEH4BcVJ.js} +1 -1
  65. package/dist/docs/assets/{deployment.md.DDmjAVbg.js → deployment.md.KW0Ni_rY.js} +5 -5
  66. package/dist/docs/assets/{evals.md.OjKb7tNA.js → evals.md.DiljU__Z.js} +1 -1
  67. package/dist/docs/assets/{guides_jev.md.Ccw4pedT.js → guides_jev.md.CEqLgjj9.js} +2 -2
  68. package/dist/docs/assets/{guides_jev.md.Ccw4pedT.lean.js → guides_jev.md.CEqLgjj9.lean.js} +1 -1
  69. package/dist/docs/assets/{guides_mcp-oauth.md.ekpWOZCC.js → guides_mcp-oauth.md.DrGY92u4.js} +1 -1
  70. package/dist/docs/assets/{guides_slack.md.BqiGSYGX.js → guides_slack.md.BwXHURvY.js} +1 -1
  71. package/dist/docs/assets/index.md.CAruw_rp.js +26 -0
  72. package/dist/docs/assets/{index.md.CVRjO09Y.lean.js → index.md.CAruw_rp.lean.js} +1 -1
  73. package/dist/docs/assets/{quickstart.md.DaLk4ZIF.js → quickstart.md.CljDaJBi.js} +3 -3
  74. package/dist/docs/assets/{quickstart.md.DaLk4ZIF.lean.js → quickstart.md.CljDaJBi.lean.js} +1 -1
  75. package/dist/docs/assets/reference_access.md.CEtibb4i.js +1 -0
  76. package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +1 -0
  77. package/dist/docs/assets/{reference_agent-config.md.11E_xe--.js → reference_agent-config.md.Ck29qYNj.js} +1 -1
  78. package/dist/docs/assets/{reference_cli.md.DQ3dCgmk.js → reference_cli.md.BkdLRbXg.js} +5 -5
  79. package/dist/docs/assets/{reference_evals.md.DYKjGFi-.js → reference_evals.md.2BXeMiO2.js} +23 -3
  80. package/dist/docs/assets/{reference_evals.md.DYKjGFi-.lean.js → reference_evals.md.2BXeMiO2.lean.js} +1 -1
  81. package/dist/docs/assets/{reference_extensions.md.pEVj72Xo.js → reference_extensions.md.DI5X5x8p.js} +1 -1
  82. package/dist/docs/assets/{reference_limits.md.Da1HegjB.js → reference_limits.md.BCCnvt3o.js} +2 -2
  83. package/dist/docs/assets/{reference_limits.md.Da1HegjB.lean.js → reference_limits.md.BCCnvt3o.lean.js} +1 -1
  84. package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +1 -0
  85. package/dist/docs/building-with-agents.html +35 -35
  86. package/dist/docs/building-with-agents.md +5 -5
  87. package/dist/docs/changelog.html +36 -36
  88. package/dist/docs/changelog.md +10 -0
  89. package/dist/docs/deployment.html +41 -41
  90. package/dist/docs/deployment.md +8 -8
  91. package/dist/docs/evals.html +37 -37
  92. package/dist/docs/evals.md +4 -2
  93. package/dist/docs/guides/agent-to-agent.html +35 -35
  94. package/dist/docs/guides/bitbucket.html +35 -35
  95. package/dist/docs/guides/cloud-agents.html +36 -36
  96. package/dist/docs/guides/convert-automation.html +35 -35
  97. package/dist/docs/guides/github.html +35 -35
  98. package/dist/docs/guides/github.md +1 -1
  99. package/dist/docs/guides/gitlab.html +35 -35
  100. package/dist/docs/guides/hooks.html +35 -35
  101. package/dist/docs/guides/improve.html +36 -36
  102. package/dist/docs/guides/jev.html +36 -36
  103. package/dist/docs/guides/jev.md +5 -0
  104. package/dist/docs/guides/mcp-oauth.html +37 -37
  105. package/dist/docs/guides/mcp-oauth.md +2 -3
  106. package/dist/docs/guides/migrate.html +35 -35
  107. package/dist/docs/guides/migrate.md +2 -2
  108. package/dist/docs/guides/opentelemetry.html +35 -35
  109. package/dist/docs/guides/pagerduty.html +35 -35
  110. package/dist/docs/guides/slack.html +37 -37
  111. package/dist/docs/guides/slack.md +5 -6
  112. package/dist/docs/guides/webhooks.html +35 -35
  113. package/dist/docs/hashmap.json +1 -1
  114. package/dist/docs/hillclimbing.html +35 -35
  115. package/dist/docs/hillclimbing.md +2 -2
  116. package/dist/docs/index.html +51 -52
  117. package/dist/docs/index.md +17 -16
  118. package/dist/docs/llms-full.txt +120 -199
  119. package/dist/docs/llms.txt +0 -1
  120. package/dist/docs/package/skills/create-agent/SKILL.md +178 -0
  121. package/dist/docs/package/skills/evals/SKILL.md +145 -0
  122. package/dist/docs/package/skills/github/SKILL.md +133 -0
  123. package/dist/docs/package/skills/hillclimb/SKILL.md +63 -0
  124. package/dist/docs/package/skills/mcp-auth/SKILL.md +60 -0
  125. package/dist/docs/package/skills/migrate-v2/SKILL.md +394 -0
  126. package/dist/docs/package/skills/setup-slack/SKILL.md +136 -0
  127. package/dist/docs/quickstart.html +38 -38
  128. package/dist/docs/quickstart.md +5 -1
  129. package/dist/docs/reference/access.html +36 -36
  130. package/dist/docs/reference/access.md +3 -3
  131. package/dist/docs/reference/agent-config.html +37 -37
  132. package/dist/docs/reference/agent-config.md +1 -1
  133. package/dist/docs/reference/artifacts.html +35 -35
  134. package/dist/docs/reference/channels.html +35 -35
  135. package/dist/docs/reference/cli.html +41 -41
  136. package/dist/docs/reference/cli.md +6 -6
  137. package/dist/docs/reference/connections.html +35 -35
  138. package/dist/docs/reference/connections.md +1 -1
  139. package/dist/docs/reference/evals.html +57 -37
  140. package/dist/docs/reference/evals.md +35 -0
  141. package/dist/docs/reference/extensions.html +37 -37
  142. package/dist/docs/reference/extensions.md +2 -2
  143. package/dist/docs/reference/hooks.html +35 -35
  144. package/dist/docs/reference/http-api.html +35 -35
  145. package/dist/docs/reference/instructions.html +35 -35
  146. package/dist/docs/reference/limits.html +37 -37
  147. package/dist/docs/reference/limits.md +2 -2
  148. package/dist/docs/reference/memory.html +35 -35
  149. package/dist/docs/reference/playground.html +35 -35
  150. package/dist/docs/reference/project-layout.html +35 -35
  151. package/dist/docs/reference/prompt.html +35 -35
  152. package/dist/docs/reference/schedules.html +35 -35
  153. package/dist/docs/reference/sessions.html +35 -35
  154. package/dist/docs/reference/skills.html +35 -35
  155. package/dist/docs/reference/subagents.html +35 -35
  156. package/dist/docs/reference/tools.html +35 -35
  157. package/dist/docs/templates/agentic-owners.html +35 -35
  158. package/dist/docs/templates/security-reviewer.html +35 -35
  159. package/dist/docs/templates/thermo-quality-review.html +35 -35
  160. package/dist/docs/templates/thermo-review.html +35 -35
  161. package/dist/docs/templates/triage.html +35 -35
  162. package/dist/docs/troubleshooting.html +36 -36
  163. package/dist/docs/troubleshooting.md +4 -4
  164. package/dist/evals.d.ts +2 -2
  165. package/dist/extensions/jev/extension.d.ts +12 -2
  166. package/dist/extensions/jev/extension.d.ts.map +1 -1
  167. package/dist/extensions/jev/extension.js +4 -0
  168. package/dist/extensions/jev/lib/evaluate.d.ts +31 -4
  169. package/dist/extensions/jev/lib/evaluate.d.ts.map +1 -1
  170. package/dist/extensions/jev/lib/evaluate.js +18 -4
  171. package/dist/internal/cli/command.d.ts +1 -1
  172. package/dist/internal/cli/command.js +1 -1
  173. package/dist/internal/cli/commands/channels.js +6 -6
  174. package/dist/internal/cli/commands/develop.d.ts.map +1 -1
  175. package/dist/internal/cli/commands/develop.js +23 -14
  176. package/dist/internal/cli/commands/hosted.js +4 -4
  177. package/dist/internal/cli/commands/index.d.ts +1 -1
  178. package/dist/internal/cli/commands/index.d.ts.map +1 -1
  179. package/dist/internal/cli/commands/index.js +1 -1
  180. package/dist/internal/cli/commands/mcp.js +1 -1
  181. package/dist/internal/cli/commands/project.js +4 -4
  182. package/dist/internal/cli/commands/scaffold.d.ts.map +1 -1
  183. package/dist/internal/cli/commands/scaffold.js +9 -6
  184. package/dist/internal/cli/commands/serve.d.ts +1 -1
  185. package/dist/internal/cli/commands/serve.js +5 -5
  186. package/dist/internal/cli/commands/session.d.ts.map +1 -1
  187. package/dist/internal/cli/commands/session.js +12 -7
  188. package/dist/internal/cli/dispatch.d.ts +3 -3
  189. package/dist/internal/cli/dispatch.js +3 -3
  190. package/dist/internal/cli/errors.d.ts +1 -1
  191. package/dist/internal/cli/errors.d.ts.map +1 -1
  192. package/dist/internal/cli/errors.js +1 -1
  193. package/dist/internal/cli/flags.d.ts +2 -2
  194. package/dist/internal/cli/flags.d.ts.map +1 -1
  195. package/dist/internal/cli/flags.js +2 -2
  196. package/dist/internal/cli/help-command.d.ts +1 -1
  197. package/dist/internal/cli/help-command.js +2 -2
  198. package/dist/internal/cli/help.d.ts +7 -7
  199. package/dist/internal/cli/help.d.ts.map +1 -1
  200. package/dist/internal/cli/help.js +8 -8
  201. package/dist/internal/cli-ax.d.ts.map +1 -1
  202. package/dist/internal/cli-ax.js +3 -0
  203. package/dist/internal/cli-convert-automation.d.ts +1 -1
  204. package/dist/internal/cli-convert-automation.js +1 -1
  205. package/dist/internal/cli-migrate.d.ts +1 -1
  206. package/dist/internal/cli-migrate.js +1 -1
  207. package/dist/internal/cli-pagerduty.d.ts +1 -1
  208. package/dist/internal/cli-pagerduty.js +1 -1
  209. package/dist/internal/convert-automation/types.d.ts +1 -1
  210. package/dist/internal/convert-automation/types.js +1 -1
  211. package/dist/internal/deploy-client.d.ts +2 -2
  212. package/dist/internal/deploy-client.d.ts.map +1 -1
  213. package/dist/internal/init-project.d.ts +7 -3
  214. package/dist/internal/init-project.d.ts.map +1 -1
  215. package/dist/internal/init-project.js +53 -7
  216. package/dist/internal/init-scaffold.d.ts +2 -1
  217. package/dist/internal/init-scaffold.d.ts.map +1 -1
  218. package/dist/internal/init-scaffold.js +20 -7
  219. package/dist/internal/peer-connections.js +1 -1
  220. package/dist/internal/server.d.ts +1 -1
  221. package/dist/internal/session-cost.d.ts +4 -4
  222. package/dist/internal/session-cost.d.ts.map +1 -1
  223. package/dist/internal/session-cost.js +4 -4
  224. package/dist/internal/session-engine.d.ts +1 -1
  225. package/dist/internal/session-engine.js +1 -1
  226. package/dist/playground/assets/{index-_3zz3yh8.js → index-Cl9zvmmf.js} +40 -40
  227. package/dist/playground/assets/index-F8b5WvWi.css +1 -0
  228. package/dist/playground/index.html +2 -2
  229. package/dist/types.d.ts +5 -5
  230. package/docs/README.md +17 -16
  231. package/docs/changelog.md +10 -0
  232. package/docs/deployment.md +8 -8
  233. package/docs/evals.md +3 -1
  234. package/docs/guides/jev.md +5 -0
  235. package/docs/guides/mcp-oauth.md +1 -2
  236. package/docs/guides/slack.md +3 -4
  237. package/docs/quickstart.md +5 -1
  238. package/docs/reference/access.md +3 -3
  239. package/docs/reference/agent-config.md +1 -1
  240. package/docs/reference/cli.md +6 -6
  241. package/docs/reference/evals.md +35 -0
  242. package/docs/reference/extensions.md +2 -2
  243. package/docs/reference/limits.md +2 -2
  244. package/docs/troubleshooting.md +4 -4
  245. package/package.json +2 -8
  246. package/skills/cli/SKILL.md +15 -15
  247. package/skills/create-agent/SKILL.md +20 -19
  248. package/skills/debug/SKILL.md +4 -4
  249. package/skills/deploy/SKILL.md +2 -2
  250. package/skills/evals/SKILL.md +8 -8
  251. package/skills/framework-map/SKILL.md +3 -3
  252. package/skills/github/SKILL.md +7 -7
  253. package/skills/hillclimb/SKILL.md +4 -4
  254. package/skills/mcp-auth/SKILL.md +3 -3
  255. package/skills/migrate-v2/SKILL.md +40 -40
  256. package/skills/otel/SKILL.md +2 -2
  257. package/skills/setup-slack/SKILL.md +8 -8
  258. package/templates/agentic-owners/README.md +5 -5
  259. package/templates/agentic-owners/bot/tools/record_review.ts +1 -1
  260. package/templates/agentic-owners/package.json +1 -1
  261. package/templates/agents-md/README.md +4 -4
  262. package/templates/agents-md/package.json +1 -1
  263. package/templates/code-wiki/README.md +3 -3
  264. package/templates/code-wiki/package.json +1 -1
  265. package/templates/demo/README.md +3 -3
  266. package/templates/demo/package.json +1 -1
  267. package/templates/pr-autofixer/package.json +1 -1
  268. package/templates/security-help/README.md +5 -5
  269. package/templates/security-help/package.json +1 -1
  270. package/templates/security-reviewer/README.md +3 -3
  271. package/templates/security-reviewer/package.json +1 -1
  272. package/templates/thermo-quality-review/README.md +4 -4
  273. package/templates/thermo-quality-review/package.json +1 -1
  274. package/templates/thermo-review/README.md +4 -4
  275. package/templates/thermo-review/package.json +1 -1
  276. package/templates/triage/README.md +3 -3
  277. package/templates/triage/overlays/jira/README.md +3 -3
  278. package/templates/triage/overlays/linear/README.md +3 -3
  279. package/templates/triage/package.json +1 -1
  280. package/dist/docs/assets/changelog.md.fZ-NNFeJ.js +0 -1
  281. package/dist/docs/assets/changelog.md.fZ-NNFeJ.lean.js +0 -1
  282. package/dist/docs/assets/chunks/@localSearchIndexroot.mfzjiOsL.js +0 -1
  283. package/dist/docs/assets/chunks/channel.goFR5lbe.js +0 -1
  284. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.B2yLtFja.js +0 -1
  285. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.B2yLtFja.js +0 -1
  286. package/dist/docs/assets/chunks/clone.CztV97Wu.js +0 -1
  287. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.CZlVHdDZ.js +0 -1
  288. package/dist/docs/assets/guides_grokbot-agents.md.D0PpM_Gf.js +0 -15
  289. package/dist/docs/assets/guides_grokbot-agents.md.D0PpM_Gf.lean.js +0 -1
  290. package/dist/docs/assets/index.md.CVRjO09Y.js +0 -27
  291. package/dist/docs/assets/reference_access.md.CExlH_mR.js +0 -1
  292. package/dist/docs/assets/reference_access.md.CExlH_mR.lean.js +0 -1
  293. package/dist/docs/assets/troubleshooting.md.AGJ3jDzj.js +0 -1
  294. package/dist/docs/guides/grokbot-agents.html +0 -74
  295. package/dist/docs/guides/grokbot-agents.md +0 -129
  296. package/dist/extensions/cursor-grokbot-agents/extension.d.ts +0 -71
  297. package/dist/extensions/cursor-grokbot-agents/extension.d.ts.map +0 -1
  298. package/dist/extensions/cursor-grokbot-agents/extension.js +0 -64
  299. package/dist/extensions/cursor-grokbot-agents/lib/agents.d.ts +0 -11
  300. package/dist/extensions/cursor-grokbot-agents/lib/agents.d.ts.map +0 -1
  301. package/dist/extensions/cursor-grokbot-agents/lib/agents.js +0 -31
  302. package/dist/extensions/cursor-grokbot-agents/lib/backend.d.ts +0 -56
  303. package/dist/extensions/cursor-grokbot-agents/lib/backend.d.ts.map +0 -1
  304. package/dist/extensions/cursor-grokbot-agents/lib/backend.js +0 -139
  305. package/dist/extensions/cursor-grokbot-agents/lib/contacts.d.ts +0 -28
  306. package/dist/extensions/cursor-grokbot-agents/lib/contacts.d.ts.map +0 -1
  307. package/dist/extensions/cursor-grokbot-agents/lib/contacts.js +0 -46
  308. package/dist/extensions/cursor-grokbot-agents/lib/conversation.d.ts +0 -53
  309. package/dist/extensions/cursor-grokbot-agents/lib/conversation.d.ts.map +0 -1
  310. package/dist/extensions/cursor-grokbot-agents/lib/conversation.js +0 -186
  311. package/dist/extensions/cursor-grokbot-agents/lib/inputs.d.ts +0 -4
  312. package/dist/extensions/cursor-grokbot-agents/lib/inputs.d.ts.map +0 -1
  313. package/dist/extensions/cursor-grokbot-agents/lib/inputs.js +0 -15
  314. package/dist/extensions/cursor-grokbot-agents/lib/lock.d.ts +0 -12
  315. package/dist/extensions/cursor-grokbot-agents/lib/lock.d.ts.map +0 -1
  316. package/dist/extensions/cursor-grokbot-agents/lib/lock.js +0 -24
  317. package/dist/extensions/cursor-grokbot-agents/skills/consult.md +0 -40
  318. package/dist/extensions/cursor-grokbot-agents/tools/ask.d.ts +0 -4
  319. package/dist/extensions/cursor-grokbot-agents/tools/ask.d.ts.map +0 -1
  320. package/dist/extensions/cursor-grokbot-agents/tools/ask.js +0 -26
  321. package/dist/extensions/cursor-grokbot-agents/tools/check.d.ts +0 -4
  322. package/dist/extensions/cursor-grokbot-agents/tools/check.d.ts.map +0 -1
  323. package/dist/extensions/cursor-grokbot-agents/tools/check.js +0 -21
  324. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.d.ts +0 -4
  325. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.d.ts.map +0 -1
  326. package/dist/extensions/cursor-grokbot-agents/tools/interrupt.js +0 -13
  327. package/dist/extensions/cursor-grokbot-agents/tools/list.d.ts +0 -4
  328. package/dist/extensions/cursor-grokbot-agents/tools/list.d.ts.map +0 -1
  329. package/dist/extensions/cursor-grokbot-agents/tools/list.js +0 -22
  330. package/dist/playground/assets/index-BMpVzZzC.css +0 -1
  331. package/docs/guides/grokbot-agents.md +0 -134
  332. /package/dist/docs/assets/{deployment.md.DDmjAVbg.lean.js → deployment.md.KW0Ni_rY.lean.js} +0 -0
  333. /package/dist/docs/assets/{evals.md.OjKb7tNA.lean.js → evals.md.DiljU__Z.lean.js} +0 -0
  334. /package/dist/docs/assets/{guides_mcp-oauth.md.ekpWOZCC.lean.js → guides_mcp-oauth.md.DrGY92u4.lean.js} +0 -0
  335. /package/dist/docs/assets/{guides_slack.md.BqiGSYGX.lean.js → guides_slack.md.BwXHURvY.lean.js} +0 -0
  336. /package/dist/docs/assets/{reference_agent-config.md.11E_xe--.lean.js → reference_agent-config.md.Ck29qYNj.lean.js} +0 -0
  337. /package/dist/docs/assets/{reference_cli.md.DQ3dCgmk.lean.js → reference_cli.md.BkdLRbXg.lean.js} +0 -0
  338. /package/dist/docs/assets/{reference_extensions.md.pEVj72Xo.lean.js → reference_extensions.md.DI5X5x8p.lean.js} +0 -0
  339. /package/dist/docs/assets/{troubleshooting.md.AGJ3jDzj.lean.js → troubleshooting.md.CGOdNVAL.lean.js} +0 -0
@@ -1,4 +1,4 @@
1
- import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions.","frontmatter":{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions."},"headers":[],"relativePath":"guides/jev.md","filePath":"guides/jev.md"}'),t={name:"guides/jev.md"};function h(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="use-jev-in-review-tools" tabindex="-1">Use Jev in review tools <a class="header-anchor" href="#use-jev-in-review-tools" aria-label="Permalink to &quot;Use Jev in review tools&quot;">​</a></h1><p>Use Jev when a review workflow needs a typed decision instead of prose. A review agent can filter speculative findings, classify pull request risk, choose a reviewer, or decide whether a merge needs a documentation follow-up. Jev returns a choice, score, or probability; your TypeScript decides what happens next.</p><p>Set <code>TYPESAFE_API_KEY</code>. The default model is <code>jev-latest</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/jev.ts</span></span>
1
+ import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions.","frontmatter":{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions."},"headers":[],"relativePath":"guides/jev.md","filePath":"guides/jev.md"}'),t={name:"guides/jev.md"};function h(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="use-jev-in-review-tools" tabindex="-1">Use Jev in review tools <a class="header-anchor" href="#use-jev-in-review-tools" aria-label="Permalink to &quot;Use Jev in review tools&quot;">​</a></h1><div class="warning custom-block github-alert"><p class="custom-block-title">WARNING</p><p><strong>Experimental.</strong> <code>@grok/agent-sdk/extensions/jev</code> is experimental. Its exports and behavior can change in any release, without a deprecation period.</p></div><p>Use Jev when a review workflow needs a typed decision instead of prose. A review agent can filter speculative findings, classify pull request risk, choose a reviewer, or decide whether a merge needs a documentation follow-up. Jev returns a choice, score, or probability; your TypeScript decides what happens next.</p><p>Set <code>TYPESAFE_API_KEY</code>. The default model is <code>jev-latest</code>.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/jev.ts</span></span>
2
2
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> jev </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@grok/agent-sdk/extensions/jev&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
3
3
  <span class="line"></span>
4
4
  <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;"> jev</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>On Cursor-managed hosting, this mount adds <code>api.typesafe.ai</code> to the deployment&#39;s egress allowlist and <code>TYPESAFE_API_KEY</code> to the secrets it expects, so <code>agent-sdk deploy</code> warns until you set the key. A project that imports <code>decide</code> or <code>evaluate</code> without mounting the extension has to list <code>api.typesafe.ai</code> in <code>hosting.egressDomains</code> itself; see <a href="./../deployment.html#add-egress-and-secrets">Add egress and secrets</a>.</p><h2 id="start-only-the-review-turns-you-need" tabindex="-1">Start only the review turns you need <a class="header-anchor" href="#start-only-the-review-turns-you-need" aria-label="Permalink to &quot;Start only the review turns you need&quot;">​</a></h2><p>Call Jev from a channel hook before a model turn starts. When a pull request opens or becomes ready for review, this hook sends its title, body, labels, and filenames to Jev to decide whether the change needs security review. A result that clears the threshold starts the review turn; otherwise, the hook returns <code>null</code>, so the agent doesn&#39;t run or post to GitHub.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/channels/github.ts</span></span>
@@ -148,4 +148,4 @@ import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o
148
148
  <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;"> jev</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
149
149
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> harnessTools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
150
150
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> skills: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
151
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>harnessTools: false</code> removes <code>jev__evaluate</code> from discovery. <code>skills: false</code> removes both Jev skills. These switches do not remove the exported helpers, so project tools can still import <code>decide</code>, <code>above</code>, and <code>needsHuman</code>.</p><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to &quot;Practices&quot;">​</a></h2><ul><li><p>Pass the pull request title, a short summary, and the draft finding. Don&#39;t send the checkout.</p></li><li><p>Calibrate <code>above</code> and <code>needsHuman</code> on pull requests you have already labeled. <code>needsHuman</code> defaults to <code>0.7</code>.</p></li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../templates/agentic-owners.html">Agentic owners</a>: a risk tier, then the host approves or asks for reviewers</li><li><a href="./../templates/security-reviewer.html">Security reviewer</a>: a finding, or no comment</li><li><a href="./../templates/thermo-review.html">Thermo review</a>: bugs and breakage, posted the same way</li><li><a href="./../reference/cli.html#init">Code wiki</a>: documentation follow-ups after a merge</li><li><a href="./../evals.html">Evals</a>: checks on the full turn</li><li><a href="./github.html">GitHub agents</a>: how the review gets onto the pull request</li></ul>`,38)])])}const g=i(t,[["render",h]]);export{o as __pageData,g as default};
151
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>harnessTools: false</code> removes <code>jev__evaluate</code> from discovery. <code>skills: false</code> removes both Jev skills. These switches do not remove the exported helpers, so project tools can still import <code>decide</code>, <code>above</code>, and <code>needsHuman</code>.</p><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to &quot;Practices&quot;">​</a></h2><ul><li><p>Pass the pull request title, a short summary, and the draft finding. Don&#39;t send the checkout.</p></li><li><p>Calibrate <code>above</code> and <code>needsHuman</code> on pull requests you have already labeled. <code>needsHuman</code> defaults to <code>0.7</code>.</p></li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../templates/agentic-owners.html">Agentic owners</a>: a risk tier, then the host approves or asks for reviewers</li><li><a href="./../templates/security-reviewer.html">Security reviewer</a>: a finding, or no comment</li><li><a href="./../templates/thermo-review.html">Thermo review</a>: bugs and breakage, posted the same way</li><li><a href="./../reference/cli.html#init">Code wiki</a>: documentation follow-ups after a merge</li><li><a href="./../evals.html">Evals</a>: checks on the full turn</li><li><a href="./github.html">GitHub agents</a>: how the review gets onto the pull request</li></ul>`,39)])])}const g=i(t,[["render",h]]);export{o as __pageData,g as default};
@@ -1 +1 @@
1
- import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions.","frontmatter":{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions."},"headers":[],"relativePath":"guides/jev.md","filePath":"guides/jev.md"}'),t={name:"guides/jev.md"};function h(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[e("",38)])])}const g=i(t,[["render",h]]);export{o as __pageData,g as default};
1
+ import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const o=JSON.parse('{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions.","frontmatter":{"title":"Jev","description":"Use typed Jev decisions to filter findings, route pull requests, and gate review actions."},"headers":[],"relativePath":"guides/jev.md","filePath":"guides/jev.md"}'),t={name:"guides/jev.md"};function h(l,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[e("",39)])])}const g=i(t,[["render",h]]);export{o as __pageData,g as default};
@@ -35,4 +35,4 @@ import{_ as i,c as e,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const c
35
35
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> stock: result.structuredContent </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">??</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
36
36
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
37
37
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
38
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The model sees <code>get_stock</code>, not the unrestricted inventory server. Use this shape when code should own an allowlist or another side-effect gate.</p><h2 id="use-an-oauth-server-from-a-hosted-agent" tabindex="-1">Use an OAuth server from a hosted agent <a class="header-anchor" href="#use-an-oauth-server-from-a-hosted-agent" aria-label="Permalink to &quot;Use an OAuth server from a hosted agent&quot;">​</a></h2><p>Tokens from <code>mcp oauth</code> stay in the CLI config directory of the machine that authorized them, so a hosted deployment doesn&#39;t receive them. For a Cursor-managed agent, add the server under MCP in the Cursor dashboard, reach it through a <a href="./../reference/connections.html#cursor-account-mcp-connection"><code>cursorAccount: true</code> connection</a>, and connect it from <strong>Deployed Agents</strong> in the <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">dashboard</a>.</p><p>Anyone able to use that agent can reach the MCP capabilities you expose, so narrow the connection&#39;s <code>servers</code> list and keep privileged operations behind a host-side wrapper.</p><h2 id="choose-where-credentials-live" tabindex="-1">Choose where credentials live <a class="header-anchor" href="#choose-where-credentials-live" aria-label="Permalink to &quot;Choose where credentials live&quot;">​</a></h2><p>Use the credential shape that matches who should own access:</p><ul><li><p>Choose <code>cursorAccount: true</code> for connectors already authorized under MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.</p></li><li><p>Choose <code>url</code> with <code>oauth: true</code> when the machine running <code>agent-sdk serve</code> should hold OAuth credentials.</p></li><li><p>Choose <code>url</code> with static <code>headers</code> when the server uses an API key or bearer token instead of OAuth.</p></li></ul><p>Host OAuth and per-session <code>auth</code> are different identity models and cannot be combined on one connection. Use per-session auth when each caller needs a different downstream identity.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>: the companion setup procedure for coding agents</li><li><a href="./../reference/connections.html">MCP connections</a>: transports, account connectors, per-session auth, and tool filtering</li><li><a href="./../reference/cli.html#mcp-oauth">CLI reference</a>: OAuth command flags and browser callback behavior</li><li><a href="./../deployment.html">Deployment</a>: hosted egress and secrets</li><li><a href="./../troubleshooting.html">Troubleshooting</a>: authorization symptoms and remedies</li></ul>`,28)])])}const E=i(t,[["render",h]]);export{c as __pageData,E as default};
38
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The model sees <code>get_stock</code>, not the unrestricted inventory server. Use this shape when code should own an allowlist or another side-effect gate.</p><h2 id="use-an-oauth-server-from-a-hosted-agent" tabindex="-1">Use an OAuth server from a hosted agent <a class="header-anchor" href="#use-an-oauth-server-from-a-hosted-agent" aria-label="Permalink to &quot;Use an OAuth server from a hosted agent&quot;">​</a></h2><p>Tokens from <code>mcp oauth</code> stay in the CLI config directory of the machine that authorized them, so a hosted deployment doesn&#39;t receive them. For a Cursor-managed agent, add the server under MCP in the Cursor dashboard, reach it through a <a href="./../reference/connections.html#cursor-account-mcp-connection"><code>cursorAccount: true</code> connection</a>, and connect it from <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a>.</p><p>Anyone able to use that agent can reach the MCP capabilities you expose, so narrow the connection&#39;s <code>servers</code> list and keep privileged operations behind a host-side wrapper.</p><h2 id="choose-where-credentials-live" tabindex="-1">Choose where credentials live <a class="header-anchor" href="#choose-where-credentials-live" aria-label="Permalink to &quot;Choose where credentials live&quot;">​</a></h2><p>Use the credential shape that matches who should own access:</p><ul><li><p>Choose <code>cursorAccount: true</code> for connectors already authorized under MCP in the Cursor dashboard. Their tokens stay on the Cursor backend.</p></li><li><p>Choose <code>url</code> with <code>oauth: true</code> when the machine running <code>agent-sdk serve</code> should hold OAuth credentials.</p></li><li><p>Choose <code>url</code> with static <code>headers</code> when the server uses an API key or bearer token instead of OAuth.</p></li></ul><p>Host OAuth and per-session <code>auth</code> are different identity models and cannot be combined on one connection. Use per-session auth when each caller needs a different downstream identity.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../../skills/mcp-auth/SKILL.html"><code>skills/mcp-auth/SKILL.md</code></a>: the companion setup procedure for coding agents</li><li><a href="./../reference/connections.html">MCP connections</a>: transports, account connectors, per-session auth, and tool filtering</li><li><a href="./../reference/cli.html#mcp-oauth">CLI reference</a>: OAuth command flags and browser callback behavior</li><li><a href="./../deployment.html">Deployment</a>: hosted egress and secrets</li><li><a href="./../troubleshooting.html">Troubleshooting</a>: authorization symptoms and remedies</li></ul>`,28)])])}const E=i(t,[["render",h]]);export{c as __pageData,E as default};
@@ -73,7 +73,7 @@ import{_ as a,c as i,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c
73
73
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {};</span></span>
74
74
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>Use the IDs on the hook <code>ctx</code> when handling an event, and <code>ctx.host.slack.getClient()</code> when a tool needs the Slack Web API.</p><h2 id="connect" tabindex="-1">Connect <a class="header-anchor" href="#connect" aria-label="Permalink to &quot;Connect&quot;">​</a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
75
75
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
76
- <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TRIAGE</span></span></code></pre></div><p>After you sign in, <code>slack create</code> opens <strong>Add Slack to this agent</strong> in the browser and writes the resulting tokens to <code>.env.local</code> without printing them. You can open the same wizard from <strong>Integrations</strong> on <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">Deployed Agents</a>.</p><p>If Slack requires workspace-admin approval, keep <code>slack create</code> running and open the <strong>Request approval</strong> link printed by the CLI. Installing from the dashboard doesn&#39;t send that request for you. After an admin approves it, return to the dashboard&#39;s <strong>Add Slack</strong> wizard and select <strong>Retry</strong>.</p><h3 id="choose-the-bot-scopes" tabindex="-1">Choose the bot scopes <a class="header-anchor" href="#choose-the-bot-scopes" aria-label="Permalink to &quot;Choose the bot scopes&quot;">​</a></h3><p>A Cursor-managed app requests these bot scopes by default:</p><p><code>app_mentions:read</code>, <code>assistant:write</code>, <code>channels:history</code>, <code>channels:read</code>, <code>chat:write</code>, <code>files:read</code>, <code>files:write</code>, <code>groups:history</code>, <code>groups:read</code>, <code>im:history</code>, <code>im:read</code>, <code>im:write</code>, <code>mpim:history</code>, <code>reactions:read</code>, <code>reactions:write</code>, <code>usergroups:read</code>, <code>users:read</code>, <code>users:read.email</code></p><p>To request a different list, set <code>botScopes</code> in <code>slack-manifest.json</code> at the root of the agent project. The app then requests exactly that list:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
76
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TRIAGE</span></span></code></pre></div><p>After you sign in, <code>slack create</code> opens <strong>Add Slack to this agent</strong> in the browser and writes the resulting tokens to <code>.env.local</code> without printing them. You can open the same wizard from <strong>Integrations</strong> on <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a>.</p><p>If Slack requires workspace-admin approval, keep <code>slack create</code> running and open the <strong>Request approval</strong> link printed by the CLI. Installing from <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> doesn&#39;t send that request for you. After an admin approves it, return to the <strong>Add Slack</strong> wizard there and select <strong>Retry</strong>.</p><h3 id="choose-the-bot-scopes" tabindex="-1">Choose the bot scopes <a class="header-anchor" href="#choose-the-bot-scopes" aria-label="Permalink to &quot;Choose the bot scopes&quot;">​</a></h3><p>A Cursor-managed app requests these bot scopes by default:</p><p><code>app_mentions:read</code>, <code>assistant:write</code>, <code>channels:history</code>, <code>channels:read</code>, <code>chat:write</code>, <code>files:read</code>, <code>files:write</code>, <code>groups:history</code>, <code>groups:read</code>, <code>im:history</code>, <code>im:read</code>, <code>im:write</code>, <code>mpim:history</code>, <code>reactions:read</code>, <code>reactions:write</code>, <code>usergroups:read</code>, <code>users:read</code>, <code>users:read.email</code></p><p>To request a different list, set <code>botScopes</code> in <code>slack-manifest.json</code> at the root of the agent project. The app then requests exactly that list:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
77
77
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;botScopes&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
78
78
  <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;app_mentions:read&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
79
79
  <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;assistant:write&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
@@ -0,0 +1,26 @@
1
+ import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const o="/docs/architecture.svg",g=JSON.parse('{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK.","frontmatter":{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),r={name:"index.md"};function i(p,e,l,d,c,h){return s(),a("div",null,[...e[0]||(e[0]=[n('<h1 id="agent-sdk" tabindex="-1">Agent SDK <a class="header-anchor" href="#agent-sdk" aria-label="Permalink to &quot;Agent SDK&quot;">​</a></h1><p>Agent SDK lets you define, test, and deploy agents as code. It uses the Cursor SDK harness that powers Bugbot, Security Review, Approval Bot, and Rollouts.</p><p>An Agent SDK project is a folder of Markdown and TypeScript. Combine deterministic code with model judgment, then make the bot or agent available in source control, Slack, issue trackers, and Cursor.</p><p>After you deploy an agent, open <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> to see it and manage it.</p><h2 id="why-use-it" tabindex="-1">Why use it <a class="header-anchor" href="#why-use-it" aria-label="Permalink to &quot;Why use it&quot;">​</a></h2><ul><li><p><strong>Bots and agents live in your repo.</strong> Instructions, tools, and evals are files you review, version, and ship like the rest of your code.</p></li><li><p><strong>Cursor runs the loop.</strong> You write the instructions and tools. Your agent gets Cursor&#39;s models, tool calling, skills, MCP, and subagents. Each turn runs on your host.</p></li><li><p><strong>Use it where you work.</strong> Trigger a project from source-control events, Slack threads, custom webhooks, or schedules.</p></li><li><p><strong>Test normal TypeScript.</strong> Add evals and unit tests without a separate configuration language.</p></li><li><p><strong>Choose where it runs.</strong> Deploy to Cursor-managed hosting or run the process on your infrastructure.</p></li></ul><h2 id="when-to-use-agent-sdk" tabindex="-1">When to use Agent SDK <a class="header-anchor" href="#when-to-use-agent-sdk" aria-label="Permalink to &quot;When to use Agent SDK&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Cursor Automations</th><th>Grok Bot</th><th>Agent SDK</th></tr></thead><tbody><tr><td><strong>Use for</strong></td><td>Repeatable jobs driven by a prompt and a trigger</td><td>Interactive agents that work with you in Cursor</td><td>Agents that need custom code, integrations, tests, or deployment choices</td></tr><tr><td><strong>You define</strong></td><td>A prompt, model, and trigger in the dashboard</td><td>Instructions, skills, and connected tools in the app</td><td>A versioned Markdown and TypeScript project</td></tr><tr><td><strong>Where it runs</strong></td><td>Cursor-managed</td><td>Cursor-managed</td><td>Cursor-managed hosting or your infrastructure</td></tr><tr><td><strong>Choose it when</strong></td><td>The job fits a schedule or event trigger</td><td>You want an agent you can configure and talk to without creating a software project</td><td>You want deterministic code around model judgment and a project your team can review and test</td></tr></tbody></table><h2 id="architecture" tabindex="-1">Architecture <a class="header-anchor" href="#architecture" aria-label="Permalink to &quot;Architecture&quot;">​</a></h2><p>Define the project in source control. Run execution, inference, and sandboxing on Cursor infrastructure or on your own host.</p><p><img src="'+o+`" alt="Agent SDK architecture: you bring the agent as code, and the platform provides triggers, runtime, integrations, and operations"></p><h2 id="get-started" tabindex="-1">Get started <a class="header-anchor" href="#get-started" aria-label="Permalink to &quot;Get started&quot;">​</a></h2><p>Install <code>@grok/agent-sdk</code>, then start with <code>agent-sdk init</code> and <code>agent-sdk dev</code>. The package was <code>@cursor/bdk</code> before.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>npm install --global @grok/agent-sdk</span></span>
2
+ <span class="line"><span>agent-sdk init ./my-bot</span></span>
3
+ <span class="line"><span>cd my-bot</span></span>
4
+ <span class="line"><span>agent-sdk dev</span></span></code></pre></div><p>Open the project in Cursor. Agent SDK projects use <code>bot/</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>my-bot/</span></span>
5
+ <span class="line"><span>├── .gitignore</span></span>
6
+ <span class="line"><span>├── AGENTS.md</span></span>
7
+ <span class="line"><span>├── package.json</span></span>
8
+ <span class="line"><span>├── tsconfig.json</span></span>
9
+ <span class="line"><span>├── bot/</span></span>
10
+ <span class="line"><span>│ ├── agent.ts # model and local harness config</span></span>
11
+ <span class="line"><span>│ ├── instructions.md # the system prompt</span></span>
12
+ <span class="line"><span>│ ├── tools/</span></span>
13
+ <span class="line"><span>│ │ └── echo.ts # demo tool</span></span>
14
+ <span class="line"><span>│ ├── hooks/</span></span>
15
+ <span class="line"><span>│ │ └── memory.ts # shared memory journal</span></span>
16
+ <span class="line"><span>│ ├── channels/</span></span>
17
+ <span class="line"><span>│ ├── lib/ # shared code, never discovered</span></span>
18
+ <span class="line"><span>│ ├── mcp-connections/</span></span>
19
+ <span class="line"><span>│ ├── sandbox/</span></span>
20
+ <span class="line"><span>│ │ └── workspace/</span></span>
21
+ <span class="line"><span>│ ├── schedules/</span></span>
22
+ <span class="line"><span>│ ├── skills/</span></span>
23
+ <span class="line"><span>│ └── subagents/</span></span>
24
+ <span class="line"><span>└── evals/</span></span>
25
+ <span class="line"><span> ├── evals.config.ts</span></span>
26
+ <span class="line"><span> └── smoke.eval.ts</span></span></code></pre></div><p>Describe your bot or agent in Cursor, or edit the files yourself.</p><h2 id="next-steps" tabindex="-1">Next steps <a class="header-anchor" href="#next-steps" aria-label="Permalink to &quot;Next steps&quot;">​</a></h2><ul><li><p><a href="./quickstart.html">Build your first PR reviewer</a>: a working GitHub reviewer, one step at a time.</p></li><li><p>Start from a template: <a href="./templates/security-reviewer.html">security reviewer</a>, <a href="./templates/thermo-review.html">Thermo review</a>, <a href="./templates/thermo-quality-review.html">Thermo quality review</a>, <a href="./templates/agentic-owners.html">owners-policy approver</a>, <a href="./templates/triage.html">issue triager</a>.</p></li><li><p><a href="./guides/convert-automation.html">Convert a Cursor Automation</a>: export an Automation from the dashboard into a project you own.</p></li><li><p><a href="./building-with-agents.html">Build agents with agents</a>: hand the build to a coding agent with the package&#39;s bundled skills.</p></li><li><p><a href="./reference/project-layout.html">Project layout</a> and <a href="./reference/cli.html">CLI</a>: every folder and every command.</p></li><li><p><a href="./reference/access.html">Access</a>: Viewer, Editor, and Owner on a deployed bot.</p></li></ul>`,19)])])}const m=t(r,[["render",i]]);export{g as __pageData,m as default};
@@ -1 +1 @@
1
- import{_ as t,c as s,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const o="/docs/architecture.svg",g=JSON.parse('{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK.","frontmatter":{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),r={name:"index.md"};function i(p,e,l,d,c,h){return a(),s("div",null,[...e[0]||(e[0]=[n("",18)])])}const m=t(r,[["render",i]]);export{g as __pageData,m as default};
1
+ import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const o="/docs/architecture.svg",g=JSON.parse('{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK.","frontmatter":{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),r={name:"index.md"};function i(p,e,l,d,c,h){return s(),a("div",null,[...e[0]||(e[0]=[n("",19)])])}const m=t(r,[["render",i]]);export{g as __pageData,m as default};
@@ -1,4 +1,4 @@
1
- import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Build a PR reviewer","description":"Create an Agent SDK bot or agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build a PR reviewer","description":"Create an Agent SDK bot or agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),h={name:"quickstart.md"};function l(p,s,e,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="build-a-pr-reviewer-with-agent-sdk" tabindex="-1">Build a PR reviewer with Agent SDK <a class="header-anchor" href="#build-a-pr-reviewer-with-agent-sdk" aria-label="Permalink to &quot;Build a PR reviewer with Agent SDK&quot;">​</a></h1><p>Build a PR reviewer with the Agent SDK. It classifies changes as <code>trivial</code>, <code>moderate</code>, or <code>large</code>, then approves safe changes or requests human review.</p><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><ul><li><p>Node 22.13 or newer.</p></li><li><p>The <code>@grok/agent-sdk</code> package:</p></li></ul><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>npm install -g @grok/agent-sdk</span></span></code></pre></div><ul><li>A Cursor credential for model turns. Sign in once:</li></ul><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk login</span></span></code></pre></div><h2 id="create-and-run-the-project" tabindex="-1">Create and run the project <a class="header-anchor" href="#create-and-run-the-project" aria-label="Permalink to &quot;Create and run the project&quot;">​</a></h2><p>The preferred Agent SDK workflow uses <code>agent-sdk init</code> and <code>agent-sdk dev</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk init ./pr-reviewer</span></span>
1
+ import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Build a PR reviewer","description":"Create an Agent SDK bot or agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build a PR reviewer","description":"Create an Agent SDK bot or agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),h={name:"quickstart.md"};function l(e,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="build-a-pr-reviewer-with-agent-sdk" tabindex="-1">Build a PR reviewer with Agent SDK <a class="header-anchor" href="#build-a-pr-reviewer-with-agent-sdk" aria-label="Permalink to &quot;Build a PR reviewer with Agent SDK&quot;">​</a></h1><p>Build a PR reviewer with the Agent SDK. It classifies changes as <code>trivial</code>, <code>moderate</code>, or <code>large</code>, then approves safe changes or requests human review.</p><h2 id="prerequisites" tabindex="-1">Prerequisites <a class="header-anchor" href="#prerequisites" aria-label="Permalink to &quot;Prerequisites&quot;">​</a></h2><ul><li><p>Node 22.13 or newer.</p></li><li><p>The <code>@grok/agent-sdk</code> package:</p></li></ul><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>npm install -g @grok/agent-sdk</span></span></code></pre></div><ul><li>A Cursor credential for model turns. Sign in once:</li></ul><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk login</span></span></code></pre></div><h2 id="create-and-run-the-project" tabindex="-1">Create and run the project <a class="header-anchor" href="#create-and-run-the-project" aria-label="Permalink to &quot;Create and run the project&quot;">​</a></h2><p>The preferred Agent SDK workflow uses <code>agent-sdk init</code> and <code>agent-sdk dev</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk init ./pr-reviewer</span></span>
2
2
  <span class="line"><span>cd pr-reviewer</span></span>
3
3
  <span class="line"><span>agent-sdk dev</span></span></code></pre></div><p>Keep <code>agent-sdk dev</code> running. In a second terminal, run:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk run --dir . --message &quot;Introduce yourself in one sentence.&quot;</span></span></code></pre></div><p>Confirm the agent replies.</p><h2 id="add-review-instructions" tabindex="-1">Add review instructions <a class="header-anchor" href="#add-review-instructions" aria-label="Permalink to &quot;Add review instructions&quot;">​</a></h2><p>Replace <code>bot/instructions.md</code>:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># PR reviewer</span></span>
4
4
  <span class="line"></span>
@@ -150,7 +150,7 @@ import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const g
150
150
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> REVIEW_ACTIONS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Set</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">([</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;opened&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;reopened&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ready_for_review&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span>
151
151
  <span class="line"></span>
152
152
  <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;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
153
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;bdk-pr-reviewer&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
153
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> botName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;agent-sdk-pr-reviewer&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
154
154
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorAccount: { repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;acme/checkout&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] },</span></span>
155
155
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> onPullRequest</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">pr</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
156
156
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">REVIEW_ACTIONS</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">has</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(pr.action) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">||</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> pr.draft) {</span></span>
@@ -167,4 +167,4 @@ import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const g
167
167
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
168
168
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Channel-turn <code>context</code> is a <code>readonly string[]</code>, so wrap each context block in an array. The <code>context</code> label under <code>progress.commitStatus</code> is a separate string option.</p><p>Keep <code>agent-sdk dev</code> running. In a second terminal, replay an open pull request. Pull access is enough; repo admin isn&#39;t required:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk github replay https://github.com/acme/checkout/pull/42 \\</span></span>
169
169
  <span class="line"><span> --dir . --action opened</span></span></code></pre></div><p>Open the playground and confirm <code>Review acme/checkout#42</code> contains the trigger, both tool calls, and the verdict.</p><h2 id="run-options" tabindex="-1">Run options <a class="header-anchor" href="#run-options" aria-label="Permalink to &quot;Run options&quot;">​</a></h2><ol><li><strong>CLI message</strong></li></ol><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span> agent-sdk run --dir . --message &quot;Review https://github.com/acme/checkout/pull/42&quot;</span></span></code></pre></div><ol start="2"><li><strong>Local replay</strong></li></ol><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span> agent-sdk github replay https://github.com/acme/checkout/pull/42 \\</span></span>
170
- <span class="line"><span> --dir . --action opened</span></span></code></pre></div><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./evals.html">Evals</a>: freeze these two PRs as regression checks so prompt changes can&#39;t flip a verdict</li><li><a href="./reference/tools.html">Tools</a>: more on typed tools, dry-run effects, and direct calls</li><li><a href="./guides/github.html">GitHub</a>: fixtures, forwarding, and pulling events from Cursor</li><li><a href="./building-with-agents.html">Building agents with agents</a>: have a coding agent extend the project for you</li></ul>`,48)])])}const o=i(h,[["render",l]]);export{g as __pageData,o as default};
170
+ <span class="line"><span> --dir . --action opened</span></span></code></pre></div><h2 id="deploy-the-reviewer" tabindex="-1">Deploy the reviewer <a class="header-anchor" href="#deploy-the-reviewer" aria-label="Permalink to &quot;Deploy the reviewer&quot;">​</a></h2><p>Follow <a href="./deployment.html">Deployment</a> and run <code>agent-sdk deploy</code>. After the command reports the runtime is running, open <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> to see the reviewer and manage it.</p><h2 id="where-to-go-next" tabindex="-1">Where to go next <a class="header-anchor" href="#where-to-go-next" aria-label="Permalink to &quot;Where to go next&quot;">​</a></h2><ul><li><a href="./evals.html">Evals</a>: freeze these two PRs as regression checks so prompt changes can&#39;t flip a verdict</li><li><a href="./reference/tools.html">Tools</a>: more on typed tools, dry-run effects, and direct calls</li><li><a href="./guides/github.html">GitHub</a>: fixtures, forwarding, and pulling events from Cursor</li><li><a href="./building-with-agents.html">Building agents with agents</a>: have a coding agent extend the project for you</li></ul>`,50)])])}const o=i(h,[["render",l]]);export{g as __pageData,o as default};
@@ -1 +1 @@
1
- import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Build a PR reviewer","description":"Create an Agent SDK bot or agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build a PR reviewer","description":"Create an Agent SDK bot or agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),h={name:"quickstart.md"};function l(p,s,e,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[t("",48)])])}const o=i(h,[["render",l]]);export{g as __pageData,o as default};
1
+ import{_ as i,c as a,o as n,a3 as t}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Build a PR reviewer","description":"Create an Agent SDK bot or agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events.","frontmatter":{"title":"Build a PR reviewer","description":"Create an Agent SDK bot or agent that reviews pull requests by complexity, approves safe changes, and handles GitHub webhook events."},"headers":[],"relativePath":"quickstart.md","filePath":"quickstart.md"}'),h={name:"quickstart.md"};function l(e,s,p,k,r,E){return n(),a("div",null,[...s[0]||(s[0]=[t("",50)])])}const o=i(h,[["render",l]]);export{g as __pageData,o as default};
@@ -0,0 +1 @@
1
+ import{_ as t,c as a,o,a3 as r}from"./chunks/framework.BNw1pucY.js";const m=JSON.parse('{"title":"Access","description":"Who can view, deploy, and manage a deployed bot.","frontmatter":{"title":"Access","description":"Who can view, deploy, and manage a deployed bot."},"headers":[],"relativePath":"reference/access.md","filePath":"reference/access.md"}'),d={name:"reference/access.md"};function s(c,e,n,l,h,i){return o(),a("div",null,[...e[0]||(e[0]=[r('<h1 id="access" tabindex="-1">Access <a class="header-anchor" href="#access" aria-label="Permalink to &quot;Access&quot;">​</a></h1><p>These rules apply only when access checks are on for the team.</p><p>A deployed bot has three access levels. <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> shows Viewer, Editor, and Owner. The API returns <code>viewer</code>, <code>deployer</code>, and <code>admin</code>. <code>admin</code> is Owner. A write also accepts <code>owner</code> for that role, and <code>editor</code> for Editor. The response value for Owner becomes <code>owner</code> in a later change, after <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> shows <code>owner</code>.</p><table tabindex="0"><thead><tr><th>Dashboard</th><th>API value</th><th>What it allows</th></tr></thead><tbody><tr><td>Viewer</td><td><code>viewer</code></td><td>Open the bot</td></tr><tr><td>Editor</td><td><code>deployer</code></td><td>Deploy, stop, and restart</td></tr><tr><td>Owner</td><td><code>admin</code></td><td>Editor, plus secrets and who else has access</td></tr></tbody></table><p>A team Admin can manage every bot that team owns. The same person cannot manage a bot another team published, including a catalog bot installed into their team.</p><p>Today every member of the owning team has Owner access. Enforcement does not remove deploy, secrets, or access management until that team grant is narrowed.</p>',6)])])}const f=t(d,[["render",s]]);export{m as __pageData,f as default};
@@ -0,0 +1 @@
1
+ import{_ as t,c as a,o,a3 as r}from"./chunks/framework.BNw1pucY.js";const m=JSON.parse('{"title":"Access","description":"Who can view, deploy, and manage a deployed bot.","frontmatter":{"title":"Access","description":"Who can view, deploy, and manage a deployed bot."},"headers":[],"relativePath":"reference/access.md","filePath":"reference/access.md"}'),d={name:"reference/access.md"};function s(c,e,n,l,h,i){return o(),a("div",null,[...e[0]||(e[0]=[r("",6)])])}const f=t(d,[["render",s]]);export{m as __pageData,f as default};
@@ -14,7 +14,7 @@ import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k
14
14
  <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>
15
15
  <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>
16
16
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
17
- <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="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.</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. 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: 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). The boundary is in the tools, not in the prompt, so it holds when an injected prompt tells the model to ignore its instructions.</p><p>BDK runs the file tools (<code>read</code>, <code>edit</code>, <code>delete</code>, <code>grep</code>, <code>glob</code>, <code>ls</code>) in the serve process, outside the sandbox. With <code>local.sandbox</code> on, these tools refuse a path outside the session workspace, after symlinks, with <code>Path is outside the workspace</code>. The read tools can also read the large-output files that web search and web fetch write. With <code>local.sandbox</code> off, the file tools can read and write any path the serve process can.</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 parent directory for local harness workspaces. Each session uses <code>&lt;cwd&gt;/&lt;sessionId&gt;</code> unless a per-send <code>workspaceDir</code> overrides it.</p><p>Session workspaces are real Cursor project directories. The harness loads <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. An agent nested in another git repo (a monorepo package) defaults to a per-project cache directory under <code>~/.cache</code> when you omit <code>cwd</code>, so the enclosing checkout does not leak rules, skills, or MCP servers into the turn. A standalone git root keeps the in-project session workspace. Point <code>cwd</code> at a checkout only when the agent should inherit that tree.</p><h2 id="persistent-hosting" tabindex="-1">Persistent hosting <a class="header-anchor" href="#persistent-hosting" aria-label="Permalink to &quot;Persistent hosting&quot;">​</a></h2><p>By default, a hosted deployment starts a runtime when an event arrives and stops it when the work ends. Set <code>persistent: true</code> to keep one long-lived runtime for the deployment instead, with its state directory on the runtime&#39;s own disk. On a redeploy, the new version starts beside the old one on the same state, and the old version stops after the new one takes over. Each team can have one persistent deployment. Local serving ignores the flag.</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>
17
+ <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="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.</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. 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: 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). The boundary is in the tools, not in the prompt, so it holds when an injected prompt tells the model to ignore its instructions.</p><p>Agent SDK runs the file tools (<code>read</code>, <code>edit</code>, <code>delete</code>, <code>grep</code>, <code>glob</code>, <code>ls</code>) in the serve process, outside the sandbox. With <code>local.sandbox</code> on, these tools refuse a path outside the session workspace, after symlinks, with <code>Path is outside the workspace</code>. The read tools can also read the large-output files that web search and web fetch write. With <code>local.sandbox</code> off, the file tools can read and write any path the serve process can.</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 parent directory for local harness workspaces. Each session uses <code>&lt;cwd&gt;/&lt;sessionId&gt;</code> unless a per-send <code>workspaceDir</code> overrides it.</p><p>Session workspaces are real Cursor project directories. The harness loads <code>AGENTS.md</code> and <code>.cursor</code> config from ancestor directories. An agent nested in another git repo (a monorepo package) defaults to a per-project cache directory under <code>~/.cache</code> when you omit <code>cwd</code>, so the enclosing checkout does not leak rules, skills, or MCP servers into the turn. A standalone git root keeps the in-project session workspace. Point <code>cwd</code> at a checkout only when the agent should inherit that tree.</p><h2 id="persistent-hosting" tabindex="-1">Persistent hosting <a class="header-anchor" href="#persistent-hosting" aria-label="Permalink to &quot;Persistent hosting&quot;">​</a></h2><p>By default, a hosted deployment starts a runtime when an event arrives and stops it when the work ends. Set <code>persistent: true</code> to keep one long-lived runtime for the deployment instead, with its state directory on the runtime&#39;s own disk. On a redeploy, the new version starts beside the old one on the same state, and the old version stops after the new one takes over. Each team can have one persistent deployment. Local serving ignores the flag.</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>
18
18
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> persistent: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
19
19
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> hosting: { image: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;incident-bot-base&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
20
20
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>hosting.image</code> names a container image that your team pushed with <code>agent-sdk image push</code>. The agent runs inside that image instead of the default Node 22 image. Only persistent agents can use it, and <code>deploy</code> rejects <code>hosting.image</code> on any other agent. A deploy pins the image it finds, so after you push a new image under the same name, deploy again to pick it up.</p><h2 id="custom-filesystem" tabindex="-1">Custom filesystem <a class="header-anchor" href="#custom-filesystem" aria-label="Permalink to &quot;Custom filesystem&quot;">​</a></h2><p><code>fs</code> is mounted at <code>/</code>. Agent SDK mounts <code>/tmp</code> and <code>/agent/skills</code> over it.</p><p><code>root</code> is the deprecated name of <code>fs</code>. Set one of them. A tree that already has <code>/agent/skills</code> fails session start unless <code>skills</code> is <code>false</code>.</p><p>Semantic search is removed. Use Grep. See <a href="#migrate-off-semantic-search">Migrate off semantic search</a>.</p><h2 id="harness-tools" tabindex="-1">Harness tools <a class="header-anchor" href="#harness-tools" aria-label="Permalink to &quot;Harness tools&quot;">​</a></h2><p>Use <code>tools</code> to limit which built-in Cursor harness tools the model can call. Omit it to keep the standard toolset. When you set it, the model gets only the tools you list. An empty list disables all native built-in tools. New platform tools stay disabled until you add them.</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>
@@ -8,7 +8,7 @@ import{_ as t,c as a,o,a3 as d}from"./chunks/framework.BNw1pucY.js";const u=JSON
8
8
  <span class="line"><span> [--peers-url &lt;url&gt;]</span></span>
9
9
  <span class="line"><span> [--no-schedules] [--no-playground] [--no-docs]</span></span>
10
10
  <span class="line"><span> [--cursor-events --repo &lt;owner/name&gt;]...</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--port &lt;n&gt;</code></td><td>Listen on this port. The default is <code>3000</code>; <code>0</code> selects an available port. When an omitted default is occupied, the CLI selects the next port. An occupied explicit port fails with a next-port hint.</td></tr><tr><td><code>--host &lt;host&gt;</code></td><td>Bind this host. The default is loopback-only <code>127.0.0.1</code>.</td></tr><tr><td><code>--mode multi</code></td><td>Mount projects at <code>/&lt;slug&gt;/v1/*</code> and <code>/&lt;slug&gt;/playground</code>, with an index at <code>/</code>. This is the default.</td></tr><tr><td><code>--mode single</code></td><td>Mount one project at <code>/v1/*</code> and <code>/playground</code>. Declared peers are omitted with a warning unless <code>--peers-url</code> is set.</td></tr><tr><td><code>--dev</code></td><td>Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and enable local playground access.</td></tr><tr><td><code>--state-root &lt;path&gt;</code></td><td>Store local sessions, streams, workspaces, and channel state here. Keep durable state outside a repository whose rules shouldn&#39;t reach agent workspaces.</td></tr><tr><td><code>--bearer-token &lt;secret&gt;</code></td><td>Require this token on routes without authored authentication. Mutually exclusive with <code>--allow-anonymous</code>.</td></tr><tr><td><code>--allow-anonymous</code></td><td>Admit callers as one anonymous principal. Use it only behind a trusted network boundary.</td></tr><tr><td><code>--allow-anonymous-cursor-github</code></td><td>Let anonymous callers use sessions with a Cursor account&#39;s repository-scoped GitHub credential. Requires an authenticating proxy.</td></tr><tr><td><code>--allow-anonymous-cursor-account-mcp</code></td><td>Let anonymous callers use Cursor account MCP connections. Requires an authenticating proxy.</td></tr><tr><td><code>--public-url &lt;url&gt;</code></td><td>Set the externally reachable base URL that turns running off the serve host use for peer MCP and host bridges. It does not expose the server; configure the listener or proxy separately. Local-runtime peers use loopback.</td></tr><tr><td><code>--peers-url &lt;url&gt;</code></td><td>Resolve declared peers for a single-agent serve through a hosting-provided peer service. Cursor-managed hosting sets this option automatically; a multi-agent serve rejects it.</td></tr><tr><td><code>--no-schedules</code></td><td>Disable schedule firing outside dev mode.</td></tr><tr><td><code>--no-playground</code></td><td>Skip the playground.</td></tr><tr><td><code>--no-docs</code></td><td>Skip the documentation site at <code>/docs</code>.</td></tr><tr><td><code>--cursor-events</code></td><td>Receive SCM events through Cursor. Requires sign-in and one or more repeatable <code>--repo owner/name</code> values.</td></tr></tbody></table><p>Multi-agent slugs start with a letter or digit and contain only letters, digits, <code>_</code>, or <code>-</code>. The reserved slugs are <code>v1</code>, <code>playground</code>, and <code>docs</code>.</p><h3 id="dev" tabindex="-1">Develop locally <a class="header-anchor" href="#dev" aria-label="Permalink to &quot;Develop locally {#dev}&quot;">​</a></h3><p><code>dev</code> is <code>serve --dev</code> with an optional positional project path:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk dev</span></span>
11
- <span class="line"><span>agent-sdk dev ./bdk-pr-reviewer --port 3000</span></span></code></pre></div><p>It accepts every <code>serve</code> option. Pass at most one positional path, and don&#39;t combine it with a different <code>--dir</code>.</p><h3 id="docs" tabindex="-1">Serve the docs <a class="header-anchor" href="#docs" aria-label="Permalink to &quot;Serve the docs {#docs}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk docs [--port &lt;n&gt;] [--host 127.0.0.1] [--print]</span></span></code></pre></div><p><code>docs</code> serves the bundled documentation without an agent project. It uses an available loopback port by default and stays open until Ctrl-C. <code>--print</code> prints the URL without opening a browser.</p><h2 id="sessions-and-turns" tabindex="-1">Sessions and turns <a class="header-anchor" href="#sessions-and-turns" aria-label="Permalink to &quot;Sessions and turns&quot;">​</a></h2><h3 id="chat" tabindex="-1">Chat with an agent <a class="header-anchor" href="#chat" aria-label="Permalink to &quot;Chat with an agent {#chat}&quot;">​</a></h3><p><code>chat</code> connects to a running server and never starts an ephemeral one:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk chat [--url &lt;baseUrl&gt;] [--message &lt;text&gt;]</span></span>
11
+ <span class="line"><span>agent-sdk dev ./agent-sdk-pr-reviewer --port 3000</span></span></code></pre></div><p>It accepts every <code>serve</code> option. Pass at most one positional path, and don&#39;t combine it with a different <code>--dir</code>.</p><h3 id="docs" tabindex="-1">Serve the docs <a class="header-anchor" href="#docs" aria-label="Permalink to &quot;Serve the docs {#docs}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk docs [--port &lt;n&gt;] [--host 127.0.0.1] [--print]</span></span></code></pre></div><p><code>docs</code> serves the bundled documentation without an agent project. It uses an available loopback port by default and stays open until Ctrl-C. <code>--print</code> prints the URL without opening a browser.</p><h2 id="sessions-and-turns" tabindex="-1">Sessions and turns <a class="header-anchor" href="#sessions-and-turns" aria-label="Permalink to &quot;Sessions and turns&quot;">​</a></h2><h3 id="chat" tabindex="-1">Chat with an agent <a class="header-anchor" href="#chat" aria-label="Permalink to &quot;Chat with an agent {#chat}&quot;">​</a></h3><p><code>chat</code> connects to a running server and never starts an ephemeral one:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk chat [--url &lt;baseUrl&gt;] [--message &lt;text&gt;]</span></span>
12
12
  <span class="line"><span> [--session &lt;id&gt; | --resume] [--continuation-token &lt;token&gt;]</span></span>
13
13
  <span class="line"><span> [--slug &lt;slug&gt;] [--json] [--text] [--no-color]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Input mode</th><th>Behavior</th></tr></thead><tbody><tr><td>TTY without <code>--message</code></td><td>Open an interactive REPL.</td></tr><tr><td>TTY with <code>--message</code></td><td>Send the message, then keep the REPL open.</td></tr><tr><td>Non-TTY with <code>--message</code></td><td>Send one turn and exit.</td></tr><tr><td>Non-TTY without <code>--message</code></td><td>Read newline-delimited messages until EOF.</td></tr><tr><td><code>--json --message &lt;text&gt;</code></td><td>Send one turn and print <code>{ ok, sessionId, continuationToken, trajectory }</code>.</td></tr><tr><td><code>--json --text --message &lt;text&gt;</code></td><td>Print a compact trajectory instead of JSON.</td></tr></tbody></table><p>Use <code>--session &lt;id&gt;</code> to reattach a stored session and replay its transcript. If you omit <code>--continuation-token</code>, the CLI looks it up from the target&#39;s session list. <code>--resume</code> selects the most recently updated session with a continuation token. An explicit session ID takes precedence.</p><h3 id="run" tabindex="-1">Run turns <a class="header-anchor" href="#run" aria-label="Permalink to &quot;Run turns {#run}&quot;">​</a></h3><p><code>run</code> sends messages to an ephemeral local server or a running server:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk run [--dir &lt;path&gt;] [--message &lt;text&gt;]...</span></span>
14
14
  <span class="line"><span> [--messages-file &lt;path&gt;] [--url &lt;baseUrl&gt;]</span></span>
@@ -23,10 +23,10 @@ import{_ as t,c as a,o,a3 as d}from"./chunks/framework.BNw1pucY.js";const u=JSON
23
23
  <span class="line"><span> [--view trajectory|events|cost] [--json [--fields &lt;a,b.c&gt;]]</span></span>
24
24
  <span class="line"><span> [--trace &lt;file.ndjson&gt;] [--web [--print]]</span></span>
25
25
  <span class="line"><span></span></span>
26
- <span class="line"><span>agent-sdk session get --file &lt;file.ndjson&gt; [--json]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td>No option</td><td>Print a compact trajectory.</td></tr><tr><td><code>--json</code></td><td>Print the trajectory object.</td></tr><tr><td><code>--view events</code></td><td>Print <code>{ sessionId, events }</code> with the raw event list. With <code>--prod</code>, each tool call is an <code>actions.requested</code> or <code>action.result</code> event. The tool name is <code>toolName</code>.</td></tr><tr><td><code>--view cost</code></td><td>Print per-turn token usage and estimated cost from a running server. <code>--prod</code> doesn&#39;t support it.</td></tr><tr><td><code>--trace &lt;file.ndjson&gt;</code></td><td>Write the raw NDJSON trace instead of printing it. Not available with <code>--prod</code>.</td></tr><tr><td><code>--file &lt;file.ndjson&gt;</code></td><td>Read a saved trace (for example from <code>run --trace</code>) instead of a server, and print its trajectory.</td></tr><tr><td><code>--web</code></td><td>Open the session in the playground, or the dashboard playground with <code>--prod</code>. <code>--print</code> prints the URL only. A running target with credentials that a browser can&#39;t send starts a loopback proxy and stays open until Ctrl-C.</td></tr></tbody></table><p>Use <a href="#chat"><code>chat --session</code></a> to continue a conversational session on a local or running server.</p><p>With <code>--prod</code>, the command prints the session&#39;s hosted executions: one line per run with its status, duration, and time, followed by that run&#39;s log lines. When the deployment stored process output, a <code>Process output:</code> section prints that output next. <code>--json</code> prints <code>{ sessionId, executions, startLog, ... }</code>. <code>startLog</code> is the process output, or <code>null</code> when none is stored. <code>--view events</code> prints <code>{ sessionId, events }</code>. <code>--trace</code> isn&#39;t available. While a turn is running, text output also reports the event count and latest event type and prints <code>Turn running; runs may lag behind events.</code> A run can show <code>running</code> with no logs until the turn ends, so a growing event count is the progress signal.</p><h3 id="session-create" tabindex="-1">Start a hosted session <a class="header-anchor" href="#session-create" aria-label="Permalink to &quot;Start a hosted session {#session-create}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk session create --message &lt;text&gt; [--session &lt;ses_...&gt;]</span></span>
26
+ <span class="line"><span>agent-sdk session get --file &lt;file.ndjson&gt; [--json]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td>No option</td><td>Print a compact trajectory.</td></tr><tr><td><code>--json</code></td><td>Print the trajectory object.</td></tr><tr><td><code>--view events</code></td><td>Print <code>{ sessionId, events }</code> with the raw event list. With <code>--prod</code>, each tool call is an <code>actions.requested</code> or <code>action.result</code> event. The tool name is <code>toolName</code>.</td></tr><tr><td><code>--view cost</code></td><td>Print per-turn token usage and estimated cost from a running server. <code>--prod</code> doesn&#39;t support it.</td></tr><tr><td><code>--trace &lt;file.ndjson&gt;</code></td><td>Write the raw NDJSON trace instead of printing it. Not available with <code>--prod</code>.</td></tr><tr><td><code>--file &lt;file.ndjson&gt;</code></td><td>Read a saved trace (for example from <code>run --trace</code>) instead of a server, and print its trajectory.</td></tr><tr><td><code>--web</code></td><td>Open the session in the playground, or the <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> playground with <code>--prod</code>. <code>--print</code> prints the URL only. A running target with credentials that a browser can&#39;t send starts a loopback proxy and stays open until Ctrl-C.</td></tr></tbody></table><p>Use <a href="#chat"><code>chat --session</code></a> to continue a conversational session on a local or running server.</p><p>With <code>--prod</code>, the command prints the session&#39;s hosted executions: one line per run with its status, duration, and time, followed by that run&#39;s log lines. When the deployment stored process output, a <code>Process output:</code> section prints that output next. <code>--json</code> prints <code>{ sessionId, executions, startLog, ... }</code>. <code>startLog</code> is the process output, or <code>null</code> when none is stored. <code>--view events</code> prints <code>{ sessionId, events }</code>. <code>--trace</code> isn&#39;t available. While a turn is running, text output also reports the event count and latest event type and prints <code>Turn running; runs may lag behind events.</code> A run can show <code>running</code> with no logs until the turn ends, so a growing event count is the progress signal.</p><h3 id="session-create" tabindex="-1">Start a hosted session <a class="header-anchor" href="#session-create" aria-label="Permalink to &quot;Start a hosted session {#session-create}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk session create --message &lt;text&gt; [--session &lt;ses_...&gt;]</span></span>
27
27
  <span class="line"><span> [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--wait [--timeout-ms &lt;n&gt;]]</span></span>
28
28
  <span class="line"><span> [--read-only] [--as-of &lt;instant&gt;] [--component &lt;key&gt;] [--dry-run] [--json]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--message &lt;text&gt;</code></td><td>The message to send. Exactly one.</td></tr><tr><td><code>--session &lt;ses_...&gt;</code></td><td>Continue a hosted session that <code>session create</code> started. Slack, SCM, and custom-route sessions can&#39;t be continued this way.</td></tr><tr><td><code>--wait</code></td><td>Poll the delivery until it names the session, then print it. Exit <code>3</code> (<code>pending</code>) when <code>--timeout-ms</code> (default 120000) passes first. A skipped or failed delivery exits <code>1</code>.</td></tr><tr><td><code>--read-only</code></td><td>Run read tools and stub write tools.</td></tr><tr><td><code>--as-of &lt;instant&gt;</code></td><td>Freeze the session&#39;s clock at an ISO-8601 instant with a timezone, such as <code>2026-08-31T12:00:00Z</code>.</td></tr><tr><td><code>--component &lt;key&gt;</code></td><td>Wake a named component instead of the deployment&#39;s default. A continued session must belong to that component.</td></tr><tr><td><code>--dry-run</code></td><td>Send nothing. Print the request it would send.</td></tr></tbody></table><p>Without <code>--wait</code>, the command returns as soon as the deployment accepts the turn and exits <code>0</code> before the turn outcome is known. It prints the delivery ID, the session ID when known, and the session mode. <code>--json</code> prints <code>deliveryId</code>, <code>workflowId</code>, <code>sessionMode</code>, and <code>sessionId</code> when known, plus <code>dryRun</code> and <code>asOf</code> when set. A fresh start has no <code>sessionId</code> until the turn starts; a continuation echoes the <code>--session</code> value. See <a href="./../deployment.html#verify-a-hosted-turn">Verify a hosted turn</a>.</p><h3 id="logs" tabindex="-1">Follow logs <a class="header-anchor" href="#logs" aria-label="Permalink to &quot;Follow logs {#logs}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk logs [sessionId] [--url &lt;baseUrl&gt; | --prod]</span></span>
29
- <span class="line"><span> [--session &lt;sessionId&gt;] [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--once] [--json]</span></span></code></pre></div><p>The command follows logs until Ctrl-C. <code>--once</code> prints the current buffer and exits; <code>--json</code> emits newline-delimited JSON events. With <code>--prod</code>, it follows the output of the hosted deployment&#39;s most recent sessions on every channel and prints a <code>==&gt; &lt;sessionId&gt; (&lt;channel&gt;) &lt;==</code> header each time the output switches sessions. A persistent deployment also prints a <code>==&gt; process-output &lt;==</code> block. That block is the process log the dashboard shows for the deployment. Pass a session ID, as an argument or with <code>--session</code>, to follow only that session; a session ID requires <code>--prod</code>. The session view starts with <code>Process output:</code> for the deployment process log and <code>Session process output:</code> for that session&#39;s own process output, and a <code>tool &lt;name&gt;</code> line for each tool call. Hosted log events carry <code>sessionId</code> and <code>line</code> rather than <code>index</code> and <code>at</code>.</p><h2 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h2><h3 id="eval" tabindex="-1">Run evals <a class="header-anchor" href="#eval" aria-label="Permalink to &quot;Run evals {#eval}&quot;">​</a></h3><p><code>eval</code> discovers <code>evals/**/*.eval.{ts,js}</code> and runs selected cases:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk eval [--dir &lt;path&gt;] [evalId...]</span></span>
29
+ <span class="line"><span> [--session &lt;sessionId&gt;] [--slug &lt;slug&gt;] [--team &lt;id&gt;] [--once] [--json]</span></span></code></pre></div><p>The command follows logs until Ctrl-C. <code>--once</code> prints the current buffer and exits; <code>--json</code> emits newline-delimited JSON events. With <code>--prod</code>, it follows the output of the hosted deployment&#39;s most recent sessions on every channel and prints a <code>==&gt; &lt;sessionId&gt; (&lt;channel&gt;) &lt;==</code> header each time the output switches sessions. A persistent deployment also prints a <code>==&gt; process-output &lt;==</code> block. That block is the process log that <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> shows for the deployment. Pass a session ID, as an argument or with <code>--session</code>, to follow only that session; a session ID requires <code>--prod</code>. The session view starts with <code>Process output:</code> for the deployment process log and <code>Session process output:</code> for that session&#39;s own process output, and a <code>tool &lt;name&gt;</code> line for each tool call. Hosted log events carry <code>sessionId</code> and <code>line</code> rather than <code>index</code> and <code>at</code>.</p><h2 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h2><h3 id="eval" tabindex="-1">Run evals <a class="header-anchor" href="#eval" aria-label="Permalink to &quot;Run evals {#eval}&quot;">​</a></h3><p><code>eval</code> discovers <code>evals/**/*.eval.{ts,js}</code> and runs selected cases:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk eval [--dir &lt;path&gt;] [evalId...]</span></span>
30
30
  <span class="line"><span> [--list] [--tag &lt;tag&gt;]... [--json] [--verbose]</span></span>
31
31
  <span class="line"><span> [--timeout-ms &lt;n&gt;] [--strict] [--max-concurrency &lt;n&gt;]</span></span>
32
32
  <span class="line"><span> [--junit &lt;path&gt;] [--artifacts &lt;dir&gt; | --no-artifacts]</span></span>
@@ -42,7 +42,7 @@ import{_ as t,c as a,o,a3 as d}from"./chunks/framework.BNw1pucY.js";const u=JSON
42
42
  <span class="line"><span>agent-sdk -V</span></span></code></pre></div><p>Text output is the version number. <code>--json</code> prints <code>{ name, version }</code>.</p><h3 id="update" tabindex="-1">Update the CLI <a class="header-anchor" href="#update" aria-label="Permalink to &quot;Update the CLI {#update}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk update</span></span></code></pre></div><p><code>update</code> checks npm&#39;s <code>latest</code> tag and upgrades a recognized global or project install with its package manager. If it can&#39;t identify an installed copy, it prints a manual upgrade command instead.</p><p>Published installs check for updates at most once every 24 hours. Set <code>AGENT_SERVE_NO_UPDATE_CHECK</code>, <code>NO_UPDATE_NOTIFIER</code>, or <code>CI</code> to disable the automatic warning.</p><h2 id="managed-hosting" tabindex="-1">Managed hosting <a class="header-anchor" href="#managed-hosting" aria-label="Permalink to &quot;Managed hosting&quot;">​</a></h2><p>Every command here that changes a deployment takes <code>--dry-run</code>. It runs the reads (sign-in, team, and deployment checks), then stops at the first request that would change state and prints that request, with secret values redacted. Nothing is sent, and the command exits <code>0</code>.</p><p><code>deployment kill</code>, <code>deployment cancel-runs</code>, <code>deployment delete</code>, <code>deployment rotate-token</code>, <code>secret delete</code>, <code>image delete</code>, and <code>slack destroy</code> cannot be undone. On a terminal they ask you to type the slug or name. Without a terminal, as when an agent runs them, they exit <code>2</code> unless you pass <code>--yes</code>.</p><h3 id="deploy" tabindex="-1">Deploy agents <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;Deploy agents {#deploy}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deploy [--dir &lt;path&gt;] [--slug &lt;slug&gt; | --all] [--team &lt;id&gt;]</span></span>
43
43
  <span class="line"><span> [--repo &lt;https-url&gt;] [--ref &lt;git-ref&gt;] [--path &lt;agent-path&gt;]</span></span>
44
44
  <span class="line"><span> [--cursor-events-repo &lt;repo&gt;]... [--no-wait] [--json]</span></span></code></pre></div><p>Managed hosting requires a team with agent hosting enabled. A team service-account API key with agent access can deploy.</p><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>--slug &lt;slug&gt;</code></td><td>Select one project and set its deployment slug. Under a folder of several agents, this deploys that one agent.</td></tr><tr><td><code>--all</code></td><td>Deploy every child under a folder of several agents. For a folder of v2 agents, print one deploy command for each agent.</td></tr><tr><td><code>--team &lt;id&gt;</code></td><td>Select the Cursor team.</td></tr><tr><td><code>--repo &lt;https-url&gt;</code></td><td>Set the source repository. The CLI infers it from the current checkout when possible. HTTPS is required.</td></tr><tr><td><code>--ref &lt;git-ref&gt;</code></td><td>Set the source Git ref. The CLI infers the current branch when possible.</td></tr><tr><td><code>--path &lt;agent-path&gt;</code></td><td>Set the project path relative to the repository root.</td></tr><tr><td><code>--cursor-events-repo &lt;repo&gt;</code></td><td>Watch a repository&#39;s Cursor events. Write <code>owner/name</code> for GitHub and Origin, <code>gitlab.com/&lt;group&gt;/&lt;project&gt;</code> for GitLab (subgroups allowed), or <code>bitbucket.org/&lt;workspace&gt;/&lt;repo&gt;</code> for Bitbucket. Repeat the flag for each repository; the repositories you pass replace the previous list. Without the flag, the deployment watches its GitHub source repository.</td></tr><tr><td><code>--no-wait</code></td><td>Return after the deployment request is accepted.</td></tr><tr><td><code>--json</code></td><td>Print one object for one target or an array for multiple targets.</td></tr></tbody></table><p>Deployment slugs contain lowercase letters, digits, <code>_</code>, or <code>-</code>, start with a letter or digit, and have at most 64 characters. Egress entries are lowercase hostnames with an alphabetic top-level domain; one leading <code>*.</code> wildcard is allowed, or a trailing <code>:port</code> for a protocol that is not HTTPS, with at most 64 entries.</p><p>By default, <code>deploy</code> waits until the deployment is running and exits nonzero if it reaches a failed state. A first deployment can return an alias token once. Store it as a secret and send it as <code>X-Agent-Alias-Token</code> when calling the stable alias URL.</p><p>When the team egress policy blocks a host, <code>deploy</code> exits nonzero and prints <code>Error: agent-sdk deploy blocked.</code> The message names each blocked host, the team egress mode, and two fixes: add the hosts to the team egress list, or remove them from <code>hosting.egressDomains</code> and deploy again. The running bot does not change.</p><p>An agent that sets <code>architecture: &quot;v1&quot;</code> does not deploy: <code>deploy</code> exits nonzero and tells you to run <a href="#migrate"><code>migrate</code></a> first.</p><h3 id="deployment-list" tabindex="-1">List deployments <a class="header-anchor" href="#deployment-list" aria-label="Permalink to &quot;List deployments {#deployment-list}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment list [--team &lt;id&gt;] [--limit &lt;n&gt;] [--page-token &lt;token&gt;]</span></span>
45
- <span class="line"><span> [--json [--fields &lt;a,b.c&gt;]]</span></span></code></pre></div><p>Text output shows slug, status, and update time. <code>--json</code> prints <code>{ items, nextPageToken }</code>. <code>--limit</code> (default 20, at most 100) sets the page size, and <code>--page-token</code> reads the next page. An empty list succeeds.</p><h3 id="deployment-get" tabindex="-1">Inspect a deployment <a class="header-anchor" href="#deployment-get" aria-label="Permalink to &quot;Inspect a deployment {#deployment-get}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment get &lt;slug&gt; [--team &lt;id&gt;] [--json [--fields &lt;a,b.c&gt;]] [--web]</span></span></code></pre></div><p>Text output includes status, release, watched repositories, routes, secret names, and the latest error. <code>--web</code> opens the deployment&#39;s page in the dashboard. A deployment still on architecture v1 shows its status with <code>architecture: v1</code> and the <a href="#migrate"><code>migrate</code></a> steps; <code>deployment stop</code> and <code>deployment delete</code> also still accept it.</p><h3 id="deployment-stop" tabindex="-1">Stop a deployment <a class="header-anchor" href="#deployment-stop" aria-label="Permalink to &quot;Stop a deployment {#deployment-stop}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment stop &lt;slug&gt; [--team &lt;id&gt;] [--no-wait] [--cancel-runs] [--json]</span></span></code></pre></div><p>The command waits for <code>stopped</code> by default. <code>--no-wait</code> returns after the request is accepted. <code>--cancel-runs</code> also requests cancellation of active runs and reminder wakes.</p><h3 id="deployment-start" tabindex="-1">Start a deployment <a class="header-anchor" href="#deployment-start" aria-label="Permalink to &quot;Start a deployment {#deployment-start}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment start &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>deployment start</code> resumes a stopped deployment. It doesn&#39;t remove the deploy lock that <a href="#deployment-kill"><code>deployment kill</code></a> sets.</p><h3 id="deployment-kill" tabindex="-1">Kill a deployment <a class="header-anchor" href="#deployment-kill" aria-label="Permalink to &quot;Kill a deployment {#deployment-kill}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment kill &lt;slug&gt; [--team &lt;id&gt;] [--yes] [--dry-run] [--json]</span></span></code></pre></div><p>Use <code>deployment kill</code> in an emergency. It locks deploys of the slug, stops the deployment, and requests cancellation of its active runs and reminder wakes. To bring the deployment back, run <a href="#deployment-unlock"><code>deployment unlock</code></a> and then <a href="#deployment-start"><code>deployment start</code></a>.</p><h3 id="deployment-unlock" tabindex="-1">Unlock deploys <a class="header-anchor" href="#deployment-unlock" aria-label="Permalink to &quot;Unlock deploys {#deployment-unlock}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment unlock &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>deployment unlock</code> removes the lock that <code>deployment kill</code> sets, so <code>deploy</code>, <code>deployment upgrade</code>, and <code>deployment rollback</code> work for the slug again. It doesn&#39;t resume traffic; run <code>deployment start</code> for that.</p><h3 id="deployment-cancel-runs" tabindex="-1">Cancel active runs <a class="header-anchor" href="#deployment-cancel-runs" aria-label="Permalink to &quot;Cancel active runs {#deployment-cancel-runs}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment cancel-runs &lt;slug&gt; [--team &lt;id&gt;] [--yes] [--dry-run] [--json]</span></span></code></pre></div><p>The command requests cancellation for a deployment&#39;s active runs and reminder wakes. It exits nonzero if any cancellation request fails to start.</p><h3 id="deployment-update" tabindex="-1">Replace event repositories <a class="header-anchor" href="#deployment-update" aria-label="Permalink to &quot;Replace event repositories {#deployment-update}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment update &lt;slug&gt; (--event-repo &lt;owner/name&gt;... | --no-event-repos)</span></span>
45
+ <span class="line"><span> [--json [--fields &lt;a,b.c&gt;]]</span></span></code></pre></div><p>Text output shows slug, status, and update time. <code>--json</code> prints <code>{ items, nextPageToken }</code>. <code>--limit</code> (default 20, at most 100) sets the page size, and <code>--page-token</code> reads the next page. An empty list succeeds.</p><h3 id="deployment-get" tabindex="-1">Inspect a deployment <a class="header-anchor" href="#deployment-get" aria-label="Permalink to &quot;Inspect a deployment {#deployment-get}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment get &lt;slug&gt; [--team &lt;id&gt;] [--json [--fields &lt;a,b.c&gt;]] [--web]</span></span></code></pre></div><p>Text output includes status, release, watched repositories, routes, secret names, and the latest error. <code>--web</code> opens the deployment&#39;s page in <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a>. A deployment still on architecture v1 shows its status with <code>architecture: v1</code> and the <a href="#migrate"><code>migrate</code></a> steps; <code>deployment stop</code> and <code>deployment delete</code> also still accept it.</p><h3 id="deployment-stop" tabindex="-1">Stop a deployment <a class="header-anchor" href="#deployment-stop" aria-label="Permalink to &quot;Stop a deployment {#deployment-stop}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment stop &lt;slug&gt; [--team &lt;id&gt;] [--no-wait] [--cancel-runs] [--json]</span></span></code></pre></div><p>The command waits for <code>stopped</code> by default. <code>--no-wait</code> returns after the request is accepted. <code>--cancel-runs</code> also requests cancellation of active runs and reminder wakes.</p><h3 id="deployment-start" tabindex="-1">Start a deployment <a class="header-anchor" href="#deployment-start" aria-label="Permalink to &quot;Start a deployment {#deployment-start}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment start &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>deployment start</code> resumes a stopped deployment. It doesn&#39;t remove the deploy lock that <a href="#deployment-kill"><code>deployment kill</code></a> sets.</p><h3 id="deployment-kill" tabindex="-1">Kill a deployment <a class="header-anchor" href="#deployment-kill" aria-label="Permalink to &quot;Kill a deployment {#deployment-kill}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment kill &lt;slug&gt; [--team &lt;id&gt;] [--yes] [--dry-run] [--json]</span></span></code></pre></div><p>Use <code>deployment kill</code> in an emergency. It locks deploys of the slug, stops the deployment, and requests cancellation of its active runs and reminder wakes. To bring the deployment back, run <a href="#deployment-unlock"><code>deployment unlock</code></a> and then <a href="#deployment-start"><code>deployment start</code></a>.</p><h3 id="deployment-unlock" tabindex="-1">Unlock deploys <a class="header-anchor" href="#deployment-unlock" aria-label="Permalink to &quot;Unlock deploys {#deployment-unlock}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment unlock &lt;slug&gt; [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>deployment unlock</code> removes the lock that <code>deployment kill</code> sets, so <code>deploy</code>, <code>deployment upgrade</code>, and <code>deployment rollback</code> work for the slug again. It doesn&#39;t resume traffic; run <code>deployment start</code> for that.</p><h3 id="deployment-cancel-runs" tabindex="-1">Cancel active runs <a class="header-anchor" href="#deployment-cancel-runs" aria-label="Permalink to &quot;Cancel active runs {#deployment-cancel-runs}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment cancel-runs &lt;slug&gt; [--team &lt;id&gt;] [--yes] [--dry-run] [--json]</span></span></code></pre></div><p>The command requests cancellation for a deployment&#39;s active runs and reminder wakes. It exits nonzero if any cancellation request fails to start.</p><h3 id="deployment-update" tabindex="-1">Replace event repositories <a class="header-anchor" href="#deployment-update" aria-label="Permalink to &quot;Replace event repositories {#deployment-update}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment update &lt;slug&gt; (--event-repo &lt;owner/name&gt;... | --no-event-repos)</span></span>
46
46
  <span class="line"><span> [--team &lt;id&gt;] [--dry-run] [--json]</span></span></code></pre></div><p>The supplied repositories replace the deployment&#39;s complete event repository list; they aren&#39;t merged with the previous list. <code>--no-event-repos</code> clears the list.</p><h3 id="deployment-upgrade" tabindex="-1">Upgrade a deployment <a class="header-anchor" href="#deployment-upgrade" aria-label="Permalink to &quot;Upgrade a deployment {#deployment-upgrade}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment upgrade &lt;slug&gt; [--release &lt;id-or-version&gt;]</span></span>
47
47
  <span class="line"><span> [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>--release</code> accepts a release ID or version. Omit it to select the newest ready release. <code>--json</code> prints <code>{ releaseId }</code>.</p><h3 id="deployment-rollback" tabindex="-1">Roll back a deployment <a class="header-anchor" href="#deployment-rollback" aria-label="Permalink to &quot;Roll back a deployment {#deployment-rollback}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment rollback &lt;slug&gt; [--release &lt;id-or-version&gt;]</span></span>
48
48
  <span class="line"><span> [--team &lt;id&gt;] [--json]</span></span></code></pre></div><p><code>deployment rollback</code> moves the deployment to an earlier ready release without building a new one. Omit <code>--release</code> to select the release before the current one. <code>--json</code> prints <code>{ releaseId }</code>.</p><h3 id="deployment-delete" tabindex="-1">Delete a deployment <a class="header-anchor" href="#deployment-delete" aria-label="Permalink to &quot;Delete a deployment {#deployment-delete}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment delete &lt;slug&gt; [--team &lt;id&gt;] [--no-wait] [--yes] [--dry-run] [--json]</span></span></code></pre></div><p><code>deployment delete</code> removes the deployment and frees its slug. It waits until the deployment is gone unless <code>--no-wait</code> is set.</p><h3 id="deployment-rotate-token" tabindex="-1">Rotate an alias token <a class="header-anchor" href="#deployment-rotate-token" aria-label="Permalink to &quot;Rotate an alias token {#deployment-rotate-token}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deployment rotate-token &lt;slug&gt; [--team &lt;id&gt;] [--yes] [--dry-run] [--json]</span></span></code></pre></div><p>The old token stops working immediately. The replacement appears once; <code>--json</code> prints <code>{ aliasToken }</code>.</p><h3 id="secret" tabindex="-1">Manage deployment secrets <a class="header-anchor" href="#secret" aria-label="Permalink to &quot;Manage deployment secrets {#secret}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk secret set &lt;slug&gt; NAME [NAME2 ...]</span></span>
@@ -68,7 +68,7 @@ import{_ as t,c as a,o,a3 as d}from"./chunks/framework.BNw1pucY.js";const u=JSON
68
68
  <span class="line"><span>agent-sdk slack manifest [--dir &lt;path&gt;] [--name &lt;name&gt;]</span></span>
69
69
  <span class="line"><span> [--env dev|prod|both] [--channel-posts] [--dry-run]</span></span>
70
70
  <span class="line"><span>agent-sdk slack doctor [--dir &lt;path&gt;]</span></span>
71
- <span class="line"><span> [--prefix &lt;prefix&gt; | --no-prefix] [--channel &lt;id&gt;]... [--json]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Subcommand</th><th>Contract</th></tr></thead><tbody><tr><td><code>setup</code></td><td>Print the setup choices without changing files.</td></tr><tr><td><code>create</code></td><td>Open the signed-in Cursor dashboard wizard, write the resulting token pair to <code>.env.local</code>, and run <code>doctor</code>. The development app is the default; <code>--env prod</code> selects production. A second create overwrites the live app manifest.</td></tr><tr><td><code>destroy</code></td><td>Delete the provisioned app. Existing local token entries remain but stop working.</td></tr><tr><td><code>icon</code></td><td>Set an HTTPS or local PNG, JPG, or GIF icon of at most 512 KB.</td></tr><tr><td><code>init --manual</code></td><td>Write the channel, manifests, Slack CLI project, and setup files for a manually managed app.</td></tr><tr><td><code>manifest</code></td><td>Generate Slack manifests. <code>--env</code> defaults to <code>both</code>; with <code>--dry-run</code>, select one environment when you need one JSON document.</td></tr><tr><td><code>doctor</code></td><td>Check both tokens, Socket Mode connectivity, Slack authentication, and any repeatable <code>--channel</code> values.</td></tr></tbody></table><p>The default token prefix is the project directory name normalized to upper snake case. <code>--no-prefix</code> uses <code>SLACK_BOT_TOKEN</code> and <code>SLACK_APP_TOKEN</code>. Channel-post subscriptions are off by default; <code>--channel-posts</code> adds message events for public and private channels as required by <code>engagement.channelPosts</code>. Multi-agent servers need one token pair per agent.</p><p>See <a href="./../guides/slack.html">Slack</a> for app consent and manual setup.</p><h3 id="github" tabindex="-1">Test GitHub webhooks <a class="header-anchor" href="#github" aria-label="Permalink to &quot;Test GitHub webhooks {#github}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk github forward [--dir &lt;path&gt;] [--slug &lt;slug&gt;] [--channel &lt;id&gt;]</span></span>
71
+ <span class="line"><span> [--prefix &lt;prefix&gt; | --no-prefix] [--channel &lt;id&gt;]... [--json]</span></span></code></pre></div><table tabindex="0"><thead><tr><th>Subcommand</th><th>Contract</th></tr></thead><tbody><tr><td><code>setup</code></td><td>Print the setup choices without changing files.</td></tr><tr><td><code>create</code></td><td>Open the signed-in <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> wizard, write the resulting token pair to <code>.env.local</code>, and run <code>doctor</code>. The development app is the default; <code>--env prod</code> selects production. A second create overwrites the live app manifest.</td></tr><tr><td><code>destroy</code></td><td>Delete the provisioned app. Existing local token entries remain but stop working.</td></tr><tr><td><code>icon</code></td><td>Set an HTTPS or local PNG, JPG, or GIF icon of at most 512 KB.</td></tr><tr><td><code>init --manual</code></td><td>Write the channel, manifests, Slack CLI project, and setup files for a manually managed app.</td></tr><tr><td><code>manifest</code></td><td>Generate Slack manifests. <code>--env</code> defaults to <code>both</code>; with <code>--dry-run</code>, select one environment when you need one JSON document.</td></tr><tr><td><code>doctor</code></td><td>Check both tokens, Socket Mode connectivity, Slack authentication, and any repeatable <code>--channel</code> values.</td></tr></tbody></table><p>The default token prefix is the project directory name normalized to upper snake case. <code>--no-prefix</code> uses <code>SLACK_BOT_TOKEN</code> and <code>SLACK_APP_TOKEN</code>. Channel-post subscriptions are off by default; <code>--channel-posts</code> adds message events for public and private channels as required by <code>engagement.channelPosts</code>. Multi-agent servers need one token pair per agent.</p><p>See <a href="./../guides/slack.html">Slack</a> for app consent and manual setup.</p><h3 id="github" tabindex="-1">Test GitHub webhooks <a class="header-anchor" href="#github" aria-label="Permalink to &quot;Test GitHub webhooks {#github}&quot;">​</a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk github forward [--dir &lt;path&gt;] [--slug &lt;slug&gt;] [--channel &lt;id&gt;]</span></span>
72
72
  <span class="line"><span> [--repo owner/repo | --org &lt;org&gt;] [--events a,b,c]</span></span>
73
73
  <span class="line"><span> [--url &lt;url&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;]</span></span>
74
74
  <span class="line"><span> [--secret &lt;secret&gt;] [--install]</span></span>
@@ -1,4 +1,4 @@
1
- import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Evals","description":"Define eval cases, drive turns, assert trajectories, and interpret results.","frontmatter":{"title":"Evals","description":"Define eval cases, drive turns, assert trajectories, and interpret results."},"headers":[],"relativePath":"reference/evals.md","filePath":"reference/evals.md"}'),n={name:"reference/evals.md"};function d(l,s,h,r,o,p){return i(),a("div",null,[...s[0]||(s[0]=[t(`<h1 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h1><p>Evals run fixed cases against an agent and record whether its turns, tools, events, and output meet a contract. Files under the project-root <code>evals/</code> directory define cases with <code>@grok/agent-sdk/evals</code>; the runner discovers their IDs, executes them, and reports every assertion. See the <a href="./../evals.html">Evals guide</a> for the regression workflow.</p><h2 id="eval-discovery-and-case-ids" tabindex="-1">Eval discovery and case IDs <a class="header-anchor" href="#eval-discovery-and-case-ids" aria-label="Permalink to &quot;Eval discovery and case IDs&quot;">​</a></h2><p>Eval files live under the project-root <code>evals/</code> directory and end in <code>.eval.ts</code> or <code>.eval.js</code>. The path under that directory becomes the eval ID:</p><ul><li><code>evals/readiness.eval.ts</code> becomes <code>readiness</code>.</li><li><code>evals/builds/api.eval.ts</code> becomes <code>builds/api</code>.</li><li><code>evals/builds/index.eval.ts</code> becomes <code>builds</code>.</li></ul><p>Export one <code>defineEval</code> with either <code>test</code> or <code>cases</code>, not both. A case ID appends one path segment to the file ID:</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;"> defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
1
+ import{_ as a,c as e,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Evals","description":"Define eval cases, drive turns, assert trajectories, and interpret results.","frontmatter":{"title":"Evals","description":"Define eval cases, drive turns, assert trajectories, and interpret results."},"headers":[],"relativePath":"reference/evals.md","filePath":"reference/evals.md"}'),n={name:"reference/evals.md"};function l(d,s,h,p,r,o){return i(),e("div",null,[...s[0]||(s[0]=[t(`<h1 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to &quot;Evals&quot;">​</a></h1><p>Evals run fixed cases against an agent and record whether its turns, tools, events, and output meet a contract. Files under the project-root <code>evals/</code> directory define cases with <code>@grok/agent-sdk/evals</code>; the runner discovers their IDs, executes them, and reports every assertion. See the <a href="./../evals.html">Evals guide</a> for the regression workflow.</p><h2 id="eval-discovery-and-case-ids" tabindex="-1">Eval discovery and case IDs <a class="header-anchor" href="#eval-discovery-and-case-ids" aria-label="Permalink to &quot;Eval discovery and case IDs&quot;">​</a></h2><p>Eval files live under the project-root <code>evals/</code> directory and end in <code>.eval.ts</code> or <code>.eval.js</code>. The path under that directory becomes the eval ID:</p><ul><li><code>evals/readiness.eval.ts</code> becomes <code>readiness</code>.</li><li><code>evals/builds/api.eval.ts</code> becomes <code>builds/api</code>.</li><li><code>evals/builds/index.eval.ts</code> becomes <code>builds</code>.</li></ul><p>Export one <code>defineEval</code> with either <code>test</code> or <code>cases</code>, not both. A case ID appends one path segment to the file ID:</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;"> defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
2
2
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tags: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;smoke&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
3
3
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cases: [</span></span>
4
4
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
@@ -51,6 +51,26 @@ import{_ as e,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k
51
51
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><h2 id="reporters-and-results" tabindex="-1">Reporters and results <a class="header-anchor" href="#reporters-and-results" aria-label="Permalink to &quot;Reporters and results&quot;">​</a></h2><p>Built-in reporters include <code>JUnit({ filePath, suiteName? })</code> and <code>Artifacts({ dir })</code>. Custom reporters can expose <code>onRunStart</code>, <code>onEvalComplete</code>, and <code>onRunComplete</code>.</p><p>JSON output contains run totals and one result per case. Results include the case ID, verdict, assertions, session ID, inputs, final text, tools, tool calls, metrics, logs, duration, metadata, tags, and any error or skip reason.</p><h2 id="select-cases" tabindex="-1">Select cases <a class="header-anchor" href="#select-cases" aria-label="Permalink to &quot;Select cases&quot;">​</a></h2><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk eval --dir . --list</span></span>
52
52
  <span class="line"><span>agent-sdk eval --dir .</span></span>
53
53
  <span class="line"><span>agent-sdk eval --dir . builds/checkout</span></span>
54
- <span class="line"><span>agent-sdk eval --dir . --tag smoke</span></span></code></pre></div><p>ID filters match an exact ID and its descendants. Repeated IDs use OR; repeated tags use OR. When both are present, a case must match both groups.</p><h2 id="inspect-run-artifacts" tabindex="-1">Inspect run artifacts <a class="header-anchor" href="#inspect-run-artifacts" aria-label="Permalink to &quot;Inspect run artifacts&quot;">​</a></h2><p>Default run artifacts go under <code>evals/&lt;stamp&gt;/</code> in the project state directory and include <code>summary.json</code>, <code>results.jsonl</code>, and <code>evals/&lt;case-id&gt;.json</code>. <code>--artifacts &lt;dir&gt;</code> chooses another destination; <code>--no-artifacts</code> disables them. This location is independent of <code>--state-root</code>.</p><h2 id="run-evals-against-a-server" tabindex="-1">Run evals against a server <a class="header-anchor" href="#run-evals-against-a-server" aria-label="Permalink to &quot;Run evals against a server&quot;">​</a></h2><p>The playground <strong>Evals</strong> view starts batches on its running server, and <code>--url</code> targets a named running server:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk eval --url http://127.0.0.1:3000/vulnerability-scanner --tag smoke</span></span>
54
+ <span class="line"><span>agent-sdk eval --dir . --tag smoke</span></span></code></pre></div><p>ID filters match an exact ID and its descendants. Repeated IDs use OR; repeated tags use OR. When both are present, a case must match both groups.</p><h2 id="suite-summary-cases" tabindex="-1">Suite summary cases <a class="header-anchor" href="#suite-summary-cases" aria-label="Permalink to &quot;Suite summary cases&quot;">​</a></h2><p>Tag a case with <code>summary</code> when that case aggregates the other cases in the same file. <code>EVAL_SUMMARY_TAG</code> is that string. Selecting the aggregator by id, or with <code>--tag summary</code>, also runs every other case from that file. A selection that includes no <code>summary</code> case stays as you wrote it. <code>--list</code> shows the same set a run would execute.</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;"> { defineEval, EVAL_SUMMARY_TAG } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@grok/agent-sdk/evals&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
55
+ <span class="line"></span>
56
+ <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;"> defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
57
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cases: [</span></span>
58
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
59
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;checkout&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
60
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
61
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Review checkout PR 42.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
62
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
63
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
64
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
65
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
66
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;overall&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
67
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tags: [</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">EVAL_SUMMARY_TAG</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
68
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
69
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Summarize the checkout review.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
70
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
71
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
72
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
73
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
74
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>When that file is <code>evals/prs.eval.ts</code>, <code>agent-sdk eval --dir . prs/overall</code> runs <code>prs/checkout</code> and <code>prs/overall</code>.</p><h2 id="inspect-run-artifacts" tabindex="-1">Inspect run artifacts <a class="header-anchor" href="#inspect-run-artifacts" aria-label="Permalink to &quot;Inspect run artifacts&quot;">​</a></h2><p>Default run artifacts go under <code>evals/&lt;stamp&gt;/</code> in the project state directory and include <code>summary.json</code>, <code>results.jsonl</code>, and <code>evals/&lt;case-id&gt;.json</code>. <code>--artifacts &lt;dir&gt;</code> chooses another destination; <code>--no-artifacts</code> disables them. This location is independent of <code>--state-root</code>.</p><h2 id="run-evals-against-a-server" tabindex="-1">Run evals against a server <a class="header-anchor" href="#run-evals-against-a-server" aria-label="Permalink to &quot;Run evals against a server&quot;">​</a></h2><p>The playground <strong>Evals</strong> view starts batches on its running server, and <code>--url</code> targets a named running server:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk eval --url http://127.0.0.1:3000/vulnerability-scanner --tag smoke</span></span>
55
75
  <span class="line"><span>agent-sdk eval get &lt;eval-id&gt; --url http://127.0.0.1:3000/vulnerability-scanner</span></span>
56
- <span class="line"><span>agent-sdk eval cancel &lt;eval-id&gt; --url http://127.0.0.1:3000/vulnerability-scanner</span></span></code></pre></div><p>Server-side batches use the target&#39;s discovered cases and return an eval ID for <code>status</code> or <code>cancel</code>. Local reporter and concurrency flags don&#39;t apply to <code>--url</code> runs.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../evals.html">Evals guide</a></li><li><a href="./cli.html#eval">CLI reference</a></li><li><a href="./sessions.html">Sessions</a></li><li><a href="./artifacts.html">Artifacts</a></li></ul>`,63)])])}const E=e(n,[["render",d]]);export{k as __pageData,E as default};
76
+ <span class="line"><span>agent-sdk eval cancel &lt;eval-id&gt; --url http://127.0.0.1:3000/vulnerability-scanner</span></span></code></pre></div><p>Server-side batches use the target&#39;s discovered cases and return an eval ID for <code>status</code> or <code>cancel</code>. Local reporter and concurrency flags don&#39;t apply to <code>--url</code> runs.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../evals.html">Evals guide</a></li><li><a href="./cli.html#eval">CLI reference</a></li><li><a href="./sessions.html">Sessions</a></li><li><a href="./artifacts.html">Artifacts</a></li></ul>`,67)])])}const E=a(n,[["render",l]]);export{c as __pageData,E as default};