@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.
- package/dist/channels/slack/cli-project.js +1 -1
- package/dist/docs/404.html +2 -2
- package/dist/docs/assets/{app.DMrZKFjI.js → app.BzTUBOAD.js} +4 -4
- package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
- package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
- package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
- package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
- package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
- package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
- package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.DH8GOhiv.js} +1 -1
- package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
- package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.BXHpx1lE.js} +1 -1
- package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
- package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
- package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
- package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
- package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
- package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
- package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
- package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
- package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
- package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
- package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
- package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.DgJ4L-8V.js} +1 -1
- package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
- package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
- package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
- package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
- package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.DXXqX4MQ.js} +1 -1
- package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.5c61gNw4.js} +1 -1
- package/dist/docs/assets/chunks/{min.SPrSp704.js → min.B1-NAjHX.js} +1 -1
- package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
- package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
- package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
- package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
- package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
- package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
- package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
- package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DMj_7q3B.js} +2 -2
- package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
- package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
- package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
- package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
- package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
- package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
- package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
- package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
- package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
- package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
- package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
- package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
- package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
- package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
- package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
- package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
- package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
- package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
- package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
- package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
- package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
- package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
- package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
- package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
- package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
- package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
- package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
- package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
- package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
- package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
- package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
- package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
- package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
- package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
- package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
- package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
- package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
- package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
- package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
- package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
- package/dist/docs/assets/{index.md.CAruw_rp.lean.js → index.md.DRfaoRCZ.lean.js} +1 -1
- package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
- package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
- package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
- package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
- package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
- package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
- package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
- package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
- package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
- package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
- package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
- package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
- package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
- package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
- package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
- package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
- package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
- package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
- package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
- package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
- package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
- package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
- package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
- package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
- package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
- package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
- package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
- package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
- package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
- package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
- package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
- package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
- package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
- package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
- package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
- package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
- package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
- package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
- package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
- package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
- package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
- package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
- package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
- package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
- package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
- package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
- package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
- package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
- package/dist/docs/building-with-agents.html +41 -44
- package/dist/docs/building-with-agents.md +11 -104
- package/dist/docs/changelog.html +37 -37
- package/dist/docs/changelog.md +5 -155
- package/dist/docs/deployment.html +54 -54
- package/dist/docs/deployment.md +83 -262
- package/dist/docs/evals.html +52 -71
- package/dist/docs/evals.md +33 -129
- package/dist/docs/guides/agent-to-agent.html +43 -43
- package/dist/docs/guides/agent-to-agent.md +27 -64
- package/dist/docs/guides/bitbucket.html +62 -62
- package/dist/docs/guides/bitbucket.md +73 -134
- package/dist/docs/guides/cloud-agents.html +37 -37
- package/dist/docs/guides/cloud-agents.md +23 -53
- package/dist/docs/guides/convert-automation.html +39 -56
- package/dist/docs/guides/convert-automation.md +31 -115
- package/dist/docs/guides/github.html +46 -54
- package/dist/docs/guides/github.md +49 -131
- package/dist/docs/guides/gitlab.html +98 -108
- package/dist/docs/guides/gitlab.md +104 -184
- package/dist/docs/guides/improve.html +38 -43
- package/dist/docs/guides/improve.md +24 -90
- package/dist/docs/guides/jev.html +55 -95
- package/dist/docs/guides/jev.md +53 -160
- package/dist/docs/guides/mcp-oauth.html +38 -40
- package/dist/docs/guides/mcp-oauth.md +33 -67
- package/dist/docs/guides/migrate.html +38 -43
- package/dist/docs/guides/migrate.md +56 -130
- package/dist/docs/guides/opentelemetry.html +41 -43
- package/dist/docs/guides/opentelemetry.md +32 -27
- package/dist/docs/guides/pagerduty.html +50 -49
- package/dist/docs/guides/pagerduty.md +65 -199
- package/dist/docs/guides/slack.html +51 -57
- package/dist/docs/guides/slack.md +76 -204
- package/dist/docs/guides/webhooks.html +42 -42
- package/dist/docs/guides/webhooks.md +64 -146
- package/dist/docs/hashmap.json +1 -1
- package/dist/docs/hillclimbing.html +40 -42
- package/dist/docs/hillclimbing.md +40 -102
- package/dist/docs/index.html +55 -61
- package/dist/docs/index.md +49 -83
- package/dist/docs/llms-full.txt +2262 -5721
- package/dist/docs/llms.txt +9 -14
- package/dist/docs/quickstart.html +95 -152
- package/dist/docs/quickstart.md +91 -180
- package/dist/docs/reference/access.html +36 -36
- package/dist/docs/reference/access.md +7 -12
- package/dist/docs/reference/agent-config.html +43 -56
- package/dist/docs/reference/agent-config.md +91 -174
- package/dist/docs/reference/artifacts.html +38 -39
- package/dist/docs/reference/artifacts.md +38 -62
- package/dist/docs/reference/channels.html +38 -39
- package/dist/docs/reference/channels.md +102 -151
- package/dist/docs/reference/cli.html +68 -84
- package/dist/docs/reference/cli.md +232 -697
- package/dist/docs/reference/connections.html +45 -57
- package/dist/docs/reference/connections.md +83 -164
- package/dist/docs/reference/evals.html +47 -54
- package/dist/docs/reference/evals.md +75 -141
- package/dist/docs/reference/extensions.html +41 -43
- package/dist/docs/reference/extensions.md +37 -70
- package/dist/docs/reference/hooks.html +40 -52
- package/dist/docs/reference/hooks.md +62 -133
- package/dist/docs/reference/http-api.html +38 -42
- package/dist/docs/reference/http-api.md +66 -118
- package/dist/docs/reference/instructions.html +39 -39
- package/dist/docs/reference/instructions.md +19 -29
- package/dist/docs/reference/limits.html +38 -38
- package/dist/docs/reference/limits.md +9 -21
- package/dist/docs/reference/memory.html +37 -38
- package/dist/docs/reference/memory.md +38 -75
- package/dist/docs/reference/playground.html +36 -36
- package/dist/docs/reference/playground.md +14 -22
- package/dist/docs/reference/project-layout.html +49 -48
- package/dist/docs/reference/project-layout.md +38 -84
- package/dist/docs/reference/schedules.html +46 -48
- package/dist/docs/reference/schedules.md +59 -90
- package/dist/docs/reference/sessions.html +37 -37
- package/dist/docs/reference/sessions.md +66 -113
- package/dist/docs/reference/skills.html +39 -39
- package/dist/docs/reference/skills.md +11 -31
- package/dist/docs/reference/subagents.html +37 -37
- package/dist/docs/reference/subagents.md +17 -31
- package/dist/docs/reference/tools.html +47 -64
- package/dist/docs/reference/tools.md +48 -130
- package/dist/docs/templates/agentic-owners.html +38 -38
- package/dist/docs/templates/agentic-owners.md +50 -74
- package/dist/docs/templates/reviews.html +69 -0
- package/dist/docs/templates/reviews.md +71 -0
- package/dist/docs/troubleshooting.html +38 -36
- package/dist/docs/troubleshooting.md +48 -101
- package/dist/internal/cli-deploy.js +1 -1
- package/dist/internal/cli-docs.js +1 -1
- package/dist/internal/cli-images.js +1 -1
- package/dist/internal/cli-skills.js +1 -1
- package/dist/internal/cursor/credentials.js +1 -1
- package/dist/internal/deploy-manifest.d.ts +1 -0
- package/dist/internal/deploy-manifest.d.ts.map +1 -1
- package/dist/internal/deploy-manifest.js +0 -1
- package/dist/internal/discovery/agent-config.d.ts +2 -6
- package/dist/internal/discovery/agent-config.d.ts.map +1 -1
- package/dist/internal/discovery/agent-config.js +8 -25
- package/dist/internal/discovery/agent.d.ts.map +1 -1
- package/dist/internal/discovery/agent.js +2 -3
- package/dist/internal/discovery/project.d.ts.map +1 -1
- package/dist/internal/discovery/project.js +15 -0
- package/dist/internal/init-project.d.ts.map +1 -1
- package/dist/internal/init-project.js +7 -5
- package/dist/internal/reminder-runner.js +1 -1
- package/dist/internal/session-engine.js +1 -1
- package/dist/internal/shallow-clone.js +1 -1
- package/dist/playground/assets/index-D6mVn9og.js +62 -0
- package/dist/playground/assets/index-DlALM6gr.css +1 -0
- package/dist/playground/index.html +2 -2
- package/dist/types.d.ts +4 -17
- package/dist/types.d.ts.map +1 -1
- package/docs/README.md +49 -83
- package/docs/building-with-agents.md +11 -104
- package/docs/changelog.md +6 -156
- package/docs/deployment.md +83 -262
- package/docs/evals.md +34 -130
- package/docs/guides/agent-to-agent.md +27 -64
- package/docs/guides/bitbucket.md +73 -134
- package/docs/guides/cloud-agents.md +23 -53
- package/docs/guides/convert-automation.md +31 -115
- package/docs/guides/github.md +49 -131
- package/docs/guides/gitlab.md +104 -184
- package/docs/guides/improve.md +24 -90
- package/docs/guides/jev.md +53 -160
- package/docs/guides/mcp-oauth.md +33 -67
- package/docs/guides/migrate.md +56 -130
- package/docs/guides/opentelemetry.md +37 -27
- package/docs/guides/pagerduty.md +68 -200
- package/docs/guides/slack.md +76 -204
- package/docs/guides/webhooks.md +64 -146
- package/docs/hillclimbing.md +41 -103
- package/docs/quickstart.md +91 -180
- package/docs/reference/access.md +7 -12
- package/docs/reference/agent-config.md +91 -174
- package/docs/reference/artifacts.md +38 -62
- package/docs/reference/channels.md +102 -151
- package/docs/reference/cli.md +232 -697
- package/docs/reference/connections.md +83 -164
- package/docs/reference/evals.md +75 -141
- package/docs/reference/extensions.md +37 -70
- package/docs/reference/hooks.md +61 -132
- package/docs/reference/http-api.md +66 -118
- package/docs/reference/instructions.md +20 -30
- package/docs/reference/limits.md +10 -22
- package/docs/reference/memory.md +38 -75
- package/docs/reference/playground.md +14 -22
- package/docs/reference/project-layout.md +38 -84
- package/docs/reference/schedules.md +59 -90
- package/docs/reference/sessions.md +66 -113
- package/docs/reference/skills.md +12 -32
- package/docs/reference/subagents.md +17 -31
- package/docs/reference/tools.md +48 -130
- package/docs/templates/agentic-owners.md +50 -74
- package/docs/templates/reviews.md +76 -0
- package/docs/troubleshooting.md +48 -101
- package/package.json +2 -2
- package/skills/deploy/SKILL.md +1 -1
- package/skills/migrate-v2/SKILL.md +0 -1
- package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
- package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
- package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
- package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
- package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
- package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
- package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
- package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
- package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
- package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
- package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
- package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
- package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
- package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
- package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
- package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
- package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
- package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
- package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
- package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
- package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
- package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
- package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
- package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
- package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
- package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
- package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
- package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
- package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
- package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
- package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
- package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
- package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
- package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
- package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
- package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
- package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
- package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
- package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
- package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
- package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
- package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
- package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
- package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
- package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
- package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
- package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
- package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
- package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
- package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
- package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
- package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
- package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
- package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
- package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
- package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
- package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
- package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
- package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
- package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
- package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
- package/dist/docs/guides/hooks.html +0 -113
- package/dist/docs/guides/hooks.md +0 -116
- package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
- package/dist/docs/package/skills/evals/SKILL.md +0 -145
- package/dist/docs/package/skills/github/SKILL.md +0 -133
- package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
- package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
- package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
- package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
- package/dist/docs/reference/prompt.html +0 -68
- package/dist/docs/reference/prompt.md +0 -47
- package/dist/docs/templates/security-reviewer.html +0 -62
- package/dist/docs/templates/security-reviewer.md +0 -81
- package/dist/docs/templates/thermo-quality-review.html +0 -62
- package/dist/docs/templates/thermo-quality-review.md +0 -75
- package/dist/docs/templates/thermo-review.html +0 -62
- package/dist/docs/templates/thermo-review.md +0 -75
- package/dist/docs/templates/triage.html +0 -68
- package/dist/docs/templates/triage.md +0 -101
- package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
- package/dist/playground/assets/index-F8b5WvWi.css +0 -1
- package/docs/guides/hooks.md +0 -121
- package/docs/reference/prompt.md +0 -52
- package/docs/templates/security-reviewer.md +0 -86
- package/docs/templates/thermo-quality-review.md +0 -80
- package/docs/templates/thermo-review.md +0 -80
- package/docs/templates/triage.md +0 -106
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
import{_ as t,c as a,o as s,a3 as i}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Migrate an early-alpha project","description":"Move a hosted Agent SDK architecture v1 project to v2 through a reviewed pull request.","frontmatter":{"title":"Migrate an early-alpha project","description":"Move a hosted Agent SDK architecture v1 project to v2 through a reviewed pull request."},"headers":[],"relativePath":"guides/migrate.md","filePath":"guides/migrate.md"}'),o={name:"guides/migrate.md"};function n(r,e,l,d,h,c){return s(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="migrate-an-early-alpha-project-to-architecture-v2" tabindex="-1">Migrate an early-alpha project to architecture v2 <a class="header-anchor" href="#migrate-an-early-alpha-project-to-architecture-v2" aria-label="Permalink to "Migrate an early-alpha project to architecture v2""></a></h1><p>Use this guide only for Agent SDK projects deployed during the early alpha. Projects that never deployed on architecture v1 already use v2 and need no migration.</p><h2 id="check-whether-your-project-needs-migration" tabindex="-1">Check whether your project needs migration <a class="header-anchor" href="#check-whether-your-project-needs-migration" aria-label="Permalink to "Check whether your project needs migration""></a></h2><p>Migrate when at least one of these signals is present:</p><ul><li><p><code>package.json</code> depends on the legacy v1 package. Remove it, then install the package <code>agent-sdk init</code> writes:</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;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> uninstall</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span></span>
|
|
2
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @grok/agent-sdk@latest</span></span></code></pre></div></li><li><p>A script or CI job runs the legacy early-alpha CLI.</p></li><li><p><code>agent/agent.ts</code> sets <code>architecture: "v1"</code>.</p></li><li><p><code>agent-sdk deployment get <slug></code> does not print <code>architecture: v2</code>.</p></li></ul><p>Stop when none of these is true. An existing <code>agent/</code> project root can remain in place; Agent SDK still loads it even though current examples use <code>bot/</code>.</p><p><code>agent-sdk migrate</code> prints <code>Nothing to migrate.</code> and exits 0 only when <code>--dir</code> shows no migration work. The check looks for an <code>@cursor/july</code> dependency, <code>architecture: "v1"</code>, <code>bot/storage.ts</code> or <code>agent/storage.ts</code>, <code>runtime: "grokbot"</code>, a literal SCM credential, a <code>/v1</code> continuation selector, an anonymous reminder, and a <code>*_MCP_URL</code> peer connection. When any of those is present, or a project file cannot be read, the command starts the agent. It does not read the hosted deployment. Run <code>agent-sdk deployment get <slug></code> when you still need to see whether that copy is on v1.</p><h2 id="start-the-migration" tabindex="-1">Start the migration <a class="header-anchor" href="#start-the-migration" aria-label="Permalink to "Start the migration""></a></h2><p>Commit and push the source you want to migrate. <code>agent-sdk migrate</code> reads that pushed Git ref, starts a Cursor cloud agent with the bundled migration skill, and waits for the agent to open a pull request. It does not deploy the project.</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;"> login</span></span>
|
|
3
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> migrate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>Inside a checkout, the command infers the repository, current ref, and project path. Pass them when you need to target a different pushed source:</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;"> migrate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
4
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./bots/triage</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --repo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/acme/agents</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
6
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --ref</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> migrate-triage-v2</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --path</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bots/triage</span></span></code></pre></div><p>Use <code>--no-wait</code> to print the cloud agent URL and return while it works. Use <code>--json</code> for machine-readable status. The <a href="./../reference/cli.html#migrate">CLI reference</a> covers every flag, output, and exit status.</p><h2 id="use-the-coding-agent-skill-directly" tabindex="-1">Use the coding-agent skill directly <a class="header-anchor" href="#use-the-coding-agent-skill-directly" aria-label="Permalink to "Use the coding-agent skill directly""></a></h2><p>You can instead ask a coding agent working in the project checkout to follow the bundled <a href="./../../skills/migrate-v2/SKILL.html"><code>bdk-migrate-v2</code> skill</a>. The skill owns the code changes, capability checks, local verification, and deployment handoff.</p><blockquote><p>Follow the <code>bdk-migrate-v2</code> skill for this project. Open one pull request with the migration, but do not deploy it or change deployment secrets.</p></blockquote><p>If the project depends on a v1 capability without a supported v2 path, the skill tells the coding agent to stop and name the blocker instead of removing the behavior.</p><h2 id="review-the-pull-request" tabindex="-1">Review the pull request <a class="header-anchor" href="#review-the-pull-request" aria-label="Permalink to "Review the pull request""></a></h2><p>Before merging, confirm the pull request:</p><ul><li><p>Uses <code>@grok/agent-sdk</code> and <code>agent-sdk</code>, and removes the v1 architecture opt-in.</p></li><li><p>Moves durable state to <code>ctx.host.kv</code> or <code>ctx.host.files</code>, reads secrets inside the handler that needs them, and accounts for hosted HTTP routes returning <code>202</code>.</p></li><li><p>Names SCM channel secrets instead of reading them: every <code>githubChannel({ credentials })</code> field and the GitLab or Bitbucket <code>webhookSecret</code> is <code>{ secretName: "NAME" }</code>. <code>agent-sdk validate</code> reports each field still written as a literal or <code>() => process.env.NAME</code> getter, as a warning while <code>architecture: "v1"</code> is set and as an error once it is removed. The <a href="./github.html#other-hosts">GitHub guide</a> explains the named form.</p></li><li><p>Rewrites each peer call that took its URL from a secret or environment variable, such as <code>BUILDER_MCP_URL</code>, to <code>defineConnection({ agent: "<slug>" })</code> under <code>bot/mcp-connections/</code> (or <code>agent/mcp-connections/</code> when the project root is <code>agent/</code>). Confirm the slug before you merge. The pull request lists each secret the rewrite left unused, and it leaves a TODO where it could not determine the slug.</p></li><li><p>Calls out unsupported behavior and any follow-up needed for reminders, schedules, Slack, or MCP connections.</p></li><li><p>Reports the validation, type checks, tests, and credential-dependent checks it ran or handed off.</p></li></ul><p>The migration pull request should change source only. Deploy after it merges.</p><h2 id="choose-a-cutover" tabindex="-1">Choose a cutover <a class="header-anchor" href="#choose-a-cutover" aria-label="Permalink to "Choose a cutover""></a></h2><table tabindex="0"><thead><tr><th>Cutover</th><th>What happens</th><th>Choose it when</th></tr></thead><tbody><tr><td>Same slug</td><td>The v2 deployment copies the v1 secrets and replaces v1 after it starts. The cutover cannot be undone, and it deletes v1's hosted sessions, KV, files, and eval runs.</td><td>A service interruption and an empty v2 state are acceptable.</td></tr><tr><td>New slug</td><td>The v1 deployment keeps serving while you configure and test v2. Move senders to the new URL, then delete the old deployment.</td><td>You use Slack, webhooks, or hosted state, or want a staged cutover.</td></tr></tbody></table><p>Prefer a new slug for Slack, webhooks, or data in <code>ctx.host.kv</code>. Point the trial at a test repository so both deployments do not act on the same source-control events. If the CLI reports that same-slug replacement is unavailable, use a new slug.</p><h2 id="deploy-after-merge" tabindex="-1">Deploy after merge <a class="header-anchor" href="#deploy-after-merge" aria-label="Permalink to "Deploy after merge""></a></h2><p>Deploy from the merged, pushed ref. Reuse every <code>--cursor-events-repo</code> value from the v1 deployment, and move every <code>--allow-domain</code> value into <code>hosting.egressDomains</code>. <code>agent-sdk deploy</code> has no <code>--allow-domain</code> flag.</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;"> validate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
|
|
8
|
-
<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:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">existing-or-new-slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><p>When the folder contains more than one agent, deploy each agent folder alone. Run <code>agent-sdk deploy --dir <agent folder></code> one time for each agent. One <code>agent-sdk deploy</code> on the parent folder prints those commands and does not deploy. Do not use <code>agent-sdk deploy --all</code>. Repeat <code>agent-sdk slack create --env prod</code> for each agent folder. The Slack app slug is the folder name.</p><p>When the pull request calls another agent with <code>defineConnection({ agent: "<slug>" })</code>, deploy the caller and that peer on <code>@grok/agent-sdk</code> 0.2.18 or newer. Both deployments must belong to the same team, and the caller reaches the peer once the peer deployment is running. The connection file is already in the merged source, so unset each URL secret the pull request lists after both deploys:</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;"> secret</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> delete</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> NAME</span></span></code></pre></div><p><code>agent-sdk migrate</code> prints the steps that follow the first deploy: one deploy per agent folder, <code>agent-sdk slack create --env prod --dir <agent-folder></code> for each Slack agent, <code>agent-sdk secret delete</code> for peer URL secrets the pull request lists, and <code>agent-sdk secret list</code> / <code>agent-sdk secret set</code> when the slug is new. Slack setup redeploys the deployment by itself. <code>agent-sdk secret set</code> takes effect on the next request. Neither step needs another deploy.</p><p>After the deployment starts, follow that checklist for Slack, webhook callers, peer connections, and secrets, then verify a hosted turn. The <a href="./../deployment.html">deployment guide</a> covers the managed hosting workflow.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to "Related""></a></h2><ul><li><a href="./../reference/cli.html#migrate">CLI reference</a>: migration flags, output, and exit status</li><li><a href="./../../skills/migrate-v2/SKILL.html"><code>bdk-migrate-v2</code> skill</a>: the coding procedure and complete capability matrix</li><li><a href="./agent-to-agent.html">Peer agents</a>: how a deployed caller reaches another agent by slug</li><li><a href="./../deployment.html">Deployment</a>: deploy and verify the reviewed project</li></ul>`,34)])])}const k=t(o,[["render",n]]);export{g as __pageData,k as default};
|
|
@@ -1,28 +0,0 @@
|
|
|
1
|
-
import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"OpenTelemetry","description":"","frontmatter":{},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),d={name:"guides/opentelemetry.md"};function n(o,e,r,l,h,c){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="opentelemetry" tabindex="-1">OpenTelemetry <a class="header-anchor" href="#opentelemetry" aria-label="Permalink to "OpenTelemetry""></a></h1><p>Agent SDK sends traces, metrics, and logs to an OTLP collector when <code>OTEL_*</code> is set. Record with <code>@opentelemetry/api</code>, and there is no <code>defineOtel</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:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">https://otel.example.com</span></span>
|
|
2
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_EXPORTER_OTLP_HEADERS</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Authorization=Bearer%20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$OTEL_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span></span>
|
|
3
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> OTEL_SERVICE_NAME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">incident-agent</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;"> serve</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;"> --dev</span></span></code></pre></div><p><code>http/protobuf</code> is the default, <code>http/json</code> works, <code>grpc</code> warns and falls back to <code>http/protobuf</code>, metrics use delta temporality, and Grafana Cloud rejects delta, so set <code>OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative</code> for Grafana Cloud or Prometheus. Providers load before <code>bot/agent.ts</code>, so a module-scope meter, tracer, or logger binds to them, and with no endpoint there are no exporters, <code>fetch</code> has no <code>traceparent</code>, and the session collector stays off.</p><h2 id="variables" tabindex="-1">Variables <a class="header-anchor" href="#variables" aria-label="Permalink to "Variables""></a></h2><table tabindex="0"><thead><tr><th>Variable</th><th>Effect</th></tr></thead><tbody><tr><td><code>OTEL_EXPORTER_OTLP_ENDPOINT</code></td><td>Base URL. Appends <code>/v1/traces</code>, <code>/v1/metrics</code>, <code>/v1/logs</code>.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_TRACES_ENDPOINT</code></td><td>Traces URL, used as written. Overrides the base URL.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_METRICS_ENDPOINT</code></td><td>Metrics URL, used as written. Overrides the base URL.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_LOGS_ENDPOINT</code></td><td>Logs URL, used as written. Overrides the base URL.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_HEADERS</code></td><td>Sent on every export. URL-encode values. Reread on each export.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_PROTOCOL</code></td><td><code>http/protobuf</code> (default) or <code>http/json</code>.</td></tr><tr><td><code>OTEL_SERVICE_NAME</code></td><td><code>service.name</code>. Defaults to the agent name, then <code>unknown_service:node</code>.</td></tr><tr><td><code>OTEL_RESOURCE_ATTRIBUTES</code></td><td><code>service.namespace</code>, <code>service.version</code>, <code>deployment.environment.name</code>.</td></tr><tr><td><code>OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE</code></td><td><code>delta</code> (default), <code>cumulative</code>, or <code>lowmemory</code>.</td></tr><tr><td><code>OTEL_LOGS_EXPORTER</code></td><td><code>otlp</code> exports logs. Unset, <code>none</code>, and <code>console</code> do not.</td></tr><tr><td><code>OTEL_SDK_DISABLED</code></td><td><code>true</code> turns export off.</td></tr><tr><td><code>OTEL_TRACES_EXPORTER</code></td><td><code>none</code> turns traces off.</td></tr><tr><td><code>OTEL_METRICS_EXPORTER</code></td><td><code>none</code> turns metrics off.</td></tr><tr><td><code>OTEL_LOG_USER_PROMPTS</code></td><td><code>1</code> adds prompt text to log records.</td></tr><tr><td><code>OTEL_LOG_TOOL_CONTENT</code></td><td><code>1</code> adds tool payloads to log records.</td></tr></tbody></table><h2 id="hosted-agents" tabindex="-1">Hosted agents <a class="header-anchor" href="#hosted-agents" aria-label="Permalink to "Hosted agents""></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;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> hosting: {</span></span>
|
|
6
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> egressDomains: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"otlp-gateway-prod-us-east-0.grafana.net"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> secretNames: [</span></span>
|
|
8
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "OTEL_EXPORTER_OTLP_ENDPOINT"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
9
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "OTEL_EXPORTER_OTLP_HEADERS"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
10
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "OTEL_SERVICE_NAME"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
11
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
|
|
12
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
13
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>egressDomains</code> is a hostname with no scheme or path. Secrets arrive with the first request that has an endpoint, and that export uses those headers and <code>service.name</code>. A later <code>agent-sdk secret set</code> updates headers on the next export, including a rotated key. A URL, protocol, or signal-list change replaces the exporter. <code>service.name</code> is fixed on the first export that attaches, so redeploy to change it.</p><h2 id="what-you-can-record" tabindex="-1">What you can record <a class="header-anchor" href="#what-you-can-record" aria-label="Permalink to "What you can record""></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;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { metrics, trace } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@opentelemetry/api"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
14
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { logs } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@opentelemetry/api-logs"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { currentConversationId } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/otel"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
16
|
-
<span class="line"></span>
|
|
17
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> tracer</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> trace.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getTracer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"incident-agent"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
18
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> lookups</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> metrics.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getMeter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"incident-agent"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">).</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">createCounter</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"incident.lookups"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
19
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> logger</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> logs.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getLogger</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"incident-agent"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
20
|
-
<span class="line"></span>
|
|
21
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">lookups.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">add</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"cursor.conversation.id"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">currentConversationId</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() });</span></span></code></pre></div><p>Record after secrets load. A span or log that ends before exporters attach is still sent, up to 2048 of each, a metric recorded before the first collect is included, and HTTP, token, and tool spans carry <code>cursor.conversation.id</code>, while a span started during a turn or a tool call gets that attribute, a value you set is kept, the id is not propagated, and a metric gets it only when you set it.</p><h2 id="tag-a-turn" tabindex="-1">Tag a turn <a class="header-anchor" href="#tag-a-turn" aria-label="Permalink to "Tag a turn""></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:#24292E;--shiki-dark:#E1E4E8;">async </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ key }, ctx) {</span></span>
|
|
22
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.telemetry.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">setTraceAttributes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"work.item"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: key });</span></span>
|
|
23
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.telemetry.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">setMetricAttributes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"work.item"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: key });</span></span>
|
|
24
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.telemetry.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">setLogAttributes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"work.item"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: key });</span></span>
|
|
25
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> jira.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getIssue</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(key);</span></span>
|
|
26
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p><code>ctx.telemetry</code> writes the current turn's store. A span started in that turn, including a span Agent SDK starts, gets the trace keys. A log record Agent SDK emits gets the log keys. <code>cursor.token.usage</code> recorded for that turn gets the metric keys. The same store is still there for a later tool in the turn. With export on, a later turn of the session keeps it. With export off, the next turn does not.</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;"> { telemetry } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/telemetry"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
27
|
-
<span class="line"></span>
|
|
28
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">telemetry.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">setTraceAttributes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"work.item"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: ticket });</span></span></code></pre></div><p>The global methods read the active context. Outside a turn they do nothing. Tags stay in this process. They are not written on the <code>baggage</code> header.</p><div class="language-promql vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">promql</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>sum by (work_item) (cursor_token_usage_total)</span></span></code></pre></div><p>Grafana renames <code>.</code> to <code>_</code>, and each distinct metric value is its own series, including a new id on every turn. Keys match <code>[A-Za-z][A-Za-z0-9._-]*</code> and are at most 128 characters, values are 1 to 256 characters, a session holds 32 trace keys, 32 metric keys, and 32 log keys, a later call replaces a key, and a metric value must not be a secret, an email, or a raw user id.</p><p>Outbound calls send <code>traceparent</code> only. With export off, the tags last for that turn, a span in the turn sees them, the next turn does not, and nothing is exported.</p><p><code>ctx.host.otel</code> is deprecated, still runs this release, and logs one warning per process. <code>setAttributes</code> writes one map onto spans and token usage, and the calls above replace it.</p><p>Trace and log keys are accepted as written. A log record keeps a key Agent SDK already set. <code>setMetricAttributes</code> rejects <code>cursor.token.type</code>, <code>agent_sdk.channel</code>, <code>cursor.tool.name</code>, <code>cursor.tool.kind</code>, <code>cursor.tool.status</code>, <code>agent_sdk.turn_status</code>, <code>agent_sdk.subagent_name</code>, <code>agent_sdk.sdk_agent_id</code>, and <code>agent_sdk.sdk_agent_url</code>. The call throws and leaves the runtime value in place.</p><p>Prompt text and tool payloads stay off log records unless <code>OTEL_LOGS_EXPORTER=otlp</code> and <code>OTEL_LOG_USER_PROMPTS</code> or <code>OTEL_LOG_TOOL_CONTENT</code> is set.</p><h2 id="limits" tabindex="-1">Limits <a class="header-anchor" href="#limits" aria-label="Permalink to "Limits""></a></h2><p>Custom span processors, samplers, views, your own SDK, library auto-instrumentation, and a <code>register()</code> hook are not supported, and <code>OTEL_TRACES_SAMPLER</code> and <code>OTEL_METRIC_EXPORT_INTERVAL</code> are read when the provider is built, before hosted secrets load, so set them and restart, because a later value only logs a warning. If a module replaces a provider Agent SDK registered, the global API uses that provider and Agent SDK shuts down a provider it created only when it is not the registered one, and if a context manager is already registered, Agent SDK logs a warning and leaves it, so load Agent SDK first or the turn store does not stay on the active context.</p><h2 id="migrating-from-serve-otel" tabindex="-1">Migrating from serve({ otel }) <a class="header-anchor" href="#migrating-from-serve-otel" aria-label="Permalink to "Migrating from serve({ otel })""></a></h2><p><code>serve({ otel })</code> is removed, so delete that option, <code>bot/otel.ts</code>, <code>agent/otel.ts</code>, and <code>bot/instrumentation.ts</code>, and do not call <code>defineOtel</code>. Each signal has one URL, and a second exporter for the same signal has no variable.</p><table tabindex="0"><thead><tr><th>Old option</th><th>Set this instead</th></tr></thead><tbody><tr><td><code>serviceName</code></td><td><code>OTEL_SERVICE_NAME</code></td></tr><tr><td><code>serviceVersion</code></td><td><code>service.version</code> in <code>OTEL_RESOURCE_ATTRIBUTES</code></td></tr><tr><td><code>resourceAttributes</code></td><td><code>OTEL_RESOURCE_ATTRIBUTES</code>, comma-separated, URL-encoded values</td></tr><tr><td><code>exporters[].url</code></td><td><code>OTEL_EXPORTER_OTLP_ENDPOINT</code> (appends <code>/v1/traces</code>, <code>/v1/metrics</code>, <code>/v1/logs</code>)</td></tr><tr><td><code>exporters[].url</code> with <code>signals</code></td><td><code>OTEL_EXPORTER_OTLP_TRACES_ENDPOINT</code>, <code>OTEL_EXPORTER_OTLP_METRICS_ENDPOINT</code>, or <code>OTEL_EXPORTER_OTLP_LOGS_ENDPOINT</code>, used as written</td></tr><tr><td><code>exporters[].headers</code></td><td><code>OTEL_EXPORTER_OTLP_HEADERS</code>, comma-separated, URL-encoded values</td></tr><tr><td><code>exporters[].protocol</code></td><td><code>OTEL_EXPORTER_OTLP_PROTOCOL</code>, or <code>OTEL_EXPORTER_OTLP_TRACES_PROTOCOL</code>, <code>OTEL_EXPORTER_OTLP_METRICS_PROTOCOL</code>, <code>OTEL_EXPORTER_OTLP_LOGS_PROTOCOL</code></td></tr><tr><td><code>exporters[].signals</code></td><td>The per-signal URL. <code>OTEL_TRACES_EXPORTER=none</code>, <code>OTEL_METRICS_EXPORTER=none</code>, or <code>OTEL_LOGS_EXPORTER=none</code> stops that signal.</td></tr><tr><td><code>traces: false</code></td><td><code>OTEL_TRACES_EXPORTER=none</code></td></tr><tr><td><code>traces: true</code></td><td>Leave <code>OTEL_TRACES_EXPORTER</code> unset. Traces start when an endpoint is set.</td></tr><tr><td><code>traces.sampleRatio</code></td><td><code>OTEL_TRACES_SAMPLER=parentbased_traceidratio</code> and <code>OTEL_TRACES_SAMPLER_ARG</code>, before process start</td></tr><tr><td><code>metrics: false</code></td><td><code>OTEL_METRICS_EXPORTER=none</code></td></tr><tr><td><code>metrics: true</code></td><td>Leave <code>OTEL_METRICS_EXPORTER</code> unset. Metrics start when a metrics URL is set.</td></tr><tr><td><code>metrics.exportIntervalMillis</code></td><td><code>OTEL_METRIC_EXPORT_INTERVAL</code>, milliseconds, before process start</td></tr><tr><td><code>logs: false</code></td><td>Unset <code>OTEL_LOGS_EXPORTER</code>, or set <code>none</code></td></tr><tr><td><code>logs: true</code></td><td><code>OTEL_LOGS_EXPORTER=otlp</code></td></tr><tr><td><code>logs.userPrompts</code></td><td><code>OTEL_LOGS_EXPORTER=otlp</code> and <code>OTEL_LOG_USER_PROMPTS=1</code></td></tr><tr><td><code>logs.toolContent</code></td><td><code>OTEL_LOGS_EXPORTER=otlp</code> and <code>OTEL_LOG_TOOL_CONTENT=1</code></td></tr><tr><td><code>otel: false</code></td><td>No endpoint, or <code>OTEL_SDK_DISABLED=true</code></td></tr></tbody></table><p>Put those names in <code>hosting.secretNames</code> and the collector host in <code>hosting.egressDomains</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;"> secret</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-agent</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> OTEL_SERVICE_NAME</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> OTEL_EXPORTER_OTLP_ENDPOINT</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> OTEL_EXPORTER_OTLP_HEADERS</span></span></code></pre></div>`,30)])])}const k=s(d,[["render",n]]);export{E as __pageData,k as default};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"OpenTelemetry","description":"","frontmatter":{},"headers":[],"relativePath":"guides/opentelemetry.md","filePath":"guides/opentelemetry.md"}'),d={name:"guides/opentelemetry.md"};function n(o,e,r,l,h,c){return a(),t("div",null,[...e[0]||(e[0]=[i("",30)])])}const k=s(d,[["render",n]]);export{E as __pageData,k as default};
|
|
@@ -1,60 +0,0 @@
|
|
|
1
|
-
import{_ as e,c as i,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"PagerDuty","description":"Respond to PagerDuty incidents: investigate a page, follow it through acknowledgement and resolution, and ignore your own actions.","frontmatter":{"title":"PagerDuty","description":"Respond to PagerDuty incidents: investigate a page, follow it through acknowledgement and resolution, and ignore your own actions."},"headers":[],"relativePath":"guides/pagerduty.md","filePath":"guides/pagerduty.md"}'),n={name:"guides/pagerduty.md"};function h(l,s,d,p,r,o){return a(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="pagerduty-agents" tabindex="-1">PagerDuty agents <a class="header-anchor" href="#pagerduty-agents" aria-label="Permalink to "PagerDuty agents""></a></h1><p>A PagerDuty agent wakes when an incident triggers, investigates it, and writes what it found back to the incident. <code>pagerdutyChannel()</code> receives PagerDuty's v3 webhooks, verifies them, and keeps every later event for the same incident in one session, so the agent sees an acknowledgement, a note, or a responder's reply in the context of the investigation it already started. Every setting has a default read from a well-known secret, so the channel needs no configuration beyond its hooks; see <a href="#connect">Connect</a> for the variables.</p><h2 id="investigate-a-new-incident" tabindex="-1">Investigate a new incident <a class="header-anchor" href="#investigate-a-new-incident" aria-label="Permalink to "Investigate a new incident""></a></h2><p>When an incident triggers, the agent starts a turn with the incident's title, service, urgency, and link. It reads whatever the investigation needs, and with <code>deliverReplies: true</code> its reply is posted as a note on the incident, where the person on call already looks.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/channels/pagerduty.ts</span></span>
|
|
2
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defaultPagerDutyAuth, pagerdutyChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/channels/pagerduty"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
3
|
-
<span class="line"></span>
|
|
4
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> pagerdutyChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> deliverReplies: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
6
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> onIncident</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (event.eventType </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "incident.triggered"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
8
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
9
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
10
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
11
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // \`auth\` starts a model turn running as the event's PagerDuty actor.</span></span>
|
|
12
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultPagerDutyAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx),</span></span>
|
|
13
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Investigate PagerDuty incident #\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">event</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">incident</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">number</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">event</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">incident</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">title</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
14
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> context: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Service: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">event</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">incident</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">service</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">?.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">summary</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "unknown"}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
|
|
16
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
17
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Reply notes are off unless you set <code>deliverReplies: true</code>, so the channel writes nothing to PagerDuty on its own. An agent that writes to PagerDuty through its own path, such as a service that audits each write, leaves it off and posts only what it chooses, from <code>events</code> or <code>ctx.pagerduty</code>.</p><p>With <code>deliverReplies: true</code>, the channel posts each completed reply as a note on the session's incident, and a short note if a turn fails, using the <code>PAGERDUTY_TOKEN</code> secret. The note goes to the incident in the verified event's state, so the model never chooses which incident it writes to. Eval runs and agents without a token post nothing. Nothing is posted until the channel knows the agent's own PagerDuty user (see <a href="#ignore-your-own-actions">Ignore your own actions</a>), because each note comes back as a webhook event that only the echo skip keeps from starting another turn. Handlers you write in <code>events</code> replace the built-in ones.</p><p>Hooks also get <code>ctx.pagerduty</code>, a REST client with the channel's credentials, for reads and writes of their own:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onIncident</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
18
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> incident</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.pagerduty.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">getIncident</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(event.incident.id);</span></span>
|
|
19
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // …</span></span>
|
|
20
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>Hosted, the agent also declares PagerDuty's API host and the token:</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>
|
|
21
|
-
<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;"> "@grok/agent-sdk"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
22
|
-
<span class="line"></span>
|
|
23
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
24
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> architecture: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"v2"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
25
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> hosting: {</span></span>
|
|
26
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> egressDomains: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"api.pagerduty.com"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
27
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> secretNames: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"PAGERDUTY_TOKEN"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
28
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
29
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="follow-the-incident-in-one-session" tabindex="-1">Follow the incident in one session <a class="header-anchor" href="#follow-the-incident-in-one-session" aria-label="Permalink to "Follow the incident in one session""></a></h2><p>People act on an incident while the agent investigates: someone acknowledges it, adds a note, pulls in a responder, or resolves it. Return a dispatch for those events too, and each one arrives in the session that is already working on the incident, with the earlier findings in context.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onIncident</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
30
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> followUps</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"incident.acknowledged"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"incident.reassigned"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"incident.resolved"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">];</span></span>
|
|
31
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (event.eventType </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "incident.triggered"</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &&</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> !</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">followUps.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(event.eventType)) {</span></span>
|
|
32
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
33
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
34
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
35
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultPagerDutyAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx),</span></span>
|
|
36
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">event</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">eventType</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">} by \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ctx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">agent</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">?.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">summary</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "PagerDuty"}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
37
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
|
|
38
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span>
|
|
39
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onNote</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">note</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
40
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
41
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultPagerDutyAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx),</span></span>
|
|
42
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Note on the incident: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">note</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">content</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
43
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
|
|
44
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>Add these to the same <code>pagerdutyChannel()</code> declaration as the investigation handler.</p><h2 id="ignore-your-own-actions" tabindex="-1">Ignore your own actions <a class="header-anchor" href="#ignore-your-own-actions" aria-label="Permalink to "Ignore your own actions""></a></h2><p>PagerDuty sends the agent's own changes back as webhook events: the note it posted, or an acknowledgement or resolve made through its PagerDuty user. The channel acknowledges those events without running a hook or starting a turn. The same action by a person is still delivered.</p><p>The channel finds the agent's user in this order, on each delivery:</p><ol><li>The <code>selfUserIds</code> option, when you pass one. Nothing below is used.</li><li>The <code>PAGERDUTY_USER_ID</code> secret: one PagerDuty user id.</li><li>The user <code>PAGERDUTY_TOKEN</code> acts as, which PagerDuty reports at <code>GET /users/me</code>.</li></ol><p>When none of these names a user, echo skip is off. <code>agent-sdk deploy</code> warns while neither <code>PAGERDUTY_USER_ID</code> nor <code>PAGERDUTY_TOKEN</code> is set, and the agent logs a warning when its token names no single user.</p><p>Inference depends on the kind of token:</p><table tabindex="0"><thead><tr><th><code>PAGERDUTY_TOKEN</code></th><th>Inferred user</th></tr></thead><tbody><tr><td>User token REST API key</td><td>The key's own user</td></tr><tr><td>OAuth user token (Classic User OAuth or Scoped OAuth), written as <code>Bearer <token></code></td><td>The user who authorized the app</td></tr><tr><td>General access (account-level) REST API key</td><td>The user whose email is exactly <code>PAGERDUTY_FROM_EMAIL</code>, if set</td></tr><tr><td>Scoped OAuth app token (client credentials)</td><td>The user whose email is exactly <code>PAGERDUTY_FROM_EMAIL</code>, if set</td></tr></tbody></table><p>PagerDuty serves <a href="https://developer.pagerduty.com/api-reference/0b6f8b0c3e8d1-get-the-current-user" target="_blank" rel="noreferrer"><code>GET /users/me</code></a> only to a user-level API key or a token from an OAuth flow, not to an account-level key. An app token <a href="https://docs.pagerduty.com/developer/private-apps" target="_blank" rel="noreferrer">acts as the app</a>, not as a user. With either, the channel looks up <code>PAGERDUTY_FROM_EMAIL</code>, the <code>From</code> user the token writes as, through <code>GET /users?query=</code> and uses the one user whose email matches exactly. The inferred id is kept in the agent's memory for an hour per token, never in agent storage, and an unresolved answer is retried after five minutes. Hosted, the lookup needs <code>api.pagerduty.com</code> (or your <code>PAGERDUTY_API_BASE_URL</code> host) in <code>hosting.egressDomains</code>, the same entry write-backs need.</p><p>A read-only agent with no token sets the id directly:</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;"> secret</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> incident-responder</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> PAGERDUTY_USER_ID</span></span></code></pre></div><p><code>PAGERDUTY_USER_ID</code> holds one id because a deployment has one token and so acts as one PagerDuty user. To skip several users, or to keep the id in code, pass <code>selfUserIds</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;"> pagerdutyChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
45
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> selfUserIds: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"PBOT001"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
46
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> onIncident</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ({ auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultPagerDutyAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) }),</span></span>
|
|
47
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>selfUserIds: { secretName: "OTHER_NAME" }</code> reads one id from another secret and never falls back to inference.</p><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to "Events""></a></h2><p>Each hook receives one family of v3 events:</p><table tabindex="0"><thead><tr><th>Hook</th><th>Events</th></tr></thead><tbody><tr><td><code>onIncident</code></td><td><code>incident.triggered</code>, <code>.acknowledged</code>, <code>.unacknowledged</code>, <code>.escalated</code>, <code>.reassigned</code>, <code>.delegated</code>, <code>.resolved</code>, <code>.reopened</code>, <code>.priority_updated</code>, <code>.incident_type.changed</code></td></tr><tr><td><code>onNote</code></td><td><code>incident.annotated</code></td></tr><tr><td><code>onResponder</code></td><td><code>incident.responder.added</code>, <code>incident.responder.replied</code></td></tr><tr><td><code>onEvent</code></td><td>Everything else, such as status updates and workflow events</td></tr></tbody></table><p>Without <code>onIncident</code>, a triggered or reopened incident starts a turn and other lifecycle events are acknowledged. Notes, responder events, and the rest are acknowledged until you add their hook. Each hook returns one of three decisions:</p><table tabindex="0"><thead><tr><th>Return</th><th>What happens</th></tr></thead><tbody><tr><td><code>{ auth }</code></td><td>Start or continue a model turn as the event's actor</td></tr><tr><td><code>{ task }</code></td><td>Acknowledge the webhook, then run host code that may also call <code>send</code></td></tr><tr><td><code>null</code></td><td>Skip the event</td></tr></tbody></table><h2 id="incident-affinity" tabindex="-1">Incident affinity <a class="header-anchor" href="#incident-affinity" aria-label="Permalink to "Incident affinity""></a></h2><p>Every event for one incident joins one session, keyed on the incident id. Lifecycle events carry the incident, and notes and responder events name it by reference, so all of them reach the same session.</p><p>A re-trigger after a resolve is a new PagerDuty incident, so it starts a new session. <code>ctx.incidentKey</code> carries the dedup key of the alert that opened an incident (its <code>incident_key</code>, set per alert by a Datadog monitor, a Sentry issue, or a Grafana rule), for an agent that wants to recall what it found the last time the same alert fired.</p><h2 id="connect" tabindex="-1">Connect <a class="header-anchor" href="#connect" aria-label="Permalink to "Connect""></a></h2><p>Create a v3 webhook subscription in PagerDuty for the services that should wake the agent, and point it at <code>https://<your-host>/<slug>/v1/channels/pagerduty</code>. Then set the channel's secrets on the deployment. Locally the same names are environment variables.</p><table tabindex="0"><thead><tr><th>Variable</th><th>Used for</th><th>Override</th></tr></thead><tbody><tr><td><code>PAGERDUTY_WEBHOOK_SECRET</code></td><td>Verifying <code>X-PagerDuty-Signature</code>. Hosted, the platform checks it before any compute starts and answers a bad delivery with <code>401</code></td><td><code>webhookSecret: { secretName }</code></td></tr><tr><td><code>PAGERDUTY_USER_ID</code></td><td>Skipping the agent's own actions: its PagerDuty user id. Optional when <code>PAGERDUTY_TOKEN</code> names a user</td><td><code>selfUserIds: [ids]</code> or <code>{ secretName }</code></td></tr><tr><td><code>PAGERDUTY_TOKEN</code></td><td>Reply notes (with <code>deliverReplies: true</code>), <code>ctx.pagerduty</code>, and inferring the agent's user: a REST API key, or an OAuth token as <code>Bearer <token></code></td><td><code>token: { secretName }</code></td></tr><tr><td><code>PAGERDUTY_FROM_EMAIL</code></td><td>The <code>From</code> user PagerDuty requires for writes made with an account-level key or app token, and the user inferred for those tokens</td><td><code>from: { secretName }</code></td></tr><tr><td><code>PAGERDUTY_API_BASE_URL</code></td><td>The REST host, such as <code>https://api.eu.pagerduty.com</code>. Defaults to <code>https://api.pagerduty.com</code></td><td><code>apiBaseUrl</code></td></tr></tbody></table><p>Set <code>token</code>, <code>from</code>, and <code>apiBaseUrl</code> on <code>pagerdutyChannel()</code>; they cover reply notes, <code>ctx.pagerduty</code>, and inference. <code>createPagerDutyClient()</code> takes the same options for code outside the channel.</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;"> incident-responder</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;"> incident-responder</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> PAGERDUTY_WEBHOOK_SECRET</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> PAGERDUTY_TOKEN</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;"> list</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> incident-responder</span></span></code></pre></div><p><code>agent-sdk deploy</code> warns until <code>PAGERDUTY_WEBHOOK_SECRET</code> is set, and until either <code>PAGERDUTY_USER_ID</code> or <code>PAGERDUTY_TOKEN</code> is. The next delivery uses a new value without another deploy.</p><h3 id="several-subscriptions" tabindex="-1">Several subscriptions <a class="header-anchor" href="#several-subscriptions" aria-label="Permalink to "Several subscriptions""></a></h3><p>PagerDuty gives each webhook subscription its own signing secret, so an agent fed by several subscriptions (one per service, say) needs all of them. Put them in <code>PAGERDUTY_WEBHOOK_SECRET</code>, one per line:</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><signing secret of subscription 1></span></span>
|
|
50
|
-
<span class="line"><span><signing secret of subscription 2></span></span></code></pre></div><p>A delivery is admitted when any <code>v1=</code> signature in its <code>X-PagerDuty-Signature</code> header matches any line. Each line is trimmed, blank lines are ignored, and a value without a line break is one secret, used as-is. The value holds at most 32 secrets. Past that, every delivery is rejected rather than checked against only some of them.</p><p>Keep the list in a file, since <code>agent-sdk secret list</code> never shows values, and set it from stdin, which keeps the line breaks:</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;"> secret</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> set</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> incident-responder</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> PAGERDUTY_WEBHOOK_SECRET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pagerduty-webhook-secrets.txt</span></span></code></pre></div><p>Rotate by adding before removing. Add the new secret as a line before PagerDuty starts signing with it, for example before creating the replacement subscription. Remove the old line only once nothing signs with the old secret, for example after deleting the subscription it replaced. While both are live, a delivery signed with either secret verifies, including one whose header carries both signatures. Removing the old line first rejects those deliveries until the new one is added.</p><p>The same format works for every <code>hmacSignatureAuth()</code> secret, including <code>GITHUB_WEBHOOK_SECRET</code> and <code>BITBUCKET_WEBHOOK_SECRET</code>. It needs <code>@grok/agent-sdk</code> 0.2.25 or later. Earlier versions check the signature again in the agent with the whole value as one secret, so they reject every delivery once the value has a second line.</p><p>Only signature checks read the value as a list. Everywhere else it is used whole: a <code>sharedSecretAuth()</code> header compares the entire value, and a <code>\${NAME}</code> template in an MCP connection's <code>headers</code> would put the line breaks into the header. Keep a list secret for webhook signing only.</p><p>Until <code>PAGERDUTY_WEBHOOK_SECRET</code> is set, the route accepts only local traffic: loopback deliveries under <code>agent-sdk dev</code>, nothing in production.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to "Test locally""></a></h2><p><code>agent-sdk pagerduty replay</code> posts synthesized v3 deliveries for one incident to the running agent, in order. With <code>PAGERDUTY_WEBHOOK_SECRET</code> unset, <code>agent-sdk dev</code> admits them unsigned from loopback; with it set, replay signs them the way PagerDuty does:</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:#24292E;--shiki-dark:#E1E4E8;"> &</span></span>
|
|
51
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> pagerduty</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --events</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> triggered,acknowledged,annotated,resolved</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
52
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --comment</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "Rolled back the 09:30 deploy."</span></span></code></pre></div><p>The trigger comes from PagerDuty itself, and the later events come from a person, so each one joins the session the trigger started. Pass an incident id to start another session, <code>--dry-run</code> to print the bodies, or <code>--out fixtures/pagerduty</code> to save them as fixtures for <a href="./../evals.html">evals</a>. <code>agent-sdk pagerduty events</code> lists the channels and the events each accepts.</p><p>To post a real delivery saved from the webhook's delivery log, sign it with the secret:</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:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> PAGERDUTY_WEBHOOK_SECRET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">local-test-secret</span></span>
|
|
53
|
-
<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:#24292E;--shiki-dark:#E1E4E8;"> &</span></span>
|
|
54
|
-
<span class="line"></span>
|
|
55
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">fixtures/pagerduty/incident-triggered.json</span></span>
|
|
56
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">signature</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">openssl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dgst</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -sha256</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -hmac</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$PAGERDUTY_WEBHOOK_SECRET</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -hex</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> awk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '{print $NF}'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
57
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/v1/channels/pagerduty</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
58
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'content-type: application/json'</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
59
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "x-pagerduty-signature: v1=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$signature</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
60
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --data-binary</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span></span></code></pre></div><p>Set <code>event.agent.id</code> in a saved body to the agent's own user id to see the delivery skipped as an echo.</p><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to "Practices""></a></h2><ul><li><p>Write back from host code with the incident in channel state or <code>ctx</code>, never from an incident id the model produced.</p></li><li><p>Make sure the agent knows its own user before it acts on incidents, so its own notes and resolves do not wake it again: a user-level token, a <code>PAGERDUTY_FROM_EMAIL</code> with an account-level key, or <code>PAGERDUTY_USER_ID</code>.</p></li><li><p>Scope the webhook subscription to the services the agent responds to; every delivery it sends reaches the channel.</p></li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to "Related""></a></h2><ul><li><a href="./../reference/channels.html">Channels reference</a>: channel hooks, dispatch decisions, and session behavior</li><li><a href="./webhooks.html">Webhooks and custom channels</a>: direct webhook auth and reply delivery</li><li><a href="./../evals.html">Evals</a>: turn saved PagerDuty payloads into regression fixtures</li></ul>`,63)])])}const E=e(n,[["render",h]]);export{c as __pageData,E as default};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{_ as e,c as i,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"PagerDuty","description":"Respond to PagerDuty incidents: investigate a page, follow it through acknowledgement and resolution, and ignore your own actions.","frontmatter":{"title":"PagerDuty","description":"Respond to PagerDuty incidents: investigate a page, follow it through acknowledgement and resolution, and ignore your own actions."},"headers":[],"relativePath":"guides/pagerduty.md","filePath":"guides/pagerduty.md"}'),n={name:"guides/pagerduty.md"};function h(l,s,d,p,r,o){return a(),i("div",null,[...s[0]||(s[0]=[t("",63)])])}const E=e(n,[["render",h]]);export{c as __pageData,E as default};
|
|
@@ -1,88 +0,0 @@
|
|
|
1
|
-
import{_ as a,c as i,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread.","frontmatter":{"title":"Slack","description":"Wake your agent from mentions, DMs, and watched posts, then reply in the thread."},"headers":[],"relativePath":"guides/slack.md","filePath":"guides/slack.md"}'),n={name:"guides/slack.md"};function l(h,s,p,o,d,k){return e(),i("div",null,[...s[0]||(s[0]=[t(`<h1 id="slack-agents" tabindex="-1">Slack agents <a class="header-anchor" href="#slack-agents" aria-label="Permalink to "Slack agents""></a></h1><p>A Slack agent wakes when someone mentions it, sends it a DM, or posts in a channel it watches. From there, it keeps the conversation in one thread and can reply all at once, stream the answer live, or decide for itself when to post updates.</p><p>Run <code>agent-sdk slack create --dir .</code>, then <code>agent-sdk slack doctor</code>.</p><h2 id="answer-a-mention-or-dm" tabindex="-1">Answer a mention or DM <a class="header-anchor" href="#answer-a-mention-or-dm" aria-label="Permalink to "Answer a mention or DM""></a></h2><p>Mention the bot in a channel or send it a DM, and it will answer in a thread on that message. Any follow-up in the same thread continues the conversation where it left 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:#6A737D;--shiki-dark:#6A737D;">// bot/channels/slack.ts</span></span>
|
|
2
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { slackChannel } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/channels/slack"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
3
|
-
<span class="line"></span>
|
|
4
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // TRIAGE_SLACK_BOT_TOKEN and TRIAGE_SLACK_APP_TOKEN</span></span>
|
|
6
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> envPrefix: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"TRIAGE"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="post-one-reply-with-a-status-chip" tabindex="-1">Post one reply with a status chip <a class="header-anchor" href="#post-one-reply-with-a-status-chip" aria-label="Permalink to "Post one reply with a status chip""></a></h2><p>By default, Slack shows a status chip beneath the thread while the turn runs, cycling through idle messages until reasoning or tool activity gives it something more specific to show. When the turn finishes, the chip disappears and one complete reply lands in the thread.</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
8
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reply: {</span></span>
|
|
9
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"post"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
10
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> status: {</span></span>
|
|
11
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // First line of each reasoning block on the chip.</span></span>
|
|
12
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reasoning: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
13
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Tool names as they start ("Running grep, glob...").</span></span>
|
|
14
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tools: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> idle: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Checking the request..."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Reviewing recent activity..."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
16
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
17
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
18
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="stream-a-live-reply" tabindex="-1">Stream a live reply <a class="header-anchor" href="#stream-a-live-reply" aria-label="Permalink to "Stream a live reply""></a></h2><p>In stream mode, the reply appears immediately and grows as the model writes. Slack shows its generic "is working..." state until the stream ends, while optional reasoning and tool cards keep progress inside the same message.</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
19
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reply: {</span></span>
|
|
20
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"stream"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
21
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Thinking card inside the streamed message.</span></span>
|
|
22
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reasoningCard: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
23
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // One card per tool in that same message.</span></span>
|
|
24
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> toolCards: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><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><h2 id="let-the-agent-own-every-message" tabindex="-1">Let the agent own every message <a class="header-anchor" href="#let-the-agent-own-every-message" aria-label="Permalink to "Let the agent own every message""></a></h2><p>Use agentic mode when the agent should decide how to communicate, not only what to say. The bot reacts to the parent message with eyes and shows a thinking chip, then the agent chooses when to post progress and how to deliver the final reply.</p><p><code>slack-communication</code> gives those posts a Slack-aware voice by default: lead with the result, share progress when the picture changes, and keep tool chatter off the thread. Use <code>tone</code> for the rest of the communication contract, including voice, level of detail, formatting, and how updates should be structured.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/slack.ts</span></span>
|
|
27
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> slackCommunication </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/extensions/slack-communication"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
28
|
-
<span class="line"></span>
|
|
29
|
-
<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;"> slackCommunication</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
30
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tone:</span></span>
|
|
31
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "Be concise but warm. Use bullets for evidence and end with the next action."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
32
|
-
<span class="line"><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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
33
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // \`post-update\` writes mid-turn progress and the final reply.</span></span>
|
|
34
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reply: { mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"agentic"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
35
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h3 id="show-steps-as-cards-or-as-a-checklist" tabindex="-1">Show steps as cards or as a checklist <a class="header-anchor" href="#show-steps-as-cards-or-as-a-checklist" aria-label="Permalink to "Show steps as cards or as a checklist""></a></h3><p>The agent calls <code>post-card</code> to show one step of its work, such as "Scan the repo". Each card has an <code>id</code>, a <code>title</code>, a <code>status</code>, and optional <code>details</code>. When the agent calls <code>post-card</code> again with the same <code>id</code>, Slack updates that card. The agent uses this to move a step from <code>in_progress</code> to <code>complete</code>.</p><p><code>cards</code> sets how Slack draws these steps:</p><table tabindex="0"><thead><tr><th><code>cards</code></th><th>What Slack shows</th><th>Use it when</th></tr></thead><tbody><tr><td><code>{ display: "timeline" }</code> (default)</td><td>Each step is a separate card in the thread.</td><td>The turn has one or two short steps.</td></tr><tr><td><code>{ display: "plan" }</code></td><td>All steps from one turn are in one checklist.</td><td>The turn has several steps, and readers want to see progress in one place.</td></tr></tbody></table><p>This bot shows its steps as one checklist with the title "Release check":</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
36
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reply: {</span></span>
|
|
37
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> mode: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"agentic"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
38
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cards: { display: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"plan"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, title: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Release check"</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>
|
|
40
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Know these rules for a plan:</p><ul><li>The <code>title</code> is optional. It can have at most 256 characters.</li><li>You set the <code>title</code> in the channel configuration. The agent cannot change the title.</li><li>Each turn starts a new checklist with the same title.</li><li>The <code>pending</code> status shows a step that has not started. Use <code>pending</code> only in a plan.</li><li><code>slackChannel</code> stops at startup if <code>cards</code> is not valid. For example, a <code>title</code> with <code>display: "timeline"</code> stops startup.</li></ul><p><code>display</code> is Slack's <a href="https://docs.slack.dev/reference/methods/chat.startStream/" target="_blank" rel="noreferrer"><code>task_display_mode</code></a>, and the channel sends <code>title</code> as a <code>plan_update</code> chunk.</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 "Wake on a channel post""></a></h2><p>This example watches <code>#triage-alerts</code>, so any substantial top-level message starts a thread even when nobody mentions the bot. The length guard filters out short posts before they can start a turn.</p><p>Mentions work in any channel the bot has joined. Listening without a mention requires an explicit allowlist with at least one channel ID starting with <code>C</code> or <code>G</code> and at most 10 distinct IDs. You can add <code>#name</code> entries for readability. A lone <code>"*"</code> watches replies in every joined channel (<code>posts: "replies"</code>), but it does not wake on top-level posts. Do not mix <code>"*"</code> with channel IDs.</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
41
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> engagement: {</span></span>
|
|
42
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> channelPosts: {</span></span>
|
|
43
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> allow: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"C0123ABCDEF"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"#triage-alerts"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
44
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> posts: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"top-level"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
45
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> debounceMs: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">15_000</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>
|
|
48
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> onChannelPost</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
49
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (message.markdown.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">length</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <=</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
50
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
51
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
52
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // \`{}\` starts a model turn as the sender.</span></span>
|
|
53
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {};</span></span>
|
|
54
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
55
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>When you create the app, pass <code>--channel-posts</code> and invite the bot to every channel in the allowlist.</p><p>On Cursor-managed hosting, the channel IDs in <code>allow</code> define which top-level posts can wake the agent. Replies in threads the agent has already joined still arrive. <code>debounceMs</code> applies only when you self-host. Add the <code>channels:read</code> scope when you include <code>#name</code> labels.</p><h2 id="control-who-can-message" tabindex="-1">Control who can message <a class="header-anchor" href="#control-who-can-message" aria-label="Permalink to "Control who can message""></a></h2><p>By default, people outside your workspace get no reply. This matters most in Slack Connect channels, where external collaborators share the channel and can mention or reply to bots installed by your organization. Keeping <code>blockExternals</code> on prevents them from starting or steering an agent session and, through it, directing any tools available to the agent.</p><p>Set <code>blockExternals: false</code> only when external collaborators are intended users of the agent.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
56
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Let external collaborators start and continue agent sessions.</span></span>
|
|
57
|
-
<span class="line"><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>
|
|
58
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Anyone in a thread can continue its session by default. If the conversation should stay between the agent and its original author, set <code>respondTo: "author"</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
59
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> policy: { respondTo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"author"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
60
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to "Events""></a></h2><p>Mentions and DMs wake the agent automatically, while <code>onChannelPost</code> runs for messages in watched channels. Declare <code>onAppMention</code> or <code>onDirectMessage</code> when you need to filter those default wakes; each handler returns <code>{}</code> to start a turn or <code>null</code> to skip it.</p><p>For example, this handler only starts a turn for DMs prefixed with <code>triage:</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onDirectMessage</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
61
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">message.markdown.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">startsWith</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"triage:"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
|
|
62
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
63
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
64
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // \`{}\` starts a model turn as the sender.</span></span>
|
|
65
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {};</span></span>
|
|
66
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><h2 id="thread-affinity" tabindex="-1">Thread affinity <a class="header-anchor" href="#thread-affinity" aria-label="Permalink to "Thread affinity""></a></h2><p>Mention the bot in a channel and it answers in a thread on that message. Follow-ups in the same thread continue that session.</p><p>A direct message continues the one session for that DM, including replies under later top-level messages. To give each top-level DM its own session, and keep replies in that message's thread on it, set the continuation selector:</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;"> slackChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
67
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> continuation: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"slack.dmthread/v2"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
68
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Under <code>slack.dmthread/v2</code>, a DM thread behaves like a channel thread: a reply loads the thread's history, the turn edits only its own placeholder, and an approval click must come from that thread.</p><p>Channel threads keep one session per thread with either selector. <code>slack.none/v2</code> starts a new session on every delivery.</p><h2 id="call-slack-from-deterministic-code-via-ctx" tabindex="-1">Call Slack from deterministic code via <code>ctx</code> <a class="header-anchor" href="#call-slack-from-deterministic-code-via-ctx" aria-label="Permalink to "Call Slack from deterministic code via \`ctx\`""></a></h2><p>Channel hooks can post before starting the model turn, which is useful for deterministic acknowledgements such as <code>Looking at this now.</code> The same bot credential also lets tools call Slack later in the turn:</p><ul><li><p>Channel hooks: <code>ctx.thread.post()</code>, <code>ctx.slack.channelId</code>, <code>ctx.slack.threadTs</code></p></li><li><p>Tools: <code>ctx.host.slack.getClient()</code></p></li></ul><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onAppMention</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">message</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
69
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (message.markdown.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">trim</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ""</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
70
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
71
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
72
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ctx.thread.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">post</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Looking at this now."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
73
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {};</span></span>
|
|
74
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>Use the IDs on the hook <code>ctx</code> when handling an event, and <code>ctx.host.slack.getClient()</code> when a tool needs the Slack Web API.</p><h2 id="connect" tabindex="-1">Connect <a class="header-anchor" href="#connect" aria-label="Permalink to "Connect""></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
|
|
75
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span>
|
|
76
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TRIAGE</span></span></code></pre></div><p>After you sign in, <code>slack create</code> opens <strong>Add Slack to this agent</strong> in the browser and writes the resulting tokens to <code>.env.local</code> without printing them. You can open the same wizard from <strong>Integrations</strong> on <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a>.</p><p>If Slack requires workspace-admin approval, keep <code>slack create</code> running and open the <strong>Request approval</strong> link printed by the CLI. Installing from <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> doesn't send that request for you. After an admin approves it, return to the <strong>Add Slack</strong> wizard there and select <strong>Retry</strong>.</p><h3 id="choose-the-bot-scopes" tabindex="-1">Choose the bot scopes <a class="header-anchor" href="#choose-the-bot-scopes" aria-label="Permalink to "Choose the bot scopes""></a></h3><p>A Cursor-managed app requests these bot scopes by default:</p><p><code>app_mentions:read</code>, <code>assistant:write</code>, <code>channels:history</code>, <code>channels:read</code>, <code>chat:write</code>, <code>files:read</code>, <code>files:write</code>, <code>groups:history</code>, <code>groups:read</code>, <code>im:history</code>, <code>im:read</code>, <code>im:write</code>, <code>mpim:history</code>, <code>reactions:read</code>, <code>reactions:write</code>, <code>usergroups:read</code>, <code>users:read</code>, <code>users:read.email</code></p><p>To request a different list, set <code>botScopes</code> in <code>slack-manifest.json</code> at the root of the agent project. The app then requests exactly that list:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
|
77
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "botScopes"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
|
|
78
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "app_mentions:read"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
79
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "assistant:write"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
80
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "channels:history"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
81
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "chat:write"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
82
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "groups:history"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
83
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "im:history"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
84
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "reactions:read"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
85
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "pins:read"</span></span>
|
|
86
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ]</span></span>
|
|
87
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Then run <code>agent-sdk slack create</code> again (add <code>--env prod</code> for the production app). The CLI shows the list before it opens the browser. Slack updates the app and installs it again. If the workspace requires admin approval, the approval request lists every scope the app requests.</p><ul><li>The list must include the required scopes: <code>app_mentions:read</code>, <code>assistant:write</code>, <code>channels:history</code>, <code>chat:write</code>, <code>groups:history</code>, <code>im:history</code>, and <code>reactions:read</code>. The Slack channel needs them to receive mentions, DMs, channel posts, and reactions, and to reply.</li><li>If you remove a default scope, the features that use it stop working. For example, file uploads need <code>files:write</code>.</li><li>Use bot scopes only, at most 50. User scopes are not supported.</li><li>Cursor rejects scopes in the Slack Marketplace forbidden families: <code>admin.*</code>, <code>identity.*</code>, <code>search:read*</code>, <code>triggers:*</code>, <code>apps_configuration:*</code>, and <code>workflow.steps:execute</code>.</li><li>Without <code>botScopes</code>, the app requests the default list plus any other scopes it already has. To remove a scope you added, list the scopes you want and run <code>agent-sdk slack create</code> again.</li></ul><p>The person who runs <code>agent-sdk slack create</code> also grants Cursor three user scopes in their own Slack account: <code>app_configurations:read</code>, <code>app_configurations:write</code>, and <code>managed_apps:install</code>. Cursor uses them to create, update, and install the agent's app. They are not scopes of the agent's app, and <code>botScopes</code> does not change them.</p><p>If you already own the Slack app, initialize it with <code>agent-sdk slack init --manual --dir . --name "Triage"</code> and follow the <a href="./../../skills/setup-slack/SKILL.html">Slack setup skill</a> for installation and tokens.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to "Test locally""></a></h2><p>Run <code>doctor</code> first to catch missing credentials, then start the agent and send it the same mention or DM a teammate would.</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;"> slack</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> doctor</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prefix</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> TRIAGE</span></span>
|
|
88
|
-
<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;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dev</span></span></code></pre></div><h2 id="practices" tabindex="-1">Practices <a class="header-anchor" href="#practices" aria-label="Permalink to "Practices""></a></h2><ul><li><p>If the tokens are missing, the Slack channel stays idle while the rest of <code>serve</code> starts normally.</p></li><li><p>Keep <code>channelPosts.allow</code> narrow because each qualifying post can start a model turn.</p></li><li><p>Set <code>envPrefix</code> when two Slack bots share a host so the token names do not collide.</p></li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to "Related""></a></h2><ul><li><a href="./../reference/cli.html#slack">CLI reference</a>: <code>slack create</code>, <code>doctor</code>, <code>init --manual</code></li><li><a href="./../../skills/setup-slack/SKILL.html"><code>skills/setup-slack/SKILL.md</code></a>: the companion skill for coding agents</li><li><a href="./webhooks.html">Webhooks and custom channels</a>: host prep on mention and DM handlers</li><li><a href="./../evals.html">Evals</a>: freeze a mention as a regression check</li></ul>`,73)])])}const E=a(n,[["render",l]]);export{c as __pageData,E as default};
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
import{_ as a,c as t,o as i,a3 as n}from"./chunks/framework.BNw1pucY.js";const g=JSON.parse('{"title":"Hillclimbing","description":"Improve one agent behavior at a time by measuring fixed inputs, changing one lever, and locking each win with an eval.","frontmatter":{"title":"Hillclimbing","description":"Improve one agent behavior at a time by measuring fixed inputs, changing one lever, and locking each win with an eval."},"headers":[],"relativePath":"hillclimbing.md","filePath":"hillclimbing.md"}'),s={name:"hillclimbing.md"};function o(r,e,l,h,c,p){return i(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="hillclimbing" tabindex="-1">Hillclimbing <a class="header-anchor" href="#hillclimbing" aria-label="Permalink to "Hillclimbing""></a></h1><p>Hillclimbing improves an agent through controlled before-and-after comparisons. Keep the inputs fixed, name one failure, change one lever, and retain the change only when the same run gets better without crossing the freeze line.</p><p>The companion <a href="./../skills/hillclimb/SKILL.html"><code>hillclimb</code> skill</a> can run this loop with you.</p><h2 id="correct-a-wrong-tool-choice" tabindex="-1">Correct a wrong tool choice <a class="header-anchor" href="#correct-a-wrong-tool-choice" aria-label="Permalink to "Correct a wrong tool choice""></a></h2><p>Suppose a PR reviewer calls <code>approve_pr</code> before <code>inspect_pr</code>. Pin one PR fixture, record the original tool order, then tighten the instruction that owns the decision. The improved run should inspect first and leave approval untouched.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk run --dir . \\</span></span>
|
|
2
|
-
<span class="line"><span> --message "Is https://github.com/acme/checkout/pull/42 ready?"</span></span></code></pre></div><p>Lock the result with the intended and tempting-wrong paths:</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:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">succeeded</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
|
|
3
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"inspect_pr"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
4
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">notCalledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"approve_pr"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Do not change the tool implementation, prompt, and evidence together. If tool choice improves, you should know which edit caused it.</p><h2 id="reduce-wandering-or-latency" tabindex="-1">Reduce wandering or latency <a class="header-anchor" href="#reduce-wandering-or-latency" aria-label="Permalink to "Reduce wandering or latency""></a></h2><p>A slow run often repeats reads, searches broad directories, or asks the model to discover evidence the host already has. Compare the trajectory by tool name and wall time, then move deterministic preparation ahead of the turn or trim the evidence shape.</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>before: 14 tool calls, 92 seconds, 6 repeated reads</span></span>
|
|
5
|
-
<span class="line"><span>after: 5 tool calls, 31 seconds, 0 repeated reads</span></span></code></pre></div><p>Keep the change only if the answer still finds the same known issue. Efficiency without a quality check can make an agent fast by making it incomplete.</p><h2 id="improve-quality-without-changing-the-contract" tabindex="-1">Improve quality without changing the contract <a class="header-anchor" href="#improve-quality-without-changing-the-contract" aria-label="Permalink to "Improve quality without changing the contract""></a></h2><p>For answer quality, freeze the public shape before editing: required sections, API fields, side effects, and existing evals. Compare both runs against a known-good answer or a small set of gold findings, then change the instructions or skill that owns the missing judgment.</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>fixture: saved checkout PR diff</span></span>
|
|
6
|
-
<span class="line"><span>success: report both gold findings with file paths</span></span>
|
|
7
|
-
<span class="line"><span>freeze: findings JSON shape; no review post; existing smoke evals</span></span></code></pre></div><p>A wording change is not a win by itself. Keep it when correctness rises and every frozen behavior remains intact.</p><h2 id="run-one-measured-round" tabindex="-1">Run one measured round <a class="header-anchor" href="#run-one-measured-round" aria-label="Permalink to "Run one measured round""></a></h2><p>Agree on four inputs before editing:</p><ol><li><strong>Target:</strong> the agent path or slug.</li><li><strong>Fixtures:</strong> one to three prompts, saved payloads, or pinned PRs.</li><li><strong>Success:</strong> the metric or decision that should improve.</li><li><strong>Freeze line:</strong> behavior that must not move.</li></ol><p>Then run one loop:</p><ol><li>Exercise the agent through the same surface a user would.</li><li>Read the trajectory and name the dominant failure in one sentence.</li><li>Change one lever.</li><li>Rerun the same fixtures.</li><li>Compare correctness, efficiency, and contract fit.</li><li>Keep, revert, or narrow the change.</li></ol><p>Do not replace a fixture mid-round. A moving input makes the comparison meaningless.</p><h2 id="choose-the-smallest-lever" tabindex="-1">Choose the smallest lever <a class="header-anchor" href="#choose-the-smallest-lever" aria-label="Permalink to "Choose the smallest lever""></a></h2><p>Start with the earliest place that can remove the failure:</p><ol><li><strong>Host preparation:</strong> fetch deterministic evidence before the turn.</li><li><strong>Evidence shape:</strong> trim, order, or label what the model receives.</li><li><strong>Instructions or skills:</strong> clarify the decision procedure.</li><li><strong>Tool surface:</strong> remove or gate tools that invite wandering.</li><li><strong>Framework:</strong> change it only when the agent cannot express the fix.</li></ol><p>Changing the host or evidence often improves both quality and latency because the model spends less time searching for ground truth.</p><h2 id="lock-every-kept-win" tabindex="-1">Lock every kept win <a class="header-anchor" href="#lock-every-kept-win" aria-label="Permalink to "Lock every kept win""></a></h2><p>Each retained change needs an eval that would have failed before it. Use a tool-choice assertion, <code>maxToolCalls</code> bound, output-shape check, or quality score that captures the measured improvement.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk eval --dir . --tag smoke</span></span></code></pre></div><p>Never weaken an existing gate to make the round pass. The eval is the record that the improvement survived after the fixture and source change leave your working memory.</p><h2 id="run-the-loop-with-a-coding-agent" tabindex="-1">Run the loop with a coding agent <a class="header-anchor" href="#run-the-loop-with-a-coding-agent" aria-label="Permalink to "Run the loop with a coding agent""></a></h2><p>Ask the coding agent to read <a href="./../skills/hillclimb/SKILL.html"><code>skills/hillclimb/SKILL.md</code></a>, then give it the target, fixtures, success criterion, and freeze line. It will measure the current run, propose one change, remeasure, and ask before starting another round.</p><p>Use saved or local surfaces during a climb. Do not deploy or post to a real external channel unless that side effect is part of an explicitly approved fixture.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to "Related""></a></h2><ul><li><a href="./evals.html">Evals</a>: author the regression check for a kept win</li><li><a href="./reference/evals.html">Evals reference</a>: trajectory assertions and scores</li><li><a href="./building-with-agents.html">Building agents with agents</a>: delegate creation and verification to a coding agent</li><li><a href="./troubleshooting.html">Fix common agent problems</a>: diagnose a run that is broken instead of underperforming</li></ul>`,36)])])}const u=a(s,[["render",o]]);export{g as __pageData,u as default};
|