@grok/agent-sdk 0.6.0 → 0.7.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 (521) hide show
  1. package/AGENTS.md +40 -0
  2. package/dist/channels/github/forward.d.ts +5 -0
  3. package/dist/channels/github/forward.d.ts.map +1 -1
  4. package/dist/channels/github/forward.js +6 -3
  5. package/dist/channels/slack/api.d.ts +18 -0
  6. package/dist/channels/slack/api.d.ts.map +1 -1
  7. package/dist/channels/slack/api.js +31 -0
  8. package/dist/channels/slack/approvals.d.ts +19 -2
  9. package/dist/channels/slack/approvals.d.ts.map +1 -1
  10. package/dist/channels/slack/approvals.js +90 -19
  11. package/dist/channels/slack/attachments.d.ts +7 -2
  12. package/dist/channels/slack/attachments.d.ts.map +1 -1
  13. package/dist/channels/slack/attachments.js +318 -156
  14. package/dist/channels/slack/connect-card.d.ts +16 -0
  15. package/dist/channels/slack/connect-card.d.ts.map +1 -0
  16. package/dist/channels/slack/connect-card.js +31 -0
  17. package/dist/channels/slack/credentials.d.ts +10 -2
  18. package/dist/channels/slack/credentials.d.ts.map +1 -1
  19. package/dist/channels/slack/credentials.js +17 -15
  20. package/dist/channels/slack/defaults.d.ts.map +1 -1
  21. package/dist/channels/slack/defaults.js +18 -9
  22. package/dist/channels/slack/dispatch.d.ts +1 -1
  23. package/dist/channels/slack/dispatch.d.ts.map +1 -1
  24. package/dist/channels/slack/dispatch.js +19 -3
  25. package/dist/channels/slack/inbound.d.ts +8 -2
  26. package/dist/channels/slack/inbound.d.ts.map +1 -1
  27. package/dist/channels/slack/inbound.js +25 -4
  28. package/dist/channels/slack/index.d.ts +3 -2
  29. package/dist/channels/slack/index.d.ts.map +1 -1
  30. package/dist/channels/slack/index.js +3 -2
  31. package/dist/channels/slack/init.d.ts.map +1 -1
  32. package/dist/channels/slack/init.js +2 -1
  33. package/dist/channels/slack/mentions.d.ts +28 -0
  34. package/dist/channels/slack/mentions.d.ts.map +1 -0
  35. package/dist/channels/slack/mentions.js +178 -0
  36. package/dist/channels/slack/setup.js +1 -1
  37. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  38. package/dist/channels/slack/slack-channel.js +46 -3
  39. package/dist/channels/slack/stop.d.ts.map +1 -1
  40. package/dist/channels/slack/stop.js +7 -1
  41. package/dist/channels/slack/thread-context.d.ts +3 -0
  42. package/dist/channels/slack/thread-context.d.ts.map +1 -1
  43. package/dist/channels/slack/thread-context.js +17 -7
  44. package/dist/channels/slack/tool-approval-events.d.ts.map +1 -1
  45. package/dist/channels/slack/tool-approval-events.js +55 -2
  46. package/dist/channels/slack/types.d.ts +2 -0
  47. package/dist/channels/slack/types.d.ts.map +1 -1
  48. package/dist/channels/teams/activity.d.ts +33 -0
  49. package/dist/channels/teams/activity.d.ts.map +1 -0
  50. package/dist/channels/teams/activity.js +213 -0
  51. package/dist/channels/teams/auth.d.ts +25 -0
  52. package/dist/channels/teams/auth.d.ts.map +1 -0
  53. package/dist/channels/teams/auth.js +55 -0
  54. package/dist/channels/teams/bot-framework-auth.d.ts +33 -0
  55. package/dist/channels/teams/bot-framework-auth.d.ts.map +1 -0
  56. package/dist/channels/teams/bot-framework-auth.js +154 -0
  57. package/dist/channels/teams/cards.d.ts +23 -0
  58. package/dist/channels/teams/cards.d.ts.map +1 -0
  59. package/dist/channels/teams/cards.js +107 -0
  60. package/dist/channels/teams/connector.d.ts +48 -0
  61. package/dist/channels/teams/connector.d.ts.map +1 -0
  62. package/dist/channels/teams/connector.js +159 -0
  63. package/dist/channels/teams/credentials.d.ts +65 -0
  64. package/dist/channels/teams/credentials.d.ts.map +1 -0
  65. package/dist/channels/teams/credentials.js +84 -0
  66. package/dist/channels/teams/delivery.d.ts +14 -0
  67. package/dist/channels/teams/delivery.d.ts.map +1 -0
  68. package/dist/channels/teams/delivery.js +169 -0
  69. package/dist/channels/teams/dispatch.d.ts +45 -0
  70. package/dist/channels/teams/dispatch.d.ts.map +1 -0
  71. package/dist/channels/teams/dispatch.js +402 -0
  72. package/dist/channels/teams/engagement.d.ts +32 -0
  73. package/dist/channels/teams/engagement.d.ts.map +1 -0
  74. package/dist/channels/teams/engagement.js +120 -0
  75. package/dist/channels/teams/index.d.ts +21 -0
  76. package/dist/channels/teams/index.d.ts.map +1 -0
  77. package/dist/channels/teams/index.js +19 -0
  78. package/dist/channels/teams/marks.d.ts +19 -0
  79. package/dist/channels/teams/marks.d.ts.map +1 -0
  80. package/dist/channels/teams/marks.js +96 -0
  81. package/dist/channels/teams/senders.d.ts +27 -0
  82. package/dist/channels/teams/senders.d.ts.map +1 -0
  83. package/dist/channels/teams/senders.js +72 -0
  84. package/dist/channels/teams/teams-channel.d.ts +43 -0
  85. package/dist/channels/teams/teams-channel.d.ts.map +1 -0
  86. package/dist/channels/teams/teams-channel.js +278 -0
  87. package/dist/channels/teams/text.d.ts +7 -0
  88. package/dist/channels/teams/text.d.ts.map +1 -0
  89. package/dist/channels/teams/text.js +63 -0
  90. package/dist/channels/teams/types.d.ts +306 -0
  91. package/dist/channels/teams/types.d.ts.map +1 -0
  92. package/dist/channels/teams/types.js +1 -0
  93. package/dist/channels.d.ts +31 -0
  94. package/dist/channels.d.ts.map +1 -1
  95. package/dist/channels.js +37 -0
  96. package/dist/connections.d.ts +1 -1
  97. package/dist/connections.d.ts.map +1 -1
  98. package/dist/docs/404.html +3 -3
  99. package/dist/docs/assets/{app.lt-BYgI2.js → app.Ch-048af.js} +4 -4
  100. package/dist/docs/assets/changelog.md.SoN0MK7o.js +1 -0
  101. package/dist/docs/assets/{changelog.md.DVNB-ApU.lean.js → changelog.md.SoN0MK7o.lean.js} +1 -1
  102. package/dist/docs/assets/chunks/@localSearchIndexroot.BdYoBKxY.js +1 -0
  103. package/dist/docs/assets/chunks/{VPLocalSearchBox.v_dV4U2Q.js → VPLocalSearchBox.D7BIa9Su.js} +2 -2
  104. package/dist/docs/assets/chunks/{arc.5o92kOg5.js → arc.BIzu7OVF.js} +1 -1
  105. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.C-oTwnNq.js → architectureDiagram-Q4EWVU46.DNznI0Sn.js} +1 -1
  106. package/dist/docs/assets/chunks/{baseUniq.zJ-VNOib.js → baseUniq.B4y6Y5eG.js} +1 -1
  107. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.B9ZJZuPd.js → blockDiagram-DXYQGD6D.BudnBsgw.js} +1 -1
  108. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.BBMwSIaN.js → c4Diagram-AHTNJAMY._bB00GdB.js} +1 -1
  109. package/dist/docs/assets/chunks/channel.CgxlmuBS.js +1 -0
  110. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.D8qAJpDD.js → chunk-4BX2VUAB.CRftnUwS.js} +1 -1
  111. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.B8QR5cdE.js → chunk-4TB4RGXK.CSx1x2Ob.js} +1 -1
  112. package/dist/docs/assets/chunks/{chunk-55IACEB6.BsWxVuew.js → chunk-55IACEB6.KkLHAAbH.js} +1 -1
  113. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.BeGygY_i.js → chunk-EDXVE4YY.DDeKCCtX.js} +1 -1
  114. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DdwgH-ZH.js → chunk-FMBD7UC4.DrLlsD9m.js} +1 -1
  115. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.B9zC_ALe.js → chunk-OYMX7WX6.DeVYOGcT.js} +1 -1
  116. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.BIxJ0rcL.js → chunk-QZHKN3VN.Cz4_bS6p.js} +1 -1
  117. package/dist/docs/assets/chunks/{chunk-YZCP3GAM.qiM_23_f.js → chunk-YZCP3GAM.CwrYtDVo.js} +1 -1
  118. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DWroREP-.js +1 -0
  119. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DWroREP-.js +1 -0
  120. package/dist/docs/assets/chunks/clone.F824-PNx.js +1 -0
  121. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BKB971D5.js → cose-bilkent-S5V4N54A.3d8hflz6.js} +1 -1
  122. package/dist/docs/assets/chunks/{dagre-KV5264BT.CcILjJgp.js → dagre-KV5264BT.BVEgjiPg.js} +1 -1
  123. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.DkY9A0nu.js → diagram-5BDNPKRD.j7dZpUK_.js} +1 -1
  124. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.BbdzmjMt.js → diagram-G4DWMVQ6.4flIgIon.js} +1 -1
  125. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.Be0zy1cM.js → diagram-MMDJMWI5.BlJiFh-S.js} +1 -1
  126. package/dist/docs/assets/chunks/{diagram-TYMM5635.zOiEycLe.js → diagram-TYMM5635.DHAOHEyM.js} +1 -1
  127. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.DUd_9HMF.js → erDiagram-SMLLAGMA.DkmyG7xK.js} +1 -1
  128. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.2KPYoZBO.js → flowDiagram-DWJPFMVM.L_WiaAU6.js} +1 -1
  129. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.DqE8_YpP.js → ganttDiagram-T4ZO3ILL.CT6kOI2a.js} +1 -1
  130. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.CO0Tk47h.js → gitGraphDiagram-UUTBAWPF.D8CRlLqh.js} +1 -1
  131. package/dist/docs/assets/chunks/{graph.CNe5KbNy.js → graph.CdOyJvsX.js} +1 -1
  132. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.BBhJ1X1B.js → infoDiagram-42DDH7IO.DcmXeSos.js} +1 -1
  133. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.KSIw9w3I.js → ishikawaDiagram-UXIWVN3A.BBjY4mxr.js} +1 -1
  134. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.BN2Y5oUJ.js → journeyDiagram-VCZTEJTY.BrXteAB6.js} +1 -1
  135. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.2KFuDYn_.js → kanban-definition-6JOO6SKY.OlHsUJVV.js} +1 -1
  136. package/dist/docs/assets/chunks/{layout.Demb_pzL.js → layout.DDwvoQlY.js} +1 -1
  137. package/dist/docs/assets/chunks/{linear.kYKxzbbR.js → linear.BRXPDWj3.js} +1 -1
  138. package/dist/docs/assets/chunks/{min.DwmCN5dF.js → min.3YwC0t3o.js} +1 -1
  139. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.CGlz01QG.js → mindmap-definition-QFDTVHPH.mPHnT2lN.js} +1 -1
  140. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.n3qsq4nA.js → pieDiagram-DEJITSTG.DEK2--em.js} +1 -1
  141. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.CGNJ1GSb.js → quadrantDiagram-34T5L4WZ.NCdRAOzK.js} +1 -1
  142. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.VhAzHDwQ.js → requirementDiagram-MS252O5E.DLAocFWZ.js} +1 -1
  143. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.DmHA5pW-.js → sankeyDiagram-XADWPNL6.afIOqpyT.js} +1 -1
  144. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23._TC1aKhg.js → sequenceDiagram-FGHM5R23.DXBjvkkE.js} +1 -1
  145. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.B-kLjV3O.js → stateDiagram-FHFEXIEX.B_SGgvgs.js} +1 -1
  146. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.OKAy5Bz7.js +1 -0
  147. package/dist/docs/assets/chunks/{theme.BaVlHHL-.js → theme.bNyH5NPA.js} +2 -2
  148. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.CresbphV.js → timeline-definition-GMOUNBTQ.CE6S1iSb.js} +1 -1
  149. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.CegHD8Y4.js → vennDiagram-DHZGUBPP.Blk7wb8V.js} +1 -1
  150. package/dist/docs/assets/chunks/{wardley-RL74JXVD.DjCmZrUO.js → wardley-RL74JXVD.DQqE3WF8.js} +1 -1
  151. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.BJ7s1zdZ.js → wardleyDiagram-NUSXRM2D.MUEQyRnz.js} +1 -1
  152. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.IrEXlemI.js → xychartDiagram-5P7HB3ND.DnJA2aXp.js} +1 -1
  153. package/dist/docs/assets/{deployment.md.DJtuDVLh.js → deployment.md.N9S5KC5R.js} +2 -2
  154. package/dist/docs/assets/{deployment.md.DJtuDVLh.lean.js → deployment.md.N9S5KC5R.lean.js} +1 -1
  155. package/dist/docs/assets/guides_cloud-agents.md.BdWqmUGb.js +14 -0
  156. package/dist/docs/assets/{guides_cloud-agents.md.CiXAW6on.lean.js → guides_cloud-agents.md.BdWqmUGb.lean.js} +1 -1
  157. package/dist/docs/assets/guides_teams.md.7Lz2sbqB.js +50 -0
  158. package/dist/docs/assets/guides_teams.md.7Lz2sbqB.lean.js +1 -0
  159. package/dist/docs/assets/{reference_channels.md.CPWOpdsC.js → reference_channels.md.CRvqgU0n.js} +1 -1
  160. package/dist/docs/assets/{reference_cli.md.DHm6DmYk.js → reference_cli.md.NS6U5a-7.js} +14 -4
  161. package/dist/docs/assets/{reference_cli.md.DHm6DmYk.lean.js → reference_cli.md.NS6U5a-7.lean.js} +1 -1
  162. package/dist/docs/assets/{reference_limits.md.CbdtFr4T.js → reference_limits.md.CW9PTdxr.js} +3 -3
  163. package/dist/docs/assets/{reference_limits.md.CbdtFr4T.lean.js → reference_limits.md.CW9PTdxr.lean.js} +1 -1
  164. package/dist/docs/assets/{reference_schedules.md.RhQ9ZLo1.js → reference_schedules.md.Dd8_d0WG.js} +3 -3
  165. package/dist/docs/assets/{reference_sessions.md.NXVQt9mP.js → reference_sessions.md.CoCyQLEz.js} +2 -2
  166. package/dist/docs/assets/{reference_sessions.md.NXVQt9mP.lean.js → reference_sessions.md.CoCyQLEz.lean.js} +1 -1
  167. package/dist/docs/assets/{reference_skills.md.DzCPNPkG.js → reference_skills.md.SFRZDC41.js} +4 -4
  168. package/dist/docs/assets/{reference_skills.md.DzCPNPkG.lean.js → reference_skills.md.SFRZDC41.lean.js} +1 -1
  169. package/dist/docs/assets/{style.DK0YX1WL.css → style.B7zPxANR.css} +1 -1
  170. package/dist/docs/assets/troubleshooting.md.CsQTleto.js +3 -0
  171. package/dist/docs/assets/{troubleshooting.md.DfKKvW1R.lean.js → troubleshooting.md.CsQTleto.lean.js} +1 -1
  172. package/dist/docs/building-with-agents.html +37 -37
  173. package/dist/docs/changelog.html +37 -37
  174. package/dist/docs/changelog.md +35 -0
  175. package/dist/docs/deployment.html +39 -39
  176. package/dist/docs/deployment.md +10 -0
  177. package/dist/docs/evals.html +37 -37
  178. package/dist/docs/guides/agent-to-agent.html +37 -37
  179. package/dist/docs/guides/bitbucket.html +37 -37
  180. package/dist/docs/guides/cloud-agents.html +43 -38
  181. package/dist/docs/guides/cloud-agents.md +47 -0
  182. package/dist/docs/guides/convert-automation.html +37 -37
  183. package/dist/docs/guides/github.html +37 -37
  184. package/dist/docs/guides/gitlab.html +37 -37
  185. package/dist/docs/guides/improve.html +37 -37
  186. package/dist/docs/guides/jev.html +37 -37
  187. package/dist/docs/guides/mcp-oauth.html +37 -37
  188. package/dist/docs/guides/migrate.html +37 -37
  189. package/dist/docs/guides/opentelemetry.html +37 -37
  190. package/dist/docs/guides/pagerduty.html +37 -37
  191. package/dist/docs/guides/slack.html +37 -37
  192. package/dist/docs/guides/teams.html +109 -0
  193. package/dist/docs/guides/teams.md +384 -0
  194. package/dist/docs/guides/webhooks.html +37 -37
  195. package/dist/docs/hashmap.json +1 -1
  196. package/dist/docs/hillclimbing.html +37 -37
  197. package/dist/docs/index.html +37 -37
  198. package/dist/docs/llms-full.txt +636 -4
  199. package/dist/docs/llms.txt +1 -0
  200. package/dist/docs/quickstart.html +37 -37
  201. package/dist/docs/reference/access.html +36 -36
  202. package/dist/docs/reference/agent-config.html +37 -37
  203. package/dist/docs/reference/artifacts.html +37 -37
  204. package/dist/docs/reference/channels.html +38 -38
  205. package/dist/docs/reference/channels.md +1 -0
  206. package/dist/docs/reference/cli.html +50 -40
  207. package/dist/docs/reference/cli.md +116 -0
  208. package/dist/docs/reference/connections.html +37 -37
  209. package/dist/docs/reference/evals.html +37 -37
  210. package/dist/docs/reference/extensions.html +37 -37
  211. package/dist/docs/reference/hooks.html +37 -37
  212. package/dist/docs/reference/http-api.html +37 -37
  213. package/dist/docs/reference/instructions.html +37 -37
  214. package/dist/docs/reference/limits.html +39 -39
  215. package/dist/docs/reference/limits.md +4 -4
  216. package/dist/docs/reference/memory.html +37 -37
  217. package/dist/docs/reference/playground.html +36 -36
  218. package/dist/docs/reference/project-layout.html +37 -37
  219. package/dist/docs/reference/schedules.html +40 -40
  220. package/dist/docs/reference/sessions.html +38 -38
  221. package/dist/docs/reference/sessions.md +13 -0
  222. package/dist/docs/reference/skills.html +40 -40
  223. package/dist/docs/reference/subagents.html +37 -37
  224. package/dist/docs/reference/tools.html +37 -37
  225. package/dist/docs/templates/agentic-owners.html +37 -37
  226. package/dist/docs/templates/reviews.html +37 -37
  227. package/dist/docs/troubleshooting.html +38 -38
  228. package/dist/docs/troubleshooting.md +21 -0
  229. package/dist/evals/run-facts.d.ts.map +1 -1
  230. package/dist/evals/run-facts.js +4 -0
  231. package/dist/extensions/cursor-cloud-agents/channels/cursor-cloud-agents.d.ts +12 -0
  232. package/dist/extensions/cursor-cloud-agents/channels/cursor-cloud-agents.d.ts.map +1 -0
  233. package/dist/extensions/cursor-cloud-agents/channels/cursor-cloud-agents.js +42 -0
  234. package/dist/extensions/cursor-cloud-agents/extension.d.ts +10 -7
  235. package/dist/extensions/cursor-cloud-agents/extension.d.ts.map +1 -1
  236. package/dist/extensions/cursor-cloud-agents/extension.js +3 -2
  237. package/dist/extensions/cursor-cloud-agents/lib/agent-id.d.ts +5 -0
  238. package/dist/extensions/cursor-cloud-agents/lib/agent-id.d.ts.map +1 -0
  239. package/dist/extensions/cursor-cloud-agents/lib/agent-id.js +10 -0
  240. package/dist/extensions/cursor-cloud-agents/lib/backend.d.ts +57 -3
  241. package/dist/extensions/cursor-cloud-agents/lib/backend.d.ts.map +1 -1
  242. package/dist/extensions/cursor-cloud-agents/lib/backend.js +150 -35
  243. package/dist/extensions/cursor-cloud-agents/lib/fleet.d.ts +32 -4
  244. package/dist/extensions/cursor-cloud-agents/lib/fleet.d.ts.map +1 -1
  245. package/dist/extensions/cursor-cloud-agents/lib/fleet.js +93 -7
  246. package/dist/extensions/cursor-cloud-agents/lib/launch-agent.d.ts +24 -7
  247. package/dist/extensions/cursor-cloud-agents/lib/launch-agent.d.ts.map +1 -1
  248. package/dist/extensions/cursor-cloud-agents/lib/launch-agent.js +158 -25
  249. package/dist/extensions/cursor-cloud-agents/lib/stop-signal.d.ts +18 -0
  250. package/dist/extensions/cursor-cloud-agents/lib/stop-signal.d.ts.map +1 -0
  251. package/dist/extensions/cursor-cloud-agents/lib/stop-signal.js +27 -0
  252. package/dist/extensions/cursor-cloud-agents/lib/transcript.d.ts.map +1 -1
  253. package/dist/extensions/cursor-cloud-agents/lib/transcript.js +2 -3
  254. package/dist/extensions/cursor-cloud-agents/lib/watch.d.ts +26 -12
  255. package/dist/extensions/cursor-cloud-agents/lib/watch.d.ts.map +1 -1
  256. package/dist/extensions/cursor-cloud-agents/lib/watch.js +115 -46
  257. package/dist/extensions/cursor-cloud-agents/reminders/cloud-agent-stop-watch.d.ts +16 -5
  258. package/dist/extensions/cursor-cloud-agents/reminders/cloud-agent-stop-watch.d.ts.map +1 -1
  259. package/dist/extensions/cursor-cloud-agents/reminders/cloud-agent-stop-watch.js +76 -20
  260. package/dist/extensions/cursor-cloud-agents/skills/handoff.md +2 -2
  261. package/dist/extensions/cursor-cloud-agents/tools/get.js +2 -2
  262. package/dist/extensions/cursor-cloud-agents/tools/launch.js +1 -1
  263. package/dist/extensions.d.ts.map +1 -1
  264. package/dist/extensions.js +18 -3
  265. package/dist/files-backends/agent-store-presigned-url.js +5 -1
  266. package/dist/index.d.ts +1 -0
  267. package/dist/index.d.ts.map +1 -1
  268. package/dist/index.js +1 -0
  269. package/dist/internal/approval-gate.d.ts +6 -1
  270. package/dist/internal/approval-gate.d.ts.map +1 -1
  271. package/dist/internal/approval-gate.js +13 -2
  272. package/dist/internal/authored-loaders.js +1 -1
  273. package/dist/internal/channel-architecture.d.ts.map +1 -1
  274. package/dist/internal/channel-architecture.js +3 -1
  275. package/dist/internal/cli/commands/channels.d.ts +9 -3
  276. package/dist/internal/cli/commands/channels.d.ts.map +1 -1
  277. package/dist/internal/cli/commands/channels.js +193 -4
  278. package/dist/internal/cli/commands/index.d.ts.map +1 -1
  279. package/dist/internal/cli/commands/index.js +6 -1
  280. package/dist/internal/cli/commands/serve.d.ts.map +1 -1
  281. package/dist/internal/cli/commands/serve.js +25 -5
  282. package/dist/internal/cli/dispatch.d.ts.map +1 -1
  283. package/dist/internal/cli/dispatch.js +22 -8
  284. package/dist/internal/cli/flags.d.ts +14 -0
  285. package/dist/internal/cli/flags.d.ts.map +1 -1
  286. package/dist/internal/cli/flags.js +14 -0
  287. package/dist/internal/cli/help.d.ts.map +1 -1
  288. package/dist/internal/cli/help.js +3 -1
  289. package/dist/internal/cli-cursor.js +2 -2
  290. package/dist/internal/cli-deploy.d.ts +1 -0
  291. package/dist/internal/cli-deploy.d.ts.map +1 -1
  292. package/dist/internal/cli-deploy.js +19 -1
  293. package/dist/internal/cli-mcp.d.ts.map +1 -1
  294. package/dist/internal/cli-mcp.js +5 -3
  295. package/dist/internal/cli-teams-doctor.d.ts +39 -0
  296. package/dist/internal/cli-teams-doctor.d.ts.map +1 -0
  297. package/dist/internal/cli-teams-doctor.js +508 -0
  298. package/dist/internal/cli-teams-forward.d.ts +84 -0
  299. package/dist/internal/cli-teams-forward.d.ts.map +1 -0
  300. package/dist/internal/cli-teams-forward.js +386 -0
  301. package/dist/internal/cli-teams-package.d.ts +26 -0
  302. package/dist/internal/cli-teams-package.d.ts.map +1 -0
  303. package/dist/internal/cli-teams-package.js +123 -0
  304. package/dist/internal/cli-teams.d.ts +15 -0
  305. package/dist/internal/cli-teams.d.ts.map +1 -0
  306. package/dist/internal/cli-teams.js +253 -0
  307. package/dist/internal/connect-click.d.ts +12 -0
  308. package/dist/internal/connect-click.d.ts.map +1 -0
  309. package/dist/internal/connect-click.js +22 -0
  310. package/dist/internal/continuation-channel.d.ts +5 -1
  311. package/dist/internal/continuation-channel.d.ts.map +1 -1
  312. package/dist/internal/continuation-channel.js +34 -0
  313. package/dist/internal/continuation-identity.d.ts +7 -4
  314. package/dist/internal/continuation-identity.d.ts.map +1 -1
  315. package/dist/internal/continuation-identity.js +66 -1
  316. package/dist/internal/convert-automation/convert-workflow.js +2 -2
  317. package/dist/internal/credential-env-names.d.ts +36 -0
  318. package/dist/internal/credential-env-names.d.ts.map +1 -0
  319. package/dist/internal/credential-env-names.js +68 -0
  320. package/dist/internal/cursor/account-mcp.d.ts +67 -9
  321. package/dist/internal/cursor/account-mcp.d.ts.map +1 -1
  322. package/dist/internal/cursor/account-mcp.js +206 -25
  323. package/dist/internal/cursor/backend-client.d.ts +10 -1
  324. package/dist/internal/cursor/backend-client.d.ts.map +1 -1
  325. package/dist/internal/cursor/backend-client.js +19 -7
  326. package/dist/internal/cursor/cloud-agent-identity.d.ts +81 -0
  327. package/dist/internal/cursor/cloud-agent-identity.d.ts.map +1 -0
  328. package/dist/internal/cursor/cloud-agent-identity.js +224 -0
  329. package/dist/internal/cursor/credentials.d.ts.map +1 -1
  330. package/dist/internal/cursor/credentials.js +3 -1
  331. package/dist/internal/cursor-account-mcp-auth.d.ts +1 -0
  332. package/dist/internal/cursor-account-mcp-auth.d.ts.map +1 -1
  333. package/dist/internal/cursor-account-mcp-auth.js +2 -1
  334. package/dist/internal/deploy-client.d.ts.map +1 -1
  335. package/dist/internal/deploy-client.js +34 -2
  336. package/dist/internal/deploy-manifest.d.ts +51 -3
  337. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  338. package/dist/internal/deploy-manifest.js +96 -7
  339. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  340. package/dist/internal/discovery/agent-config.js +6 -1
  341. package/dist/internal/discovery/connections.d.ts.map +1 -1
  342. package/dist/internal/discovery/connections.js +53 -0
  343. package/dist/internal/discovery/extensions.d.ts.map +1 -1
  344. package/dist/internal/discovery/extensions.js +2 -0
  345. package/dist/internal/discovery/info.d.ts.map +1 -1
  346. package/dist/internal/discovery/info.js +4 -0
  347. package/dist/internal/env-file.d.ts +1 -0
  348. package/dist/internal/env-file.d.ts.map +1 -1
  349. package/dist/internal/env-file.js +18 -17
  350. package/dist/internal/env-prefix.d.ts +11 -0
  351. package/dist/internal/env-prefix.d.ts.map +1 -0
  352. package/dist/internal/env-prefix.js +23 -0
  353. package/dist/internal/event-id-dedupe.d.ts +12 -0
  354. package/dist/internal/event-id-dedupe.d.ts.map +1 -0
  355. package/dist/{channels/slack → internal}/event-id-dedupe.js +7 -4
  356. package/dist/internal/event-mapper.d.ts +7 -2
  357. package/dist/internal/event-mapper.d.ts.map +1 -1
  358. package/dist/internal/event-mapper.js +7 -0
  359. package/dist/internal/expected-delivery-failure.d.ts.map +1 -1
  360. package/dist/internal/expected-delivery-failure.js +3 -0
  361. package/dist/internal/extension-namespace.d.ts +9 -0
  362. package/dist/internal/extension-namespace.d.ts.map +1 -0
  363. package/dist/internal/extension-namespace.js +14 -0
  364. package/dist/internal/guid.d.ts +2 -0
  365. package/dist/internal/guid.d.ts.map +1 -0
  366. package/dist/internal/guid.js +4 -0
  367. package/dist/internal/host-kv-cas.d.ts +13 -0
  368. package/dist/internal/host-kv-cas.d.ts.map +1 -0
  369. package/dist/internal/host-kv-cas.js +8 -0
  370. package/dist/internal/host-kv.d.ts +4 -1
  371. package/dist/internal/host-kv.d.ts.map +1 -1
  372. package/dist/internal/host-kv.js +15 -2
  373. package/dist/internal/hosted-catch-protocol.d.ts +5 -0
  374. package/dist/internal/hosted-catch-protocol.d.ts.map +1 -1
  375. package/dist/internal/hosted-catch-protocol.js +5 -0
  376. package/dist/internal/hosted-catch.d.ts +2 -0
  377. package/dist/internal/hosted-catch.d.ts.map +1 -1
  378. package/dist/internal/hosted-catch.js +6 -1
  379. package/dist/internal/hosted-delivery-protocol.d.ts +3 -0
  380. package/dist/internal/hosted-delivery-protocol.d.ts.map +1 -1
  381. package/dist/internal/hosted-delivery-protocol.js +69 -1
  382. package/dist/internal/hosted-delivery.d.ts +5 -2
  383. package/dist/internal/hosted-delivery.d.ts.map +1 -1
  384. package/dist/internal/hosted-delivery.js +11 -2
  385. package/dist/internal/hosted-session-fixture.js +1 -1
  386. package/dist/internal/hosting.d.ts +5 -0
  387. package/dist/internal/hosting.d.ts.map +1 -1
  388. package/dist/internal/hosting.js +7 -1
  389. package/dist/internal/install-cursor-skills.d.ts +6 -7
  390. package/dist/internal/install-cursor-skills.d.ts.map +1 -1
  391. package/dist/internal/install-cursor-skills.js +15 -9
  392. package/dist/internal/interview/agent-questions.d.ts +1 -1
  393. package/dist/internal/interview/agent-questions.d.ts.map +1 -1
  394. package/dist/internal/interview/agent-questions.js +4 -3
  395. package/dist/internal/local-control-plane.d.ts.map +1 -1
  396. package/dist/internal/local-control-plane.js +24 -0
  397. package/dist/internal/mcp-allowlist-in-use.d.ts +23 -0
  398. package/dist/internal/mcp-allowlist-in-use.d.ts.map +1 -0
  399. package/dist/internal/mcp-allowlist-in-use.js +93 -0
  400. package/dist/internal/mcp-endpoint.d.ts.map +1 -1
  401. package/dist/internal/mcp-endpoint.js +8 -10
  402. package/dist/internal/mcp-host.d.ts +19 -1
  403. package/dist/internal/mcp-host.d.ts.map +1 -1
  404. package/dist/internal/mcp-host.js +67 -3
  405. package/dist/internal/mcp-oauth.d.ts.map +1 -1
  406. package/dist/internal/mcp-oauth.js +5 -7
  407. package/dist/internal/oidcAudiences.d.ts +22 -0
  408. package/dist/internal/oidcAudiences.d.ts.map +1 -0
  409. package/dist/internal/oidcAudiences.js +35 -0
  410. package/dist/internal/otel/collector.d.ts.map +1 -1
  411. package/dist/internal/otel/collector.js +2 -0
  412. package/dist/internal/platform-timers.d.ts +2 -0
  413. package/dist/internal/platform-timers.d.ts.map +1 -1
  414. package/dist/internal/platform-timers.js +14 -0
  415. package/dist/internal/private-file.d.ts +32 -1
  416. package/dist/internal/private-file.d.ts.map +1 -1
  417. package/dist/internal/private-file.js +209 -7
  418. package/dist/internal/redact-values.d.ts +3 -0
  419. package/dist/internal/redact-values.d.ts.map +1 -0
  420. package/dist/internal/redact-values.js +19 -0
  421. package/dist/internal/reminder-control-plane-protocol.d.ts +7 -1
  422. package/dist/internal/reminder-control-plane-protocol.d.ts.map +1 -1
  423. package/dist/internal/reminder-followup-error.d.ts +23 -0
  424. package/dist/internal/reminder-followup-error.d.ts.map +1 -0
  425. package/dist/internal/reminder-followup-error.js +12 -0
  426. package/dist/internal/reminder-runner.d.ts +15 -1
  427. package/dist/internal/reminder-runner.d.ts.map +1 -1
  428. package/dist/internal/reminder-runner.js +95 -21
  429. package/dist/internal/resolved-connections.d.ts.map +1 -1
  430. package/dist/internal/resolved-connections.js +23 -3
  431. package/dist/internal/run-client.js +2 -1
  432. package/dist/internal/run-program.d.ts +31 -0
  433. package/dist/internal/run-program.d.ts.map +1 -0
  434. package/dist/internal/run-program.js +150 -0
  435. package/dist/internal/sdk-runner.d.ts +28 -2
  436. package/dist/internal/sdk-runner.d.ts.map +1 -1
  437. package/dist/internal/sdk-runner.js +298 -38
  438. package/dist/internal/server.d.ts.map +1 -1
  439. package/dist/internal/server.js +45 -4
  440. package/dist/internal/session-credential.d.ts +14 -0
  441. package/dist/internal/session-credential.d.ts.map +1 -0
  442. package/dist/internal/session-credential.js +25 -0
  443. package/dist/internal/session-engine.d.ts +136 -5
  444. package/dist/internal/session-engine.d.ts.map +1 -1
  445. package/dist/internal/session-engine.js +580 -92
  446. package/dist/internal/storage-coordinator.d.ts +3 -1
  447. package/dist/internal/storage-coordinator.d.ts.map +1 -1
  448. package/dist/internal/storage-coordinator.js +13 -0
  449. package/dist/internal/storage-roles.d.ts +9 -1
  450. package/dist/internal/storage-roles.d.ts.map +1 -1
  451. package/dist/internal/teams-channel-profile.d.ts +41 -0
  452. package/dist/internal/teams-channel-profile.d.ts.map +1 -0
  453. package/dist/internal/teams-channel-profile.js +91 -0
  454. package/dist/internal/teams-devtunnel.d.ts +55 -0
  455. package/dist/internal/teams-devtunnel.d.ts.map +1 -0
  456. package/dist/internal/teams-devtunnel.js +205 -0
  457. package/dist/internal/teams-tunnel-proxy.d.ts +17 -0
  458. package/dist/internal/teams-tunnel-proxy.d.ts.map +1 -0
  459. package/dist/internal/teams-tunnel-proxy.js +100 -0
  460. package/dist/internal/testing/conversation-identity-vectors.d.ts +7 -1
  461. package/dist/internal/testing/conversation-identity-vectors.d.ts.map +1 -1
  462. package/dist/internal/testing/conversation-identity-vectors.js +67 -0
  463. package/dist/internal/testing/hosted-http.d.ts +15 -0
  464. package/dist/internal/testing/hosted-http.d.ts.map +1 -0
  465. package/dist/internal/testing/hosted-http.js +86 -0
  466. package/dist/internal/testing/teams-activity-fixtures.d.ts +28 -0
  467. package/dist/internal/testing/teams-activity-fixtures.d.ts.map +1 -0
  468. package/dist/internal/testing/teams-activity-fixtures.js +236 -0
  469. package/dist/internal/testing/teams-doctor-fixtures.d.ts +76 -0
  470. package/dist/internal/testing/teams-doctor-fixtures.d.ts.map +1 -0
  471. package/dist/internal/testing/teams-doctor-fixtures.js +216 -0
  472. package/dist/internal/tunnel-process.d.ts +29 -0
  473. package/dist/internal/tunnel-process.d.ts.map +1 -0
  474. package/dist/internal/tunnel-process.js +105 -0
  475. package/dist/internal/turn-context.d.ts +28 -0
  476. package/dist/internal/turn-context.d.ts.map +1 -0
  477. package/dist/internal/turn-context.js +1 -0
  478. package/dist/oidc-token.d.ts +127 -0
  479. package/dist/oidc-token.d.ts.map +1 -0
  480. package/dist/oidc-token.js +221 -0
  481. package/dist/playground/assets/index-BaBSZXki.css +1 -0
  482. package/dist/playground/assets/index-BkAF8YlO.js +62 -0
  483. package/dist/playground/index.html +2 -2
  484. package/dist/teams-app-package.d.ts +78 -0
  485. package/dist/teams-app-package.d.ts.map +1 -0
  486. package/dist/teams-app-package.js +204 -0
  487. package/dist/tools.d.ts +1 -1
  488. package/dist/tools.d.ts.map +1 -1
  489. package/dist/types.d.ts +271 -2
  490. package/dist/types.d.ts.map +1 -1
  491. package/docs/changelog.md +35 -0
  492. package/docs/deployment.md +10 -0
  493. package/docs/guides/cloud-agents.md +47 -0
  494. package/docs/guides/teams.md +389 -0
  495. package/docs/reference/channels.md +1 -0
  496. package/docs/reference/cli.md +116 -0
  497. package/docs/reference/limits.md +4 -4
  498. package/docs/reference/sessions.md +13 -0
  499. package/docs/troubleshooting.md +21 -0
  500. package/package.json +21 -46
  501. package/skills/create-agent/SKILL.md +17 -4
  502. package/skills/debug/SKILL.md +1 -0
  503. package/skills/deploy/SKILL.md +1 -1
  504. package/skills/framework-map/SKILL.md +1 -0
  505. package/skills/setup-teams/SKILL.md +141 -0
  506. package/templates/agentic-owners/bot/lib/owners/parse.ts +1 -0
  507. package/dist/channels/slack/event-id-dedupe.d.ts +0 -10
  508. package/dist/channels/slack/event-id-dedupe.d.ts.map +0 -1
  509. package/dist/docs/assets/changelog.md.DVNB-ApU.js +0 -1
  510. package/dist/docs/assets/chunks/@localSearchIndexroot.DdlR-9Oe.js +0 -1
  511. package/dist/docs/assets/chunks/channel.CdyTxaXV.js +0 -1
  512. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.CeUcN6TW.js +0 -1
  513. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.CeUcN6TW.js +0 -1
  514. package/dist/docs/assets/chunks/clone.DpIwUbur.js +0 -1
  515. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.HtBkUH4J.js +0 -1
  516. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +0 -9
  517. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +0 -3
  518. package/dist/playground/assets/index-CnFd5R1_.js +0 -62
  519. package/dist/playground/assets/index-DNzRv6G8.css +0 -1
  520. /package/dist/docs/assets/{reference_channels.md.CPWOpdsC.lean.js → reference_channels.md.CRvqgU0n.lean.js} +0 -0
  521. /package/dist/docs/assets/{reference_schedules.md.RhQ9ZLo1.lean.js → reference_schedules.md.Dd8_d0WG.lean.js} +0 -0
