@grok/agent-sdk 0.2.29 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (396) hide show
  1. package/dist/channels/slack/cli-project.js +1 -1
  2. package/dist/docs/404.html +2 -2
  3. package/dist/docs/assets/{app.DMrZKFjI.js → app.BzTUBOAD.js} +4 -4
  4. package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
  5. package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
  6. package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
  7. package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
  8. package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
  9. package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
  10. package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.DH8GOhiv.js} +1 -1
  11. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
  12. package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.BXHpx1lE.js} +1 -1
  13. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
  14. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
  15. package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
  16. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
  17. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
  18. package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
  19. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
  20. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
  21. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
  22. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
  23. package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
  24. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
  25. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
  26. package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
  27. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
  28. package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
  29. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
  30. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
  31. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
  32. package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
  33. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
  34. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
  35. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
  36. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
  37. package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.DgJ4L-8V.js} +1 -1
  38. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
  39. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
  40. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
  41. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
  42. package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.DXXqX4MQ.js} +1 -1
  43. package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.5c61gNw4.js} +1 -1
  44. package/dist/docs/assets/chunks/{min.SPrSp704.js → min.B1-NAjHX.js} +1 -1
  45. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
  46. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
  47. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
  48. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
  49. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
  50. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
  51. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
  52. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
  53. package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DMj_7q3B.js} +2 -2
  54. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
  55. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
  56. package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
  57. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
  58. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
  59. package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
  60. package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
  61. package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
  62. package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
  63. package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
  64. package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
  65. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
  66. package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
  67. package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
  68. package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
  69. package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
  70. package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
  71. package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
  72. package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
  73. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
  74. package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
  75. package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
  76. package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
  77. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
  78. package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
  79. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
  80. package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
  81. package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
  82. package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
  83. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
  84. package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
  85. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
  86. package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
  87. package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
  88. package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
  89. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
  90. package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
  91. package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
  92. package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
  93. package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
  94. package/dist/docs/assets/{index.md.CAruw_rp.lean.js → index.md.DRfaoRCZ.lean.js} +1 -1
  95. package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
  96. package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
  97. package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
  98. package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
  99. package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
  100. package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
  101. package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
  102. package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
  103. package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
  104. package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
  105. package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
  106. package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
  107. package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
  108. package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
  109. package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
  110. package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
  111. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
  112. package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
  113. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
  114. package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
  115. package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
  116. package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
  117. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
  118. package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
  119. package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
  120. package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
  121. package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
  122. package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
  123. package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
  124. package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
  125. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
  126. package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
  127. package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
  128. package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
  129. package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
  130. package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
  131. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
  132. package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
  133. package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
  134. package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
  135. package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
  136. package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
  137. package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
  138. package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
  139. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
  140. package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
  141. package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
  142. package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
  143. package/dist/docs/building-with-agents.html +41 -44
  144. package/dist/docs/building-with-agents.md +11 -104
  145. package/dist/docs/changelog.html +37 -37
  146. package/dist/docs/changelog.md +5 -155
  147. package/dist/docs/deployment.html +54 -54
  148. package/dist/docs/deployment.md +83 -262
  149. package/dist/docs/evals.html +52 -71
  150. package/dist/docs/evals.md +33 -129
  151. package/dist/docs/guides/agent-to-agent.html +43 -43
  152. package/dist/docs/guides/agent-to-agent.md +27 -64
  153. package/dist/docs/guides/bitbucket.html +62 -62
  154. package/dist/docs/guides/bitbucket.md +73 -134
  155. package/dist/docs/guides/cloud-agents.html +37 -37
  156. package/dist/docs/guides/cloud-agents.md +23 -53
  157. package/dist/docs/guides/convert-automation.html +39 -56
  158. package/dist/docs/guides/convert-automation.md +31 -115
  159. package/dist/docs/guides/github.html +46 -54
  160. package/dist/docs/guides/github.md +49 -131
  161. package/dist/docs/guides/gitlab.html +98 -108
  162. package/dist/docs/guides/gitlab.md +104 -184
  163. package/dist/docs/guides/improve.html +38 -43
  164. package/dist/docs/guides/improve.md +24 -90
  165. package/dist/docs/guides/jev.html +55 -95
  166. package/dist/docs/guides/jev.md +53 -160
  167. package/dist/docs/guides/mcp-oauth.html +38 -40
  168. package/dist/docs/guides/mcp-oauth.md +33 -67
  169. package/dist/docs/guides/migrate.html +38 -43
  170. package/dist/docs/guides/migrate.md +56 -130
  171. package/dist/docs/guides/opentelemetry.html +41 -43
  172. package/dist/docs/guides/opentelemetry.md +32 -27
  173. package/dist/docs/guides/pagerduty.html +50 -49
  174. package/dist/docs/guides/pagerduty.md +65 -199
  175. package/dist/docs/guides/slack.html +51 -57
  176. package/dist/docs/guides/slack.md +76 -204
  177. package/dist/docs/guides/webhooks.html +42 -42
  178. package/dist/docs/guides/webhooks.md +64 -146
  179. package/dist/docs/hashmap.json +1 -1
  180. package/dist/docs/hillclimbing.html +40 -42
  181. package/dist/docs/hillclimbing.md +40 -102
  182. package/dist/docs/index.html +55 -61
  183. package/dist/docs/index.md +49 -83
  184. package/dist/docs/llms-full.txt +2262 -5721
  185. package/dist/docs/llms.txt +9 -14
  186. package/dist/docs/quickstart.html +95 -152
  187. package/dist/docs/quickstart.md +91 -180
  188. package/dist/docs/reference/access.html +36 -36
  189. package/dist/docs/reference/access.md +7 -12
  190. package/dist/docs/reference/agent-config.html +43 -56
  191. package/dist/docs/reference/agent-config.md +91 -174
  192. package/dist/docs/reference/artifacts.html +38 -39
  193. package/dist/docs/reference/artifacts.md +38 -62
  194. package/dist/docs/reference/channels.html +38 -39
  195. package/dist/docs/reference/channels.md +102 -151
  196. package/dist/docs/reference/cli.html +68 -84
  197. package/dist/docs/reference/cli.md +232 -697
  198. package/dist/docs/reference/connections.html +45 -57
  199. package/dist/docs/reference/connections.md +83 -164
  200. package/dist/docs/reference/evals.html +47 -54
  201. package/dist/docs/reference/evals.md +75 -141
  202. package/dist/docs/reference/extensions.html +41 -43
  203. package/dist/docs/reference/extensions.md +37 -70
  204. package/dist/docs/reference/hooks.html +40 -52
  205. package/dist/docs/reference/hooks.md +62 -133
  206. package/dist/docs/reference/http-api.html +38 -42
  207. package/dist/docs/reference/http-api.md +66 -118
  208. package/dist/docs/reference/instructions.html +39 -39
  209. package/dist/docs/reference/instructions.md +19 -29
  210. package/dist/docs/reference/limits.html +38 -38
  211. package/dist/docs/reference/limits.md +9 -21
  212. package/dist/docs/reference/memory.html +37 -38
  213. package/dist/docs/reference/memory.md +38 -75
  214. package/dist/docs/reference/playground.html +36 -36
  215. package/dist/docs/reference/playground.md +14 -22
  216. package/dist/docs/reference/project-layout.html +49 -48
  217. package/dist/docs/reference/project-layout.md +38 -84
  218. package/dist/docs/reference/schedules.html +46 -48
  219. package/dist/docs/reference/schedules.md +59 -90
  220. package/dist/docs/reference/sessions.html +37 -37
  221. package/dist/docs/reference/sessions.md +66 -113
  222. package/dist/docs/reference/skills.html +39 -39
  223. package/dist/docs/reference/skills.md +11 -31
  224. package/dist/docs/reference/subagents.html +37 -37
  225. package/dist/docs/reference/subagents.md +17 -31
  226. package/dist/docs/reference/tools.html +47 -64
  227. package/dist/docs/reference/tools.md +48 -130
  228. package/dist/docs/templates/agentic-owners.html +38 -38
  229. package/dist/docs/templates/agentic-owners.md +50 -74
  230. package/dist/docs/templates/reviews.html +69 -0
  231. package/dist/docs/templates/reviews.md +71 -0
  232. package/dist/docs/troubleshooting.html +38 -36
  233. package/dist/docs/troubleshooting.md +48 -101
  234. package/dist/internal/cli-deploy.js +1 -1
  235. package/dist/internal/cli-docs.js +1 -1
  236. package/dist/internal/cli-images.js +1 -1
  237. package/dist/internal/cli-skills.js +1 -1
  238. package/dist/internal/cursor/credentials.js +1 -1
  239. package/dist/internal/deploy-manifest.d.ts +1 -0
  240. package/dist/internal/deploy-manifest.d.ts.map +1 -1
  241. package/dist/internal/deploy-manifest.js +0 -1
  242. package/dist/internal/discovery/agent-config.d.ts +2 -6
  243. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  244. package/dist/internal/discovery/agent-config.js +8 -25
  245. package/dist/internal/discovery/agent.d.ts.map +1 -1
  246. package/dist/internal/discovery/agent.js +2 -3
  247. package/dist/internal/discovery/project.d.ts.map +1 -1
  248. package/dist/internal/discovery/project.js +15 -0
  249. package/dist/internal/init-project.d.ts.map +1 -1
  250. package/dist/internal/init-project.js +7 -5
  251. package/dist/internal/reminder-runner.js +1 -1
  252. package/dist/internal/session-engine.js +1 -1
  253. package/dist/internal/shallow-clone.js +1 -1
  254. package/dist/playground/assets/index-D6mVn9og.js +62 -0
  255. package/dist/playground/assets/index-DlALM6gr.css +1 -0
  256. package/dist/playground/index.html +2 -2
  257. package/dist/types.d.ts +4 -17
  258. package/dist/types.d.ts.map +1 -1
  259. package/docs/README.md +49 -83
  260. package/docs/building-with-agents.md +11 -104
  261. package/docs/changelog.md +6 -156
  262. package/docs/deployment.md +83 -262
  263. package/docs/evals.md +34 -130
  264. package/docs/guides/agent-to-agent.md +27 -64
  265. package/docs/guides/bitbucket.md +73 -134
  266. package/docs/guides/cloud-agents.md +23 -53
  267. package/docs/guides/convert-automation.md +31 -115
  268. package/docs/guides/github.md +49 -131
  269. package/docs/guides/gitlab.md +104 -184
  270. package/docs/guides/improve.md +24 -90
  271. package/docs/guides/jev.md +53 -160
  272. package/docs/guides/mcp-oauth.md +33 -67
  273. package/docs/guides/migrate.md +56 -130
  274. package/docs/guides/opentelemetry.md +37 -27
  275. package/docs/guides/pagerduty.md +68 -200
  276. package/docs/guides/slack.md +76 -204
  277. package/docs/guides/webhooks.md +64 -146
  278. package/docs/hillclimbing.md +41 -103
  279. package/docs/quickstart.md +91 -180
  280. package/docs/reference/access.md +7 -12
  281. package/docs/reference/agent-config.md +91 -174
  282. package/docs/reference/artifacts.md +38 -62
  283. package/docs/reference/channels.md +102 -151
  284. package/docs/reference/cli.md +232 -697
  285. package/docs/reference/connections.md +83 -164
  286. package/docs/reference/evals.md +75 -141
  287. package/docs/reference/extensions.md +37 -70
  288. package/docs/reference/hooks.md +61 -132
  289. package/docs/reference/http-api.md +66 -118
  290. package/docs/reference/instructions.md +20 -30
  291. package/docs/reference/limits.md +10 -22
  292. package/docs/reference/memory.md +38 -75
  293. package/docs/reference/playground.md +14 -22
  294. package/docs/reference/project-layout.md +38 -84
  295. package/docs/reference/schedules.md +59 -90
  296. package/docs/reference/sessions.md +66 -113
  297. package/docs/reference/skills.md +12 -32
  298. package/docs/reference/subagents.md +17 -31
  299. package/docs/reference/tools.md +48 -130
  300. package/docs/templates/agentic-owners.md +50 -74
  301. package/docs/templates/reviews.md +76 -0
  302. package/docs/troubleshooting.md +48 -101
  303. package/package.json +2 -2
  304. package/skills/deploy/SKILL.md +1 -1
  305. package/skills/migrate-v2/SKILL.md +0 -1
  306. package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
  307. package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
  308. package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
  309. package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
  310. package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
  311. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
  312. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
  313. package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
  314. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
  315. package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
  316. package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
  317. package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
  318. package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
  319. package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
  320. package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
  321. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
  322. package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
  323. package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
  324. package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
  325. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
  326. package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
  327. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
  328. package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
  329. package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
  330. package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
  331. package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
  332. package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
  333. package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
  334. package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
  335. package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
  336. package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
  337. package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
  338. package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
  339. package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
  340. package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
  341. package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
  342. package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
  343. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
  344. package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
  345. package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
  346. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
  347. package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
  348. package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
  349. package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
  350. package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
  351. package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
  352. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
  353. package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
  354. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
  355. package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
  356. package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
  357. package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
  358. package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
  359. package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
  360. package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
  361. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
  362. package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
  363. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
  364. package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
  365. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
  366. package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
  367. package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
  368. package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
  369. package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
  370. package/dist/docs/guides/hooks.html +0 -113
  371. package/dist/docs/guides/hooks.md +0 -116
  372. package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
  373. package/dist/docs/package/skills/evals/SKILL.md +0 -145
  374. package/dist/docs/package/skills/github/SKILL.md +0 -133
  375. package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
  376. package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
  377. package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
  378. package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
  379. package/dist/docs/reference/prompt.html +0 -68
  380. package/dist/docs/reference/prompt.md +0 -47
  381. package/dist/docs/templates/security-reviewer.html +0 -62
  382. package/dist/docs/templates/security-reviewer.md +0 -81
  383. package/dist/docs/templates/thermo-quality-review.html +0 -62
  384. package/dist/docs/templates/thermo-quality-review.md +0 -75
  385. package/dist/docs/templates/thermo-review.html +0 -62
  386. package/dist/docs/templates/thermo-review.md +0 -75
  387. package/dist/docs/templates/triage.html +0 -68
  388. package/dist/docs/templates/triage.md +0 -101
  389. package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
  390. package/dist/playground/assets/index-F8b5WvWi.css +0 -1
  391. package/docs/guides/hooks.md +0 -121
  392. package/docs/reference/prompt.md +0 -52
  393. package/docs/templates/security-reviewer.md +0 -86
  394. package/docs/templates/thermo-quality-review.md +0 -80
  395. package/docs/templates/thermo-review.md +0 -80
  396. package/docs/templates/triage.md +0 -106
