@grok/agent-sdk 0.2.29 → 0.3.0

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 (396) hide show
  1. package/dist/channels/slack/cli-project.js +1 -1
  2. package/dist/docs/404.html +2 -2
  3. package/dist/docs/assets/{app.DMrZKFjI.js → app.BzTUBOAD.js} +4 -4
  4. package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
  5. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
  6. package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
  7. package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
  8. package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
  9. package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
  10. package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.DH8GOhiv.js} +1 -1
  11. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
  12. package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.BXHpx1lE.js} +1 -1
  13. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
  14. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
  15. package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
  16. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
  17. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
  18. package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
  19. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
  20. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
  21. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
  22. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
  23. package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
  24. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
  25. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
  26. package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
  27. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
  28. package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
  29. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
  30. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
  31. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
  32. package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
  33. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
  34. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
  35. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
  36. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
  37. package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.DgJ4L-8V.js} +1 -1
  38. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
  39. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
  40. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
  41. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
  42. package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.DXXqX4MQ.js} +1 -1
  43. package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.5c61gNw4.js} +1 -1
  44. package/dist/docs/assets/chunks/{min.SPrSp704.js → min.B1-NAjHX.js} +1 -1
  45. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
  46. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
  47. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
  48. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
  49. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
  50. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
  51. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
  52. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
  53. package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DMj_7q3B.js} +2 -2
  54. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
  55. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
  56. package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
  57. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
  58. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
  59. package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
  60. package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
  61. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  62. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  63. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
  64. package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
  65. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  66. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  67. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  68. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  69. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  70. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  71. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
  72. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
  73. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  74. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  75. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  76. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  77. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
  78. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  79. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
  80. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
  81. package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
  82. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
  83. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  84. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  85. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  86. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  87. package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
  88. package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
  89. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  90. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  91. package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
  92. package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
  93. package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
  94. package/dist/docs/assets/{index.md.CAruw_rp.lean.js → index.md.DRfaoRCZ.lean.js} +1 -1
  95. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  96. package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  97. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  98. package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
  99. package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
  100. package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
  101. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  102. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  103. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  104. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  105. package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
  106. package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
  107. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  108. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  109. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  110. package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  111. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  112. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  113. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
  114. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
  115. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  116. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  117. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  118. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  119. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  120. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  121. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  122. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  123. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  124. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  125. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  126. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  127. package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
  128. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
  129. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  130. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  131. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  132. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  133. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  134. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  135. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  136. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  137. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  138. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  139. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  140. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  141. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  142. package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  143. package/dist/docs/building-with-agents.html +41 -44
  144. package/dist/docs/building-with-agents.md +11 -104
  145. package/dist/docs/changelog.html +37 -37
  146. package/dist/docs/changelog.md +5 -155
  147. package/dist/docs/deployment.html +54 -54
  148. package/dist/docs/deployment.md +83 -262
  149. package/dist/docs/evals.html +52 -71
  150. package/dist/docs/evals.md +33 -129
  151. package/dist/docs/guides/agent-to-agent.html +43 -43
  152. package/dist/docs/guides/agent-to-agent.md +27 -64
  153. package/dist/docs/guides/bitbucket.html +62 -62
  154. package/dist/docs/guides/bitbucket.md +73 -134
  155. package/dist/docs/guides/cloud-agents.html +37 -37
  156. package/dist/docs/guides/cloud-agents.md +23 -53
  157. package/dist/docs/guides/convert-automation.html +39 -56
  158. package/dist/docs/guides/convert-automation.md +31 -115
  159. package/dist/docs/guides/github.html +46 -54
  160. package/dist/docs/guides/github.md +49 -131
  161. package/dist/docs/guides/gitlab.html +98 -108
  162. package/dist/docs/guides/gitlab.md +104 -184
  163. package/dist/docs/guides/improve.html +38 -43
  164. package/dist/docs/guides/improve.md +24 -90
  165. package/dist/docs/guides/jev.html +55 -95
  166. package/dist/docs/guides/jev.md +53 -160
  167. package/dist/docs/guides/mcp-oauth.html +38 -40
  168. package/dist/docs/guides/mcp-oauth.md +33 -67
  169. package/dist/docs/guides/migrate.html +38 -43
  170. package/dist/docs/guides/migrate.md +56 -130
  171. package/dist/docs/guides/opentelemetry.html +41 -43
  172. package/dist/docs/guides/opentelemetry.md +32 -27
  173. package/dist/docs/guides/pagerduty.html +50 -49
  174. package/dist/docs/guides/pagerduty.md +65 -199
  175. package/dist/docs/guides/slack.html +51 -57
  176. package/dist/docs/guides/slack.md +76 -204
  177. package/dist/docs/guides/webhooks.html +42 -42
  178. package/dist/docs/guides/webhooks.md +64 -146
  179. package/dist/docs/hashmap.json +1 -1
  180. package/dist/docs/hillclimbing.html +40 -42
  181. package/dist/docs/hillclimbing.md +40 -102
  182. package/dist/docs/index.html +55 -61
  183. package/dist/docs/index.md +49 -83
  184. package/dist/docs/llms-full.txt +2262 -5721
  185. package/dist/docs/llms.txt +9 -14
  186. package/dist/docs/quickstart.html +95 -152
  187. package/dist/docs/quickstart.md +91 -180
  188. package/dist/docs/reference/access.html +36 -36
  189. package/dist/docs/reference/access.md +7 -12
  190. package/dist/docs/reference/agent-config.html +43 -56
  191. package/dist/docs/reference/agent-config.md +91 -174
  192. package/dist/docs/reference/artifacts.html +38 -39
  193. package/dist/docs/reference/artifacts.md +38 -62
  194. package/dist/docs/reference/channels.html +38 -39
  195. package/dist/docs/reference/channels.md +102 -151
  196. package/dist/docs/reference/cli.html +68 -84
  197. package/dist/docs/reference/cli.md +232 -697
  198. package/dist/docs/reference/connections.html +45 -57
  199. package/dist/docs/reference/connections.md +83 -164
  200. package/dist/docs/reference/evals.html +47 -54
  201. package/dist/docs/reference/evals.md +75 -141
  202. package/dist/docs/reference/extensions.html +41 -43
  203. package/dist/docs/reference/extensions.md +37 -70
  204. package/dist/docs/reference/hooks.html +40 -52
  205. package/dist/docs/reference/hooks.md +62 -133
  206. package/dist/docs/reference/http-api.html +38 -42
  207. package/dist/docs/reference/http-api.md +66 -118
  208. package/dist/docs/reference/instructions.html +39 -39
  209. package/dist/docs/reference/instructions.md +19 -29
  210. package/dist/docs/reference/limits.html +38 -38
  211. package/dist/docs/reference/limits.md +9 -21
  212. package/dist/docs/reference/memory.html +37 -38
  213. package/dist/docs/reference/memory.md +38 -75
  214. package/dist/docs/reference/playground.html +36 -36
  215. package/dist/docs/reference/playground.md +14 -22
  216. package/dist/docs/reference/project-layout.html +49 -48
  217. package/dist/docs/reference/project-layout.md +38 -84
  218. package/dist/docs/reference/schedules.html +46 -48
  219. package/dist/docs/reference/schedules.md +59 -90
  220. package/dist/docs/reference/sessions.html +37 -37
  221. package/dist/docs/reference/sessions.md +66 -113
  222. package/dist/docs/reference/skills.html +39 -39
  223. package/dist/docs/reference/skills.md +11 -31
  224. package/dist/docs/reference/subagents.html +37 -37
  225. package/dist/docs/reference/subagents.md +17 -31
  226. package/dist/docs/reference/tools.html +47 -64
  227. package/dist/docs/reference/tools.md +48 -130
  228. package/dist/docs/templates/agentic-owners.html +38 -38
  229. package/dist/docs/templates/agentic-owners.md +50 -74
  230. package/dist/docs/templates/reviews.html +69 -0
  231. package/dist/docs/templates/reviews.md +71 -0
  232. package/dist/docs/troubleshooting.html +38 -36
  233. package/dist/docs/troubleshooting.md +48 -101
  234. package/dist/internal/cli-deploy.js +1 -1
  235. package/dist/internal/cli-docs.js +1 -1
  236. package/dist/internal/cli-images.js +1 -1
  237. package/dist/internal/cli-skills.js +1 -1
  238. package/dist/internal/cursor/credentials.js +1 -1
  239. package/dist/internal/deploy-manifest.d.ts +1 -0
  240. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  241. package/dist/internal/deploy-manifest.js +0 -1
  242. package/dist/internal/discovery/agent-config.d.ts +2 -6
  243. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  244. package/dist/internal/discovery/agent-config.js +8 -25
  245. package/dist/internal/discovery/agent.d.ts.map +1 -1
  246. package/dist/internal/discovery/agent.js +2 -3
  247. package/dist/internal/discovery/project.d.ts.map +1 -1
  248. package/dist/internal/discovery/project.js +15 -0
  249. package/dist/internal/init-project.d.ts.map +1 -1
  250. package/dist/internal/init-project.js +7 -5
  251. package/dist/internal/reminder-runner.js +1 -1
  252. package/dist/internal/session-engine.js +1 -1
  253. package/dist/internal/shallow-clone.js +1 -1
  254. package/dist/playground/assets/index-D6mVn9og.js +62 -0
  255. package/dist/playground/assets/index-DlALM6gr.css +1 -0
  256. package/dist/playground/index.html +2 -2
  257. package/dist/types.d.ts +4 -17
  258. package/dist/types.d.ts.map +1 -1
  259. package/docs/README.md +49 -83
  260. package/docs/building-with-agents.md +11 -104
  261. package/docs/changelog.md +6 -156
  262. package/docs/deployment.md +83 -262
  263. package/docs/evals.md +34 -130
  264. package/docs/guides/agent-to-agent.md +27 -64
  265. package/docs/guides/bitbucket.md +73 -134
  266. package/docs/guides/cloud-agents.md +23 -53
  267. package/docs/guides/convert-automation.md +31 -115
  268. package/docs/guides/github.md +49 -131
  269. package/docs/guides/gitlab.md +104 -184
  270. package/docs/guides/improve.md +24 -90
  271. package/docs/guides/jev.md +53 -160
  272. package/docs/guides/mcp-oauth.md +33 -67
  273. package/docs/guides/migrate.md +56 -130
  274. package/docs/guides/opentelemetry.md +37 -27
  275. package/docs/guides/pagerduty.md +68 -200
  276. package/docs/guides/slack.md +76 -204
  277. package/docs/guides/webhooks.md +64 -146
  278. package/docs/hillclimbing.md +41 -103
  279. package/docs/quickstart.md +91 -180
  280. package/docs/reference/access.md +7 -12
  281. package/docs/reference/agent-config.md +91 -174
  282. package/docs/reference/artifacts.md +38 -62
  283. package/docs/reference/channels.md +102 -151
  284. package/docs/reference/cli.md +232 -697
  285. package/docs/reference/connections.md +83 -164
  286. package/docs/reference/evals.md +75 -141
  287. package/docs/reference/extensions.md +37 -70
  288. package/docs/reference/hooks.md +61 -132
  289. package/docs/reference/http-api.md +66 -118
  290. package/docs/reference/instructions.md +20 -30
  291. package/docs/reference/limits.md +10 -22
  292. package/docs/reference/memory.md +38 -75
  293. package/docs/reference/playground.md +14 -22
  294. package/docs/reference/project-layout.md +38 -84
  295. package/docs/reference/schedules.md +59 -90
  296. package/docs/reference/sessions.md +66 -113
  297. package/docs/reference/skills.md +12 -32
  298. package/docs/reference/subagents.md +17 -31
  299. package/docs/reference/tools.md +48 -130
  300. package/docs/templates/agentic-owners.md +50 -74
  301. package/docs/templates/reviews.md +76 -0
  302. package/docs/troubleshooting.md +48 -101
  303. package/package.json +2 -2
  304. package/skills/deploy/SKILL.md +1 -1
  305. package/skills/migrate-v2/SKILL.md +0 -1
  306. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  307. package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
  308. package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
  309. package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
  310. package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
  311. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
  312. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
  313. package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
  314. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
  315. package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
  316. package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
  317. package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
  318. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  319. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  320. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  321. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  322. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  323. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  324. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  325. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  326. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  327. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  328. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  329. package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
  330. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  331. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  332. package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
  333. package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
  334. package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
  335. package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
  336. package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
  337. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  338. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  339. package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
  340. package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
  341. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  342. package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
  343. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  344. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  345. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  346. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  347. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  348. package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
  349. package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
  350. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  351. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  352. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  353. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  354. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  355. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  356. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  357. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  358. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  359. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  360. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  361. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  362. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  363. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  364. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  365. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  366. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  367. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  368. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  369. package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
  370. package/dist/docs/guides/hooks.html +0 -113
  371. package/dist/docs/guides/hooks.md +0 -116
  372. package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
  373. package/dist/docs/package/skills/evals/SKILL.md +0 -145
  374. package/dist/docs/package/skills/github/SKILL.md +0 -133
  375. package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
  376. package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
  377. package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
  378. package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
  379. package/dist/docs/reference/prompt.html +0 -68
  380. package/dist/docs/reference/prompt.md +0 -47
  381. package/dist/docs/templates/security-reviewer.html +0 -62
  382. package/dist/docs/templates/security-reviewer.md +0 -81
  383. package/dist/docs/templates/thermo-quality-review.html +0 -62
  384. package/dist/docs/templates/thermo-quality-review.md +0 -75
  385. package/dist/docs/templates/thermo-review.html +0 -62
  386. package/dist/docs/templates/thermo-review.md +0 -75
  387. package/dist/docs/templates/triage.html +0 -68
  388. package/dist/docs/templates/triage.md +0 -101
  389. package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
  390. package/dist/playground/assets/index-F8b5WvWi.css +0 -1
  391. package/docs/guides/hooks.md +0 -121
  392. package/docs/reference/prompt.md +0 -52
  393. package/docs/templates/security-reviewer.md +0 -86
  394. package/docs/templates/thermo-quality-review.md +0 -80
  395. package/docs/templates/thermo-review.md +0 -80
  396. package/docs/templates/triage.md +0 -106
