@grok/agent-sdk 0.2.29 → 0.4.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/channels/slack/slack-channel.d.ts.map +1 -1
- package/dist/channels/slack/slack-channel.js +27 -14
- package/dist/docs/404.html +2 -2
- package/dist/docs/assets/{app.DMrZKFjI.js → app.BSH__xV4.js} +4 -4
- package/dist/docs/assets/building-with-agents.md.Bo3ct-rf.js +6 -0
- package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.Bo3ct-rf.lean.js} +1 -1
- package/dist/docs/assets/changelog.md.b6H_ea44.js +1 -0
- package/dist/docs/assets/changelog.md.b6H_ea44.lean.js +1 -0
- package/dist/docs/assets/chunks/@localSearchIndexroot.CiRGcfZg.js +1 -0
- package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.Cadl7A0k.js} +1 -1
- package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.K7t9nNY6.js} +1 -1
- package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.SlHEknkX.js} +1 -1
- package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.DJLRMLkz.js} +1 -1
- package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.Bs6XxFpe.js} +1 -1
- package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.CyLg6Ovc.js} +1 -1
- package/dist/docs/assets/chunks/channel.CVTdqYx0.js +1 -0
- package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.DTQ4TinT.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.Es84IgcH.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.Clm3cGPQ.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DE4CRkS5.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.Bf8HCvqp.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.eub-7nSx.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.WyP9VAS_.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.LO9ohhDE.js} +1 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.CsJJyx6-.js +1 -0
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.CsJJyx6-.js +1 -0
- package/dist/docs/assets/chunks/clone.Dk8KvtOB.js +1 -0
- package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.D5za6aH0.js} +1 -1
- package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.Dq1daUru.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.j1YL5BKS.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.Bi1aLdhC.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.BOzMEkAr.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.Dx2FVhCr.js} +1 -1
- package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.DI4TNkye.js} +1 -1
- package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.C58Z9uPK.js} +1 -1
- package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.DXSpW809.js} +1 -1
- package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B955oaFl.js} +1 -1
- package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.BQXhKtxS.js} +1 -1
- package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.Dozj_-Gm.js} +1 -1
- package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D2140OzH.js} +1 -1
- package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.DrqrMhCk.js} +1 -1
- package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Dv-LTrlw.js} +1 -1
- package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.CGtHp49X.js} +1 -1
- package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.CHZLYB52.js} +1 -1
- package/dist/docs/assets/chunks/{min.SPrSp704.js → min.D4Vt3eIy.js} +1 -1
- package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BBfpYTea.js} +1 -1
- package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.BVYvElmY.js} +1 -1
- package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.C6Gc2mdY.js} +1 -1
- package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.DWa8b4cn.js} +1 -1
- package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.Bi-g4ajv.js} +1 -1
- package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.DlU3vVN9.js} +1 -1
- package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.CeqJRqnU.js} +1 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.DE0BnUZh.js +1 -0
- package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DGq7D4tt.js} +2 -2
- package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.Cqf2kjq9.js} +1 -1
- package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.BeOpE_lM.js} +1 -1
- package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.FMQXA-6q.js} +1 -1
- package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.BXS65dAC.js} +1 -1
- package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.haEiSxqc.js} +1 -1
- package/dist/docs/assets/deployment.md.DJtuDVLh.js +31 -0
- package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.DJtuDVLh.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.DcB3nhOz.js} +8 -8
- package/dist/docs/assets/guides_agent-to-agent.md.DcB3nhOz.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.CcuZ7keS.js} +11 -19
- package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.CcuZ7keS.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.GVPMKcYl.js} +3 -5
- package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.GVPMKcYl.lean.js} +1 -1
- package/dist/docs/assets/guides_migrate.md.B8CZxnnX.js +3 -0
- package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.B8CZxnnX.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.D7Rwyva4.js +82 -0
- package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.D7Rwyva4.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.M51bF-oT.js +5 -0
- package/dist/docs/assets/hillclimbing.md.M51bF-oT.lean.js +1 -0
- package/dist/docs/assets/index.md.DnJPj_B6.js +14 -0
- package/dist/docs/assets/index.md.DnJPj_B6.lean.js +1 -0
- 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.BSNp2uJ7.js +27 -0
- package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.BSNp2uJ7.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.DHm6DmYk.js +83 -0
- package/dist/docs/assets/reference_cli.md.DHm6DmYk.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.vbIM394-.js +39 -0
- package/dist/docs/assets/reference_hooks.md.vbIM394-.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.Dd8_d0WG.js +45 -0
- package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.Dd8_d0WG.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 +14 -145
- package/dist/docs/deployment.html +54 -54
- package/dist/docs/deployment.md +97 -270
- 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 +29 -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 +49 -61
- package/dist/docs/index.md +42 -82
- package/dist/docs/llms-full.txt +2272 -5711
- 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 +45 -58
- package/dist/docs/reference/agent-config.md +92 -176
- 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 +44 -46
- 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/filesystem.d.ts +7 -320
- package/dist/filesystem.d.ts.map +1 -1
- package/dist/filesystem.js +10 -691
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/internal/authored-alias-hooks.d.ts +6 -0
- package/dist/internal/authored-alias-hooks.d.ts.map +1 -1
- package/dist/internal/authored-alias-hooks.js +12 -0
- package/dist/internal/authored-loaders.js +10 -1
- package/dist/internal/cli/commands/scaffold.js +1 -1
- 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/continuation-session-ids.d.ts +15 -0
- package/dist/internal/continuation-session-ids.d.ts.map +1 -0
- package/dist/internal/continuation-session-ids.js +43 -0
- 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/filesystem/walk.d.ts +1 -5
- package/dist/internal/filesystem/walk.d.ts.map +1 -1
- package/dist/internal/filesystem/walk.js +1 -9
- package/dist/internal/hosted-catch-protocol.d.ts +3 -3
- package/dist/internal/hosted-catch-protocol.js +3 -3
- package/dist/internal/hosted-fetch.d.ts +7 -0
- package/dist/internal/hosted-fetch.d.ts.map +1 -0
- package/dist/internal/hosted-fetch.js +26 -0
- package/dist/internal/init-project.d.ts.map +1 -1
- package/dist/internal/init-project.js +7 -5
- package/dist/internal/install-cursor-skills.d.ts +5 -6
- package/dist/internal/install-cursor-skills.d.ts.map +1 -1
- package/dist/internal/install-cursor-skills.js +19 -4
- package/dist/internal/mcp-endpoint.js +4 -4
- package/dist/internal/model-config.d.ts.map +1 -1
- package/dist/internal/model-config.js +11 -4
- package/dist/internal/platform-timers.d.ts +3 -7
- package/dist/internal/platform-timers.d.ts.map +1 -1
- package/dist/internal/platform-timers.js +10 -51
- package/dist/internal/reminder-runner.js +1 -1
- package/dist/internal/server.d.ts.map +1 -1
- package/dist/internal/server.js +6 -1
- package/dist/internal/session-engine.d.ts +3 -0
- package/dist/internal/session-engine.d.ts.map +1 -1
- package/dist/internal/session-engine.js +13 -4
- package/dist/internal/shallow-clone.js +1 -1
- package/dist/playground/assets/index-Bno25Cg0.css +1 -0
- package/dist/playground/assets/index-SGKsaznh.js +62 -0
- package/dist/playground/index.html +2 -2
- package/dist/types.d.ts +6 -17
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +2 -2
- package/docs/README.md +42 -82
- package/docs/building-with-agents.md +11 -104
- package/docs/changelog.md +15 -146
- package/docs/deployment.md +97 -270
- package/docs/evals.md +34 -130
- package/docs/guides/agent-to-agent.md +29 -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 +92 -176
- 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 +4 -4
- package/skills/cli/SKILL.md +1 -1
- package/skills/create-agent/SKILL.md +61 -7
- package/skills/debug/SKILL.md +1 -1
- package/skills/deploy/SKILL.md +3 -3
- package/skills/evals/SKILL.md +1 -1
- package/skills/framework-map/SKILL.md +2 -2
- package/skills/github/SKILL.md +1 -1
- package/skills/hillclimb/SKILL.md +1 -1
- package/skills/mcp-auth/SKILL.md +1 -1
- package/skills/migrate-v2/SKILL.md +2 -3
- package/skills/otel/SKILL.md +1 -1
- package/skills/setup-slack/SKILL.md +2 -2
- 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/index.md.CAruw_rp.lean.js +0 -1
- 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/internal/filesystem/errors.d.ts +0 -64
- package/dist/internal/filesystem/errors.d.ts.map +0 -1
- package/dist/internal/filesystem/errors.js +0 -180
- package/dist/internal/filesystem/merge.d.ts +0 -34
- package/dist/internal/filesystem/merge.d.ts.map +0 -1
- package/dist/internal/filesystem/merge.js +0 -154
- 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 +0,0 @@
|
|
|
1
|
-
import{U as a,D as n}from"../app.DMrZKFjI.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK.5A3YmkhI.js";import{_ as i}from"../app.DMrZKFjI.js";import"./chunk-FMBD7UC4.DnC5NO4e.js";import"./chunk-YZCP3GAM._oboyZ1A.js";import"./chunk-55IACEB6.B4uf1yYV.js";import"./chunk-EDXVE4YY.CoXBce8t.js";import"./framework.BNw1pucY.js";import"./theme.DRciHmS1.js";var f={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{f as diagram};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK.5A3YmkhI.js";import{_ as i}from"../app.DMrZKFjI.js";import"./chunk-FMBD7UC4.DnC5NO4e.js";import"./chunk-YZCP3GAM._oboyZ1A.js";import"./chunk-55IACEB6.B4uf1yYV.js";import"./chunk-EDXVE4YY.CoXBce8t.js";import"./framework.BNw1pucY.js";import"./theme.DRciHmS1.js";var f={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{f as diagram};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{b as r}from"./graph.BS02KkWA.js";var e=4;function a(o){return r(o,e)}export{a as c};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{s as r,b as e,a,S as s}from"./chunk-OYMX7WX6.CzfHCeIi.js";import{_ as i}from"../app.DMrZKFjI.js";import"./chunk-55IACEB6.B4uf1yYV.js";import"./chunk-EDXVE4YY.CoXBce8t.js";import"./framework.BNw1pucY.js";import"./theme.DRciHmS1.js";var u={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{u as diagram};
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
import{_ as s,c as t,o as a,a3 as o}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Deployment","description":"Deploy an Agent SDK project from Git with Cursor-managed hosting, or run one secure process on your own infrastructure.","frontmatter":{"title":"Deployment","description":"Deploy an Agent SDK project from Git with Cursor-managed hosting, or run one secure process on your own infrastructure."},"headers":[],"relativePath":"deployment.md","filePath":"deployment.md"}'),n={name:"deployment.md"};function i(r,e,d,l,h,p){return a(),t("div",null,[...e[0]||(e[0]=[o(`<h1 id="deploy-an-agent-sdk-project" tabindex="-1">Deploy an Agent SDK project <a class="header-anchor" href="#deploy-an-agent-sdk-project" aria-label="Permalink to "Deploy an Agent SDK project""></a></h1><p>Deploying an Agent SDK project from a pushed Git ref creates a stable service. Cursor-managed hosting builds the selected ref and operates the runtime; self-hosting gives you control of the network, process, and filesystem.</p><h2 id="choose-managed-hosting-or-self-hosting" tabindex="-1">Choose managed hosting or self-hosting <a class="header-anchor" href="#choose-managed-hosting-or-self-hosting" aria-label="Permalink to "Choose managed hosting or self-hosting""></a></h2><table tabindex="0"><thead><tr><th>Option</th><th>Use it when</th><th>You manage</th></tr></thead><tbody><tr><td>Cursor-managed hosting</td><td>You want the shortest path from Git to a running agent</td><td>Source, declared egress, secrets, and agent behavior</td></tr><tr><td>Self-hosting</td><td>You need your own network, proxy, filesystem, or process controls</td><td>The Node process, TLS, auth, secrets, state, monitoring, and upgrades</td></tr></tbody></table><p>The rest of this guide starts with managed hosting. The <a href="#self-host-securely">self-host recipe</a> uses the same project and HTTP API.</p><h2 id="deploy-from-git" tabindex="-1">Deploy from Git <a class="header-anchor" href="#deploy-from-git" aria-label="Permalink to "Deploy from Git""></a></h2><p>Commit and push the exact ref you want to run, then sign in, validate, and deploy. The preferred CLI is <code>agent-sdk</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>cd my-agent</span></span>
|
|
2
|
-
<span class="line"><span>agent-sdk login</span></span>
|
|
3
|
-
<span class="line"><span>agent-sdk whoami</span></span>
|
|
4
|
-
<span class="line"><span>agent-sdk validate</span></span>
|
|
5
|
-
<span class="line"><span>agent-sdk deploy</span></span></code></pre></div><p>The deploy command waits until the runtime is running and prints the stable deployment URL. Open <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> to see the agent and manage it.</p><p><code>deploy</code> reads from Git; it does not upload your working tree. Inside a checkout, it infers the HTTPS origin, current ref, agent path, and slug. Pass them explicitly when the checkout is not the source you want:</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 deploy \\</span></span>
|
|
6
|
-
<span class="line"><span> --repo https://github.com/acme/agents \\</span></span>
|
|
7
|
-
<span class="line"><span> --ref main \\</span></span>
|
|
8
|
-
<span class="line"><span> --path agents/weather \\</span></span>
|
|
9
|
-
<span class="line"><span> --slug weather-agent</span></span></code></pre></div><p>The source repository must be available through the team's repository integration, and a nested <code>--path</code> must contain an installable Agent SDK project.</p><h3 id="connect-deployed-peers" tabindex="-1">Connect deployed peers <a class="header-anchor" href="#connect-deployed-peers" aria-label="Permalink to "Connect deployed peers""></a></h3><p>A team-owned deployment can call another agent deployed by the same team with <code>defineConnection({ agent: "weather-agent" })</code>. Deploy the specialist and the caller; Cursor-managed hosting resolves the slug and authenticates the call, so you don't configure a peer URL, header, or secret.</p><p>Redeploy the caller after adding or changing a peer connection. An agent last deployed before hosted peer connections became available also needs one redeploy. See <a href="./guides/agent-to-agent.html">Peer agents</a> for delegation, session affinity, and local development.</p><h3 id="privacy-mode" tabindex="-1">Privacy Mode <a class="header-anchor" href="#privacy-mode" aria-label="Permalink to "Privacy Mode""></a></h3><p>A hosted deployment stores a snapshot of its source repository, along with the sessions, KV, files, and logs the agent creates for your team. Whether managed hosting is available depends on the privacy setting that applies to you, which is your team's setting when the team enforces one:</p><table tabindex="0"><thead><tr><th>Privacy setting</th><th>Managed hosting</th></tr></thead><tbody><tr><td>Privacy Mode</td><td>Available. Cursor stores deployment data the same way it does without Privacy Mode, and the agent's model requests get the same Privacy Mode handling as your other Cursor requests.</td></tr><tr><td>Privacy Mode (Legacy)</td><td>Not available. <code>deploy</code>, a hosted session, and an eval run all refuse.</td></tr></tbody></table><p><code>deploy</code> refuses because a deployment stores a snapshot of your repository. A hosted session refuses, and Cursor does not store the message. An eval run refuses because it stores prompts and replies. Switch to Privacy Mode, or ask a team admin when your team enforces this setting.</p><p>The stored data includes the <a href="./reference/memory.html">memory</a> journal, which <code>agent-sdk init</code> turns on. The journal holds user messages and the agent's replies. With Privacy Mode, Cursor stores it only to run your agent and doesn't train on it.</p><h2 id="add-egress-and-secrets" tabindex="-1">Add egress and secrets <a class="header-anchor" href="#add-egress-and-secrets" aria-label="Permalink to "Add egress and secrets""></a></h2><p>Declare the external hosts and secret names the agent needs. Mounted extensions add the ones they declare, so list only what your own code calls; <code>agent-sdk info --dir .</code> shows the combined list and what each mount adds. Deploy the agent, then set each value at the hidden prompt. The next task uses the new value. You do not deploy again to apply that value.</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>
|
|
10
|
-
<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>
|
|
11
|
-
<span class="line"></span>
|
|
12
|
-
<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>
|
|
13
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> hosting: {</span></span>
|
|
14
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> egressDomains: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"api.weather.example.com"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> secretNames: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"WEATHER_API_KEY"</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></code></pre></div><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deploy --dir . --slug weather-agent</span></span>
|
|
18
|
-
<span class="line"><span>agent-sdk secret set weather-agent WEATHER_API_KEY</span></span>
|
|
19
|
-
<span class="line"><span>agent-sdk secret list weather-agent</span></span></code></pre></div><p>Commit secret names, never values. <code>secret set</code> accepts names and reads values without echoing them; <code>secret list</code> returns names and creation times only. Do not pass <code>NAME=VALUE</code>, print a secret to verify it, or put names beginning with reserved <code>CURSOR_</code> in <code>secretNames</code>.</p><p>A hosted deployment receives its secrets per request, after its modules are loaded, so code that reads <code>process.env</code> while a module is still loading sees nothing. Read a secret inside the handler, tool, or callback that needs it, and give an MCP connection its credential as a <code>\${NAME}</code> template, which resolves when the connection opens. See <a href="./reference/connections.html#credentials-in-headers-and-env">credentials in headers and env</a>.</p><p><code>agent-sdk deploy</code> runs the top-level code in your files one time to build the snapshot. No secrets exist at that time. The snapshot keeps those values.</p><p>SCM webhook channels go one step further and name their secrets in the channel definition, as <code>{ secretName: "GITHUB_WEBHOOK_SECRET" }</code>, so the platform can verify each delivery's signature before any compute starts. <code>validate</code> rejects a literal or getter there. The <a href="./guides/github.html#other-hosts">GitHub guide</a> shows the named form.</p><p>Enter egress hosts without schemes or paths. An HTTPS host needs no port; add one, as <code>clickhouse.example.com:9440</code>, only for a protocol the proxy reads no hostname from. The <a href="./guides/mcp-oauth.html">Host MCP OAuth guide</a> covers OAuth-backed MCP servers on a hosted agent.</p><p>Your team egress policy limits <code>hosting.egressDomains</code>. <code>agent-sdk deploy</code> fails when a requested host is outside that policy, and the bot that is already running keeps the policy from its last successful deploy. A bot that lists no egress hosts receives only the platform base. Architecture v2 stores that decision on the release, from the hosts the release itself declares. The server reads those hosts from the engine once the release is healthy. It does not use a host list sent by the CLI, the portal, or MCP. An older client that omits the optional field is marked the same way. A new release with no stored set for that team does not start. On a shared release each installing team has its own stored set. A release written before this change keeps its previous behavior.</p><p>A PlanetScale Postgres host (<code>*.pg.psdb.cloud</code>) has no port in the declaration. Under a restricted team mode it is a snapshot key for ports 5432 and 6432, using the team <code>CIDR:port</code> entries that cover every resolved address. An address outside those entries blocks the deploy. The snapshot does not pin the addresses from that lookup.</p><table tabindex="0"><thead><tr><th>Team egress mode</th><th>What <code>agent-sdk deploy</code> allows</th></tr></thead><tbody><tr><td>No mode set</td><td>Every host in <code>hosting.egressDomains</code>.</td></tr><tr><td>Allow all network access</td><td>Every host in <code>hosting.egressDomains</code>. The bot stays limited to that list.</td></tr><tr><td>Defaults + team allowlist</td><td>The platform default list, plus the team list.</td></tr><tr><td>Team allowlist only</td><td>The team list.</td></tr></tbody></table><p>The platform base is always allowed. A team list cannot remove it. The base is a small set of exact hosts and a few wildcards the pod needs to install and run: Cursor API hosts, npm and Yarn registries, Slack, Origin, and the artifact and Agent Store buckets. <code>agent-sdk deploy --json</code> includes those hosts on <code>egress.effective</code>, together with the hosts the team policy allowed. <code>agent-sdk deployment --json</code> includes <code>egressAllowedDomains</code>, the hosts from <code>hosting.egressDomains</code> that the last successful deploy allowed.</p><p>A team entry <code>*.example.com</code> allows <code>example.com</code>, any subdomain, and a narrower wildcard such as <code>*.api.example.com</code>. A bot entry <code>*.example.com</code> does not add <code>example.com</code>. List the apex on the bot when the bot calls it.</p><p>A raw TCP host such as <code>db.example.com:5432</code> is allowed only when the team list has a public IPv4 <code>CIDR:port</code> entry that contains every address that name resolves to, on the same port. Private addresses and IPv6 are refused. When deploy blocks hosts, the error names each host, the team mode, and two fixes: ask a team admin to add the hosts (admins get the settings link directly), or remove the hosts from <code>hosting.egressDomains</code> and deploy again.</p><h2 id="use-the-hosted-agent" tabindex="-1">Use the hosted agent <a class="header-anchor" href="#use-the-hosted-agent" aria-label="Permalink to "Use the hosted agent""></a></h2><h3 id="verify-a-hosted-turn" tabindex="-1">Verify a hosted turn <a class="header-anchor" href="#verify-a-hosted-turn" aria-label="Permalink to "Verify a hosted turn""></a></h3><p>After <code>deploy</code> reports <code>running</code>, message the deployment from the CLI:</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;"> session</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> create</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
20
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "Forecast for Paris"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --wait</span></span></code></pre></div><p>The deployment accepts the turn as a delivery and creates the session when the turn starts. <code>--wait</code> polls the delivery until it names the session, then prints the <code>sessionId</code>. Without <code>--wait</code>, the output has a <code>deliveryId</code> and <code>workflowId</code> but no <code>sessionId</code> yet. Add <code>--read-only</code> to check a deployment without side effects: read tools run and write tools are stubbed.</p><p>You can also find the session in the deployment's recent output, which prints a <code>==> ses_... (http) <==</code> header for each session, or open the deployment in <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> and select <strong>Sessions</strong>:</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;"> logs</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --once</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> weather-agent</span></span></code></pre></div><p>Then follow the turn:</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;"> session</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> get</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ses_...</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> weather-agent</span></span></code></pre></div><p>The command lists each hosted run with its status and log lines. When the deployment stored process output, a <code>Process output:</code> section prints that output. <code>agent-sdk logs --prod</code> prints the same process output that <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> shows for a persistent deployment, under <code>==> process-output <==</code>. Pass the session ID to also print that session's process output under <code>Session process output:</code> and a <code>tool <name></code> line for each tool call. While the turn is still working, the session command reports how many events have arrived and prints <code>Turn running; runs may lag behind events.</code> Rerun it until the latest run shows a final status such as <code>finished</code>. A high-effort turn can take several minutes, and its run can show no logs until it ends, so a growing event count is the progress signal.</p><p>To see which tools the bot called, print the hosted events:</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;"> session</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> get</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ses_...</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --prod</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> weather-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --view</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> events</span></span></code></pre></div><p>Each tool call is an <code>actions.requested</code> or <code>action.result</code> event. The tool name is <code>toolName</code>.</p><p>To continue the same conversation, pass <code>--session ses_...</code> to <code>session create</code>. <code>agent-sdk session get ses_... --prod --slug weather-agent --web</code> opens the session in the <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> playground. Hosted deployments don't support <code>agent-sdk chat</code>, <code>tool call</code>, <code>--view cost</code>, or <code>mcp</code>; use <code>session create</code>, <code>logs --prod</code>, <code>session list --prod</code>, and <code>session get --prod</code> instead.</p><h3 id="send-work-to-the-deployment" tabindex="-1">Send work to the deployment <a class="header-anchor" href="#send-work-to-the-deployment" aria-label="Permalink to "Send work to the deployment""></a></h3><p>A hosted agent wakes from its channels: Slack mentions and DMs, SCM events, and custom channel routes. External HTTP clients call a custom route on the stable alias URL and send the alias token on every request:</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;">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;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_ALIAS_URL</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/channels/tickets/ticket"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
21
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -H</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "X-Agent-Alias-Token: </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$AGENT_ALIAS_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
22
|
-
<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>
|
|
23
|
-
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '{"ticketId":"ENG-142","message":"CSV export returns 500"}'</span></span></code></pre></div><p>The deployment answers <code>202 Accepted</code> with an empty body as soon as the request arrives, then runs the route's handler, so the caller never receives a session ID or a result. Deliver results from the channel, as described in <a href="./reference/channels.html#route-responses">Route responses</a>.</p><p>To confirm the work started, find the new session with <code>agent-sdk logs --prod</code> and follow it with <code>agent-sdk session get --prod</code>, as in <a href="#verify-a-hosted-turn">Verify a hosted turn</a>.</p><h3 id="protect-the-alias-token" tabindex="-1">Protect the alias token <a class="header-anchor" href="#protect-the-alias-token" aria-label="Permalink to "Protect the alias token""></a></h3><p>The first deploy prints the alias token once. Store it outside terminal transcripts; it cannot be retrieved later. If it is lost or exposed, <code>agent-sdk deployment rotate-token weather-agent</code> replaces it and invalidates the old value.</p><p><code>deployment --json</code> can include short-lived access headers, so treat that output as a credential too.</p><p>For a custom webhook whose provider cannot send the alias token, use <code>publicEndpoint()</code> only when the channel verifies the provider signature. That opens the custom channel path, not the built-in session or tool APIs. See <a href="./guides/webhooks.html">Webhooks</a>.</p><h2 id="update-the-deployment" tabindex="-1">Update the deployment <a class="header-anchor" href="#update-the-deployment" aria-label="Permalink to "Update the deployment""></a></h2><p>Push the new ref and deploy the same slug. The stable URL remains while the new generation replaces the previous one.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deploy --dir . --slug weather-agent</span></span></code></pre></div><p>A redeploy replaces its source, its watched repositories, and any egress domains supplied through CLI flags. Pass every <code>--cursor-events-repo</code> value again; without the flag, the deployment watches its GitHub source repository. Keep source-controlled egress in the <code>hosting</code> block when possible.</p><p>Use <code>agent-sdk deployment get weather-agent</code> to inspect a rollout. The <a href="./reference/cli.html#deploy">CLI reference</a> owns <code>--no-wait</code>, multi-agent deployment, stop, and delete behavior.</p><h2 id="keep-state-across-replacements" tabindex="-1">Keep state across replacements <a class="header-anchor" href="#keep-state-across-replacements" aria-label="Permalink to "Keep state across replacements""></a></h2><p>Managed hosting persists framework-owned session, KV, and file state across normal runtime replacements. Files written elsewhere on the runtime's local filesystem are disposable; use <code>ctx.host.kv</code> or <code>ctx.host.files</code> for durable application state.</p><p>On architecture v2, the default, reminders take a prompt or a named handler. See <a href="./reference/schedules.html#reminders">Reminders</a>.</p><h2 id="self-host-securely" tabindex="-1">Self-host securely <a class="header-anchor" href="#self-host-securely" aria-label="Permalink to "Self-host securely""></a></h2><p>Run Agent SDK under Node 22.13 or newer, never Bun. One supervised process can serve every agent under a directory while a persistent state root keeps sessions across restarts.</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>export CURSOR_API_KEY="<cursor-api-key>"</span></span>
|
|
24
|
-
<span class="line"><span>export AGENT_SDK_BEARER_TOKEN="$(openssl rand -hex 32)"</span></span>
|
|
25
|
-
<span class="line"><span></span></span>
|
|
26
|
-
<span class="line"><span>agent-sdk serve \\</span></span>
|
|
27
|
-
<span class="line"><span> --dir /srv/agents \\</span></span>
|
|
28
|
-
<span class="line"><span> --host 127.0.0.1 \\</span></span>
|
|
29
|
-
<span class="line"><span> --port 3000 \\</span></span>
|
|
30
|
-
<span class="line"><span> --state-root /var/lib/agent-sdk \\</span></span>
|
|
31
|
-
<span class="line"><span> --bearer-token "$AGENT_SDK_BEARER_TOKEN"</span></span></code></pre></div><p>Before exposing the host:</p><ul><li><p>Put TLS or an authenticating proxy in front of the loopback server.</p></li><li><p>Keep <code>--bearer-token</code> on shared hosts. Use <code>--allow-anonymous</code> only behind a proxy that authenticates every caller.</p></li><li><p>Mount <code>--state-root</code> on a persistent volume outside the agent repository and back it up.</p></li><li><p>Inject credentials at startup instead of baking them into an image.</p></li><li><p>Run the process under a supervisor and enable schedules on exactly one serving process per project.</p></li></ul><p>Containers use the same command with <code>--host 0.0.0.0</code>, a mounted state volume, and an authenticating network boundary. The <a href="./reference/channels.html#auth-policies">Channels reference</a> covers per-caller and channel-specific auth.</p><h2 id="observability" tabindex="-1">Observability <a class="header-anchor" href="#observability" aria-label="Permalink to "Observability""></a></h2><p>Use <code>agent-sdk logs --prod</code> for a hosted session's process output, and <code>agent-sdk session get <sessionId> --prod</code> for its runs. Add <code>--view events</code> to print the tool calls. <a href="./guides/opentelemetry.html">OpenTelemetry</a> covers traces and metrics, and <a href="./reference/sessions.html#inspect-a-saved-event-stream">session traces</a> cover a local conversation.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to "Related""></a></h2><ul><li><a href="./guides/migrate.html">Early-alpha migration</a>: move a hosted architecture v1 project to v2 through a reviewed pull request</li><li><a href="./reference/cli.html#deploy">CLI reference</a>: inspect, update, stop, delete, and rotate deployments</li><li><a href="./guides/github.html">GitHub</a>: Cursor-event repositories and direct webhook delivery</li><li><a href="./guides/slack.html">Slack</a>: provision a dedicated hosted Slack app</li><li><a href="./guides/mcp-oauth.html">Host MCP OAuth</a>: reach OAuth-backed MCP servers from a hosted agent</li><li><a href="./troubleshooting.html">Troubleshooting</a>: diagnose failed or stale deployments</li></ul>`,76)])])}const g=s(n,[["render",i]]);export{u as __pageData,g as default};
|
|
@@ -1,68 +0,0 @@
|
|
|
1
|
-
import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Evals","description":"Protect agent decisions with fixed inputs, trajectory assertions, and regression checks that run locally or in CI.","frontmatter":{"title":"Evals","description":"Protect agent decisions with fixed inputs, trajectory assertions, and regression checks that run locally or in CI."},"headers":[],"relativePath":"evals.md","filePath":"evals.md"}'),t={name:"evals.md"};function l(h,s,p,k,r,o){return e(),a("div",null,[...s[0]||(s[0]=[n(`<h1 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to "Evals""></a></h1><p>An eval sends a fixed input to the real agent and checks the resulting trajectory: whether the turn succeeded, which tools ran, and what shape the answer took. Use evals to protect behavior you already understand, not to discover what the prompt should do.</p><p>Evals run real model turns and real tools. Guard external writes before running a suite against an agent that can post, merge, or deploy.</p><h2 id="protect-a-tool-decision" tabindex="-1">Protect a tool decision <a class="header-anchor" href="#protect-a-tool-decision" aria-label="Permalink to "Protect a tool decision""></a></h2><p>This smoke case asks for a PR verdict, requires the read-only inspection tool, and fails if the agent tries to approve. The CLI reports all three decisions together instead of stopping at the first miss.</p><p>Use the <a href="./guides/jev.html">Jev extension</a> when host code needs a typed choice, score, or boolean before it writes.</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;">// evals/readiness.eval.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;"> { defineEval, includes } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/evals"</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;"> defineEval</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tags: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"smoke"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
6
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
|
|
8
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "Is https://github.com/acme/checkout/pull/42 ready to approve?"</span></span>
|
|
9
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> );</span></span>
|
|
10
|
-
<span class="line"></span>
|
|
11
|
-
<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>
|
|
12
|
-
<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>
|
|
13
|
-
<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>
|
|
14
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(t.reply, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">ready</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">blocked</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">approve</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">i</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></code></pre></div><p>Evals live in the project-root <code>evals/</code> directory, beside <code>bot/</code>. Blank <code>agent-sdk init</code> writes <code>evals/smoke.eval.ts</code>, which uses the scaffolded <code>echo</code> tool and asserts <code>t.succeeded()</code> and <code>t.calledTool("echo")</code>. It also writes this concurrency config:</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;">// evals/evals.config.ts</span></span>
|
|
17
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineEvalConfig } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/evals"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
18
|
-
<span class="line"></span>
|
|
19
|
-
<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;"> defineEvalConfig</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
20
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> maxConcurrency: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">20</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
21
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk eval --dir . --list</span></span>
|
|
22
|
-
<span class="line"><span>agent-sdk eval --dir . --tag smoke</span></span></code></pre></div><h2 id="check-answer-shape-or-quality" tabindex="-1">Check answer shape or quality <a class="header-anchor" href="#check-answer-shape-or-quality" aria-label="Permalink to "Check answer shape or quality""></a></h2><p>Prefer a deterministic shape check when the output has a contract. The failure tells you which field was wrong, and the case remains stable when the model changes its wording.</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;"> { matches } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/evals"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
23
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "zod"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
24
|
-
<span class="line"></span>
|
|
25
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> verdict</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> JSON</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">parse</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(t.reply </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>
|
|
26
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
|
|
27
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> verdict,</span></span>
|
|
28
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> matches</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
|
|
29
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
30
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ready: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">boolean</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
|
|
31
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> blockers: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">array</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</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>
|
|
33
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> )</span></span>
|
|
34
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Use a judge when correctness depends on meaning that a schema, regex, or known value cannot capture:</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.judge</span></span>
|
|
35
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">factuality</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"The lint step failed on src/sidebar.ts."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
36
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> .</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">atLeast</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.8</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>Judge checks are tracked scores until you give them a hard gate. Configure the judge model in <code>evals.config.ts</code>. The <a href="./reference/evals.html#judges">Evals reference</a> owns grader options and severity rules.</p><h2 id="test-a-conversation" tabindex="-1">Test a conversation <a class="header-anchor" href="#test-a-conversation" aria-label="Permalink to "Test a conversation""></a></h2><p>Several <code>t.send</code> calls in one case share a session. Assertions on a returned turn inspect only that turn, while assertions on <code>t</code> inspect the whole conversation.</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;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> first</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;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Inspect PR 42."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
37
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">first.</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>
|
|
38
|
-
<span class="line"></span>
|
|
39
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> followUp</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;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Now summarize only the blockers."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
40
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">followUp.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">usedNoTools</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
|
|
41
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">check</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(followUp.message, </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/</span><span style="--shiki-light:#032F62;--shiki-dark:#DBEDFF;">blocker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">));</span></span>
|
|
42
|
-
<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></code></pre></div><h2 id="pin-realistic-inputs" tabindex="-1">Pin realistic inputs <a class="header-anchor" href="#pin-realistic-inputs" aria-label="Permalink to "Pin realistic inputs""></a></h2><p>A useful eval changes only when the agent changes. Freeze canonical chat prompts, seed workspace evidence directly, and save webhook payloads instead of depending on a developer's checkout or live external state.</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;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Review pr/diff.patch and report blockers."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
|
|
43
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> workspaceFiles: {</span></span>
|
|
44
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "pr/diff.patch"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
|
|
45
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "diff --git a/app/routes/search.ts b/app/routes/search.ts"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
46
|
-
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "+res.send(\`<h1>Results for \${req.query.q}</h1>\`);"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
47
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ].</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">join</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
|
|
48
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
49
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>For GitHub agents, snapshot a PR into committed fixtures:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk github replay acme/checkout#42 \\</span></span>
|
|
50
|
-
<span class="line"><span> --events '*' \\</span></span>
|
|
51
|
-
<span class="line"><span> --dry-run \\</span></span>
|
|
52
|
-
<span class="line"><span> --out fixtures/github</span></span></code></pre></div><p>Keep a small, fast <code>smoke</code> set for every change. Put larger datasets and drift-prone live cases behind an explicit selection. See <a href="./reference/evals.html#datasets-and-fixtures">Datasets and fixtures</a> for loaders and case expansion.</p><h2 id="run-and-debug-a-regression-suite" tabindex="-1">Run and debug a regression suite <a class="header-anchor" href="#run-and-debug-a-regression-suite" aria-label="Permalink to "Run and debug a regression suite""></a></h2><p>Run one case while iterating, then the smoke suite before review. A failure artifact records the input, assertions, tool calls, and final text, making it the first place to look before changing the prompt.</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 . readiness</span></span>
|
|
53
|
-
<span class="line"><span>agent-sdk eval --dir . --tag smoke</span></span>
|
|
54
|
-
<span class="line"><span>agent-sdk eval --dir . --json</span></span></code></pre></div><p>By default, results land under <code>evals/<stamp>/</code> in the project state directory. Open <code>evals/<case-id>.json</code> inside that run directory for the failed case. This artifact location is independent of <code>--state-root</code>; pass <code>--artifacts <dir></code> to choose another destination.</p><p>Model turns need a credential. Resolution checks <code>CURSOR_API_KEY</code>, <code>CURSOR_API_KEY_FILE</code>, <code>CURSOR_SERVICE_ACCOUNT_KEY</code>, then a saved <code>agent-sdk login</code>. <code>eval --list</code> only discovers cases and needs none.</p><h2 id="run-evals-in-ci" tabindex="-1">Run evals in CI <a class="header-anchor" href="#run-evals-in-ci" aria-label="Permalink to "Run evals in CI""></a></h2><p>Write machine-readable output and JUnit annotations, then let a failed gate fail the job:</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># CURSOR_API_KEY comes from the CI secret store.</span></span>
|
|
55
|
-
<span class="line"><span>agent-sdk eval --dir . --json --no-stream \\</span></span>
|
|
56
|
-
<span class="line"><span> --junit reports/evals.xml \\</span></span>
|
|
57
|
-
<span class="line"><span> --artifacts reports/evals \\</span></span>
|
|
58
|
-
<span class="line"><span> > reports/evals.json</span></span></code></pre></div><p>Run <code>--tag smoke</code> on pull requests and the full suite on a schedule when cost or latency makes every-push coverage impractical. Use soft scores for a new probabilistic benchmark until its threshold is trustworthy.</p><p>The <a href="./reference/cli.html#eval">CLI reference</a> covers selectors, server-side batches, exit codes, and JSON output.</p><h2 id="keep-side-effects-out-of-eval-sessions" tabindex="-1">Keep side effects out of eval sessions <a class="header-anchor" href="#keep-side-effects-out-of-eval-sessions" aria-label="Permalink to "Keep side effects out of eval sessions""></a></h2><p>Eval sessions carry <code>purpose: "eval"</code>. Check it at the deterministic write boundary and return the decision without performing the external action:</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;">async </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ findings }, ctx) {</span></span>
|
|
59
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "eval"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
60
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
61
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> posted: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
62
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reason: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"eval"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
63
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> count: findings.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">length</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
64
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
|
|
65
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
66
|
-
<span class="line"></span>
|
|
67
|
-
<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:#6F42C1;--shiki-dark:#B392F0;"> postFindings</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(findings);</span></span>
|
|
68
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>This preserves the tool call in the trajectory, so the eval can still assert that the agent chose to post.</p><h2 id="evals-hooks-or-hillclimbing" tabindex="-1">Evals, hooks, or hillclimbing? <a class="header-anchor" href="#evals-hooks-or-hillclimbing" aria-label="Permalink to "Evals, hooks, or hillclimbing?""></a></h2><p>Use an eval to gate one fixed input. Use a <a href="./reference/hooks.html">hook</a> to observe every live session for metrics, auditing, or alerts. Use <a href="./hillclimbing.html">hillclimbing</a> to decide which source change improves a fixed set of inputs; every kept hillclimb change should add an eval.</p><h2 id="gates-and-scores" tabindex="-1">Gates and scores <a class="header-anchor" href="#gates-and-scores" aria-label="Permalink to "Gates and scores""></a></h2><p><code>t.succeeded()</code>, tool assertions, and deterministic checks are hard gates by default. A failed gate fails the case. <code>.soft()</code> records a measurement without blocking, while <code>.atLeast(threshold)</code> records a score and marks a miss as <code>scored</code>.</p><p>Start with decisions and output shape: the intended tool, the tempting wrong tool, and one structural check. Exact prose is rarely a stable contract.</p><h2 id="keep-improvements-with-regression-evals" tabindex="-1">Keep improvements with regression evals <a class="header-anchor" href="#keep-improvements-with-regression-evals" aria-label="Permalink to "Keep improvements with regression evals""></a></h2><p>Every kept improvement needs an eval that would have failed before the change. A tool-choice gate, bounded <code>maxToolCalls</code>, or output-shape check turns the improvement into a durable contract.</p><p>Never weaken an existing gate to make a new implementation pass. That moves the freeze line instead of proving the change.</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/evals.html">Evals reference</a>: complete authoring and runner contracts</li><li><a href="./../skills/evals/SKILL.html"><code>skills/evals/SKILL.md</code></a>: author and seed cases with a coding agent</li><li><a href="./hillclimbing.html">Hillclimbing</a>: measure a change and lock the win</li><li><a href="./reference/sessions.html">Sessions</a>: events available to trajectory assertions</li></ul>`,49)])])}const E=i(t,[["render",l]]);export{c as __pageData,E as default};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Evals","description":"Protect agent decisions with fixed inputs, trajectory assertions, and regression checks that run locally or in CI.","frontmatter":{"title":"Evals","description":"Protect agent decisions with fixed inputs, trajectory assertions, and regression checks that run locally or in CI."},"headers":[],"relativePath":"evals.md","filePath":"evals.md"}'),t={name:"evals.md"};function l(h,s,p,k,r,o){return e(),a("div",null,[...s[0]||(s[0]=[n("",49)])])}const E=i(t,[["render",l]]);export{c as __pageData,E as default};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{_ as i,c as a,o as t,a3 as e}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Peer agents","description":"Let one Agent SDK agent consult an independent specialist, continue its session, or call its deterministic tools.","frontmatter":{"title":"Peer agents","description":"Let one Agent SDK agent consult an independent specialist, continue its session, or call its deterministic tools."},"headers":[],"relativePath":"guides/agent-to-agent.md","filePath":"guides/agent-to-agent.md"}'),n={name:"guides/agent-to-agent.md"};function h(l,s,p,k,r,o){return t(),a("div",null,[...s[0]||(s[0]=[e("",35)])])}const E=i(n,[["render",h]]);export{c as __pageData,E as default};
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
import{_ as t,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const p=JSON.parse('{"title":"Cursor cloud agents","description":"Let an Agent SDK agent hand coding work to Cursor cloud agents and steer them: mount the extension and pick the repositories it may touch.","frontmatter":{"title":"Cursor cloud agents","description":"Let an Agent SDK agent hand coding work to Cursor cloud agents and steer them: mount the extension and pick the repositories it may touch."},"headers":[],"relativePath":"guides/cloud-agents.md","filePath":"guides/cloud-agents.md"}'),i={name:"guides/cloud-agents.md"};function o(r,e,h,d,l,c){return s(),a("div",null,[...e[0]||(e[0]=[n(`<h1 id="cloud-agents" tabindex="-1">Cloud agents <a class="header-anchor" href="#cloud-agents" aria-label="Permalink to "Cloud agents""></a></h1><p>The <code>cursor-cloud-agents</code> extension adds repository delegation to an existing Agent SDK conversation. Cloud agents work on repository checkouts and push branches and pull requests; your agent can hand off a task, keep talking while it runs, inspect the result, and steer or stop the same branch.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to "Mount it""></a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/cloud.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;"> cursorCloudAgents </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/extensions/cursor-cloud-agents"</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;"> cursorCloudAgents</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cloud: {</span></span>
|
|
6
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> repos: [{ url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"https://github.com/acme/api"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, startingRef: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"main"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }],</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> autoCreatePR: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
8
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
9
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Launches run under the host's signed-in account (<code>agent-sdk login</code>, <code>CURSOR_API_KEY</code>, or <code>CURSOR_SERVICE_ACCOUNT_KEY</code>) and spend its cloud-agent budget. Name the repositories the agent may target in <code>cloud.repos</code>.</p><h2 id="what-the-agent-can-do" tabindex="-1">What the agent can do <a class="header-anchor" href="#what-the-agent-can-do" aria-label="Permalink to "What the agent can do""></a></h2><p>With the extension mounted, the agent can hand off coding work and stay in the conversation while it happens:</p><ul><li><strong>Hand off a task.</strong> Launch a cloud agent on one of your repositories, or on a pull request, with a self-contained brief. It gets back an agent id and a URL to share.</li><li><strong>Check on it.</strong> See whether the agent is still running, what it produced, and which branches or pull requests it pushed.</li><li><strong>Read what was done.</strong> Pull the agent's full conversation into the workspace, quote its final report, or trace the exact edits before summarizing for a person.</li><li><strong>Steer or stop.</strong> Send a follow-up to an agent it launched; it queues behind the current run, or interrupts it on request. Cancel a run that went sideways.</li><li><strong>Keep track.</strong> List the agents launched in this conversation, or everything it has launched before.</li></ul><p>A skill teaches the model when to delegate, how to write a brief a cloud agent can act on alone, and how to follow up. Everything the extension launches stays bound to whoever launched it: an agent started by another user, or outside the extension, is out of reach. That separation is only as fine as your host's auth; a shared bearer token or <code>--allow-anonymous</code> makes every caller one principal, so use <a href="./../reference/channels.html#auth-policies">authored auth</a> when callers need their own.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to "Configure it""></a></h2><table tabindex="0"><thead><tr><th>Option</th><th>What it controls</th></tr></thead><tbody><tr><td><code>cloud</code></td><td>Launch defaults for repositories, environment, and pull request behavior.</td></tr><tr><td><code>cloud.repos</code></td><td>The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can't name one, so secrets in <code>cloud.envVars</code> never reach a repository you didn't list.</td></tr><tr><td><code>cloud.teamMcpServers</code></td><td>The team MCP servers, by name, that launched agents may use (up to 50 names, matched case-insensitively; every team server with a listed name is kept). Every other team server is left out. Personal servers and <code>cloud.mcpServers</code> aren't filtered. Omit it to give agents every team server the launching account can use.</td></tr><tr><td><code>model</code></td><td>The model launched agents run. Omit it to use the account default.</td></tr><tr><td><code>apiKey</code></td><td>A Cursor API key to launch with instead of the host's own.</td></tr></tbody></table><h2 id="adjust-it" tabindex="-1">Adjust it <a class="header-anchor" href="#adjust-it" aria-label="Permalink to "Adjust it""></a></h2><p>To take a capability away, such as sending follow-ups, mount as a directory and disable that tool; see <a href="./../reference/extensions.html#adjust-a-mounted-extension">overlays</a>.</p><h2 id="what-s-next" tabindex="-1">What's next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to "What's next""></a></h2><p>Continue with these pages:</p><ul><li><a href="./../reference/extensions.html">Extensions</a>: how mounts, namespaces, and overrides work</li></ul>`,16)])])}const g=t(i,[["render",o]]);export{p as __pageData,g as default};
|
|
@@ -1,43 +0,0 @@
|
|
|
1
|
-
import{_ as a,c as i,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Convert a Cursor Automation","description":"Turn a dashboard Automation into an Agent SDK project, then reconnect its actions and triggers.","frontmatter":{"title":"Convert a Cursor Automation","description":"Turn a dashboard Automation into an Agent SDK project, then reconnect its actions and triggers."},"headers":[],"relativePath":"guides/convert-automation.md","filePath":"guides/convert-automation.md"}'),t={name:"guides/convert-automation.md"};function l(r,s,h,o,p,c){return e(),i("div",null,[...s[0]||(s[0]=[n(`<h1 id="convert-a-cursor-automation" tabindex="-1">Convert a Cursor Automation <a class="header-anchor" href="#convert-a-cursor-automation" aria-label="Permalink to "Convert a Cursor Automation""></a></h1><p>Convert a dashboard Automation when you want to edit its behavior as code, test it locally, or deploy it as an Agent SDK project. If you only need to change the prompt or trigger, the dashboard remains the shorter path.</p><p><code>init --from automation:…</code> carries over what it can prove from the exported configuration and prints a checklist for everything that still needs your judgment.</p><h2 id="convert-and-run-locally" tabindex="-1">Convert and run locally <a class="header-anchor" href="#convert-and-run-locally" aria-label="Permalink to "Convert and run locally""></a></h2><p>The command creates a project named after the Automation, installs its dependencies, and prints the generated files along with warnings and setup steps. Once <code>dev</code> starts, you can exercise the converted agent in the playground before reconnecting any live trigger.</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 login</span></span>
|
|
2
|
-
<span class="line"><span>agent-sdk init --from \\</span></span>
|
|
3
|
-
<span class="line"><span> automation:https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555</span></span>
|
|
4
|
-
<span class="line"><span></span></span>
|
|
5
|
-
<span class="line"><span>cd nightly-triage</span></span>
|
|
6
|
-
<span class="line"><span>agent-sdk validate</span></span>
|
|
7
|
-
<span class="line"><span>agent-sdk dev</span></span></code></pre></div><p>The project includes the Automation's prompt and model plus any schedules, channels, and account connections the converter could represent directly. The <a href="./../reference/cli.html#convert-automation">CLI reference</a> covers custom output directories, JSON output, and command failures.</p><h2 id="reconnect-account-backed-actions" tabindex="-1">Reconnect account-backed actions <a class="header-anchor" href="#reconnect-account-backed-actions" aria-label="Permalink to "Reconnect account-backed actions""></a></h2><p>For an HTTP or SSE MCP server, the converter writes a name-based connection instead of copying its URL or credentials. After you connect the same server under MCP in Cursor and sign in the local host, the converted agent can use that server's tools through your account.</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/mcp-connections/linear.ts</span></span>
|
|
8
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineConnection } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/connections"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
9
|
-
<span class="line"></span>
|
|
10
|
-
<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;"> defineConnection</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
11
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorAccount: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
12
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> servers: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Linear"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
13
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The summary adds a <code>Verify:</code> step when an original dashboard action does not map to one generated tool. Treat that step as a behavior test: run the converted agent with a representative input and confirm the same external write happens before you consider the action restored.</p><h2 id="bring-a-slack-trigger-online" tabindex="-1">Bring a Slack trigger online <a class="header-anchor" href="#bring-a-slack-trigger-online" aria-label="Permalink to "Bring a Slack trigger online""></a></h2><p>After you create the dedicated Slack app, mentions wake the converted agent and its answers land in the same thread. A channel watch also wakes on allowed posts, but only after you subscribe the app with <code>--channel-posts</code>.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk slack create --dir . --channel-posts</span></span></code></pre></div><p>The converter preserves the watch allowlist. If a warning says Cursor previously filtered messages by text, add that decision to the generated channel before inviting the bot:</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>
|
|
14
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> envPrefix: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"NIGHTLY_TRIAGE"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> engagement: {</span></span>
|
|
16
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> channelPosts: { allow: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"C123"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] },</span></span>
|
|
17
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
18
|
-
<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>
|
|
19
|
-
<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;">includes</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"deploy"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)) {</span></span>
|
|
20
|
-
<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>
|
|
21
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
22
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // \`{}\` starts a model turn as the sender.</span></span>
|
|
23
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {};</span></span>
|
|
24
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
25
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>For mention-only Automations, run <code>agent-sdk slack create --dir .</code> without <code>--channel-posts</code>. The <a href="./slack.html">Slack guide</a> covers the reply experience and app setup.</p><h2 id="bring-a-github-trigger-online" tabindex="-1">Bring a GitHub trigger online <a class="header-anchor" href="#bring-a-github-trigger-online" aria-label="Permalink to "Bring a GitHub trigger online""></a></h2><p>The generated GitHub channel keeps mechanical filters such as PR actions, branches, issue actions, repositories, and simple user allowlists. Conditions that depend on dashboard-only context stay fail-closed, so the corresponding hook returns <code>null</code> until you replace them.</p><p>For example, a converted CI trigger can wake only when the suite fails:</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;"> {</span></span>
|
|
26
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> defaultGitHubAuth,</span></span>
|
|
27
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> githubChannel,</span></span>
|
|
28
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/channels/github"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
29
|
-
<span class="line"></span>
|
|
30
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> githubChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
31
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cursorAccount: { repos: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"acme/api"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">] },</span></span>
|
|
32
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> webhookEvents: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"check_suite"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
33
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> onCheckSuite</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;">suite</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>
|
|
34
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (suite.conclusion </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "failure"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
35
|
-
<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>
|
|
36
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
37
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // \`auth\` starts a model turn running as the sender.</span></span>
|
|
38
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { auth: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">defaultGitHubAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(ctx) };</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>Replay a PR with a failing check before connecting live delivery:</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk github replay acme/api#42 \\</span></span>
|
|
41
|
-
<span class="line"><span> --dir . \\</span></span>
|
|
42
|
-
<span class="line"><span> --events '*' \\</span></span>
|
|
43
|
-
<span class="line"><span> --conclusion failure</span></span></code></pre></div><p>Cursor-account delivery carries PR and comment events. Push, issue, and CI triggers need real GitHub webhook delivery through a GitHub App or <code>github forward</code>. The <a href="./github.html">GitHub guide</a> covers both paths.</p><h2 id="treat-warnings-as-the-migration-checklist" tabindex="-1">Treat warnings as the migration checklist <a class="header-anchor" href="#treat-warnings-as-the-migration-checklist" aria-label="Permalink to "Treat warnings as the migration checklist""></a></h2><p>A successful conversion means the project was generated, not that every source behavior survived. Read the warnings and setup steps before turning on a live trigger:</p><ul><li><p>A setup step names something you must connect or configure.</p></li><li><p>A <code>Verify:</code> step names an external action whose behavior needs a test.</p></li><li><p>A fail-closed hook intentionally starts no turns until you restore its filter.</p></li><li><p>A <code>.todo.md</code> file is ignored by the framework and marks a connection you must replace.</p></li></ul><p>Keep the source Automation enabled while you work through this list, so you still have its behavior as a reference.</p><h2 id="know-the-conversion-boundary" tabindex="-1">Know the conversion boundary <a class="header-anchor" href="#know-the-conversion-boundary" aria-label="Permalink to "Know the conversion boundary""></a></h2><p>The converter can reproduce configuration that has a direct home in an Agent SDK project: instructions, the selected model, cron schedules, mechanical GitHub filters, Slack mentions and watch allowlists, and named Cursor-account MCP connections.</p><p>It cannot infer policy that lived behind the dashboard. Bespoke trigger conditions, provider webhook registration and auth, credentials, unsupported trigger semantics, and built-in action behavior remain warnings, comments, or TODO files for you to resolve. Credentials are never exported. Automation memory does not carry over. See <a href="https://linear.app/xai-linear/issue/RA-893" target="_blank" rel="noreferrer">RA-893</a>.</p><p>Cursor-managed Automations do not convert because their behavior lives entirely in managed configuration.</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#convert-automation">CLI reference</a>: arguments, JSON output, and failures</li><li><a href="./../reference/connections.html">MCP connections</a>: Cursor-account connectors and hosted authorization</li><li><a href="./github.html">GitHub</a>: event delivery, hook filters, and replay</li><li><a href="./slack.html">Slack</a>: mentions, channel watches, and reply modes</li><li><a href="./webhooks.html">Webhooks</a>: auth and filtering for generated provider routes</li><li><a href="./../deployment.html">Deployment</a>: deploy the reviewed project, then disable the source Automation before enabling the same live triggers</li></ul>`,34)])])}const g=a(t,[["render",l]]);export{k as __pageData,g as default};
|
|
@@ -1,54 +0,0 @@
|
|
|
1
|
-
import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn.","frontmatter":{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn."},"headers":[],"relativePath":"guides/hooks.md","filePath":"guides/hooks.md"}'),t={name:"guides/hooks.md"};function h(l,s,k,p,r,o){return n(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to "Hooks""></a></h1><p>Hooks observe session events after they are recorded and run side effects such as updating metrics or sending alerts. They never change the turn, prompt, or reply. Author them under <code>bot/hooks/</code> with <code>defineHook</code> from <code>@grok/agent-sdk/hooks</code>.</p><h2 id="meter-token-usage" tabindex="-1">Meter token usage <a class="header-anchor" href="#meter-token-usage" aria-label="Permalink to "Meter token usage""></a></h2><p>With <a href="./opentelemetry.html">OpenTelemetry</a> configured, this hook adds a live turn's reported input and output tokens to your counters. Eval runs stay quiet, so the dashboard reflects live traffic instead of the test suite.</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/hooks/usage.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;"> { metrics } </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>
|
|
3
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/hooks"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
4
|
-
<span class="line"></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> meter</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;">"acme"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
6
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> inputTokens</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> meter.</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;">"acme.tokens.input"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> outputTokens</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> meter.</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;">"acme.tokens.output"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
8
|
-
<span class="line"></span>
|
|
9
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
10
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> events: {</span></span>
|
|
11
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "turn.completed"</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:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
12
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "eval"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
13
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
14
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (event.data.usage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
16
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
17
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
18
|
-
<span class="line"></span>
|
|
19
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> inputTokens.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">add</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(event.data.usage.inputTokens);</span></span>
|
|
20
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> outputTokens.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">add</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(event.data.usage.outputTokens);</span></span>
|
|
21
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
22
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
23
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="alert-on-failure" tabindex="-1">Alert on failure <a class="header-anchor" href="#alert-on-failure" aria-label="Permalink to "Alert on failure""></a></h2><p>Set <code>PAGER_WEBHOOK_URL</code> to your pager's webhook. When a live turn fails, this hook posts the agent, session, and failure message there. Eval runs and interrupted turns stay quiet, so tests and preemptions do not page anyone.</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/hooks/page-on-failure.ts</span></span>
|
|
24
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/hooks"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
25
|
-
<span class="line"></span>
|
|
26
|
-
<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;"> defineHook</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
27
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> events: {</span></span>
|
|
28
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "turn.failed"</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:#E36209;--shiki-dark:#FFAB70;">ctx</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
29
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (ctx.session.purpose </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "eval"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
30
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
31
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
32
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (event.data.message </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "turn interrupted"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
33
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
34
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
35
|
-
<span class="line"></span>
|
|
36
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> pagerUrl</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> process.env.</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">PAGER_WEBHOOK_URL</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
37
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (pagerUrl </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
38
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</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>
|
|
41
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fetch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(pagerUrl, {</span></span>
|
|
42
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> method: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"POST"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
43
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> headers: { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"content-type"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"application/json"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
44
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> body: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">JSON</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">stringify</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
45
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> agent: ctx.agent.name,</span></span>
|
|
46
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> session: ctx.session.id,</span></span>
|
|
47
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> channel: ctx.channel.id,</span></span>
|
|
48
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: event.data.message,</span></span>
|
|
49
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
|
|
50
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> signal: AbortSignal.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">timeout</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">5_000</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:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
53
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
54
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="events-when-hooks-run" tabindex="-1">Events / when hooks run <a class="header-anchor" href="#events-when-hooks-run" aria-label="Permalink to "Events / when hooks run""></a></h2><p>Use event names from the <a href="./../reference/sessions.html#stream-events">session event vocabulary</a>. A hook receives each matching event after it is recorded, and the model does not wait for the handler.</p><p>Within one session, handlers run one at a time. A slow handler delays later handlers for that session, but it does not delay the model or handlers for other sessions. Hooks also fire for evals, so check <code>ctx.session.purpose === "eval"</code> before metering or paging. A restart does not replay recorded events into hooks.</p><h2 id="when-not-to-use-a-hook" tabindex="-1">When not to use a hook <a class="header-anchor" href="#when-not-to-use-a-hook" aria-label="Permalink to "When not to use a hook""></a></h2><table tabindex="0"><thead><tr><th>Want</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model</td><td><code>instructions.md</code>, skills, or <code>workspaceFiles</code></td></tr><tr><td>Deliver to Slack or a PR</td><td>Channel <a href="./../reference/channels.html#events"><code>events</code></a> or packs</td></tr><tr><td>Gate behavior</td><td><a href="./../evals.html">Evals</a></td></tr></tbody></table><p>To act on a turn's decision, have the model record it with an authored <a href="./../reference/tools.html">tool</a>, then act on it from a <code>turn.completed</code> hook.</p><p><a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a> in <code>.cursor/hooks.json</code> are a different product. They can observe, block, or modify the local agent loop.</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/hooks.html">Hooks reference</a>: payloads, context, and discovery</li><li><a href="./../reference/sessions.html#stream-events">Sessions: stream events</a>: event vocabulary and payload sequence</li><li><a href="./opentelemetry.html">OpenTelemetry</a>: export traces and custom metrics</li><li><a href="./../reference/channels.html#events">Channels: events</a>: deliver replies back to Slack, source control, or another surface</li></ul>`,17)])])}const g=i(t,[["render",h]]);export{E as __pageData,g as default};
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
import{_ as i,c as a,o as n,a3 as e}from"./chunks/framework.BNw1pucY.js";const E=JSON.parse('{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn.","frontmatter":{"title":"Hooks","description":"Observe session events for metrics, alerts, and other side effects without changing the turn."},"headers":[],"relativePath":"guides/hooks.md","filePath":"guides/hooks.md"}'),t={name:"guides/hooks.md"};function h(l,s,k,p,r,o){return n(),a("div",null,[...s[0]||(s[0]=[e("",17)])])}const g=i(t,[["render",h]]);export{E as __pageData,g as default};
|
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
import{_ as s,c as a,o as i,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate.","frontmatter":{"title":"Self-improvement","description":"Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate."},"headers":[],"relativePath":"guides/improve.md","filePath":"guides/improve.md"}'),n={name:"guides/improve.md"};function o(r,e,l,h,p,d){return i(),a("div",null,[...e[0]||(e[0]=[t(`<h1 id="self-improvement" tabindex="-1">Self-improvement <a class="header-anchor" href="#self-improvement" aria-label="Permalink to "Self-improvement""></a></h1><p>The <code>improve</code> extension teaches an agent how to turn "change how you work" into a source change. The agent prepares a brief, a Cursor cloud agent edits a checkout and opens a pull request, and the running agent reports the verified PR for human review.</p><p>Durable behavior does not change until that source is merged and deployed.</p><h2 id="mount-it" tabindex="-1">Mount it <a class="header-anchor" href="#mount-it" aria-label="Permalink to "Mount it""></a></h2><p>Mount Cloud agents with the agent's own repository allowlisted, then mount <code>improve</code> with the source directory.</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/cloud.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;"> cursorCloudAgents </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/extensions/cursor-cloud-agents"</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;"> cursorCloudAgents</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cloud: {</span></span>
|
|
6
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> repos: [</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
8
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"https://github.com/acme/agents"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
9
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> startingRef: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"main"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
10
|
-
<span class="line"><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;"> autoCreatePR: </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:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
14
|
-
<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:#6A737D;--shiki-dark:#6A737D;">// bot/extensions/improve.ts</span></span>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> improve </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/extensions/improve"</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;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> improve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
18
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> repo: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"https://github.com/acme/agents"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
19
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> path: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"agents/concierge"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
20
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ref: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"main"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
21
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Mounted as <code>improve</code>, the extension contributes the <code>improve__yourself</code> skill. It does not contribute a tool that can bypass the normal repository workflow.</p><h2 id="ask-for-one-behavioral-change" tabindex="-1">Ask for one behavioral change <a class="header-anchor" href="#ask-for-one-behavioral-change" aria-label="Permalink to "Ask for one behavioral change""></a></h2><p>State the change, how to tell it worked, and what behavior must stay fixed. The agent maps the request to instructions, a skill, a tool, channel configuration, or the model setting before preparing the coding brief.</p><blockquote><p>Improve yourself: stop opening incident replies with a summary. Start with the decision, keep the existing evidence bullets, and preserve every current eval.</p></blockquote><p>The success criterion and freeze line keep the cloud agent from turning a narrow behavior request into an unrelated refactor.</p><h2 id="follow-the-source-change" tabindex="-1">Follow the source change <a class="header-anchor" href="#follow-the-source-change" aria-label="Permalink to "Follow the source change""></a></h2><p>The agent launches one cloud agent on the configured repository and ref. It reports the complete cloud-agent ID and URL immediately, then checks the same run instead of launching another agent for follow-up work.</p><p>When the cloud agent opens a pull request, the running agent reads the result and the PR before reporting what changed and which checks passed. The pull request, not the delegation transcript, is the durable deliverable.</p><p>Use the <a href="./cloud-agents.html">Cloud agents guide</a> for launch, status, transcript, steering, and cancellation behavior.</p><h2 id="review-merge-then-deploy" tabindex="-1">Review, merge, then deploy <a class="header-anchor" href="#review-merge-then-deploy" aria-label="Permalink to "Review, merge, then deploy""></a></h2><p>The workflow stops at a pull request. A human reviews the diff and decides whether to merge it; a separate deployment action decides when the new behavior becomes live.</p><p>This separation gives each boundary a real control:</p><ul><li>Repository permissions limit who can push the branch.</li><li>Branch protection and review policy govern the merge.</li><li>Deployment authorization governs the running agent.</li></ul><p>After deployment, repeat the original request or regression eval to confirm the behavior changed without crossing the freeze line.</p><h2 id="configure-it" tabindex="-1">Configure it <a class="header-anchor" href="#configure-it" aria-label="Permalink to "Configure it""></a></h2><ul><li><code>repo</code> is the source repository URL.</li><li><code>path</code> is the agent's repository-relative directory.</li><li><code>ref</code> is the deployed branch or ref that new branches and pull requests target; it defaults to <code>main</code>.</li><li><code>notes</code> adds tree-specific guidance to every coding brief, such as a required test command or PR convention.</li><li><code>deploy</code> tells the skill who deploys a merged change and when it becomes live.</li></ul><p><code>notes</code> and <code>deploy</code> insert prose into the contributed skill. They do not run checks, merge a branch, or trigger a deployment.</p><p>Validation checks the URL and path shape. It does not prove the source exists, matches the current deployment, or appears in the Cloud agents repository allowlist, so keep those values aligned yourself.</p><h2 id="what-the-extension-enforces" tabindex="-1">What the extension enforces <a class="header-anchor" href="#what-the-extension-enforces" aria-label="Permalink to "What the extension enforces""></a></h2><p><code>improve__yourself</code> is model guidance for locating the change, writing a brief, following repository rules, opening a PR, and reporting it. Rules such as "never merge" are instructions, not framework-enforced permissions.</p><p>Use repository and deployment controls for hard enforcement. The extension provides a repeatable path through those controls; it does not replace them.</p><h2 id="what-s-next" tabindex="-1">What's next <a class="header-anchor" href="#what-s-next" aria-label="Permalink to "What's next""></a></h2><ul><li><a href="./cloud-agents.html">Cloud agents</a>: delegation and steering</li><li><a href="./../building-with-agents.html">Build with a coding agent</a>: have an external coding agent edit the project directly</li><li><a href="./../reference/extensions.html">Extensions</a>: namespaces and overlays</li><li><a href="./../deployment.html">Deployment</a>: make a merged source change live</li><li><a href="./../evals.html">Evals</a>: protect the requested behavior before and after the change</li></ul>`,30)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};
|