@@ -0,0 +1,50 @@
1
+ import{_ as e,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Microsoft Teams","description":"Answer mentions, personal chats, and watched channel posts in Microsoft Teams with your own Azure Bot.","frontmatter":{"title":"Microsoft Teams","description":"Answer mentions, personal chats, and watched channel posts in Microsoft Teams with your own Azure Bot."},"headers":[],"relativePath":"guides/teams.md","filePath":"guides/teams.md"}'),n={name:"guides/teams.md"};function o(h,s,l,p,d,r){return t(),a("div",null,[...s[0]||(s[0]=[i(`<h1 id="microsoft-teams-agents" tabindex="-1">Microsoft Teams agents <a class="header-anchor" href="#microsoft-teams-agents" aria-label="Permalink to &quot;Microsoft Teams agents&quot;">​</a></h1><p>A Teams agent wakes when someone @mentions it in a channel or group chat, messages it in a personal chat, or posts in a channel it watches. It answers in the same reply chain. <code>teamsChannel()</code> takes the same engagement options as <code>slackChannel()</code>, so an agent that already runs in Slack can run in Teams with the same shape of config.</p><p>The agent answers as an Azure Bot that you register and own. Teams sends each message to the bot&#39;s messaging endpoint, and the channel checks the Bot Framework token on every request before it starts a turn.</p><h2 id="set-up-with-the-cli" tabindex="-1">Set up with the CLI <a class="header-anchor" href="#set-up-with-the-cli" aria-label="Permalink to &quot;Set up with the CLI&quot;">​</a></h2><p>The <code>agent-sdk channels teams</code> commands do every step except the clicks in the Azure portal and in Teams:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> channels</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> teams</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> setup</span></span>
2
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">printf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> %s</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$CLIENT_SECRET</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> channels</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> teams</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./helm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
3
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --app-id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">microsoft-app-i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --tenant-id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">app-tenant-i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span>
4
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> channels</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> teams</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> package</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./helm</span></span>
5
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./helm</span></span>
6
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> channels</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> teams</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./helm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --endpoint</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &lt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">printed</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> UR</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">L</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">&gt;</span></span></code></pre></div><ol><li><code>setup</code> prints the Azure portal steps in <a href="#register-the-azure-bot">Register the Azure Bot</a>.</li><li><code>init</code> writes <code>bot/channels/teams.ts</code> and puts the app id, the client secret, and the tenant id in <code>.env.local</code>. It reads the secret from a hidden prompt or stdin, never from an argument.</li><li><code>package</code> writes <code>helm-teams-app.zip</code>. Upload it in Teams, as <a href="#install-the-bot-in-teams">Install the bot in Teams</a> describes.</li><li><code>dev</code> opens a tunnel and prints the messaging endpoint. Set it on the Azure Bot.</li><li><code>doctor</code> checks the env names, the token, the Azure Bot, and the endpoint, and names the part that fails.</li></ol><p>The <a href="./../reference/cli.html#teams">CLI reference</a> lists every flag. The rest of this guide explains what the commands write and how the channel behaves.</p><h2 id="answer-a-mention-or-personal-chat" tabindex="-1">Answer a mention or personal chat <a class="header-anchor" href="#answer-a-mention-or-personal-chat" aria-label="Permalink to &quot;Answer a mention or personal chat&quot;">​</a></h2><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/teams.ts</span></span>
7
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { teamsChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@grok/agent-sdk/channels/teams&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
8
+ <span class="line"></span>
9
+ <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;"> teamsChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span></code></pre></div><p>By default the agent answers @mentions in channels and group chats, and every message in a personal chat. While a turn runs, Teams shows the typing indicator, and the reply arrives as one message in the reply chain. In a channel, each reply chain is its own conversation. A personal chat and a group chat have no reply chains, so each one is a single conversation.</p><p>The channel reads three variables:</p><table tabindex="0"><thead><tr><th>Variable</th><th>Value</th></tr></thead><tbody><tr><td><code>TEAMS_APP_ID</code></td><td>The Azure Bot&#39;s Microsoft App ID</td></tr><tr><td><code>TEAMS_APP_PASSWORD</code></td><td>A client secret of that app registration</td></tr><tr><td><code>TEAMS_TENANT_ID</code></td><td>Required. The home tenant of your single-tenant Azure Bot</td></tr></tbody></table><p>The Azure Bot is a single-tenant bot in your own tenant, because Azure does not create new multi-tenant bots after July 31, 2025. The channel mints its Bot Connector token in that tenant and ignores activities from any other tenant. To run several agents in one <code>agent-sdk dev</code>, give each its own bot and an <code>envPrefix</code>. <code>channels teams init --prefix HELPDESK</code> writes it for you. The prefix starts with a letter.</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;"> teamsChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ envPrefix: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;HELPDESK&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
10
+ <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// HELPDESK_TEAMS_APP_ID, HELPDESK_TEAMS_APP_PASSWORD, HELPDESK_TEAMS_TENANT_ID</span></span></code></pre></div><p>The channel file owns these names. When the file exists, <code>init</code> writes the names it reads, and <code>doctor</code> and <code>package</code> read them from the loaded channel.</p><h2 id="register-the-azure-bot" tabindex="-1">Register the Azure Bot <a class="header-anchor" href="#register-the-azure-bot" aria-label="Permalink to &quot;Register the Azure Bot&quot;">​</a></h2><ol><li>In the Azure portal, create an <strong>Azure Bot</strong> resource. Set <strong>Type of App</strong> to <strong>Single Tenant</strong> and <strong>Creation type</strong> to <strong>Create new Microsoft App ID</strong>.</li><li>Open the bot&#39;s <strong>Configuration</strong> page. Copy <strong>Microsoft App ID</strong> and <strong>App Tenant ID</strong>. <code>init</code> takes them as <code>--app-id</code> and <code>--tenant-id</code>.</li><li>From <strong>Configuration</strong>, open <strong>Manage Password</strong>, add a client secret, and copy its value. Azure shows the value once. <code>init</code> reads it from the hidden prompt or stdin.</li><li>Under <strong>Channels</strong>, add <strong>Microsoft Teams</strong>.</li><li>Set <strong>Messaging endpoint</strong> to the URL in <a href="#messaging-endpoint">Messaging endpoint</a>, or for a hosted deploy, the URL in <a href="#deploy">Deploy</a>.</li></ol><h2 id="install-the-bot-in-teams" tabindex="-1">Install the bot in Teams <a class="header-anchor" href="#install-the-bot-in-teams" aria-label="Permalink to &quot;Install the bot in Teams&quot;">​</a></h2><p>Teams installs a bot from an app package: a zip of <code>manifest.json</code> and two icons. <code>agent-sdk channels teams package</code> builds it from the channel. The <code>bots</code> entry names the Azure Bot by its app ID and the places people can talk to it:</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>
11
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;&lt;TEAMS_APP_ID&gt;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
12
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;bots&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
13
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
14
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;botId&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;&lt;TEAMS_APP_ID&gt;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
15
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;scopes&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;personal&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;team&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;groupChat&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
16
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;isNotificationOnly&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span></span>
17
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
18
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ]</span></span>
19
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>A full manifest also needs <code>manifestVersion</code>, <code>version</code>, <code>developer</code>, <code>name</code>, <code>description</code>, <code>icons</code>, and <code>accentColor</code>; see the <a href="https://learn.microsoft.com/microsoftteams/platform/resources/schema/manifest-schema" target="_blank" rel="noreferrer">app manifest schema</a>. Upload the package in Teams under <strong>Apps</strong> &gt; <strong>Manage your apps</strong> &gt; <strong>Upload an app</strong>, or have a Teams admin publish it to your organization in the Teams admin center. Then add the app to a team, a group chat, or a personal chat.</p><h2 id="wake-on-a-channel-post" tabindex="-1">Wake on a channel post <a class="header-anchor" href="#wake-on-a-channel-post" aria-label="Permalink to &quot;Wake on a channel post&quot;">​</a></h2><p>Teams sends a channel post without a mention only to an app that holds the resource-specific consent permission <code>ChannelMessage.Read.Group</code>. <code>package</code> adds it when the channel sets <code>engagement.channelPosts</code>, and a team owner grants it when they add the app to the team:</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>
20
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;webApplicationInfo&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: { </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;id&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;&lt;TEAMS_APP_ID&gt;&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
21
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;authorization&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
22
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;permissions&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
23
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;resourceSpecific&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [{ </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;name&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ChannelMessage.Read.Group&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">&quot;type&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Application&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }]</span></span>
24
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
25
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
26
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Then name the channels to watch. Copy a channel&#39;s ID from its <strong>Get link to channel</strong> URL: it&#39;s the <code>19:…@thread.tacv2</code> part.</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;"> teamsChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
27
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> engagement: {</span></span>
28
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> channelPosts: {</span></span>
29
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> allow: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;19:4b7c2f9e1d6a4e8f9a3b5c7d1e2f3a4b@thread.tacv2&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
30
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> posts: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;all&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
31
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
32
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
33
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Watched posts go to <code>onChannelPost</code> when you set it, the same way mentions go to <code>onAppMention</code> and personal chats to <code>onDirectMessage</code>. Return <code>null</code> from a hook to skip a message. <code>posts</code> is <code>&quot;top-level&quot;</code> (the default), <code>&quot;replies&quot;</code>, or <code>&quot;all&quot;</code>. Use <code>allow: [&quot;*&quot;]</code> to watch every channel the app is in, and <code>replies: &quot;joined&quot;</code> to also answer replies in any reply chain the agent already answered. Bot posts stay out unless you set <code>includeBotPosts: true</code>; the agent&#39;s own posts never start a turn.</p><p>To let another bot wake the agent with an @mention, list it in <code>engagement.botMentions.allowFrom</code> as <code>28:&lt;its app ID&gt;</code>. Each thread allows 5 bot wakes an hour and 20 in total by default (<code>maxPerThreadPerHour</code>, <code>maxPerThreadTotal</code>).</p><h2 id="stream-the-reply" tabindex="-1">Stream the reply <a class="header-anchor" href="#stream-the-reply" aria-label="Permalink to &quot;Stream the reply&quot;">​</a></h2><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;"> teamsChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ reply: { mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;stream&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } });</span></span></code></pre></div><p>In stream mode the agent posts one message as soon as it starts working. That message names the tool the agent is running until text arrives, then fills in as the reply grows, and it ends as the final answer. Teams limits how often a bot can edit a message, so the channel edits at most once every 1.5 seconds; set <code>updateIntervalMs</code> to change that.</p><h2 id="approve-tool-calls-in-teams" tabindex="-1">Approve tool calls in Teams <a class="header-anchor" href="#approve-tool-calls-in-teams" aria-label="Permalink to &quot;Approve tool calls in Teams&quot;">​</a></h2><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;"> teamsChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ toolApprovals: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span></code></pre></div><p>When a server tool with <code>needsApproval</code> is about to run, the agent posts an Adaptive Card in the thread with the tool&#39;s arguments, secrets redacted, and <strong>Approve</strong> and <strong>Deny</strong> buttons. Anyone who could continue the conversation can decide; set <code>policy: { respondTo: &quot;author&quot; }</code> to limit that, and follow-ups, to the person who started it. After the click, the card shows the decision and who made it.</p><p>For your own cards, handle other <code>Action.Submit</code> clicks in <code>onCardAction</code>, which receives the submitted data and can start a turn in the card&#39;s thread.</p><h2 id="refuse-guests-and-other-tenants" tabindex="-1">Refuse guests and other tenants <a class="header-anchor" href="#refuse-guests-and-other-tenants" aria-label="Permalink to &quot;Refuse guests and other tenants&quot;">​</a></h2><p>By default the channel answers only members and owners of the bot&#39;s tenant. It asks Teams for the sender&#39;s role and tenant. It refuses a guest, an anonymous meeting user, or a person from another organization. This applies when they message the agent and when they click a card. <strong>Approve</strong> and <strong>Deny</strong> are card clicks. A sender with no role is refused. A sender Teams does not list is refused too.</p><p>The agent posts one short reply to a refused sender. It posts at most once per conversation and sender per hour. The default text is &quot;I can only help members of this organization. Ask the agent owner to allow guests.&quot;</p><p>Set <code>policy.refusalMessage</code> to change the default text. Set <code>policy.refusalMessage</code> to <code>false</code> to stay silent. Silence applies to a refused sender and to a sender the lookup could not verify.</p><p>A failed lookup gets the reply &quot;I couldn&#39;t verify your access, try again shortly.&quot; The agent does not reply to a card click from a refused sender. The agent ignores a card click from a bot, including a bot that <code>engagement.botMentions</code> allows. The agent does not reply to an activity from another tenant.</p><p>To let guests and external members in, set <code>blockExternals</code> to <code>false</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:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> teamsChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ policy: { blockExternals: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } });</span></span></code></pre></div><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;"> teamsChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
34
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> policy: {</span></span>
35
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> refusalMessage: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Ask your team owner to add you to this organization.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
36
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
37
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="welcome-message" tabindex="-1">Welcome message <a class="header-anchor" href="#welcome-message" aria-label="Permalink to &quot;Welcome message&quot;">​</a></h2><p>When someone installs the app in a conversation, the agent posts one greeting there. Teams reports the install as an <code>installationUpdate</code> activity whose action is <code>add</code>. The greeting does not start a model turn. The agent posts it once per conversation.</p><p>The default text is &quot;Hi! Mention me in a channel, or message me here, to get started.&quot;</p><p>Set <code>welcome</code> to change the greeting. Set <code>welcome</code> to <code>false</code> to turn it off.</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;"> teamsChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
38
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> welcome: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Hi. Mention me when you want help with a laptop.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
39
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="messaging-endpoint" tabindex="-1">Messaging endpoint <a class="header-anchor" href="#messaging-endpoint" aria-label="Permalink to &quot;Messaging endpoint&quot;">​</a></h2><p>Under <code>agent-sdk dev</code> or self-hosted <code>agent-sdk serve</code>, the Azure Bot&#39;s messaging endpoint is the server&#39;s public origin plus the channel&#39;s 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>https://&lt;origin&gt;/&lt;slug&gt;/v1/channels/&lt;channel&gt;</span></span></code></pre></div><p><code>&lt;slug&gt;</code> is the agent&#39;s slug and <code>&lt;channel&gt;</code> is the channel file&#39;s name, so <code>bot/channels/teams.ts</code> in the <code>helm</code> agent answers at <code>https://&lt;origin&gt;/helm/v1/channels/teams</code>. The URL has no trailing slash. With <code>teamsChannel({ path: &quot;/messages&quot; })</code>, the channel appends that path: <code>https://&lt;origin&gt;/helm/v1/channels/teams/messages</code>. A hosted deploy has a different URL; see <a href="#deploy">Deploy</a>.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;">​</a></h2><p>Teams reaches the bot only at a public HTTPS URL. <code>agent-sdk dev</code> opens a <code>cloudflared</code> tunnel and prints the messaging endpoint on the tunnel&#39;s origin:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./helm</span></span></code></pre></div><p>Copy the printed URL into the Azure Bot&#39;s <strong>Messaging endpoint</strong>, then mention the bot in Teams. <code>--tunnel devtunnel</code> keeps one URL across restarts. Next to a plain <code>agent-sdk serve</code>, <code>agent-sdk channels teams forward</code> opens the same tunnel. <code>agent-sdk dev --mode single</code> serves one agent without a slug, so its endpoint is <code>https://&lt;origin&gt;/v1/channels/teams</code>. Without <code>--mode single</code>, the endpoint includes the agent&#39;s slug: <code>https://&lt;origin&gt;/helm/v1/channels/teams</code>.</p><p>To run your own tunnel instead, serve with plain <code>agent-sdk serve</code>, which opens no tunnel, and point <code>cloudflared</code> at its port:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./helm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --mode</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> single</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --port</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 3978</span></span>
40
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">cloudflared</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tunnel</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://localhost:3978</span></span></code></pre></div><p>Add <code>--protocol http2</code> to <code>cloudflared</code> if your network blocks QUIC. Set the Azure Bot&#39;s <strong>Messaging endpoint</strong> to the printed <code>&lt;public-url&gt;</code> plus <code>/v1/channels/teams</code>, or <code>&lt;public-url&gt;/helm/v1/channels/teams</code> without <code>--mode single</code>. The built-in tunnel forwards only <code>POST</code> requests to the Teams messaging paths. A tunnel you run yourself exposes every route on the port.</p><p>Requests through a tunnel always get the Bot Framework token check, so only Teams can start turns there. A tunnel adds proxy headers or forwards its public hostname, and the dev exception for unsigned activities refuses both. To replay a saved activity without Teams, POST it to the same path on <code>http://127.0.0.1:&lt;port&gt;</code> from the same machine; <code>agent-sdk dev</code> admits unsigned activities from loopback only.</p><h2 id="deploy" tabindex="-1">Deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to &quot;Deploy&quot;">​</a></h2><p>Hosted, the agent needs its three secrets:</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/agent.ts</span></span>
41
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineAgent } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@grok/agent-sdk&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
42
+ <span class="line"></span>
43
+ <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>
44
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> hosting: {</span></span>
45
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> secretNames: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;TEAMS_APP_ID&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;TEAMS_APP_PASSWORD&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;TEAMS_TENANT_ID&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
46
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
47
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Hosting adds the Microsoft hosts that a Teams channel calls (<code>login.microsoftonline.com</code>, <code>login.botframework.com</code>, and <code>smba.trafficmanager.net</code>), so you do not list them in <code>egressDomains</code>. Your team&#39;s network settings still apply to them. If your team restricts egress, its allowlist must include all three hosts, or the agent&#39;s replies fail.</p><p>An <code>envPrefix</code> changes the secret names. With <code>teamsChannel({ envPrefix: &quot;ECHO&quot; })</code>, list <code>ECHO_TEAMS_APP_ID</code>, <code>ECHO_TEAMS_APP_PASSWORD</code>, and <code>ECHO_TEAMS_TENANT_ID</code> in <code>secretNames</code>, and set those names with <code>agent-sdk secret set</code>.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> helpdesk</span></span>
48
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secret</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> helpdesk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TEAMS_APP_ID</span></span>
49
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secret</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> helpdesk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TEAMS_APP_PASSWORD</span></span>
50
+ <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> secret</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> helpdesk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TEAMS_TENANT_ID</span></span></code></pre></div><p><code>agent-sdk deploy</code> prints the hosted messaging endpoint on a <code>public:</code> line that ends in <code>/v1/channels/teams</code>. Set the Azure Bot&#39;s <strong>Messaging endpoint</strong> to that URL, not to the slug URL from local testing. With a custom <code>path</code>, add it after the printed URL.</p><p>On hosting, Cursor checks the Bot Framework token and the tenant before the agent starts. Activities that the channel cannot act on, such as a reaction or an unmentioned post outside <code>channelPosts</code>, stop there and use no compute. Each personal or group chat is one session, and each channel reply chain is one session. Tool approvals work on hosting: an Approve or Deny click reaches the turn that waits for it, and a call that nobody approves in 10 minutes is denied.</p><p>Hosting runs Teams channels only in the commercial Microsoft cloud, and only for teams that have Teams channels turned on. The deploy fails otherwise.</p><h2 id="how-teams-differs-from-slack" tabindex="-1">How Teams differs from Slack <a class="header-anchor" href="#how-teams-differs-from-slack" aria-label="Permalink to &quot;How Teams differs from Slack&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Slack</th><th>Teams</th></tr></thead><tbody><tr><td>App</td><td>Your Slack app&#39;s bot and app tokens</td><td>Your Azure Bot&#39;s app ID, client secret, and tenant</td></tr><tr><td>Local transport</td><td>Socket Mode, no public URL</td><td><code>agent-sdk dev</code> opens a tunnel to the messaging endpoint</td></tr><tr><td>Watch channel posts</td><td><code>message.channels</code> subscription</td><td><code>ChannelMessage.Read.Group</code> consent at install</td></tr><tr><td>Threads</td><td>Every message can start a thread</td><td>Reply chains in channels; personal and group chats are one conversation each</td></tr><tr><td>Bot-to-bot wakes</td><td><code>maxDepth</code> from message metadata, plus per-thread caps</td><td>Per-thread caps only</td></tr><tr><td>Progress</td><td>Status chip, streaming API, tool and reasoning cards</td><td>Typing indicator, or one edited message in stream mode</td></tr><tr><td>Approvals</td><td>Block Kit buttons</td><td>Adaptive Card buttons</td></tr><tr><td>Hosted sessions</td><td>One per thread</td><td>One per chat, or one per channel reply chain</td></tr><tr><td>Not available in Teams</td><td></td><td>Reactions, file uploads and downloads, suggested prompts, <code>eval</code> commands, edit debounce</td></tr></tbody></table><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="./slack.html">Slack</a></li><li><a href="./webhooks.html">Webhooks</a></li><li><a href="./../deployment.html">Deployment</a></li><li><a href="./../reference/channels.html">Channels reference</a></li></ul>`,74)])])}const g=e(n,[["render",o]]);export{k as __pageData,g as default};
@@ -0,0 +1 @@
1
+ import{_ as e,c as a,o as t,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Microsoft Teams","description":"Answer mentions, personal chats, and watched channel posts in Microsoft Teams with your own Azure Bot.","frontmatter":{"title":"Microsoft Teams","description":"Answer mentions, personal chats, and watched channel posts in Microsoft Teams with your own Azure Bot."},"headers":[],"relativePath":"guides/teams.md","filePath":"guides/teams.md"}'),n={name:"guides/teams.md"};function o(h,s,l,p,d,r){return t(),a("div",null,[...s[0]||(s[0]=[i("",74)])])}const g=e(n,[["render",o]]);export{k as __pageData,g as default};
@@ -18,4 +18,4 @@ import{_ as t,c as s,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const u
18
18
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
19
19
  <span class="line"><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>
21
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>This route is <code>POST /v1/channels/&lt;id&gt;/review</code>. Calls for the same pull request pass the same <a href="./sessions.html#session-identifiers">continuation token</a>, so they share one conversation.</p><h2 id="route-responses" tabindex="-1">Route responses <a class="header-anchor" href="#route-responses" aria-label="Permalink to &quot;Route responses&quot;">​</a></h2><p>On Cursor hosting, the deployment answers every custom route with an empty <code>202 Accepted</code> as soon as the request arrives, then runs the handler. The caller never sees the handler&#39;s <code>Response</code>, so a route can&#39;t return a session ID, a result, or an error status. A request that fails the alias token, <code>sharedSecretAuth</code>, or <code>hmacSignatureAuth</code> check still gets <code>401</code>.</p><p>Deliver results through <a href="#events"><code>events</code></a> handlers, a callback to the sender, or a tool the turn calls. Local <code>serve</code> returns the handler&#39;s response, so return <code>new Response(null, { status: 202 })</code> to match hosting.</p><h2 id="route-verbs-and-schemas" tabindex="-1">Route verbs and schemas <a class="header-anchor" href="#route-verbs-and-schemas" aria-label="Permalink to &quot;Route verbs and schemas&quot;">​</a></h2><p>Route paths must begin with <code>/</code>.</p><p><code>GET</code> requires a <code>querySchema</code>.</p><p><code>POST</code>, <code>PUT</code>, and <code>PATCH</code> require a <code>bodySchema</code>. They also accept a <code>querySchema</code>.</p><p><code>DELETE</code> takes a <code>bodySchema</code>, a <code>querySchema</code>, either, or neither.</p><p>Plain JSON Schema objects don&#39;t type-check, so use <code>z.object({})</code> or <code>z.unknown()</code> for an open surface. The host validates input before the handler runs, and declared schemas appear in <code>GET /v1/info</code> for the playground and slash commands.</p><h2 id="handler-arguments" tabindex="-1">Handler arguments <a class="header-anchor" href="#handler-arguments" aria-label="Permalink to &quot;Handler arguments&quot;">​</a></h2><p>A handler receives the Fetch <code>Request</code> and these arguments:</p><table tabindex="0"><thead><tr><th>Member</th><th>Contract</th></tr></thead><tbody><tr><td><code>send(message, options?)</code></td><td>Start or resume a session on this channel</td></tr><tr><td><code>getSession(sessionId)</code></td><td>This channel&#39;s session, or <code>null</code></td></tr><tr><td><code>receive(channel, input)</code></td><td>Hand work to another channel</td></tr><tr><td><code>callTool(name, input, options?)</code></td><td><a href="./tools.html#call-a-tool-without-a-model-turn">Call a server tool</a> without a model turn</td></tr><tr><td><code>body</code>, <code>query</code>, <code>params</code></td><td>Validated inputs and <code>:param</code> path segments</td></tr><tr><td><code>auth</code></td><td>The <code>AuthContext</code> from the route&#39;s auth chain</td></tr><tr><td><code>requestIp</code></td><td>The TCP peer address, or <code>null</code></td></tr><tr><td><code>host</code></td><td>Host services such as MCP, storage, telemetry, and reminders</td></tr><tr><td><code>waitUntil(promise)</code></td><td>Keep work running after the handler returns</td></tr><tr><td><code>sessionUrls(request, sessionId)</code></td><td>Playground and trace URLs for a session</td></tr><tr><td><code>artifacts</code></td><td>List or tag <a href="./artifacts.html">artifacts</a></td></tr></tbody></table><h3 id="send-options" tabindex="-1"><code>send</code> options <a class="header-anchor" href="#send-options" aria-label="Permalink to &quot;\`send\` options&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>continuationToken</code></td><td>Channel-local key that resumes its session, or creates one when new</td></tr><tr><td><code>admission</code></td><td><code>&quot;preempt&quot;</code> (the default) interrupts a busy turn. <code>&quot;coalesce&quot;</code> queues behind it</td></tr><tr><td><code>workspaceFiles</code></td><td>Relative files to add before the next turn</td></tr><tr><td><code>workspaceDir</code></td><td>Absolute local working directory</td></tr><tr><td><code>auth</code></td><td>Session principal. Defaults to the request principal</td></tr><tr><td><code>state</code></td><td>Starting channel state for a new session</td></tr><tr><td><code>title</code>, <code>purpose</code>, <code>dryRun</code>, <code>asOf</code></td><td>Set up a new session, as in the <a href="./http-api.html#start-a-session"><code>POST /v1/session</code> body</a></td></tr><tr><td><code>deliveryId</code></td><td>Names this send on the session&#39;s <a href="./sessions.html#track-which-follow-up-reached-the-agent">events</a>, up to 256 characters. Defaults to a fresh <code>dlv_…</code> ID</td></tr></tbody></table><p><code>send</code> returns a <code>ChannelSession</code> with <code>id</code>, the current <code>continuationToken</code>, <code>isNew</code>, and <code>coalesced: true</code> for a coalesced call. On Cursor hosting, it returns the ID before the session exists.</p><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for its sessions. Keys are types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>&quot;*&quot;</code>. Each handler receives <code>(event, channel, ctx)</code> with <code>channel.state</code>, session info, and host services, so it can post progress and replies. <code>state</code> on the channel definition is each new session&#39;s starting JSON, unless a route passes <code>state</code> to <code>send</code>, and handlers update it through <code>channel.state</code>.</p><h2 id="start-and-stop-a-channel" tabindex="-1">Start and stop a channel <a class="header-anchor" href="#start-and-stop-a-channel" aria-label="Permalink to &quot;Start and stop a channel&quot;">​</a></h2><p><code>onStart(args)</code> runs when the channel mounts, and <code>onStop()</code> runs when the host stops. Besides the route helpers, <code>onStart</code> receives <code>emitAssistantMessage(sessionId, text)</code>, which appends assistant text without a model turn, and <code>hasContinuationSession</code>, <code>isContinuationBusy</code>, and <code>interruptContinuation</code>, which check or stop the session behind a token.</p><h2 id="auth-policies" tabindex="-1">Auth policies <a class="header-anchor" href="#auth-policies" aria-label="Permalink to &quot;Auth policies&quot;">​</a></h2><p>Every route runs the channel&#39;s <code>auth</code> array, which defaults to <code>[localDevStrict()]</code>. The first policy to return an <code>AuthContext</code> admits the request, and if every policy returns <code>null</code>, the route answers <code>401</code>.</p><table tabindex="0"><thead><tr><th>Policy</th><th>Admits</th></tr></thead><tbody><tr><td><code>localDevStrict()</code></td><td>Direct loopback requests with a loopback hostname and no forwarding headers</td></tr><tr><td><code>localDev()</code></td><td>The same, with any hostname</td></tr><tr><td><code>loopbackOnly()</code></td><td>Any loopback peer, including relays that add forwarding headers</td></tr><tr><td><code>bearerAuth(tokenOrVerify)</code></td><td>A matching bearer token, or one the verifier accepts</td></tr><tr><td><code>sharedSecretAuth({ header, secret })</code></td><td>A header that matches the named secret</td></tr><tr><td><code>hmacSignatureAuth({ header, secret, prefix?, separator? })</code></td><td>A hex HMAC-SHA256 signature of the raw body under the named secret, or any of several signatures split by <code>separator</code>. The secret can hold up to 32 values, one per line, and any of them verifies</td></tr><tr><td><code>allowAll()</code></td><td>Every caller, as an anonymous principal</td></tr><tr><td><code>publicEndpoint()</code></td><td>Every caller, with no alias token on hosting. The handler must verify the provider&#39;s signature</td></tr></tbody></table><p>Use <code>allowAll()</code> only for a public surface or one protected upstream. <code>publicEndpoint()</code> applies only to custom channel routes and doesn&#39;t open the built-in session or tool API.</p><p>The admitted <code>AuthContext</code> becomes the request principal, which <a href="./sessions.html#session-contents">owns the sessions it creates</a>.</p><p>On a channel without its own <code>auth</code>, <code>--bearer-token</code> swaps the default for <code>bearerAuth(...)</code> and <code>--allow-anonymous</code> swaps it for <code>allowAll()</code>.</p><h2 id="prebuilt-channels" tabindex="-1">Prebuilt channels <a class="header-anchor" href="#prebuilt-channels" aria-label="Permalink to &quot;Prebuilt channels&quot;">​</a></h2><p>Import each one from <code>@grok/agent-sdk/channels/&lt;name&gt;</code>.</p><table tabindex="0"><thead><tr><th>Function</th><th>Details</th></tr></thead><tbody><tr><td><code>slackChannel()</code></td><td><a href="./../guides/slack.html">Slack</a></td></tr><tr><td><code>githubChannel()</code></td><td><a href="./../guides/github.html">GitHub</a></td></tr><tr><td><code>gitlabChannel()</code></td><td><a href="./../guides/gitlab.html">GitLab</a></td></tr><tr><td><code>bitbucketChannel()</code></td><td><a href="./../guides/bitbucket.html">Bitbucket</a></td></tr><tr><td><code>pagerdutyChannel()</code></td><td><a href="./../guides/pagerduty.html">PagerDuty</a></td></tr><tr><td><code>deploymentsChannel()</code></td><td>Deployment events filtered by source, environment, or event name</td></tr></tbody></table><p>Use <code>defineChannel</code> for other platforms, such as Discord.</p><h2 id="handler-results" tabindex="-1">Handler results <a class="header-anchor" href="#handler-results" aria-label="Permalink to &quot;Handler results&quot;">​</a></h2><p>Hooks on the GitHub, GitLab, Bitbucket, and PagerDuty channels, such as <code>onPullRequest</code> or <code>onIncident</code>, return one of three results:</p><table tabindex="0"><thead><tr><th>Return value</th><th>What happens</th></tr></thead><tbody><tr><td><code>{ auth }</code></td><td>Runs the model turn with that auth. It can also set the turn&#39;s <code>message</code>, <code>title</code>, or <code>context</code></td></tr><tr><td><code>{ task }</code></td><td>Runs your function on the host. That function can call <code>send</code> to start a model turn</td></tr><tr><td><code>null</code></td><td>Ignores the event</td></tr></tbody></table><h2 id="hosted-session-keys" tabindex="-1">Hosted session keys <a class="header-anchor" href="#hosted-session-keys" aria-label="Permalink to &quot;Hosted session keys&quot;">​</a></h2><p>On Cursor hosting, each request to a <code>defineChannel</code> route starts a new session unless it carries <code>X-BDK-Session-Key</code>. Requests with the same value on one channel share one session, in arrival order. The handler&#39;s <code>continuationToken</code> doesn&#39;t change that choice, and local <code>serve</code> ignores the header.</p><table tabindex="0"><thead><tr><th>Rule</th><th>Contract</th></tr></thead><tbody><tr><td>Auth</td><td>The alias token or <code>sharedSecretAuth()</code>. Routes admitted by <code>hmacSignatureAuth()</code> or <code>publicEndpoint()</code> answer <code>400</code></td></tr><tr><td>Value</td><td>1 to 256 printable ASCII characters with no space or comma, or the request gets <code>400</code>. Hosting stores the value, so keep secrets and personal data out of it</td></tr><tr><td>Scope</td><td>One channel on one deployment. Prebuilt channels ignore the header</td></tr><tr><td>Retries</td><td>Hosting doesn&#39;t deduplicate. A retry runs a second turn</td></tr></tbody></table><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="./../guides/webhooks.html">Webhooks</a></li><li><a href="./sessions.html">Sessions</a></li></ul>`,43)])])}const k=t(i,[["render",o]]);export{u as __pageData,k as default};
21
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>This route is <code>POST /v1/channels/&lt;id&gt;/review</code>. Calls for the same pull request pass the same <a href="./sessions.html#session-identifiers">continuation token</a>, so they share one conversation.</p><h2 id="route-responses" tabindex="-1">Route responses <a class="header-anchor" href="#route-responses" aria-label="Permalink to &quot;Route responses&quot;">​</a></h2><p>On Cursor hosting, the deployment answers every custom route with an empty <code>202 Accepted</code> as soon as the request arrives, then runs the handler. The caller never sees the handler&#39;s <code>Response</code>, so a route can&#39;t return a session ID, a result, or an error status. A request that fails the alias token, <code>sharedSecretAuth</code>, or <code>hmacSignatureAuth</code> check still gets <code>401</code>.</p><p>Deliver results through <a href="#events"><code>events</code></a> handlers, a callback to the sender, or a tool the turn calls. Local <code>serve</code> returns the handler&#39;s response, so return <code>new Response(null, { status: 202 })</code> to match hosting.</p><h2 id="route-verbs-and-schemas" tabindex="-1">Route verbs and schemas <a class="header-anchor" href="#route-verbs-and-schemas" aria-label="Permalink to &quot;Route verbs and schemas&quot;">​</a></h2><p>Route paths must begin with <code>/</code>.</p><p><code>GET</code> requires a <code>querySchema</code>.</p><p><code>POST</code>, <code>PUT</code>, and <code>PATCH</code> require a <code>bodySchema</code>. They also accept a <code>querySchema</code>.</p><p><code>DELETE</code> takes a <code>bodySchema</code>, a <code>querySchema</code>, either, or neither.</p><p>Plain JSON Schema objects don&#39;t type-check, so use <code>z.object({})</code> or <code>z.unknown()</code> for an open surface. The host validates input before the handler runs, and declared schemas appear in <code>GET /v1/info</code> for the playground and slash commands.</p><h2 id="handler-arguments" tabindex="-1">Handler arguments <a class="header-anchor" href="#handler-arguments" aria-label="Permalink to &quot;Handler arguments&quot;">​</a></h2><p>A handler receives the Fetch <code>Request</code> and these arguments:</p><table tabindex="0"><thead><tr><th>Member</th><th>Contract</th></tr></thead><tbody><tr><td><code>send(message, options?)</code></td><td>Start or resume a session on this channel</td></tr><tr><td><code>getSession(sessionId)</code></td><td>This channel&#39;s session, or <code>null</code></td></tr><tr><td><code>receive(channel, input)</code></td><td>Hand work to another channel</td></tr><tr><td><code>callTool(name, input, options?)</code></td><td><a href="./tools.html#call-a-tool-without-a-model-turn">Call a server tool</a> without a model turn</td></tr><tr><td><code>body</code>, <code>query</code>, <code>params</code></td><td>Validated inputs and <code>:param</code> path segments</td></tr><tr><td><code>auth</code></td><td>The <code>AuthContext</code> from the route&#39;s auth chain</td></tr><tr><td><code>requestIp</code></td><td>The TCP peer address, or <code>null</code></td></tr><tr><td><code>host</code></td><td>Host services such as MCP, storage, telemetry, and reminders</td></tr><tr><td><code>waitUntil(promise)</code></td><td>Keep work running after the handler returns</td></tr><tr><td><code>sessionUrls(request, sessionId)</code></td><td>Playground and trace URLs for a session</td></tr><tr><td><code>artifacts</code></td><td>List or tag <a href="./artifacts.html">artifacts</a></td></tr></tbody></table><h3 id="send-options" tabindex="-1"><code>send</code> options <a class="header-anchor" href="#send-options" aria-label="Permalink to &quot;\`send\` options&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>continuationToken</code></td><td>Channel-local key that resumes its session, or creates one when new</td></tr><tr><td><code>admission</code></td><td><code>&quot;preempt&quot;</code> (the default) interrupts a busy turn. <code>&quot;coalesce&quot;</code> queues behind it</td></tr><tr><td><code>workspaceFiles</code></td><td>Relative files to add before the next turn</td></tr><tr><td><code>workspaceDir</code></td><td>Absolute local working directory</td></tr><tr><td><code>auth</code></td><td>Session principal. Defaults to the request principal</td></tr><tr><td><code>state</code></td><td>Starting channel state for a new session</td></tr><tr><td><code>title</code>, <code>purpose</code>, <code>dryRun</code>, <code>asOf</code></td><td>Set up a new session, as in the <a href="./http-api.html#start-a-session"><code>POST /v1/session</code> body</a></td></tr><tr><td><code>deliveryId</code></td><td>Names this send on the session&#39;s <a href="./sessions.html#track-which-follow-up-reached-the-agent">events</a>, up to 256 characters. Defaults to a fresh <code>dlv_…</code> ID</td></tr></tbody></table><p><code>send</code> returns a <code>ChannelSession</code> with <code>id</code>, the current <code>continuationToken</code>, <code>isNew</code>, and <code>coalesced: true</code> for a coalesced call. On Cursor hosting, it returns the ID before the session exists.</p><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for its sessions. Keys are types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>&quot;*&quot;</code>. Each handler receives <code>(event, channel, ctx)</code> with <code>channel.state</code>, session info, and host services, so it can post progress and replies. <code>state</code> on the channel definition is each new session&#39;s starting JSON, unless a route passes <code>state</code> to <code>send</code>, and handlers update it through <code>channel.state</code>.</p><h2 id="start-and-stop-a-channel" tabindex="-1">Start and stop a channel <a class="header-anchor" href="#start-and-stop-a-channel" aria-label="Permalink to &quot;Start and stop a channel&quot;">​</a></h2><p><code>onStart(args)</code> runs when the channel mounts, and <code>onStop()</code> runs when the host stops. Besides the route helpers, <code>onStart</code> receives <code>emitAssistantMessage(sessionId, text)</code>, which appends assistant text without a model turn, and <code>hasContinuationSession</code>, <code>isContinuationBusy</code>, and <code>interruptContinuation</code>, which check or stop the session behind a token.</p><h2 id="auth-policies" tabindex="-1">Auth policies <a class="header-anchor" href="#auth-policies" aria-label="Permalink to &quot;Auth policies&quot;">​</a></h2><p>Every route runs the channel&#39;s <code>auth</code> array, which defaults to <code>[localDevStrict()]</code>. The first policy to return an <code>AuthContext</code> admits the request, and if every policy returns <code>null</code>, the route answers <code>401</code>.</p><table tabindex="0"><thead><tr><th>Policy</th><th>Admits</th></tr></thead><tbody><tr><td><code>localDevStrict()</code></td><td>Direct loopback requests with a loopback hostname and no forwarding headers</td></tr><tr><td><code>localDev()</code></td><td>The same, with any hostname</td></tr><tr><td><code>loopbackOnly()</code></td><td>Any loopback peer, including relays that add forwarding headers</td></tr><tr><td><code>bearerAuth(tokenOrVerify)</code></td><td>A matching bearer token, or one the verifier accepts</td></tr><tr><td><code>sharedSecretAuth({ header, secret })</code></td><td>A header that matches the named secret</td></tr><tr><td><code>hmacSignatureAuth({ header, secret, prefix?, separator? })</code></td><td>A hex HMAC-SHA256 signature of the raw body under the named secret, or any of several signatures split by <code>separator</code>. The secret can hold up to 32 values, one per line, and any of them verifies</td></tr><tr><td><code>allowAll()</code></td><td>Every caller, as an anonymous principal</td></tr><tr><td><code>publicEndpoint()</code></td><td>Every caller, with no alias token on hosting. The handler must verify the provider&#39;s signature</td></tr></tbody></table><p>Use <code>allowAll()</code> only for a public surface or one protected upstream. <code>publicEndpoint()</code> applies only to custom channel routes and doesn&#39;t open the built-in session or tool API.</p><p>The admitted <code>AuthContext</code> becomes the request principal, which <a href="./sessions.html#session-contents">owns the sessions it creates</a>.</p><p>On a channel without its own <code>auth</code>, <code>--bearer-token</code> swaps the default for <code>bearerAuth(...)</code> and <code>--allow-anonymous</code> swaps it for <code>allowAll()</code>.</p><h2 id="prebuilt-channels" tabindex="-1">Prebuilt channels <a class="header-anchor" href="#prebuilt-channels" aria-label="Permalink to &quot;Prebuilt channels&quot;">​</a></h2><p>Import each one from <code>@grok/agent-sdk/channels/&lt;name&gt;</code>.</p><table tabindex="0"><thead><tr><th>Function</th><th>Details</th></tr></thead><tbody><tr><td><code>slackChannel()</code></td><td><a href="./../guides/slack.html">Slack</a></td></tr><tr><td><code>teamsChannel()</code></td><td><a href="./../guides/teams.html">Microsoft Teams</a></td></tr><tr><td><code>githubChannel()</code></td><td><a href="./../guides/github.html">GitHub</a></td></tr><tr><td><code>gitlabChannel()</code></td><td><a href="./../guides/gitlab.html">GitLab</a></td></tr><tr><td><code>bitbucketChannel()</code></td><td><a href="./../guides/bitbucket.html">Bitbucket</a></td></tr><tr><td><code>pagerdutyChannel()</code></td><td><a href="./../guides/pagerduty.html">PagerDuty</a></td></tr><tr><td><code>deploymentsChannel()</code></td><td>Deployment events filtered by source, environment, or event name</td></tr></tbody></table><p>Use <code>defineChannel</code> for other platforms, such as Discord.</p><h2 id="handler-results" tabindex="-1">Handler results <a class="header-anchor" href="#handler-results" aria-label="Permalink to &quot;Handler results&quot;">​</a></h2><p>Hooks on the GitHub, GitLab, Bitbucket, and PagerDuty channels, such as <code>onPullRequest</code> or <code>onIncident</code>, return one of three results:</p><table tabindex="0"><thead><tr><th>Return value</th><th>What happens</th></tr></thead><tbody><tr><td><code>{ auth }</code></td><td>Runs the model turn with that auth. It can also set the turn&#39;s <code>message</code>, <code>title</code>, or <code>context</code></td></tr><tr><td><code>{ task }</code></td><td>Runs your function on the host. That function can call <code>send</code> to start a model turn</td></tr><tr><td><code>null</code></td><td>Ignores the event</td></tr></tbody></table><h2 id="hosted-session-keys" tabindex="-1">Hosted session keys <a class="header-anchor" href="#hosted-session-keys" aria-label="Permalink to &quot;Hosted session keys&quot;">​</a></h2><p>On Cursor hosting, each request to a <code>defineChannel</code> route starts a new session unless it carries <code>X-BDK-Session-Key</code>. Requests with the same value on one channel share one session, in arrival order. The handler&#39;s <code>continuationToken</code> doesn&#39;t change that choice, and local <code>serve</code> ignores the header.</p><table tabindex="0"><thead><tr><th>Rule</th><th>Contract</th></tr></thead><tbody><tr><td>Auth</td><td>The alias token or <code>sharedSecretAuth()</code>. Routes admitted by <code>hmacSignatureAuth()</code> or <code>publicEndpoint()</code> answer <code>400</code></td></tr><tr><td>Value</td><td>1 to 256 printable ASCII characters with no space or comma, or the request gets <code>400</code>. Hosting stores the value, so keep secrets and personal data out of it</td></tr><tr><td>Scope</td><td>One channel on one deployment. Prebuilt channels ignore the header</td></tr><tr><td>Retries</td><td>Hosting doesn&#39;t deduplicate. A retry runs a second turn</td></tr></tbody></table><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="./../guides/webhooks.html">Webhooks</a></li><li><a href="./sessions.html">Sessions</a></li></ul>`,43)])])}const k=t(i,[["render",o]]);export{u as __pageData,k as default};
@@ -1,4 +1,4 @@
1
- import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"CLI","description":"Look up Agent SDK commands, targets, flags, outputs, and exit status.","frontmatter":{"title":"CLI","description":"Look up Agent SDK commands, targets, flags, outputs, and exit status."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function d(c,e,l,i,r,p){return s(),a("div",null,[...e[0]||(e[0]=[o(`<h1 id="agent-sdk-cli" tabindex="-1">Agent SDK CLI <a class="header-anchor" href="#agent-sdk-cli" aria-label="Permalink to &quot;Agent SDK CLI&quot;">​</a></h1><p>The CLI needs Node 22.13 or newer. Run <code>agent-sdk &lt;command&gt; --help</code> to see every flag for that command.</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 &lt;command&gt;</span></span></code></pre></div><p><code>agent-sdk help --all</code> prints every command, and <code>agent-sdk help &lt;command&gt; --json</code> prints one command&#39;s flags as JSON.</p><p>Commands are named <code>agent-sdk &lt;resource&gt; &lt;verb&gt;</code>, such as <code>agent-sdk deployment list</code>, apart from workflow verbs such as <code>init</code>, <code>dev</code>, and <code>deploy</code>. Older names, such as <code>agent-sdk deployments</code> or <code>agent-sdk secrets set</code>, still run and print the new form on stderr. The <code>bdk</code> command remains available.</p><h2 id="command-catalog" tabindex="-1">Command catalog <a class="header-anchor" href="#command-catalog" aria-label="Permalink to &quot;Command catalog&quot;">​</a></h2><h3 id="development-commands" tabindex="-1">Development commands <a class="header-anchor" href="#development-commands" aria-label="Permalink to &quot;Development commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><code>help</code>, <code>--help</code>, <code>-h</code></td><td>Print the command index, or one command&#39;s help</td></tr><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve one or more agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Serve agents with local-development behavior</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the bundled documentation</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or convert an Automation</td></tr><tr><td><a href="#migrate"><code>migrate</code></a></td><td>Open a pull request that migrates an early-alpha project</td></tr><tr><td><a href="#skills-install"><code>skills list</code>, <code>skills install</code></a></td><td>List or refresh the bundled coding-agent skills</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print a project&#39;s discovered parts or deployment manifest</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check project diagnostics and set the exit status</td></tr><tr><td><a href="#version"><code>version</code></a></td><td>Print the installed package version</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code>, <code>logout</code>, <code>whoami</code></a></td><td>Store, remove, or show the Cursor credential</td></tr></tbody></table><h3 id="session-and-eval-commands" tabindex="-1">Session and eval commands <a class="header-anchor" href="#session-and-eval-commands" aria-label="Permalink to &quot;Session and eval commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent, or reattach a session</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run turns on a local or running agent</td></tr><tr><td><a href="#tool-call"><code>tool call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow or dump agent logs</td></tr><tr><td><a href="#session-list"><code>session list</code></a></td><td>List sessions, or their costs</td></tr><tr><td><a href="#session-get"><code>session get</code></a></td><td>Inspect a session or a saved trace</td></tr><tr><td><a href="#session-create"><code>session create</code></a></td><td>Start or continue a hosted session</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run evals, or list, get, and cancel remote eval batches</td></tr></tbody></table><h3 id="managed-hosting-commands" tabindex="-1">Managed hosting commands <a class="header-anchor" href="#managed-hosting-commands" aria-label="Permalink to &quot;Managed hosting commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy an agent</td></tr><tr><td><a href="#deployment-list"><code>deployment list</code>, <code>deployment get</code></a></td><td>List deployments, or inspect one</td></tr><tr><td><a href="#deployment-lifecycle"><code>deployment stop</code>, <code>start</code>, <code>kill</code>, <code>unlock</code>, <code>cancel-runs</code>, <code>upgrade</code>, <code>rollback</code>, <code>delete</code>, <code>rotate-token</code></a></td><td>Change a deployment&#39;s state, release, or alias token</td></tr><tr><td><a href="#deployment-update"><code>deployment update</code></a></td><td>Replace a deployment&#39;s event repositories</td></tr><tr><td><a href="#secret"><code>secret</code></a></td><td>Set, list, or delete deployment secrets</td></tr></tbody></table><h3 id="connection-and-channel-commands" tabindex="-1">Connection and channel commands <a class="header-anchor" href="#connection-and-channel-commands" aria-label="Permalink to &quot;Connection and channel commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#mcp"><code>mcp serve</code>, <code>mcp install</code></a></td><td>Connect an MCP client to an agent</td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize an MCP connection</td></tr><tr><td><a href="#slack"><code>slack</code></a></td><td>Provision and check Slack channel apps</td></tr><tr><td><a href="#github"><code>github</code></a></td><td>Forward, replay, and inspect GitHub webhooks</td></tr><tr><td><a href="#replay-other-webhooks"><code>gitlab</code>, <code>bitbucket</code>, <code>pagerduty</code></a></td><td>Replay and inspect GitLab, Bitbucket, or PagerDuty webhooks</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Targets <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Targets {#choose-a-target}&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Target</th><th>Selection</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>tool call</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code></td><td><code>chat</code>, <code>run</code>, <code>tool call</code>, <code>eval</code>, <code>logs</code>, <code>session list</code>, <code>session get</code>, <code>mcp serve</code></td></tr><tr><td>Default local server</td><td>Omit <code>--url</code> and <code>--prod</code> to use <code>http://127.0.0.1:3000</code></td><td><code>chat</code>, <code>logs</code>, <code>session list</code>, <code>session get</code></td></tr><tr><td>Hosted deployment</td><td>Pass <code>--prod</code></td><td><code>session list</code>, <code>session get</code>, <code>logs</code>. <code>session create</code> is always hosted.</td></tr></tbody></table><p>A hosted deployment supports only the commands in its row. <code>chat</code>, <code>run</code>, <code>tool call</code>, <code>eval</code>, <code>mcp serve</code>, and <code>mcp install</code> exit with a usage error when you pass <code>--prod</code>. To test a hosted agent, start a turn with <a href="#session-create"><code>session create</code></a> and inspect it with <a href="#session-get"><code>session get</code></a>.</p><p><code>--url</code> and <code>--prod</code> are mutually exclusive. An explicit <code>--url</code> must include the slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. Otherwise <code>--slug</code> picks the agent, and under <code>--prod</code> it defaults to the <code>--dir</code> basename. <code>--json</code> prints one JSON document on stdout, including errors. Without it, output is text, even when piped.</p><h2 id="local-servers" tabindex="-1">Local servers <a class="header-anchor" href="#local-servers" aria-label="Permalink to &quot;Local servers&quot;">​</a></h2><h3 id="serve" tabindex="-1">Serve agents <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;Serve agents {#serve}&quot;">​</a></h3><p><code>serve</code> mounts every project discovered under <code>--dir</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 serve [--dir &lt;path&gt;] [--port &lt;n&gt;] [--host &lt;host&gt;]</span></span>
1
+ import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"CLI","description":"Look up Agent SDK commands, targets, flags, outputs, and exit status.","frontmatter":{"title":"CLI","description":"Look up Agent SDK commands, targets, flags, outputs, and exit status."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function d(c,e,i,l,r,p){return s(),a("div",null,[...e[0]||(e[0]=[o(`<h1 id="agent-sdk-cli" tabindex="-1">Agent SDK CLI <a class="header-anchor" href="#agent-sdk-cli" aria-label="Permalink to &quot;Agent SDK CLI&quot;">​</a></h1><p>The CLI needs Node 22.13 or newer. Run <code>agent-sdk &lt;command&gt; --help</code> to see every flag for that command.</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 &lt;command&gt;</span></span></code></pre></div><p><code>agent-sdk help --all</code> prints every command, and <code>agent-sdk help &lt;command&gt; --json</code> prints one command&#39;s flags as JSON.</p><p>Commands are named <code>agent-sdk &lt;resource&gt; &lt;verb&gt;</code>, such as <code>agent-sdk deployment list</code>, apart from workflow verbs such as <code>init</code>, <code>dev</code>, and <code>deploy</code>. Older names, such as <code>agent-sdk deployments</code> or <code>agent-sdk secrets set</code>, still run and print the new form on stderr. The <code>bdk</code> command remains available.</p><h2 id="command-catalog" tabindex="-1">Command catalog <a class="header-anchor" href="#command-catalog" aria-label="Permalink to &quot;Command catalog&quot;">​</a></h2><h3 id="development-commands" tabindex="-1">Development commands <a class="header-anchor" href="#development-commands" aria-label="Permalink to &quot;Development commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><code>help</code>, <code>--help</code>, <code>-h</code></td><td>Print the command index, or one command&#39;s help</td></tr><tr><td><a href="#serve"><code>serve</code></a></td><td>Serve one or more agents over HTTP</td></tr><tr><td><a href="#dev"><code>dev</code></a></td><td>Serve agents with local-development behavior</td></tr><tr><td><a href="#docs"><code>docs</code></a></td><td>Serve the bundled documentation</td></tr><tr><td><a href="#init"><code>init</code></a></td><td>Scaffold a project, or convert an Automation</td></tr><tr><td><a href="#migrate"><code>migrate</code></a></td><td>Open a pull request that migrates an early-alpha project</td></tr><tr><td><a href="#skills-install"><code>skills list</code>, <code>skills install</code></a></td><td>List or refresh the bundled coding-agent skills</td></tr><tr><td><a href="#info"><code>info</code></a></td><td>Print a project&#39;s discovered parts or deployment manifest</td></tr><tr><td><a href="#validate"><code>validate</code></a></td><td>Check project diagnostics and set the exit status</td></tr><tr><td><a href="#version"><code>version</code></a></td><td>Print the installed package version</td></tr><tr><td><a href="#update"><code>update</code></a></td><td>Upgrade the installed CLI</td></tr><tr><td><a href="#login-logout-whoami"><code>login</code>, <code>logout</code>, <code>whoami</code></a></td><td>Store, remove, or show the Cursor credential</td></tr></tbody></table><h3 id="session-and-eval-commands" tabindex="-1">Session and eval commands <a class="header-anchor" href="#session-and-eval-commands" aria-label="Permalink to &quot;Session and eval commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#chat"><code>chat</code></a></td><td>Talk to a running agent, or reattach a session</td></tr><tr><td><a href="#run"><code>run</code></a></td><td>Run turns on a local or running agent</td></tr><tr><td><a href="#tool-call"><code>tool call</code></a></td><td>Call a server tool without a model turn</td></tr><tr><td><a href="#logs"><code>logs</code></a></td><td>Follow or dump agent logs</td></tr><tr><td><a href="#session-list"><code>session list</code></a></td><td>List sessions, or their costs</td></tr><tr><td><a href="#session-get"><code>session get</code></a></td><td>Inspect a session or a saved trace</td></tr><tr><td><a href="#session-create"><code>session create</code></a></td><td>Start or continue a hosted session</td></tr><tr><td><a href="#eval"><code>eval</code></a></td><td>Run evals, or list, get, and cancel remote eval batches</td></tr></tbody></table><h3 id="managed-hosting-commands" tabindex="-1">Managed hosting commands <a class="header-anchor" href="#managed-hosting-commands" aria-label="Permalink to &quot;Managed hosting commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#deploy"><code>deploy</code></a></td><td>Deploy an agent</td></tr><tr><td><a href="#deployment-list"><code>deployment list</code>, <code>deployment get</code></a></td><td>List deployments, or inspect one</td></tr><tr><td><a href="#deployment-lifecycle"><code>deployment stop</code>, <code>start</code>, <code>kill</code>, <code>unlock</code>, <code>cancel-runs</code>, <code>upgrade</code>, <code>rollback</code>, <code>delete</code>, <code>rotate-token</code></a></td><td>Change a deployment&#39;s state, release, or alias token</td></tr><tr><td><a href="#deployment-update"><code>deployment update</code></a></td><td>Replace a deployment&#39;s event repositories</td></tr><tr><td><a href="#secret"><code>secret</code></a></td><td>Set, list, or delete deployment secrets</td></tr></tbody></table><h3 id="connection-and-channel-commands" tabindex="-1">Connection and channel commands <a class="header-anchor" href="#connection-and-channel-commands" aria-label="Permalink to &quot;Connection and channel commands&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Command</th><th>Contract</th></tr></thead><tbody><tr><td><a href="#mcp"><code>mcp serve</code>, <code>mcp install</code></a></td><td>Connect an MCP client to an agent</td></tr><tr><td><a href="#mcp-oauth"><code>mcp oauth</code></a></td><td>Authorize an MCP connection</td></tr><tr><td><a href="#slack"><code>slack</code></a></td><td>Provision and check Slack channel apps</td></tr><tr><td><a href="#teams"><code>teams</code></a></td><td>Connect, check, and package a Microsoft Teams bot</td></tr><tr><td><a href="#github"><code>github</code></a></td><td>Forward, replay, and inspect GitHub webhooks</td></tr><tr><td><a href="#replay-other-webhooks"><code>gitlab</code>, <code>bitbucket</code>, <code>pagerduty</code></a></td><td>Replay and inspect GitLab, Bitbucket, or PagerDuty webhooks</td></tr></tbody></table><h2 id="choose-a-target" tabindex="-1">Targets <a class="header-anchor" href="#choose-a-target" aria-label="Permalink to &quot;Targets {#choose-a-target}&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Target</th><th>Selection</th><th>Commands</th></tr></thead><tbody><tr><td>Ephemeral local server</td><td>Omit <code>--url</code> and <code>--prod</code></td><td><code>run</code>, <code>tool call</code>, <code>eval</code></td></tr><tr><td>Running server</td><td>Pass <code>--url &lt;baseUrl&gt;</code></td><td><code>chat</code>, <code>run</code>, <code>tool call</code>, <code>eval</code>, <code>logs</code>, <code>session list</code>, <code>session get</code>, <code>mcp serve</code></td></tr><tr><td>Default local server</td><td>Omit <code>--url</code> and <code>--prod</code> to use <code>http://127.0.0.1:3000</code></td><td><code>chat</code>, <code>logs</code>, <code>session list</code>, <code>session get</code></td></tr><tr><td>Hosted deployment</td><td>Pass <code>--prod</code></td><td><code>session list</code>, <code>session get</code>, <code>logs</code>. <code>session create</code> is always hosted.</td></tr></tbody></table><p>A hosted deployment supports only the commands in its row. <code>chat</code>, <code>run</code>, <code>tool call</code>, <code>eval</code>, <code>mcp serve</code>, and <code>mcp install</code> exit with a usage error when you pass <code>--prod</code>. To test a hosted agent, start a turn with <a href="#session-create"><code>session create</code></a> and inspect it with <a href="#session-get"><code>session get</code></a>.</p><p><code>--url</code> and <code>--prod</code> are mutually exclusive. An explicit <code>--url</code> must include the slug for a multi-agent server, such as <code>http://127.0.0.1:3000/pr-approver</code>. Otherwise <code>--slug</code> picks the agent, and under <code>--prod</code> it defaults to the <code>--dir</code> basename. <code>--json</code> prints one JSON document on stdout, including errors. Without it, output is text, even when piped.</p><h2 id="local-servers" tabindex="-1">Local servers <a class="header-anchor" href="#local-servers" aria-label="Permalink to &quot;Local servers&quot;">​</a></h2><h3 id="serve" tabindex="-1">Serve agents <a class="header-anchor" href="#serve" aria-label="Permalink to &quot;Serve agents {#serve}&quot;">​</a></h3><p><code>serve</code> mounts every project discovered under <code>--dir</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 serve [--dir &lt;path&gt;] [--port &lt;n&gt;] [--host &lt;host&gt;]</span></span>
2
2
  <span class="line"><span> [--mode multi|single] [--dev] [--api-key &lt;key&gt;]</span></span>
3
3
  <span class="line"><span> [--state-root &lt;path&gt;]</span></span>
4
4
  <span class="line"><span> [--bearer-token &lt;secret&gt; | --allow-anonymous]</span></span>
@@ -8,7 +8,7 @@ import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const g
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><p><code>serve</code> listens on <code>127.0.0.1:3000</code>, or the next free port when that one is taken. <code>--mode multi</code>, the default, mounts each project at <code>/&lt;slug&gt;/v1/*</code>, and <code>--mode single</code> mounts one project at <code>/v1/*</code>. <code>--dev</code> turns off schedule and reminder firing and admits unsigned loopback GitHub deliveries.</p><p><code>--bearer-token</code> requires a token on routes that don&#39;t declare their own authentication. <code>--allow-anonymous</code> admits every caller as one principal, so use it only behind a trusted network boundary. The slugs <code>v1</code>, <code>playground</code>, and <code>docs</code> are reserved.</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 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 ./agent-sdk-pr-reviewer --port 3000</span></span></code></pre></div><p>It accepts every <code>serve</code> option. Don&#39;t combine the path 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 on a loopback port until you press 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><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. Don&#39;t combine the path with a different <code>--dir</code>.</p><p>When an agent has a Microsoft Teams channel, <code>dev</code> also opens a cloudflared quick tunnel and prints that channel&#39;s messaging endpoint. Pass <code>--tunnel devtunnel</code> for an endpoint that stays the same across restarts, and <code>--tunnel-id &lt;id&gt;</code> to pick the dev tunnel. See <a href="#teams">Configure Microsoft Teams</a>.</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 on a loopback port until you press 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><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><p>On a TTY, <code>chat</code> opens a REPL and sends any <code>--message</code> first. Without a TTY, it sends <code>--message</code> as one turn, or reads newline-delimited messages until EOF. <code>--session &lt;id&gt;</code> reattaches a stored session, and <code>--resume</code> picks the most recent one.</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><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>
@@ -66,7 +66,17 @@ import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const g
66
66
  <span class="line"><span>agent-sdk slack manifest [--dir &lt;path&gt;] [--name &lt;name&gt;]</span></span>
67
67
  <span class="line"><span> [--env dev|prod|both] [--channel-posts] [--dry-run]</span></span>
68
68
  <span class="line"><span>agent-sdk slack doctor [--dir &lt;path&gt;]</span></span>
69
- <span class="line"><span> [--prefix &lt;prefix&gt; | --no-prefix] [--channel &lt;id&gt;]... [--json]</span></span></code></pre></div><p><code>slack create</code> opens the <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> wizard, writes the token pair to <code>.env.local</code>, and runs <code>doctor</code>, which checks both tokens and Socket Mode. It makes the development app unless you pass <code>--env prod</code>. The token prefix defaults to the project directory name in upper snake case. <code>--channel-posts</code> adds the message events that <code>engagement.channelPosts</code> needs. See <a href="./../guides/slack.html">Slack</a> for 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>
69
+ <span class="line"><span> [--prefix &lt;prefix&gt; | --no-prefix] [--channel &lt;id&gt;]... [--json]</span></span></code></pre></div><p><code>slack create</code> opens the <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> wizard, writes the token pair to <code>.env.local</code>, and runs <code>doctor</code>, which checks both tokens and Socket Mode. It makes the development app unless you pass <code>--env prod</code>. The token prefix defaults to the project directory name in upper snake case. <code>--channel-posts</code> adds the message events that <code>engagement.channelPosts</code> needs. See <a href="./../guides/slack.html">Slack</a> for manual setup.</p><h3 id="teams" tabindex="-1">Configure Microsoft Teams <a class="header-anchor" href="#teams" aria-label="Permalink to &quot;Configure Microsoft Teams {#teams}&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 channels teams setup</span></span>
70
+ <span class="line"><span>agent-sdk channels teams init --app-id &lt;guid&gt; --tenant-id &lt;guid&gt; [--dir &lt;path&gt;]</span></span>
71
+ <span class="line"><span> [--prefix &lt;prefix&gt;] [--dry-run] [--json]</span></span>
72
+ <span class="line"><span>agent-sdk channels teams doctor [--dir &lt;path&gt;] [--slug &lt;slug&gt;] [--channel &lt;id&gt;]</span></span>
73
+ <span class="line"><span> [--endpoint &lt;url&gt;] [--json]</span></span>
74
+ <span class="line"><span>agent-sdk channels teams package [--dir &lt;path&gt;] [--slug &lt;slug&gt;] [--channel &lt;id&gt;]</span></span>
75
+ <span class="line"><span> [--name &lt;name&gt;] [--icon &lt;png&gt;] [--app-version &lt;x.y.z&gt;] [--endpoint &lt;url&gt;]</span></span>
76
+ <span class="line"><span> [--out &lt;file&gt;] [--dry-run] [--json]</span></span>
77
+ <span class="line"><span>agent-sdk channels teams forward [--dir &lt;path&gt;] [--slug &lt;slug&gt;] [--channel &lt;id&gt;]</span></span>
78
+ <span class="line"><span> [--host &lt;host&gt;] [--port &lt;n&gt;] [--tunnel cloudflared|devtunnel]</span></span>
79
+ <span class="line"><span> [--tunnel-id &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 Azure Bot setup steps without changing files.</td></tr><tr><td><code>init</code></td><td>Read the bot&#39;s client secret from a hidden prompt or stdin, never from an argument. Write <code>bot/channels/teams.ts</code> when it&#39;s missing, and write the app id, secret, and tenant id to <code>.env.local</code>. A second <code>init</code> keeps the channel file and replaces the secret.</td></tr><tr><td><code>doctor</code></td><td>Run the checks below and exit <code>1</code> when one fails. A check it can&#39;t run is skipped and says why.</td></tr><tr><td><code>package</code></td><td>Write the Teams app package: <code>manifest.json</code>, a 192 by 192 color icon, and a 32 by 32 outline icon. By default it writes <code>&lt;slug&gt;-teams-app.zip</code> in the agent folder and adds <code>*-teams-app.zip</code> to <code>.gitignore</code>. <code>--out &lt;file&gt;</code> writes it to that path instead. Upload it in Teams under <strong>Apps</strong> &gt; <strong>Manage your apps</strong> &gt; <strong>Upload an app</strong>.</td></tr><tr><td><code>forward</code></td><td>Open a tunnel to a running <code>agent-sdk serve</code> and print the messaging endpoint of each Teams channel. It runs until you stop it.</td></tr></tbody></table><p><code>agent-sdk dev</code> opens the same tunnel by itself. The endpoint is the tunnel origin plus <code>/&lt;slug&gt;/v1/channels/&lt;channel&gt;</code>, such as <code>https://&lt;random&gt;.trycloudflare.com/helm/v1/channels/teams</code>. Set it as the Azure Bot&#39;s messaging endpoint. The tunnel forwards only <code>POST</code> requests to the Teams messaging paths, so the rest of the agent&#39;s API stays local. Every other request on the tunnel host gets a <code>404</code>.</p><p><code>--tunnel</code> picks the tunnel for <code>dev</code> and <code>channels teams forward</code>:</p><table tabindex="0"><thead><tr><th><code>--tunnel</code></th><th>Needs</th><th>Endpoint</th></tr></thead><tbody><tr><td><code>cloudflared</code> (default)</td><td><code>cloudflared</code> on <code>PATH</code>. No account.</td><td>A new <code>trycloudflare.com</code> URL on every start. Set it on the bot again after each restart.</td></tr><tr><td><code>devtunnel</code></td><td>The <code>devtunnel</code> CLI on <code>PATH</code>, logged in with <code>devtunnel user login</code>.</td><td>The same <code>devtunnels.ms</code> URL on every start. Set it on the bot once.</td></tr></tbody></table><p>With <code>devtunnel</code>, the first start creates a dev tunnel that allows anonymous access, adds port <code>3978</code>, and saves the tunnel id as <code>TEAMS_DEVTUNNEL_ID</code> in <code>.env.local</code>. Later starts reuse that tunnel. <code>--tunnel-id &lt;id&gt;</code> picks the id. Microsoft deletes a dev tunnel after 30 days without use, and the next start creates it again under the same id. Port <code>3978</code> belongs to the tunnel, so <code>--port 3978</code> with <code>--tunnel devtunnel</code> stops with a usage error. Run the agent on another port. <code>devtunnel host</code> publishes every port on the tunnel, so the tunnel stops when it reports a port other than <code>3978</code>. Remove that port with <code>devtunnel port delete &lt;id&gt; -p &lt;port&gt;</code>, or pass another <code>--tunnel-id</code>.</p><p>The package manifest uses Teams manifest version 1.25. It names the bot by its app id and lists the scopes the channel answers in: mentions add <code>team</code> and <code>groupChat</code>, and personal chats add <code>personal</code>. With <code>engagement.channelPosts</code>, it also asks for <code>ChannelMessage.Read.Group</code> consent. <code>--endpoint</code> adds the messaging endpoint&#39;s host to <code>validDomains</code>. <code>--app-version</code> sets the app version. It defaults to <code>1.&lt;YYYYMMDD&gt;.&lt;second of the day&gt;</code> in UTC, so each new zip is higher than the last, and Teams and the Teams admin center accept it as an update. Teams refuses an update whose version is not higher than the installed one. After you set <code>--app-version 2.0.0</code>, a later default <code>1.x</code> version is lower, so keep passing a higher <code>--app-version</code>. The default&#39;s middle part has 8 digits, which is fine for a bot-only app. An app that adds an Office Add-in limits each part to 5 digits.</p><p><code>doctor</code> runs these checks in order:</p><table tabindex="0"><thead><tr><th>Check</th><th>Passes when</th></tr></thead><tbody><tr><td><code>env</code></td><td>The app id, password, and tenant id variables are set.</td></tr><tr><td><code>token</code></td><td>Microsoft Entra issues a Bot Framework token for the app within 10 seconds.</td></tr><tr><td><code>bot-tenant</code></td><td>The Azure Bot is <strong>Single Tenant</strong> and its tenant is the one in the channel&#39;s tenant id variable.</td></tr><tr><td><code>bot-endpoint</code></td><td>The Azure Bot&#39;s messaging endpoint is <code>--endpoint</code>. Without <code>--endpoint</code>, it reports the bot&#39;s endpoint.</td></tr><tr><td><code>teams-channel</code></td><td>The Azure Bot&#39;s Microsoft Teams channel is added and on.</td></tr><tr><td><code>endpoint</code></td><td>The endpoint&#39;s path names this channel, and an unsigned <code>POST</code> to it gets <code>401</code>.</td></tr></tbody></table><p>The three Azure checks need the Azure CLI, logged in with <code>az login</code>, on any operating system. Without it they are skipped. When no Azure Bot in the current subscription has the app id, they fail. Each <code>az</code> call has a time limit. The endpoint&#39;s path must end in <code>/v1/channels/&lt;channel&gt;</code> plus the channel&#39;s <code>path</code>, after nothing, the agent&#39;s slug, or <code>/engine</code> on Cursor-managed hosting. A URL for another channel or agent fails without a probe. The <code>endpoint</code> answers mean:</p><table tabindex="0"><thead><tr><th>Answer</th><th>Meaning</th></tr></thead><tbody><tr><td><code>401</code> with <code>invalid_token</code></td><td>The Teams channel serves this URL and its credentials resolve. Teams signs its requests, so the channel refuses the unsigned probe.</td></tr><tr><td><code>401</code> with <code>Unauthorized</code></td><td>Cursor-managed hosting serves this URL and refuses the unsigned probe before the agent.</td></tr><tr><td><code>503</code> with <code>teams_not_configured</code></td><td>The server has no app id or password for this channel. Check <code>envPrefix</code> and the secrets.</td></tr><tr><td><code>404</code></td><td>No Teams channel at this path. Check the slug, the channel name, and the route path.</td></tr><tr><td>A redirect</td><td>A dev tunnel that needs sign-in. Run <code>devtunnel access create &lt;id&gt; --anonymous</code>.</td></tr></tbody></table><p><code>--endpoint</code> must be the public <code>https</code> URL that <code>dev</code> or <code>channels teams forward</code> prints. <code>agent-sdk dev</code> admits unsigned requests from loopback, so a loopback probe proves nothing. Without <code>--endpoint</code>, <code>doctor</code> probes the Azure Bot&#39;s messaging endpoint.</p><p>The channel&#39;s <code>envPrefix</code> owns the variable names. A new channel file reads <code>TEAMS_APP_ID</code>, <code>TEAMS_APP_PASSWORD</code>, and <code>TEAMS_TENANT_ID</code>. <code>init --prefix HELM</code> writes <code>envPrefix: &quot;HELM&quot;</code> into the new file and the names <code>HELM_TEAMS_APP_ID</code>, <code>HELM_TEAMS_APP_PASSWORD</code>, and <code>HELM_TEAMS_TENANT_ID</code>. The prefix must start with a letter, and each name must be a valid deployment secret name. When the agent already has a Teams channel, under any file name, <code>init</code> keeps it and writes the names it reads; a <code>--prefix</code> that disagrees with it stops with an error. <code>doctor</code> and <code>package</code> read the names from the loaded channel. Multi-agent servers need one Azure Bot per agent.</p><p>A channel that sets <code>credentials</code> in code has no env names for the CLI to read. <code>doctor</code> then skips the <code>env</code>, <code>token</code>, and Azure checks and says why, <code>package</code> and <code>init</code> stop with an error, and <code>doctor</code> still probes <code>--endpoint</code>.</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>
70
80
  <span class="line"><span> [--repo owner/repo | --org &lt;org&gt;] [--events a,b,c]</span></span>
71
81
  <span class="line"><span> [--url &lt;url&gt;] [--host &lt;host&gt;] [--port &lt;n&gt;]</span></span>
72
82
  <span class="line"><span> [--secret &lt;secret&gt;] [--install]</span></span>
@@ -80,4 +90,4 @@ import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const g
80
90
  <span class="line"><span>agent-sdk bitbucket replay &lt;pr-url-or-workspace/repo#N&gt; [replay flags]</span></span>
81
91
  <span class="line"><span>agent-sdk pagerduty replay [incident-id] [replay flags]</span></span>
82
92
  <span class="line"><span>agent-sdk &lt;gitlab|bitbucket|pagerduty&gt; events [--dir &lt;path&gt;] [--json]</span></span>
83
- <span class="line"><span>agent-sdk &lt;gitlab|bitbucket&gt; forward [--dir &lt;path&gt;]</span></span></code></pre></div><p>Replay takes the same flags as <code>github replay</code>, including <code>--fixtures-dir</code>. <code>events</code> lists the discovered channels, and <code>forward</code> prints the webhook and tunnel recipe for live deliveries.</p><table tabindex="0"><thead><tr><th>Command</th><th>Replay events</th><th>Default event</th><th>Read credential</th><th><code>--secret</code> default</th></tr></thead><tbody><tr><td><code>gitlab replay</code></td><td><code>merge_request</code>, <code>note</code>, <code>pipeline</code>, <code>push</code></td><td><code>merge_request</code></td><td><code>GITLAB_TOKEN</code></td><td><code>GITLAB_WEBHOOK_SECRET</code></td></tr><tr><td><code>bitbucket replay</code></td><td><code>pullrequest:created</code>, <code>pullrequest:updated</code>, <code>pullrequest:comment_created</code>, <code>repo:push</code>, in Cloud or Data Center format</td><td><code>pullrequest:created</code></td><td><code>BITBUCKET_TOKEN</code></td><td><code>BITBUCKET_WEBHOOK_SECRET</code></td></tr><tr><td><code>pagerduty replay</code></td><td><code>incident.triggered</code>, <code>.acknowledged</code>, <code>.annotated</code>, <code>.escalated</code>, <code>.resolved</code>, <code>.reopened</code></td><td><code>incident.triggered</code></td><td>None</td><td><code>PAGERDUTY_WEBHOOK_SECRET</code></td></tr></tbody></table><p>PagerDuty replay&#39;s incident ID defaults to <code>PREPLAY1</code>, and <code>--comment</code> is the note body for <code>annotated</code>. Without a secret, its deliveries are unsigned, and <code>agent-sdk dev</code> admits them from loopback. See <a href="./../guides/gitlab.html">GitLab</a>, <a href="./../guides/bitbucket.html">Bitbucket</a>, and <a href="./../guides/pagerduty.html">PagerDuty</a> for channel setup.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables {#environment-variables}&quot;">​</a></h2><p>The CLI tries <code>--api-key</code>, <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then the stored <code>agent-sdk login</code> credential, in that order.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Contract</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential.</td></tr><tr><td><code>CURSOR_API_KEY_FILE</code></td><td>Path to a Cursor credential file.</td></tr><tr><td><code>CURSOR_SERVICE_ACCOUNT_KEY</code></td><td>Team service-account credential.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend for login, account, deployment, and event commands.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend for agent turns. Set it with <code>CURSOR_API_BASE_URL</code> for a non-default backend.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>CLI config directory for stored credentials and update state.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code>, <code>NO_UPDATE_NOTIFIER</code>, <code>CI</code></td><td>Turn off update checks when set to a value other than <code>0</code>.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code>, <code>GITHUB_APP_PRIVATE_KEY</code>, <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App credentials for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code>, <code>GH_TOKEN</code></td><td>Tokens for outbound GitHub calls.</td></tr><tr><td><code>GITLAB_TOKEN</code>, <code>GITLAB_WEBHOOK_SECRET</code></td><td>GitLab API token and default webhook token.</td></tr><tr><td><code>GITLAB_API_BASE_URL</code></td><td>GitLab REST base URL for self-managed hosts.</td></tr><tr><td><code>BITBUCKET_TOKEN</code>, <code>BITBUCKET_WEBHOOK_SECRET</code></td><td>Bitbucket API token and default signing secret.</td></tr><tr><td><code>BITBUCKET_API_BASE_URL</code></td><td>Bitbucket Data Center REST base URL.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code>, <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Multi-agent servers use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code>.</td></tr></tbody></table><h2 id="exit-status" tabindex="-1">Exit status <a class="header-anchor" href="#exit-status" aria-label="Permalink to &quot;Exit status&quot;">​</a></h2><p>Every command uses these exit codes, and <code>agent-sdk help --json</code> lists them as <code>exitCodes</code>.</p><table tabindex="0"><thead><tr><th>Code</th><th>Meaning</th></tr></thead><tbody><tr><td><code>0</code></td><td><code>ok</code></td></tr><tr><td><code>1</code></td><td><code>failed</code>, <code>aborted</code>, <code>invalid_argument</code>, <code>rate_limited</code>, or <code>unavailable</code></td></tr><tr><td><code>2</code></td><td><code>usage</code>, for a bad command, flag, or argument</td></tr><tr><td><code>3</code></td><td><code>pending</code>, while the work still runs</td></tr><tr><td><code>4</code></td><td><code>not_found</code></td></tr><tr><td><code>5</code></td><td><code>unauthenticated</code> or <code>permission_denied</code></td></tr><tr><td><code>6</code></td><td><code>conflict</code> or <code>failed_precondition</code></td></tr></tbody></table><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="./project-layout.html">Project layout</a></li><li><a href="./sessions.html">Sessions, events, and streaming</a></li><li><a href="./../deployment.html">Deployment</a></li><li><a href="./../guides/migrate.html">Early-alpha migration</a></li></ul>`,143)])])}const u=t(n,[["render",d]]);export{g as __pageData,u as default};
93
+ <span class="line"><span>agent-sdk &lt;gitlab|bitbucket&gt; forward [--dir &lt;path&gt;]</span></span></code></pre></div><p>Replay takes the same flags as <code>github replay</code>, including <code>--fixtures-dir</code>. <code>events</code> lists the discovered channels, and <code>forward</code> prints the webhook and tunnel recipe for live deliveries.</p><table tabindex="0"><thead><tr><th>Command</th><th>Replay events</th><th>Default event</th><th>Read credential</th><th><code>--secret</code> default</th></tr></thead><tbody><tr><td><code>gitlab replay</code></td><td><code>merge_request</code>, <code>note</code>, <code>pipeline</code>, <code>push</code></td><td><code>merge_request</code></td><td><code>GITLAB_TOKEN</code></td><td><code>GITLAB_WEBHOOK_SECRET</code></td></tr><tr><td><code>bitbucket replay</code></td><td><code>pullrequest:created</code>, <code>pullrequest:updated</code>, <code>pullrequest:comment_created</code>, <code>repo:push</code>, in Cloud or Data Center format</td><td><code>pullrequest:created</code></td><td><code>BITBUCKET_TOKEN</code></td><td><code>BITBUCKET_WEBHOOK_SECRET</code></td></tr><tr><td><code>pagerduty replay</code></td><td><code>incident.triggered</code>, <code>.acknowledged</code>, <code>.annotated</code>, <code>.escalated</code>, <code>.resolved</code>, <code>.reopened</code></td><td><code>incident.triggered</code></td><td>None</td><td><code>PAGERDUTY_WEBHOOK_SECRET</code></td></tr></tbody></table><p>PagerDuty replay&#39;s incident ID defaults to <code>PREPLAY1</code>, and <code>--comment</code> is the note body for <code>annotated</code>. Without a secret, its deliveries are unsigned, and <code>agent-sdk dev</code> admits them from loopback. See <a href="./../guides/gitlab.html">GitLab</a>, <a href="./../guides/bitbucket.html">Bitbucket</a>, and <a href="./../guides/pagerduty.html">PagerDuty</a> for channel setup.</p><h2 id="environment-variables" tabindex="-1">Environment variables <a class="header-anchor" href="#environment-variables" aria-label="Permalink to &quot;Environment variables {#environment-variables}&quot;">​</a></h2><p>The CLI tries <code>--api-key</code>, <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then the stored <code>agent-sdk login</code> credential, in that order.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Contract</th></tr></thead><tbody><tr><td><code>CURSOR_API_KEY</code></td><td>Cursor credential.</td></tr><tr><td><code>CURSOR_API_KEY_FILE</code></td><td>Path to a Cursor credential file.</td></tr><tr><td><code>CURSOR_SERVICE_ACCOUNT_KEY</code></td><td>Team service-account credential.</td></tr><tr><td><code>CURSOR_API_BASE_URL</code></td><td>Backend for login, account, deployment, and event commands.</td></tr><tr><td><code>CURSOR_BACKEND_URL</code></td><td>Backend for agent turns. Set it with <code>CURSOR_API_BASE_URL</code> for a non-default backend.</td></tr><tr><td><code>AGENT_SERVE_CONFIG_DIR</code></td><td>CLI config directory for stored credentials and update state.</td></tr><tr><td><code>AGENT_SERVE_NO_UPDATE_CHECK</code>, <code>NO_UPDATE_NOTIFIER</code>, <code>CI</code></td><td>Turn off update checks when set to a value other than <code>0</code>.</td></tr><tr><td><code>GITHUB_WEBHOOK_SECRET</code></td><td>Default secret for GitHub forwarding and replay.</td></tr><tr><td><code>GITHUB_APP_ID</code>, <code>GITHUB_APP_PRIVATE_KEY</code>, <code>GITHUB_APP_INSTALLATION_ID</code></td><td>GitHub App credentials for outbound API calls.</td></tr><tr><td><code>GITHUB_TOKEN</code>, <code>GH_TOKEN</code></td><td>Tokens for outbound GitHub calls.</td></tr><tr><td><code>GITLAB_TOKEN</code>, <code>GITLAB_WEBHOOK_SECRET</code></td><td>GitLab API token and default webhook token.</td></tr><tr><td><code>GITLAB_API_BASE_URL</code></td><td>GitLab REST base URL for self-managed hosts.</td></tr><tr><td><code>BITBUCKET_TOKEN</code>, <code>BITBUCKET_WEBHOOK_SECRET</code></td><td>Bitbucket API token and default signing secret.</td></tr><tr><td><code>BITBUCKET_API_BASE_URL</code></td><td>Bitbucket Data Center REST base URL.</td></tr><tr><td><code>SLACK_BOT_TOKEN</code>, <code>SLACK_APP_TOKEN</code></td><td>Slack tokens for one agent. Multi-agent servers use <code>&lt;PREFIX&gt;_SLACK_BOT_TOKEN</code> and <code>&lt;PREFIX&gt;_SLACK_APP_TOKEN</code>.</td></tr></tbody></table><h2 id="exit-status" tabindex="-1">Exit status <a class="header-anchor" href="#exit-status" aria-label="Permalink to &quot;Exit status&quot;">​</a></h2><p>Every command uses these exit codes, and <code>agent-sdk help --json</code> lists them as <code>exitCodes</code>.</p><table tabindex="0"><thead><tr><th>Code</th><th>Meaning</th></tr></thead><tbody><tr><td><code>0</code></td><td><code>ok</code></td></tr><tr><td><code>1</code></td><td><code>failed</code>, <code>aborted</code>, <code>invalid_argument</code>, <code>rate_limited</code>, or <code>unavailable</code></td></tr><tr><td><code>2</code></td><td><code>usage</code>, for a bad command, flag, or argument</td></tr><tr><td><code>3</code></td><td><code>pending</code>, while the work still runs</td></tr><tr><td><code>4</code></td><td><code>not_found</code></td></tr><tr><td><code>5</code></td><td><code>unauthenticated</code> or <code>permission_denied</code></td></tr><tr><td><code>6</code></td><td><code>conflict</code> or <code>failed_precondition</code></td></tr></tbody></table><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="./project-layout.html">Project layout</a></li><li><a href="./sessions.html">Sessions, events, and streaming</a></li><li><a href="./../deployment.html">Deployment</a></li><li><a href="./../guides/migrate.html">Early-alpha migration</a></li></ul>`,159)])])}const u=t(n,[["render",d]]);export{g as __pageData,u as default};
@@ -1 +1 @@
1
- import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"CLI","description":"Look up Agent SDK commands, targets, flags, outputs, and exit status.","frontmatter":{"title":"CLI","description":"Look up Agent SDK commands, targets, flags, outputs, and exit status."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function d(c,e,l,i,r,p){return s(),a("div",null,[...e[0]||(e[0]=[o("",143)])])}const u=t(n,[["render",d]]);export{g as __pageData,u as default};
1
+ import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"CLI","description":"Look up Agent SDK commands, targets, flags, outputs, and exit status.","frontmatter":{"title":"CLI","description":"Look up Agent SDK commands, targets, flags, outputs, and exit status."},"headers":[],"relativePath":"reference/cli.md","filePath":"reference/cli.md"}'),n={name:"reference/cli.md"};function d(c,e,i,l,r,p){return s(),a("div",null,[...e[0]||(e[0]=[o("",159)])])}const u=t(n,[["render",d]]);export{g as __pageData,u as default};
@@ -1,8 +1,8 @@
1
- import{_ as t,c as e,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Limits","description":"How many deployments and deploys a team can have on Cursor-managed hosting, and the error a deploy returns at the cap.","frontmatter":{"title":"Limits","description":"How many deployments and deploys a team can have on Cursor-managed hosting, and the error a deploy returns at the cap."},"headers":[],"relativePath":"reference/limits.md","filePath":"reference/limits.md"}'),n={name:"reference/limits.md"};function l(o,s,h,p,d,r){return i(),e("div",null,[...s[0]||(s[0]=[a(`<h1 id="limits" tabindex="-1">Limits <a class="header-anchor" href="#limits" aria-label="Permalink to &quot;Limits&quot;">​</a></h1><p>Cursor caps deployments for some teams. If your team has caps, these are the default values.</p><table tabindex="0"><thead><tr><th>Limit</th><th>Default</th><th>What counts</th></tr></thead><tbody><tr><td><code>owner.deployments</code></td><td>20</td><td>Each slug, running or stopped</td></tr><tr><td><code>owner.deploysPerDay</code></td><td>100 per 24 hours</td><td>Each accepted deploy, including redeploys</td></tr></tbody></table><p>The error looks like this:</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>
1
+ import{_ as t,c as i,o as e,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Limits","description":"How many deployments and deploys a team can have on Cursor-managed hosting, and the error a deploy returns at the cap.","frontmatter":{"title":"Limits","description":"How many deployments and deploys a team can have on Cursor-managed hosting, and the error a deploy returns at the cap."},"headers":[],"relativePath":"reference/limits.md","filePath":"reference/limits.md"}'),n={name:"reference/limits.md"};function l(o,s,d,h,r,p){return e(),i("div",null,[...s[0]||(s[0]=[a(`<h1 id="limits" tabindex="-1">Limits <a class="header-anchor" href="#limits" aria-label="Permalink to &quot;Limits&quot;">​</a></h1><p>Cursor caps deployments for every team. These are the default values.</p><table tabindex="0"><thead><tr><th>Limit</th><th>Default</th><th>What counts</th></tr></thead><tbody><tr><td><code>owner.deployments</code></td><td>20</td><td>Each installed slug, including a stopped slug. An uninstalled slug counts when a build from the last 2 hours is still in progress or has finished successfully.</td></tr><tr><td><code>owner.deploysPerDay</code></td><td>100</td><td>Each accepted deploy in a rolling 24-hour window, including a redeploy.</td></tr></tbody></table><p>The error looks like this:</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>
2
2
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;error&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Your team has 20 of 20 deployments. Delete one with \`agent-sdk deployment delete &lt;slug&gt;\`, or contact support to raise the limit. Redeploying an existing slug doesn&#39;t count.&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
3
3
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;code&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;limit_exceeded&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
4
4
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;limit&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;owner.deployments&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
5
5
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;max&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
6
6
  <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;current&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
7
- <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;docsUrl&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://cursor.com/docs/bdk/reference/limits&quot;</span></span>
8
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>To free a slot, run <code>agent-sdk deployment delete &lt;slug&gt;</code>, or wait until the oldest counted deploy is 24 hours old. A deploy can also answer <code>503</code> with a <code>Retry-After</code> header, and you can retry it after that many seconds.</p>`,6)])])}const E=t(n,[["render",l]]);export{c as __pageData,E as default};
7
+ <span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> &quot;docsUrl&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;https://cursor.com/docs/agent-sdk/reference/limits&quot;</span></span>
8
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>To free a slot, run <code>agent-sdk deployment delete &lt;slug&gt;</code>, or wait until the oldest counted deploy is 24 hours old. A deploy can also answer <code>503</code> with a <code>Retry-After</code> header, and you can retry it after that many seconds.</p>`,6)])])}const u=t(n,[["render",l]]);export{c as __pageData,u as default};
@@ -1 +1 @@
1
- import{_ as t,c as e,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Limits","description":"How many deployments and deploys a team can have on Cursor-managed hosting, and the error a deploy returns at the cap.","frontmatter":{"title":"Limits","description":"How many deployments and deploys a team can have on Cursor-managed hosting, and the error a deploy returns at the cap."},"headers":[],"relativePath":"reference/limits.md","filePath":"reference/limits.md"}'),n={name:"reference/limits.md"};function l(o,s,h,p,d,r){return i(),e("div",null,[...s[0]||(s[0]=[a("",6)])])}const E=t(n,[["render",l]]);export{c as __pageData,E as default};
1
+ import{_ as t,c as i,o as e,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Limits","description":"How many deployments and deploys a team can have on Cursor-managed hosting, and the error a deploy returns at the cap.","frontmatter":{"title":"Limits","description":"How many deployments and deploys a team can have on Cursor-managed hosting, and the error a deploy returns at the cap."},"headers":[],"relativePath":"reference/limits.md","filePath":"reference/limits.md"}'),n={name:"reference/limits.md"};function l(o,s,d,h,r,p){return e(),i("div",null,[...s[0]||(s[0]=[a("",6)])])}const u=t(n,[["render",l]]);export{c as __pageData,u as default};
@@ -1,6 +1,6 @@
1
- import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,d,p,k,r){return e(),a("div",null,[...s[0]||(s[0]=[n(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to &quot;Schedules and reminders&quot;">​</a></h1><p>A schedule or a reminder lets an agent act without an inbound message.</p><h2 id="schedules-vs-reminders" tabindex="-1">Schedules vs reminders <a class="header-anchor" href="#schedules-vs-reminders" aria-label="Permalink to &quot;Schedules vs reminders&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Schedule</th><th>Reminder</th></tr></thead><tbody><tr><td>Defined</td><td>At deploy time, in <code>bot/schedules/*</code></td><td>At runtime, with <code>createReminder</code> or <code>host.reminders</code></td></tr><tr><td>Scope</td><td>The whole agent</td><td>One conversation</td></tr><tr><td>Session</td><td>Starts a new task session, or hands off through <code>receive</code></td><td>Wakes an existing conversation</td></tr><tr><td>Cadence</td><td>5-field cron, in UTC, to the minute</td><td><code>every</code>, <code>cron</code>, <code>delay</code>, or <code>at</code></td></tr><tr><td>Dev mode</td><td>Manual dispatch only</td><td>Manual dispatch only, with timers off</td></tr></tbody></table><h2 id="schedules" tabindex="-1">Schedules <a class="header-anchor" href="#schedules" aria-label="Permalink to &quot;Schedules&quot;">​</a></h2><h3 id="markdown-schedules" tabindex="-1">Markdown schedules <a class="header-anchor" href="#markdown-schedules" aria-label="Permalink to &quot;Markdown schedules&quot;">​</a></h3><p>A Markdown file with <code>cron:</code> frontmatter is a fire-and-forget task:</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;">---</span></span>
2
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">cron: &quot;0 9 * * 1-5&quot;</span></span>
3
- <span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
1
+ import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,d,p,k,r){return e(),a("div",null,[...s[0]||(s[0]=[n(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to &quot;Schedules and reminders&quot;">​</a></h1><p>A schedule or a reminder lets an agent act without an inbound message.</p><h2 id="schedules-vs-reminders" tabindex="-1">Schedules vs reminders <a class="header-anchor" href="#schedules-vs-reminders" aria-label="Permalink to &quot;Schedules vs reminders&quot;">​</a></h2><table tabindex="0"><thead><tr><th></th><th>Schedule</th><th>Reminder</th></tr></thead><tbody><tr><td>Defined</td><td>At deploy time, in <code>bot/schedules/*</code></td><td>At runtime, with <code>createReminder</code> or <code>host.reminders</code></td></tr><tr><td>Scope</td><td>The whole agent</td><td>One conversation</td></tr><tr><td>Session</td><td>Starts a new task session, or hands off through <code>receive</code></td><td>Wakes an existing conversation</td></tr><tr><td>Cadence</td><td>5-field cron, in UTC, to the minute</td><td><code>every</code>, <code>cron</code>, <code>delay</code>, or <code>at</code></td></tr><tr><td>Dev mode</td><td>Manual dispatch only</td><td>Manual dispatch only, with timers off</td></tr></tbody></table><h2 id="schedules" tabindex="-1">Schedules <a class="header-anchor" href="#schedules" aria-label="Permalink to &quot;Schedules&quot;">​</a></h2><h3 id="markdown-schedules" tabindex="-1">Markdown schedules <a class="header-anchor" href="#markdown-schedules" aria-label="Permalink to &quot;Markdown schedules&quot;">​</a></h3><p>A Markdown file with <code>cron:</code> frontmatter is a fire-and-forget task:</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:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
2
+ <span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">cron</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;0 9 * * 1-5&quot;</span></span>
3
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
4
4
  <span class="line"></span>
5
5
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Pull open incidents and post a summary to the metrics endpoint.</span></span></code></pre></div><p>Each fire starts a task-mode session with the body as its prompt, and the session runs to <code>session.completed</code> or <code>session.failed</code> without follow-ups.</p><h3 id="schedule-handlers" tabindex="-1">Schedule handlers <a class="header-anchor" href="#schedule-handlers" aria-label="Permalink to &quot;Schedule handlers&quot;">​</a></h3><p>A <code>run</code> handler can call tools or hand work to a channel, whose delivery events then fire:</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;"> { defineSchedule } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@grok/agent-sdk/schedules&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
6
6
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> webhook </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../channels/webhook.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>