@@ -5,172 +5,98 @@ description: "Move a hosted Agent SDK architecture v1 project to v2 through a re
5
5
 
6
6
  # Migrate an early-alpha project to architecture v2
7
7
 
8
- Use this guide only for Agent SDK projects deployed during the
9
- early alpha. Projects that never deployed on architecture v1 already use v2
10
- and need no migration.
8
+ Use this guide only for an Agent SDK project deployed on architecture v1 during
9
+ the early alpha. Every other project already runs on v2.
11
10
 
12
11
  ## Check whether your project needs migration
13
12
 
14
- Migrate when at least one of these signals is present:
13
+ Your project needs migration if any of these is true:
15
14
 
16
- - `package.json` depends on the legacy v1 package. Remove it, then install
17
- the package `agent-sdk init` writes:
15
+ - `package.json` depends on `@cursor/july`.
16
+ - A script or CI job runs the early-alpha CLI.
17
+ - The agent sets `architecture: "v1"` or `runtime: "grokbot"`.
18
+ - The project has `bot/storage.ts` or `agent/storage.ts`.
19
+ - An SCM channel credential is a literal value.
20
+ - Code uses a `/v1` continuation selector.
21
+ - A reminder uses an anonymous `run` or `until` function.
22
+ - A peer connection reads its URL from a `*_MCP_URL` secret.
23
+ - `agent-sdk deployment get <slug>` doesn't print `architecture: v2`.
18
24
 