package/docs/evals.md CHANGED
@@ -1,26 +1,18 @@
1
1
  ---
2
2
  title: "Evals"
3
- description: "Protect agent decisions with fixed inputs, trajectory assertions, and regression checks that run locally or in CI."
3
+ description: "Measure and Improve agent behavior with Evals"
4
4
  ---
5
5
 
6
6
  # Evals
7
7
 
8
- An eval sends a fixed input to the real agent and checks the resulting
9
- trajectory: whether the turn succeeded, which tools ran, and what shape
10
- the answer took. Use evals to protect behavior you already understand,
11
- not to discover what the prompt should do.
8
+ An eval sends a fixed input to the real agent and checks which tools ran and what the answer looks
9
+ like. To improve an agent and lock each win with an eval, follow [Hillclimbing](./hillclimbing.md).
12
10
 
13
- Evals run real model turns and real tools. Guard external writes before
14
- running a suite against an agent that can post, merge, or deploy.
11
+ Evals run real tools, so [guard any writes](#keep-side-effects-out-of-eval-sessions) first.
15
12
 
16
13
  ## Protect a tool decision
17
14
 
18
- This smoke case asks for a PR verdict, requires the read-only inspection
19
- tool, and fails if the agent tries to approve. The CLI reports all three
20
- decisions together instead of stopping at the first miss.
21
-
22
- Use the [Jev extension](./guides/jev.md) when host code needs a typed
23
- choice, score, or boolean before it writes.
15
+ The case below passes only if the agent calls the inspection tool and doesn't approve.
24
16
 
25
17
  ```ts
26
18
  // evals/readiness.eval.ts
@@ -29,9 +21,7 @@ import { defineEval, includes } from "@grok/agent-sdk/evals";
29
21
  export default defineEval({
30
22
  tags: ["smoke"],
31
23
  async test(t) {
32
- await t.send(
33
- "Is https://github.com/acme/checkout/pull/42 ready to approve?"
34
- );
24
+ await t.send("Is https://github.com/acme/checkout/pull/42 ready to approve?");
35
25
 
36
26
  t.succeeded();
37
27
  t.calledTool("inspect_pr");
@@ -41,10 +31,7 @@ export default defineEval({
41
31
  });
42
32
  ```
43
33
 
44
- Evals live in the project-root `evals/` directory, beside `bot/`.
45
- Blank `agent-sdk init` writes `evals/smoke.eval.ts`, which uses the scaffolded
46
- `echo` tool and asserts `t.succeeded()` and `t.calledTool("echo")`.
47
- It also writes this concurrency config:
34
+ Evals live in `evals/` beside `bot/`. Set how many cases run at once:
48
35
 
49
36
  ```ts
50
37
  // evals/evals.config.ts
@@ -55,52 +42,34 @@ export default defineEvalConfig({
55
42
  });
56
43
  ```
57
44
 
58
- ```text
45
+ ```bash
59
46
  agent-sdk eval --dir . --list
60
47
  agent-sdk eval --dir . --tag smoke
61
48
  ```
62
49
 
63
50
  ## Check answer shape or quality
64
51
 
65
- Prefer a deterministic shape check when the output has a contract. The
66
- failure tells you which field was wrong, and the case remains stable
67
- when the model changes its wording.
52
+ When the output has a contract, check its shape:
68
53
 
69
54
  ```ts
70
55
  import { matches } from "@grok/agent-sdk/evals";
71
56
  import { z } from "zod";
72
57
 
73
58
  const verdict = JSON.parse(t.reply ?? "{}");
74
- t.check(
75
- verdict,
76
- matches(
77
- z.object({
78
- ready: z.boolean(),
79
- blockers: z.array(z.string()),
80
- })
81
- )
82
- );
59
+ t.check(verdict, matches(z.object({ ready: z.boolean(), blockers: z.array(z.string()) })));
83
60
  ```
84
61
 
85
- Use a judge when correctness depends on meaning that a schema, regex, or
86
- known value cannot capture:
62
+ When correctness depends on meaning, use a judge. [Judges](./reference/evals.md#judges) covers
63
+ models and grader options.
87
64
 
88
65
  ```ts
89
- t.judge
90
- .factuality("The lint step failed on src/sidebar.ts.")
91
- .atLeast(0.8);
66
+ t.judge.factuality("The lint step failed on src/sidebar.ts.").atLeast(0.8);
92
67
  ```
93
68
 
94
- Judge checks are tracked scores until you give them a hard gate.
95
- Configure the judge model in `evals.config.ts`. The
96
- [Evals reference](./reference/evals.md#judges) owns grader options and
97
- severity rules.
98
-
99
69
  ## Test a conversation
100
70
 
101
- Several `t.send` calls in one case share a session. Assertions on a
102
- returned turn inspect only that turn, while assertions on `t` inspect
103
- the whole conversation.
71
+ Several `t.send` calls in one case share a session. An assertion on a returned turn checks only that
72
+ turn, and an assertion on `t` checks the whole conversation.
104
73
 
105
74
  ```ts
106
75
  const first = await t.send("Inspect PR 42.");
@@ -114,9 +83,7 @@ t.succeeded();
114
83
 
115
84
  ## Pin realistic inputs
116
85
 
117
- A useful eval changes only when the agent changes. Freeze canonical chat
118
- prompts, seed workspace evidence directly, and save webhook payloads
119
- instead of depending on a developer's checkout or live external state.
86
+ Seed the files the agent reads instead of depending on your checkout:
120
87
 
121
88
  ```ts
122
89
  await t.send("Review pr/diff.patch and report blockers.", {
@@ -129,47 +96,32 @@ await t.send("Review pr/diff.patch and report blockers.", {
129
96
  });
130
97
  ```
131
98
 
132
- For GitHub agents, snapshot a PR into committed fixtures:
99
+ Save a GitHub pull request's webhook payloads as fixtures:
133
100
 
134
- ```text
135
- agent-sdk github replay acme/checkout#42 \
136
- --events '*' \
137
- --dry-run \
138
- --out fixtures/github
101
+ ```bash
102
+ agent-sdk github replay https://github.com/acme/checkout/pull/42 \
103
+ --events '*' --dry-run --fixtures-dir fixtures/github
139
104
  ```
140
105
 
141
- Keep a small, fast `smoke` set for every change. Put larger datasets and
142
- drift-prone live cases behind an explicit selection. See
143
- [Datasets and fixtures](./reference/evals.md#datasets-and-fixtures) for
144
- loaders and case expansion.
106
+ [Datasets and fixtures](./reference/evals.md#datasets-and-fixtures) covers loaders for larger sets.
145
107
 
146
108
  ## Run and debug a regression suite
147
109
 
148
- Run one case while iterating, then the smoke suite before review. A
149
- failure artifact records the input, assertions, tool calls, and final
150
- text, making it the first place to look before changing the prompt.
110
+ Run one case while you iterate, then the smoke set before review:
151
111
 
152
- ```text
112
+ ```bash
153
113
  agent-sdk eval --dir . readiness
154
114
  agent-sdk eval --dir . --tag smoke
155
- agent-sdk eval --dir . --json
156
115
  ```
157
116
 
158
- By default, results land under `evals/<stamp>/` in the project state
159
- directory. Open `evals/<case-id>.json` inside that run directory for the
160
- failed case. This artifact location is independent of `--state-root`;
161
- pass `--artifacts <dir>` to choose another destination.
162
-
163
- Model turns need a credential. Resolution checks `CURSOR_API_KEY`,
164
- `CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, then a saved
165
- `agent-sdk login`. `eval --list` only discovers cases and needs none.
117
+ Each run writes a folder under `evals/` in the project state directory, or under `--artifacts <dir>`
118
+ if you pass it. Open `evals/<case-id>.json` in that folder to see a failed case's input, assertions,
119
+ tool calls, and final text. Model turns need a
120
+ [Cursor credential](./reference/cli.md#environment-variables).
166
121
 
167
122
  ## Run evals in CI
168
123
 
169
- Write machine-readable output and JUnit annotations, then let a failed
170
- gate fail the job:
171
-
172
- ```text
124
+ ```bash
173
125
  # CURSOR_API_KEY comes from the CI secret store.
174
126
  agent-sdk eval --dir . --json --no-stream \
175
127
  --junit reports/evals.xml \
@@ -177,70 +129,22 @@ agent-sdk eval --dir . --json --no-stream \
177
129
  > reports/evals.json
178
130
  ```
179
131
 
180
- Run `--tag smoke` on pull requests and the full suite on a schedule when
181
- cost or latency makes every-push coverage impractical. Use soft scores
182
- for a new probabilistic benchmark until its threshold is trustworthy.
183
-
184
- The [CLI reference](./reference/cli.md#eval) covers selectors,
185
- server-side batches, exit codes, and JSON output.
132
+ Run `--tag smoke` on pull requests and the full suite on a schedule. The
133
+ [CLI reference](./reference/cli.md#eval) covers every flag.
186
134
 
187
135
  ## Keep side effects out of eval sessions
188
136
 
189
- Eval sessions carry `purpose: "eval"`. Check it at the deterministic
190
- write boundary and return the decision without performing the external
191
- action:
137
+ Eval sessions carry `purpose: "eval"`. Check it where the tool writes, and return the decision
138
+ without the external action:
192
139
 
193
140
  ```ts
194
141
  async execute({ findings }, ctx) {
195
142
  if (ctx.session.purpose === "eval") {
196
- return {
197
- posted: false,
198
- reason: "eval",
199
- count: findings.length,
200
- };
143
+ return { posted: false, reason: "eval", count: findings.length };
201
144
  }
202
145
 
203
146
  return await postFindings(findings);
204
147
  }
205
148
  ```
206
149
 
207
- This preserves the tool call in the trajectory, so the eval can still
208
- assert that the agent chose to post.
209
-
210
- ## Evals, hooks, or hillclimbing?
211
-
212
- Use an eval to gate one fixed input. Use a
213
- [hook](./reference/hooks.md) to observe every live session for metrics,
214
- auditing, or alerts. Use [hillclimbing](./hillclimbing.md) to decide
215
- which source change improves a fixed set of inputs; every kept
216
- hillclimb change should add an eval.
217
-
218
- ## Gates and scores
219
-
220
- `t.succeeded()`, tool assertions, and deterministic checks are hard
221
- gates by default. A failed gate fails the case. `.soft()` records a
222
- measurement without blocking, while `.atLeast(threshold)` records a
223
- score and marks a miss as `scored`.
224
-
225
- Start with decisions and output shape: the intended tool, the tempting
226
- wrong tool, and one structural check. Exact prose is rarely a stable
227
- contract.
228
-
229
- ## Keep improvements with regression evals
230
-
231
- Every kept improvement needs an eval that would have failed before the
232
- change. A tool-choice gate, bounded `maxToolCalls`, or output-shape check
233
- turns the improvement into a durable contract.
234
-
235
- Never weaken an existing gate to make a new implementation pass. That
236
- moves the freeze line instead of proving the change.
237
-
238
- ## Related
239
-
240
- - [Evals reference](./reference/evals.md): complete authoring and runner
241
- contracts
242
- - [`skills/evals/SKILL.md`](../skills/evals/SKILL.md): author and seed
243
- cases with a coding agent
244
- - [Hillclimbing](./hillclimbing.md): measure a change and lock the win
245
- - [Sessions](./reference/sessions.md): events available to trajectory
246
- assertions
150
+ The tool call stays in the trajectory, so the eval can still assert that the agent chose to post.
@@ -5,18 +5,15 @@ description: "Let one Agent SDK agent consult an independent specialist, continu
5
5
 
6
6
  # Peer agents
7
7
 
8
- A peer connection lets one agent ask an independent specialist for help.
9
- On Cursor-managed hosting, team-owned agents reach peers by deployment
10
- slug. Deploy both agents and Agent SDK handles routing and authentication; you
11
- don't configure a URL, header, or secret. The specialist keeps its own
12
- instructions, tools, and session while the caller decides when to delegate
13
- and returns the answer to the user.
8
+ A peer connection lets one agent ask an independent specialist for help. The
9
+ specialist keeps its own instructions, tools, and sessions. On Cursor hosting,
10
+ team-owned agents reach each other by deployment slug, and Agent SDK handles
11
+ routing and authentication for you.
14
12
 
15
13
  ## Delegate a question to a specialist
16
14
 
17
- Ask the concierge about the weather and it hands the question to the
18
- specialist. The weather agent answers in its own context, then the
19
- concierge returns that answer to you.
15
+ Ask the concierge about the weather, and it hands the question to the weather
16
+ agent and returns the answer.
20
17
 
21
18
  ```ts
22
19
  // bot/mcp-connections/weather.ts
@@ -28,30 +25,27 @@ export default defineConnection({
28
25
  });
29
26
  ```
30
27
 
31
- Give the concierge a narrow routing rule:
28
+ The filename, `weather.ts`, becomes the
29
+ [MCP server name](../reference/connections.md#peer-mcp-connection), and `agent`
30
+ is the specialist's lowercase deployment slug. Give the concierge a one-way
31
+ routing rule, so the agents never pass a request back and forth:
32
32
 
33
33
  ```md
34
34
  When a request needs current weather, ask the `weather` peer. Return its
35
35
  answer.
36
36
  ```
37
37
 
38
- Deploy the specialist and caller from pushed Git refs:
38
+ Deploy both agents from pushed Git refs:
39
39
 
40
40
  ```bash
41
41
  agent-sdk deploy --dir ./agents/weather-agent --slug weather-agent
42
42
  agent-sdk deploy --dir ./agents/concierge --slug concierge
43
43
  ```
44
44
 
45
- The connection filename, `weather.ts`, becomes the MCP server name the
46
- concierge calls. Set `agent` to the specialist's lowercase deployment slug.
47
-
48
45
  ## Continue the specialist's session
49
46
 
50
- Ask a follow-up about the same forecast and the specialist picks up
51
- where it left off, with its own instructions and tool history still in
52
- place. The first `ask` returns `{ status, sessionId, reply }` as text on
53
- the `callTool` result. Parse `sessionId` and pass it on the next `ask`
54
- so the peer remembers its earlier work instead of starting fresh.
47
+ The first `ask` returns `{ status, sessionId, reply }` as text. Pass that
48
+ `sessionId` on the next `ask` to continue the specialist's earlier work.
55
49
 
56
50
  ```ts
57
51
  const first = await ctx.host.mcp.callTool("weather", "ask", {
@@ -69,8 +63,8 @@ await ctx.host.mcp.callTool("weather", "ask", {
69
63
  });
70
64
  ```
71
65
 
72
- If the specialist is still working, `ask` returns `status: "running"`
73
- with the session ID, and you can do other work before calling `check`.
66
+ If the specialist is still working, `ask` returns `status: "running"`, and
67
+ `check` waits for the answer.
74
68
 
75
69
  ```ts
76
70
  await ctx.host.mcp.callTool("weather", "check", {
@@ -79,14 +73,12 @@ await ctx.host.mcp.callTool("weather", "check", {
79
73
  });
80
74
  ```
81
75
 
82
- The peer owns this session, so follow-ups continue the specialist's
83
- context.
84
-
85
- ## Call a deterministic peer tool
76
+ ## Call a peer tool directly
86
77
 
87
- You need a forecast for Paris, and the weather agent already has
88
- `get_forecast`. Host code calls that tool in the specialist's workspace
89
- and the forecast comes back to the concierge, with no second model turn.
78
+ Use `call_tool` when you want to run a tool on a peer agent directly, without
79
+ starting a model turn on that agent. The peer needs at least one server tool,
80
+ and the call follows the
81
+ [direct-call rules](../reference/tools.md#call-a-tool-without-a-model-turn).
90
82
 
91
83
  ```ts
92
84
  const result = await ctx.host.mcp.callTool("weather", "call_tool", {
@@ -108,12 +100,9 @@ return {
108
100
  };
109
101
  ```
110
102
 
111
- `call_tool` appears only when the peer declares at least one
112
- deterministic server tool.
113
-
114
103
  ## Try it locally
115
104
 
116
- Run both projects under one process to try the same connection locally:
105
+ To try it locally, run both projects in one process:
117
106
 
118
107
  ```bash
119
108
  agent-sdk dev ./agents
@@ -121,14 +110,12 @@ agent-sdk chat --url http://127.0.0.1:3000/concierge \
121
110
  --message "What's the weather in Paris right now?"
122
111
  ```
123
112
 
124
- In a local multi-agent serve, `agent` is the specialist's mount slug,
125
- normally its directory name.
113
+ Locally, `agent` is the specialist's mount slug, usually its directory name.
126
114
 
127
115
  ## Peer or subagent?
128
116
 
129
- Use a [subagent](../reference/subagents.md) to split one agent's job
130
- into roles that share its project. Use a peer when the specialist is a
131
- complete agent you would also run, inspect, or expose on its own.
117
+ Use a [subagent](../reference/subagents.md) to split one agent's job into roles.
118
+ Use a peer when the specialist is a complete agent you also run on its own.
132
119
 
133
120
  | | Subagent | Peer |
134
121
  | --- | --- | --- |
@@ -136,32 +123,8 @@ complete agent you would also run, inspect, or expose on its own.
136
123
  | Tools and connections | Inherits the parent project | Owns its project surface |
137
124
  | Reachability | Parent only | Local co-hosted agents, or declared deployments on the same team |
138
125
 
139
- ## Affinity
140
-
141
- Peer sessions appear in the specialist's playground. Only the calling
142
- deployment can continue a hosted peer session.
143
-
144
- ## Practices
145
-
146
- - Give each caller a one-way routing rule, and don't configure reciprocal
147
- routes for the same request.
148
-
149
- - Prefer `ask` when the specialist should reason. Use `call_tool` when
150
- host code already knows which server tool to run.
151
-
152
126
  ## Other hosts
153
127
 
154
- For self-hosting, run peers under one `agent-sdk` process. If turns run on remote
155
- workers, protect the process with `--bearer-token` and set its external URL
156
- with `--public-url`. Hosts that run one agent per process can supply
157
- `--peers-url`; Cursor-managed hosting configures it automatically. See
158
- [Deployment](../deployment.md) for the secure hosting setup.
159
-
160
- ## Related
161
-
162
- - [MCP connections](../reference/connections.md#peer-mcp-connection):
163
- peer configuration and connection naming
164
- - [MCP endpoint](../reference/http-api.md#mcp-endpoint): exact `ask`,
165
- `check`, and `call_tool` schemas
166
- - [Subagents](../reference/subagents.md): specialists inside one agent
167
- - [Deployment](../deployment.md): secure shared-host setup
128
+ To self-host, run the peers under one `agent-sdk` process, and if turns run on
129
+ remote workers, protect it with `--bearer-token` and set `--public-url` as
130
+ [Deployment](../deployment.md) describes.