19
- ```bash
20
- npm uninstall @cursor/july
21
- npm install __BDK_PACKAGE__@latest
22
- ```
25
+ `agent-sdk migrate` checks the source for these signals and prints
26
+ `Nothing to migrate.` when it finds none. It doesn't check scripts, CI jobs, or
27
+ the hosted deployment.
23
28
 
24
- - A script or CI job runs the legacy early-alpha CLI.
29
+ To swap the early-alpha package, run:
25
30
 
26
- - `agent/agent.ts` sets `architecture: "v1"`.
27
-
28
- - `agent-sdk deployment get <slug>` does not print `architecture: v2`.
29
-
30
- Stop when none of these is true. An existing `agent/` project root can remain
31
- in place; Agent SDK still loads it even though current examples use `bot/`.
31
+ ```bash
32
+ npm uninstall @cursor/july
33
+ npm install __BDK_PACKAGE__@latest
34
+ ```
32
35
 
33
- `agent-sdk migrate` prints `Nothing to migrate.` and exits 0 only when `--dir` shows
34
- no migration work. The check looks for an `@cursor/july` dependency,
35
- `architecture: "v1"`, `bot/storage.ts` or `agent/storage.ts`,
36
- `runtime: "grokbot"`, a literal SCM credential, a `/v1` continuation selector,
37
- an anonymous reminder, and a `*_MCP_URL` peer connection. When any of those is
38
- present, or a project file cannot be read, the command starts the agent. It
39
- does not read the hosted deployment. Run `agent-sdk deployment get <slug>` when you still
40
- need to see whether that copy is on v1.
36
+ An existing `agent/` folder still works.
41
37
 
42
38
  ## Start the migration
43
39
 
44
- Commit and push the source you want to migrate. `agent-sdk migrate` reads that
45
- pushed Git ref, starts a Cursor cloud agent with the bundled migration skill,
46
- and waits for the agent to open a pull request. It does not deploy the project.
40
+ Commit and push the source first. `agent-sdk migrate` starts a Cursor cloud
41
+ agent on that pushed ref, and the agent opens a pull request without deploying.
47
42
 
48
43
  ```bash
49
44
  agent-sdk login
50
45
  agent-sdk migrate --dir .
51
46
  ```
52
47
 
53
- Inside a checkout, the command infers the repository, current ref, and project
54
- path. Pass them when you need to target a different pushed source:
55
-
56
- ```bash
57
- agent-sdk migrate \
58
- --dir ./bots/triage \
59
- --repo https://github.com/acme/agents \
60
- --ref migrate-triage-v2 \
61
- --path bots/triage
62
- ```
63
-
64
- Use `--no-wait` to print the cloud agent URL and return while it works. Use
65
- `--json` for machine-readable status. The
66
- [CLI reference](../reference/cli.md#migrate) covers every flag, output, and
67
- exit status.
68
-
69
- ## Use the coding-agent skill directly
70
-
71
- You can instead ask a coding agent working in the project checkout to follow
72
- the bundled
73
- [`bdk-migrate-v2` skill](../../skills/migrate-v2/SKILL.md). The skill owns the
74
- code changes, capability checks, local verification, and deployment handoff.
48
+ To migrate a pushed source outside your checkout, pass `--repo`, `--ref`, and
49
+ `--path`. The [CLI reference](../reference/cli.md#migrate) lists every flag.
75
50
 
76
- > Follow the `bdk-migrate-v2` skill for this project. Open one pull request
77
- > with the migration, but do not deploy it or change deployment secrets.
78
-
79
- If the project depends on a v1 capability without a supported v2 path, the
80
- skill tells the coding agent to stop and name the blocker instead of removing
81
- the behavior.
51
+ You can also ask a coding agent in your checkout to follow the bundled `bdk-migrate-v2` skill. If the project
52
+ relies on a v1 capability that has no v2 path, the agent stops and names the
53
+ blocker.
82
54
 
83
55
  ## Review the pull request
84
56
 
85
- Before merging, confirm the pull request:
86
-
87
- - Uses `@grok/agent-sdk` and `agent-sdk`, and removes the v1 architecture opt-in.
88
-
89
- - Moves durable state to `ctx.host.kv` or `ctx.host.files`, reads secrets
90
- inside the handler that needs them, and accounts for hosted HTTP routes
91
- returning `202`.
92
-
93
- - Names SCM channel secrets instead of reading them: every
94
- `githubChannel({ credentials })` field and the GitLab or Bitbucket
95
- `webhookSecret` is `{ secretName: "NAME" }`. `agent-sdk validate` reports each
96
- field still written as a literal or `() => process.env.NAME` getter, as a
97
- warning while `architecture: "v1"` is set and as an error once it is
98
- removed. The [GitHub guide](./github.md#other-hosts) explains the named
99
- form.
100
-
101
- - Rewrites each peer call that took its URL from a secret or environment
102
- variable, such as `BUILDER_MCP_URL`, to
103
- `defineConnection({ agent: "<slug>" })` under `bot/mcp-connections/`
104
- (or `agent/mcp-connections/` when the project root is `agent/`).
105
- Confirm the slug before you merge. The pull request lists each secret the
106
- rewrite left unused, and it leaves a TODO where it could not determine
107
- the slug.
57
+ Before you merge, check that the pull request:
108
58
 
109
- - Calls out unsupported behavior and any follow-up needed for reminders,
110
- schedules, Slack, or MCP connections.
111
-
112
- - Reports the validation, type checks, tests, and credential-dependent checks
113
- it ran or handed off.
114
-
115
- The migration pull request should change source only. Deploy after it merges.
59
+ - Uses `@grok/agent-sdk` and `agent-sdk`, and removes `architecture: "v1"`.
60
+ - Moves durable state to `ctx.host.kv` or `ctx.host.files`, reads secrets inside
61
+ the handler that needs them, and expects hosted routes to return `202`.
62
+ - Passes every SCM credential as `{ secretName: "NAME" }`. `agent-sdk validate`
63
+ warns about a literal or `process.env` getter while `architecture: "v1"` is
64
+ set, and fails once you remove it.
65
+ - Replaces each peer URL secret, such as `BUILDER_MCP_URL`, with
66
+ `defineConnection({ agent: "<slug>" })`. Check each slug and any TODO the
67
+ agent left.
68
+ - Lists unsupported behavior, follow-ups, and the checks it ran or handed off.
116
69
 
117
70
  ## Choose a cutover
118
71
 
119
72
  | Cutover | What happens | Choose it when |
120
73
  | --- | --- | --- |
121
- | Same slug | The v2 deployment copies the v1 secrets and replaces v1 after it starts. The cutover cannot be undone, and it deletes v1's hosted sessions, KV, files, and eval runs. | A service interruption and an empty v2 state are acceptable. |
122
- | New slug | The v1 deployment keeps serving while you configure and test v2. Move senders to the new URL, then delete the old deployment. | You use Slack, webhooks, or hosted state, or want a staged cutover. |
74
+ | Same slug | v2 copies the v1 secrets and replaces v1 once it starts. You can't undo it, and it deletes v1's hosted sessions, KV, files, and eval runs. | A short outage and an empty v2 state are fine. |
75
+ | New slug | v1 keeps serving while you test v2. Move senders to the new URL, then delete v1. | You use Slack, webhooks, or hosted state. |
123
76
 
124
- Prefer a new slug for Slack, webhooks, or data in `ctx.host.kv`. Point the trial
125
- at a test repository so both deployments do not act on the same source-control
126
- events. If the CLI reports that same-slug replacement is unavailable, use a
127
- new slug.
77
+ With a new slug, point the trial at a test repository so the two deployments
78
+ don't both act on the same events.
128
79
 
129
80
  ## Deploy after merge
130
81
 
131
82
  Deploy from the merged, pushed ref. Reuse every `--cursor-events-repo` value
132
- from the v1 deployment, and move every `--allow-domain` value into
133
- `hosting.egressDomains`. `agent-sdk deploy` has no `--allow-domain` flag.
83
+ from v1, and move every `--allow-domain` value into `hosting.egressDomains`.
134
84
 
135
85
  ```bash
136
- agent-sdk validate --dir .
137
86
  agent-sdk deploy --dir . --slug <existing-or-new-slug>
138
87
  ```
139
88
 
140
- When the folder contains more than one agent, deploy each agent folder
141
- alone. Run `agent-sdk deploy --dir <agent folder>` one time for each agent. One
142
- `agent-sdk deploy` on the parent folder prints those commands and does not deploy.
143
- Do not use `agent-sdk deploy --all`. Repeat `agent-sdk slack create --env prod` for each
144
- agent folder. The Slack app slug is the folder name.
145
-
146
- When the pull request calls another agent with
147
- `defineConnection({ agent: "<slug>" })`, deploy the caller and that peer
148
- on `@grok/agent-sdk` 0.2.18 or newer. Both deployments must belong to the
149
- same team, and the caller reaches the peer once the peer deployment is
150
- running. The connection file is already in the merged source, so unset
151
- each URL secret the pull request lists after both deploys:
89
+ Then follow the checklist that `agent-sdk migrate` printed:
152
90
 
153
- ```bash
154
- agent-sdk secret delete <slug> NAME
155
- ```
91
+ 1. Deploy each agent folder separately by running
92
+ `agent-sdk deploy --dir <agent-folder>` once for each one.
93
+ 2. For each Slack agent, run
94
+ `agent-sdk slack create --env prod --dir <agent-folder>`. Then uninstall the
95
+ old app and invite the new bot to its channels.
96
+ 3. For a [peer connection](./agent-to-agent.md), deploy both agents to the same
97
+ team. Then delete each peer URL secret the pull request lists with
98
+ `agent-sdk secret delete <slug> NAME`.
99
+ 4. For a new slug, add each secret with `agent-sdk secret set <slug> NAME`. It
100
+ applies without a redeploy.
156
101
 
157
- `agent-sdk migrate` prints the steps that follow the first deploy: one deploy per
158
- agent folder, `agent-sdk slack create --env prod --dir <agent-folder>` for each Slack
159
- agent, `agent-sdk secret delete` for peer URL secrets the pull request lists, and
160
- `agent-sdk secret list` / `agent-sdk secret set` when the slug is new. Slack setup
161
- redeploys the deployment by itself. `agent-sdk secret set` takes effect on the
162
- next request. Neither step needs another deploy.
163
-
164
- After the deployment starts, follow that checklist for Slack, webhook callers,
165
- peer connections, and secrets, then verify a hosted turn. The
166
- [deployment guide](../deployment.md) covers the managed hosting workflow.
167
-
168
- ## Related
169
-
170
- - [CLI reference](../reference/cli.md#migrate): migration flags, output, and
171
- exit status
172
- - [`bdk-migrate-v2` skill](../../skills/migrate-v2/SKILL.md): the coding
173
- procedure and complete capability matrix
174
- - [Peer agents](./agent-to-agent.md): how a deployed caller reaches another
175
- agent by slug
176
- - [Deployment](../deployment.md): deploy and verify the reviewed project
102
+ Finally, [verify a hosted turn](../deployment.md).
@@ -1,6 +1,12 @@
1
+ ---
2
+ title: "OpenTelemetry"
3
+ description: "Export traces, metrics, and logs to an OTLP collector and tag them per turn."
4
+ ---
5
+
1
6
  # OpenTelemetry
2
7
 
3
- Agent SDK sends traces, metrics, and logs to an OTLP collector when `OTEL_*` is set. Record with `@opentelemetry/api`, and there is no `defineOtel`.
8
+ Agent SDK sends traces, metrics, and logs to an OTLP collector when you
9
+ set the `OTEL_*` variables. Record your own with `@opentelemetry/api`.
4
10
 
5
11
  ```bash
6
12
  export OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
@@ -9,7 +15,14 @@ export OTEL_SERVICE_NAME=incident-agent
9
15
  agent-sdk serve --dir . --dev
10
16
  ```
11
17
 
12
- `http/protobuf` is the default, `http/json` works, `grpc` warns and falls back to `http/protobuf`, metrics use delta temporality, and Grafana Cloud rejects delta, so set `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative` for Grafana Cloud or Prometheus. Providers load before `bot/agent.ts`, so a module-scope meter, tracer, or logger binds to them, and with no endpoint there are no exporters, `fetch` has no `traceparent`, and the session collector stays off.
18
+ - The default protocol is `http/protobuf`. `http/json` also works, and
19
+ `grpc` logs a warning and falls back to `http/protobuf`.
20
+ - Metrics use delta temporality. Grafana Cloud and Prometheus reject
21
+ delta, so set `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative`
22
+ when you export to either one.
23
+ - If you don't set an endpoint, Agent SDK doesn't export anything.
24
+ - You can create a meter, tracer, or logger at the top of
25
+ `bot/agent.ts`, and it will use Agent SDK's providers.
13
26
 
14
27
  ## Variables
15
28
 
@@ -46,9 +59,9 @@ export default defineAgent({
46
59
  });
47
60
  ```
48
61
 
49
- `egressDomains` is a hostname with no scheme or path. Secrets arrive with the first request that has an endpoint, and that export uses those headers and `service.name`. A later `agent-sdk secret set` updates headers on the next export, including a rotated key. A URL, protocol, or signal-list change replaces the exporter. `service.name` is fixed on the first export that attaches, so redeploy to change it.
62
+ `service.name` is fixed by the first export, so redeploy to change it.
50
63
 
51
- ## What you can record
64
+ ## Record and tag
52
65
 
53
66
  ```ts
54
67
  import { metrics, trace } from "@opentelemetry/api";
@@ -62,9 +75,13 @@ const logger = logs.getLogger("incident-agent");
62
75
  lookups.add(1, { "cursor.conversation.id": currentConversationId() });
63
76
  ```
64
77
 
65
- Record after secrets load. A span or log that ends before exporters attach is still sent, up to 2048 of each, a metric recorded before the first collect is included, and HTTP, token, and tool spans carry `cursor.conversation.id`, while a span started during a turn or a tool call gets that attribute, a value you set is kept, the id is not propagated, and a metric gets it only when you set it.
78
+ Spans started during a turn get `cursor.conversation.id`, and a metric
79
+ gets it only when you set it.
66
80
 
67
- ## Tag a turn
81
+ To tag a whole turn, call `ctx.telemetry` from a tool. Spans in the
82
+ turn get the trace keys, Agent SDK's log records get the log keys, and
83
+ `cursor.token.usage` gets the metric keys. Outside a tool, use
84
+ `telemetry` from `@grok/agent-sdk/telemetry`.
68
85
 
69
86
  ```ts
70
87
  async execute({ key }, ctx) {
@@ -75,37 +92,30 @@ async execute({ key }, ctx) {
75
92
  }
76
93
  ```
77
94
 
78
- `ctx.telemetry` writes the current turn's store. A span started in that turn, including a span Agent SDK starts, gets the trace keys. A log record Agent SDK emits gets the log keys. `cursor.token.usage` recorded for that turn gets the metric keys. The same store is still there for a later tool in the turn. With export on, a later turn of the session keeps it. With export off, the next turn does not.
79
-
80
- ```ts
81
- import { telemetry } from "@grok/agent-sdk/telemetry";
82
-
83
- telemetry.setTraceAttributes({ "work.item": ticket });
84
- ```
85
-
86
- The global methods read the active context. Outside a turn they do nothing. Tags stay in this process. They are not written on the `baggage` header.
95
+ Grafana renames a `.` in a metric key to `_`.
87
96
 
88
97
  ```promql
89
98
  sum by (work_item) (cursor_token_usage_total)
90
99
  ```
91
100
 
92
- Grafana renames `.` to `_`, and each distinct metric value is its own series, including a new id on every turn. Keys match `[A-Za-z][A-Za-z0-9._-]*` and are at most 128 characters, values are 1 to 256 characters, a session holds 32 trace keys, 32 metric keys, and 32 log keys, a later call replaces a key, and a metric value must not be a secret, an email, or a raw user id.
93
-
94
- Outbound calls send `traceparent` only. With export off, the tags last for that turn, a span in the turn sees them, the next turn does not, and nothing is exported.
95
-
96
- `ctx.host.otel` is deprecated, still runs this release, and logs one warning per process. `setAttributes` writes one map onto spans and token usage, and the calls above replace it.
97
-
98
- Trace and log keys are accepted as written. A log record keeps a key Agent SDK already set. `setMetricAttributes` rejects `cursor.token.type`, `agent_sdk.channel`, `cursor.tool.name`, `cursor.tool.kind`, `cursor.tool.status`, `agent_sdk.turn_status`, `agent_sdk.subagent_name`, `agent_sdk.sdk_agent_id`, and `agent_sdk.sdk_agent_url`. The call throws and leaves the runtime value in place.
99
-
100
- Prompt text and tool payloads stay off log records unless `OTEL_LOGS_EXPORTER=otlp` and `OTEL_LOG_USER_PROMPTS` or `OTEL_LOG_TOOL_CONTENT` is set.
101
+ - Each distinct metric value is a new series, so never use a per-turn
102
+ ID, a secret, an email, or a raw user ID.
103
+ - A session holds up to 32 keys of each kind, with keys up to 128
104
+ characters and values up to 256.
101
105
 
102
106
  ## Limits
103
107
 
104
- Custom span processors, samplers, views, your own SDK, library auto-instrumentation, and a `register()` hook are not supported, and `OTEL_TRACES_SAMPLER` and `OTEL_METRIC_EXPORT_INTERVAL` are read when the provider is built, before hosted secrets load, so set them and restart, because a later value only logs a warning. If a module replaces a provider Agent SDK registered, the global API uses that provider and Agent SDK shuts down a provider it created only when it is not the registered one, and if a context manager is already registered, Agent SDK logs a warning and leaves it, so load Agent SDK first or the turn store does not stay on the active context.
108
+ - Agent SDK doesn't support custom span processors, samplers, views,
109
+ your own OpenTelemetry SDK, or library auto-instrumentation. It reads
110
+ `OTEL_TRACES_SAMPLER` and `OTEL_METRIC_EXPORT_INTERVAL` once at
111
+ startup, so restart the process after you change either one.
112
+ - Import Agent SDK before any other OpenTelemetry setup. Otherwise the
113
+ turn's tags may not reach your spans.
105
114
 
106
115
  ## Migrating from serve({ otel })
107
116
 
108
- `serve({ otel })` is removed, so delete that option, `bot/otel.ts`, `agent/otel.ts`, and `bot/instrumentation.ts`, and do not call `defineOtel`. Each signal has one URL, and a second exporter for the same signal has no variable.
117
+ Delete `serve({ otel })`, `bot/otel.ts`, `bot/instrumentation.ts`, and
118
+ any `defineOtel` call. Set these variables instead.
109
119
 
110
120
  | Old option | Set this instead |
111
121
  | --- | --- |
@@ -129,7 +139,7 @@ Custom span processors, samplers, views, your own SDK, library auto-instrumentat
129
139
  | `logs.toolContent` | `OTEL_LOGS_EXPORTER=otlp` and `OTEL_LOG_TOOL_CONTENT=1` |
130
140
  | `otel: false` | No endpoint, or `OTEL_SDK_DISABLED=true` |
131
141
 
132
- Put those names in `hosting.secretNames` and the collector host in `hosting.egressDomains`.
142
+ Set the hosted values after deploy:
133
143
 
134
144
  ```bash
135
145
  agent-sdk secret set my-agent OTEL_SERVICE_NAME OTEL_EXPORTER_OTLP_ENDPOINT OTEL_EXPORTER_OTLP_HEADERS