@grok/agent-sdk 0.2.29 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/channels/slack/cli-project.js +1 -1
- package/dist/docs/404.html +2 -2
- package/dist/docs/assets/{app.DMrZKFjI.js → app.BzTUBOAD.js} +4 -4
- package/dist/docs/assets/building-with-agents.md.BqJ7AAjG.js +6 -0
- package/dist/docs/assets/{building-with-agents.md.Bf1yH2tG.lean.js → building-with-agents.md.BqJ7AAjG.lean.js} +1 -1
- package/dist/docs/assets/changelog.md.BWhC6DET.js +1 -0
- package/dist/docs/assets/changelog.md.BWhC6DET.lean.js +1 -0
- package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +1 -0
- package/dist/docs/assets/chunks/{VPLocalSearchBox.DQvuw1KA.js → VPLocalSearchBox.DsnRlUT5.js} +1 -1
- package/dist/docs/assets/chunks/{arc.ahOG-Qza.js → arc.DH8GOhiv.js} +1 -1
- package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.BcgfYNO_.js → architectureDiagram-Q4EWVU46.9m9ObyuE.js} +1 -1
- package/dist/docs/assets/chunks/{baseUniq.DeIYZrWh.js → baseUniq.BXHpx1lE.js} +1 -1
- package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.HjJ2goMX.js → blockDiagram-DXYQGD6D.xY3EX59q.js} +1 -1
- package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.C1QTb9GM.js → c4Diagram-AHTNJAMY.DnqgMVgc.js} +1 -1
- package/dist/docs/assets/chunks/channel.Cctv0f7X.js +1 -0
- package/dist/docs/assets/chunks/{chunk-4BX2VUAB.UuZiDiVp.js → chunk-4BX2VUAB.BjFxK2A3.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-4TB4RGXK.5A3YmkhI.js → chunk-4TB4RGXK.BujS_Spt.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-55IACEB6.B4uf1yYV.js → chunk-55IACEB6.YbTjhdaM.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-EDXVE4YY.CoXBce8t.js → chunk-EDXVE4YY.DnQ8t4GC.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DnC5NO4e.js → chunk-FMBD7UC4.B67AwAmj.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-OYMX7WX6.CzfHCeIi.js → chunk-OYMX7WX6.DrZIAFOm.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-QZHKN3VN.C6tcwkVd.js → chunk-QZHKN3VN.BLmmydkn.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-YZCP3GAM._oboyZ1A.js → chunk-YZCP3GAM.DaoOfw0O.js} +1 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +1 -0
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +1 -0
- package/dist/docs/assets/chunks/clone.B9rdNt6j.js +1 -0
- package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.BfPVKeId.js → cose-bilkent-S5V4N54A.DMQuNhM5.js} +1 -1
- package/dist/docs/assets/chunks/{dagre-KV5264BT.CLMLc0lD.js → dagre-KV5264BT.CZoGVuUf.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-5BDNPKRD.C7OF7UfH.js → diagram-5BDNPKRD.CLt9uOyL.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.Dpao0Bl1.js → diagram-G4DWMVQ6.DpczEm1G.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-MMDJMWI5.DLnM9eLp.js → diagram-MMDJMWI5.D4r13DvJ.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-TYMM5635.BcpVgA_M.js → diagram-TYMM5635.CYU9eGFu.js} +1 -1
- package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.CsL5JuCV.js → erDiagram-SMLLAGMA.QA9naWEw.js} +1 -1
- package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.MFihq9AF.js → flowDiagram-DWJPFMVM.BbNoVZYd.js} +1 -1
- package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CJeLodyG.js → ganttDiagram-T4ZO3ILL.IHjDoG7r.js} +1 -1
- package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.1HhlE45Z.js → gitGraphDiagram-UUTBAWPF.B21VMdf5.js} +1 -1
- package/dist/docs/assets/chunks/{graph.BS02KkWA.js → graph.DgJ4L-8V.js} +1 -1
- package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.fp5gvytQ.js → infoDiagram-42DDH7IO.CQjrcthc.js} +1 -1
- package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.C6Wk1V4I.js → ishikawaDiagram-UXIWVN3A.D4tPGtVo.js} +1 -1
- package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.qJt4uJ_H.js → journeyDiagram-VCZTEJTY.BD3WaNbQ.js} +1 -1
- package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.z2tG9kly.js → kanban-definition-6JOO6SKY.Ca0o4Tqz.js} +1 -1
- package/dist/docs/assets/chunks/{layout.BPCkdejr.js → layout.DXXqX4MQ.js} +1 -1
- package/dist/docs/assets/chunks/{linear.CL3TC3u7.js → linear.5c61gNw4.js} +1 -1
- package/dist/docs/assets/chunks/{min.SPrSp704.js → min.B1-NAjHX.js} +1 -1
- package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.DgrQRFZW.js → mindmap-definition-QFDTVHPH.BELznv3-.js} +1 -1
- package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.Ba7yxiW2.js → pieDiagram-DEJITSTG.qPzO1mq5.js} +1 -1
- package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Bvskad4p.js → quadrantDiagram-34T5L4WZ.CxIvzbjX.js} +1 -1
- package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.Ce70ugV9.js → requirementDiagram-MS252O5E.CqA0iJx8.js} +1 -1
- package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.BJ5OEULO.js → sankeyDiagram-XADWPNL6.XRTutBnb.js} +1 -1
- package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.C8a1hDs6.js → sequenceDiagram-FGHM5R23.E--7bRLQ.js} +1 -1
- package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.D2D8A5CK.js → stateDiagram-FHFEXIEX.C4vGu8zq.js} +1 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +1 -0
- package/dist/docs/assets/chunks/{theme.DRciHmS1.js → theme.DMj_7q3B.js} +2 -2
- package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C4ePrY8-.js → timeline-definition-GMOUNBTQ.C7LgNVAL.js} +1 -1
- package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Dzso6dEA.js → vennDiagram-DHZGUBPP.HUwoZcy_.js} +1 -1
- package/dist/docs/assets/chunks/{wardley-RL74JXVD.djgXR0ar.js → wardley-RL74JXVD.BxFEFYZS.js} +1 -1
- package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.Bf2ICxjh.js → wardleyDiagram-NUSXRM2D.B2pSo5rB.js} +1 -1
- package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DEH4BcVJ.js → xychartDiagram-5P7HB3ND.NQhMiOOL.js} +1 -1
- package/dist/docs/assets/deployment.md.BtqJrHhp.js +31 -0
- package/dist/docs/assets/{deployment.md.KW0Ni_rY.lean.js → deployment.md.BtqJrHhp.lean.js} +1 -1
- package/dist/docs/assets/evals.md.Dne6VRmZ.js +49 -0
- package/dist/docs/assets/evals.md.Dne6VRmZ.lean.js +1 -0
- package/dist/docs/assets/{guides_agent-to-agent.md.D1D5f6Jc.js → guides_agent-to-agent.md.BcmSqL2z.js} +8 -8
- package/dist/docs/assets/guides_agent-to-agent.md.BcmSqL2z.lean.js +1 -0
- package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.js → guides_bitbucket.md.BiA6ZMFW.js} +27 -27
- package/dist/docs/assets/{guides_bitbucket.md.DkjkBRU8.lean.js → guides_bitbucket.md.BiA6ZMFW.lean.js} +1 -1
- package/dist/docs/assets/guides_cloud-agents.md.CiXAW6on.js +9 -0
- package/dist/docs/assets/{guides_cloud-agents.md.Ceyjv0ul.lean.js → guides_cloud-agents.md.CiXAW6on.lean.js} +1 -1
- package/dist/docs/assets/guides_convert-automation.md.BvTxsJ8J.js +26 -0
- package/dist/docs/assets/{guides_convert-automation.md.BjraCvok.lean.js → guides_convert-automation.md.BvTxsJ8J.lean.js} +1 -1
- package/dist/docs/assets/{guides_github.md.CgN5sNbW.js → guides_github.md.6jiEH7dg.js} +11 -19
- package/dist/docs/assets/{guides_github.md.CgN5sNbW.lean.js → guides_github.md.6jiEH7dg.lean.js} +1 -1
- package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.js → guides_gitlab.md.DcKusOcU.js} +63 -73
- package/dist/docs/assets/{guides_gitlab.md.DCE0p7_w.lean.js → guides_gitlab.md.DcKusOcU.lean.js} +1 -1
- package/dist/docs/assets/guides_improve.md.o3WOGR7n.js +16 -0
- package/dist/docs/assets/{guides_improve.md.BFYtrtLE.lean.js → guides_improve.md.o3WOGR7n.lean.js} +1 -1
- package/dist/docs/assets/{guides_jev.md.CEqLgjj9.js → guides_jev.md.DGCzkMUN.js} +20 -60
- package/dist/docs/assets/{guides_jev.md.CEqLgjj9.lean.js → guides_jev.md.DGCzkMUN.lean.js} +1 -1
- package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.js → guides_mcp-oauth.md.C-Sx_IPa.js} +3 -5
- package/dist/docs/assets/{guides_mcp-oauth.md.DrGY92u4.lean.js → guides_mcp-oauth.md.C-Sx_IPa.lean.js} +1 -1
- package/dist/docs/assets/guides_migrate.md.BbhHYeCr.js +3 -0
- package/dist/docs/assets/{guides_migrate.md.RS9Eu-Xh.lean.js → guides_migrate.md.BbhHYeCr.lean.js} +1 -1
- package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.js +26 -0
- package/dist/docs/assets/guides_opentelemetry.md.BRSktBHt.lean.js +1 -0
- package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.js +61 -0
- package/dist/docs/assets/guides_pagerduty.md.pMXUkZZc.lean.js +1 -0
- package/dist/docs/assets/guides_slack.md.BgIGG9ur.js +82 -0
- package/dist/docs/assets/{guides_slack.md.BwXHURvY.lean.js → guides_slack.md.BgIGG9ur.lean.js} +1 -1
- package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.js → guides_webhooks.md.B5DXt2v1.js} +7 -7
- package/dist/docs/assets/{guides_webhooks.md.BJk63ZTs.lean.js → guides_webhooks.md.B5DXt2v1.lean.js} +1 -1
- package/dist/docs/assets/hillclimbing.md.3TkdF79A.js +5 -0
- package/dist/docs/assets/hillclimbing.md.3TkdF79A.lean.js +1 -0
- package/dist/docs/assets/index.md.DRfaoRCZ.js +20 -0
- package/dist/docs/assets/{index.md.CAruw_rp.lean.js → index.md.DRfaoRCZ.lean.js} +1 -1
- package/dist/docs/assets/quickstart.md.r-oE8nkX.js +113 -0
- package/dist/docs/assets/{quickstart.md.CljDaJBi.lean.js → quickstart.md.r-oE8nkX.lean.js} +1 -1
- package/dist/docs/assets/reference_access.md.C5lblfUC.js +1 -0
- package/dist/docs/assets/reference_access.md.C5lblfUC.lean.js +1 -0
- package/dist/docs/assets/reference_agent-config.md.C0Tp_Fk9.js +27 -0
- package/dist/docs/assets/{reference_agent-config.md.Ck29qYNj.lean.js → reference_agent-config.md.C0Tp_Fk9.lean.js} +1 -1
- package/dist/docs/assets/reference_artifacts.md.BJpAI7h9.js +17 -0
- package/dist/docs/assets/{reference_artifacts.md.C-hKR2hp.lean.js → reference_artifacts.md.BJpAI7h9.lean.js} +1 -1
- package/dist/docs/assets/reference_channels.md.CPWOpdsC.js +21 -0
- package/dist/docs/assets/{reference_channels.md.DsJfGSBJ.lean.js → reference_channels.md.CPWOpdsC.lean.js} +1 -1
- package/dist/docs/assets/reference_cli.md.B8GdpaRj.js +83 -0
- package/dist/docs/assets/reference_cli.md.B8GdpaRj.lean.js +1 -0
- package/dist/docs/assets/reference_connections.md.DoY4vrDH.js +54 -0
- package/dist/docs/assets/{reference_connections.md.BoAotr7_.lean.js → reference_connections.md.DoY4vrDH.lean.js} +1 -1
- package/dist/docs/assets/reference_evals.md.DgfUtfIc.js +69 -0
- package/dist/docs/assets/{reference_evals.md.2BXeMiO2.lean.js → reference_evals.md.DgfUtfIc.lean.js} +1 -1
- package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.js → reference_extensions.md.DHbW6eOf.js} +6 -8
- package/dist/docs/assets/{reference_extensions.md.DI5X5x8p.lean.js → reference_extensions.md.DHbW6eOf.lean.js} +1 -1
- package/dist/docs/assets/reference_hooks.md.CSWmOwMM.js +39 -0
- package/dist/docs/assets/reference_hooks.md.CSWmOwMM.lean.js +1 -0
- package/dist/docs/assets/reference_http-api.md.C7Cb0r2J.js +7 -0
- package/dist/docs/assets/{reference_http-api.md._RWELr3d.lean.js → reference_http-api.md.C7Cb0r2J.lean.js} +1 -1
- package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.js +14 -0
- package/dist/docs/assets/reference_instructions.md.CV6Qq0UX.lean.js +1 -0
- package/dist/docs/assets/reference_limits.md.CbdtFr4T.js +8 -0
- package/dist/docs/assets/reference_limits.md.CbdtFr4T.lean.js +1 -0
- package/dist/docs/assets/reference_memory.md.CdoJISM-.js +3 -0
- package/dist/docs/assets/{reference_memory.md.Dd7cyV9V.lean.js → reference_memory.md.CdoJISM-.lean.js} +1 -1
- package/dist/docs/assets/reference_playground.md.DIUsRAcy.js +1 -0
- package/dist/docs/assets/{reference_playground.md.CQiJk9CM.lean.js → reference_playground.md.DIUsRAcy.lean.js} +1 -1
- package/dist/docs/assets/reference_project-layout.md.9DiKoE16.js +26 -0
- package/dist/docs/assets/reference_project-layout.md.9DiKoE16.lean.js +1 -0
- package/dist/docs/assets/reference_schedules.md.RhQ9ZLo1.js +45 -0
- package/dist/docs/assets/{reference_schedules.md.RC47aFm4.lean.js → reference_schedules.md.RhQ9ZLo1.lean.js} +1 -1
- package/dist/docs/assets/reference_sessions.md.NXVQt9mP.js +22 -0
- package/dist/docs/assets/{reference_sessions.md.C7KFhWXV.lean.js → reference_sessions.md.NXVQt9mP.lean.js} +1 -1
- package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js} +4 -4
- package/dist/docs/assets/{reference_skills.md.Dej2zQxi.lean.js → reference_skills.md.DzCPNPkG.lean.js} +1 -1
- package/dist/docs/assets/reference_subagents.md.Dvpq2sUu.js +10 -0
- package/dist/docs/assets/{reference_subagents.md.CAhvW4yS.lean.js → reference_subagents.md.Dvpq2sUu.lean.js} +1 -1
- package/dist/docs/assets/reference_tools.md.B2OaR1Nb.js +62 -0
- package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js} +1 -1
- package/dist/docs/assets/templates_agentic-owners.md.B6ZmKAzT.js +13 -0
- package/dist/docs/assets/{templates_agentic-owners.md.Dh2nDSqg.lean.js → templates_agentic-owners.md.B6ZmKAzT.lean.js} +1 -1
- package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.js +10 -0
- package/dist/docs/assets/templates_reviews.md.dr9Xv_KM.lean.js +1 -0
- package/dist/docs/assets/troubleshooting.md.DfKKvW1R.js +3 -0
- package/dist/docs/assets/{troubleshooting.md.CGOdNVAL.lean.js → troubleshooting.md.DfKKvW1R.lean.js} +1 -1
- package/dist/docs/building-with-agents.html +41 -44
- package/dist/docs/building-with-agents.md +11 -104
- package/dist/docs/changelog.html +37 -37
- package/dist/docs/changelog.md +5 -155
- package/dist/docs/deployment.html +54 -54
- package/dist/docs/deployment.md +83 -262
- package/dist/docs/evals.html +52 -71
- package/dist/docs/evals.md +33 -129
- package/dist/docs/guides/agent-to-agent.html +43 -43
- package/dist/docs/guides/agent-to-agent.md +27 -64
- package/dist/docs/guides/bitbucket.html +62 -62
- package/dist/docs/guides/bitbucket.md +73 -134
- package/dist/docs/guides/cloud-agents.html +37 -37
- package/dist/docs/guides/cloud-agents.md +23 -53
- package/dist/docs/guides/convert-automation.html +39 -56
- package/dist/docs/guides/convert-automation.md +31 -115
- package/dist/docs/guides/github.html +46 -54
- package/dist/docs/guides/github.md +49 -131
- package/dist/docs/guides/gitlab.html +98 -108
- package/dist/docs/guides/gitlab.md +104 -184
- package/dist/docs/guides/improve.html +38 -43
- package/dist/docs/guides/improve.md +24 -90
- package/dist/docs/guides/jev.html +55 -95
- package/dist/docs/guides/jev.md +53 -160
- package/dist/docs/guides/mcp-oauth.html +38 -40
- package/dist/docs/guides/mcp-oauth.md +33 -67
- package/dist/docs/guides/migrate.html +38 -43
- package/dist/docs/guides/migrate.md +56 -130
- package/dist/docs/guides/opentelemetry.html +41 -43
- package/dist/docs/guides/opentelemetry.md +32 -27
- package/dist/docs/guides/pagerduty.html +50 -49
- package/dist/docs/guides/pagerduty.md +65 -199
- package/dist/docs/guides/slack.html +51 -57
- package/dist/docs/guides/slack.md +76 -204
- package/dist/docs/guides/webhooks.html +42 -42
- package/dist/docs/guides/webhooks.md +64 -146
- package/dist/docs/hashmap.json +1 -1
- package/dist/docs/hillclimbing.html +40 -42
- package/dist/docs/hillclimbing.md +40 -102
- package/dist/docs/index.html +55 -61
- package/dist/docs/index.md +49 -83
- package/dist/docs/llms-full.txt +2262 -5721
- package/dist/docs/llms.txt +9 -14
- package/dist/docs/quickstart.html +95 -152
- package/dist/docs/quickstart.md +91 -180
- package/dist/docs/reference/access.html +36 -36
- package/dist/docs/reference/access.md +7 -12
- package/dist/docs/reference/agent-config.html +43 -56
- package/dist/docs/reference/agent-config.md +91 -174
- package/dist/docs/reference/artifacts.html +38 -39
- package/dist/docs/reference/artifacts.md +38 -62
- package/dist/docs/reference/channels.html +38 -39
- package/dist/docs/reference/channels.md +102 -151
- package/dist/docs/reference/cli.html +68 -84
- package/dist/docs/reference/cli.md +232 -697
- package/dist/docs/reference/connections.html +45 -57
- package/dist/docs/reference/connections.md +83 -164
- package/dist/docs/reference/evals.html +47 -54
- package/dist/docs/reference/evals.md +75 -141
- package/dist/docs/reference/extensions.html +41 -43
- package/dist/docs/reference/extensions.md +37 -70
- package/dist/docs/reference/hooks.html +40 -52
- package/dist/docs/reference/hooks.md +62 -133
- package/dist/docs/reference/http-api.html +38 -42
- package/dist/docs/reference/http-api.md +66 -118
- package/dist/docs/reference/instructions.html +39 -39
- package/dist/docs/reference/instructions.md +19 -29
- package/dist/docs/reference/limits.html +38 -38
- package/dist/docs/reference/limits.md +9 -21
- package/dist/docs/reference/memory.html +37 -38
- package/dist/docs/reference/memory.md +38 -75
- package/dist/docs/reference/playground.html +36 -36
- package/dist/docs/reference/playground.md +14 -22
- package/dist/docs/reference/project-layout.html +49 -48
- package/dist/docs/reference/project-layout.md +38 -84
- package/dist/docs/reference/schedules.html +46 -48
- package/dist/docs/reference/schedules.md +59 -90
- package/dist/docs/reference/sessions.html +37 -37
- package/dist/docs/reference/sessions.md +66 -113
- package/dist/docs/reference/skills.html +39 -39
- package/dist/docs/reference/skills.md +11 -31
- package/dist/docs/reference/subagents.html +37 -37
- package/dist/docs/reference/subagents.md +17 -31
- package/dist/docs/reference/tools.html +47 -64
- package/dist/docs/reference/tools.md +48 -130
- package/dist/docs/templates/agentic-owners.html +38 -38
- package/dist/docs/templates/agentic-owners.md +50 -74
- package/dist/docs/templates/reviews.html +69 -0
- package/dist/docs/templates/reviews.md +71 -0
- package/dist/docs/troubleshooting.html +38 -36
- package/dist/docs/troubleshooting.md +48 -101
- package/dist/internal/cli-deploy.js +1 -1
- package/dist/internal/cli-docs.js +1 -1
- package/dist/internal/cli-images.js +1 -1
- package/dist/internal/cli-skills.js +1 -1
- package/dist/internal/cursor/credentials.js +1 -1
- package/dist/internal/deploy-manifest.d.ts +1 -0
- package/dist/internal/deploy-manifest.d.ts.map +1 -1
- package/dist/internal/deploy-manifest.js +0 -1
- package/dist/internal/discovery/agent-config.d.ts +2 -6
- package/dist/internal/discovery/agent-config.d.ts.map +1 -1
- package/dist/internal/discovery/agent-config.js +8 -25
- package/dist/internal/discovery/agent.d.ts.map +1 -1
- package/dist/internal/discovery/agent.js +2 -3
- package/dist/internal/discovery/project.d.ts.map +1 -1
- package/dist/internal/discovery/project.js +15 -0
- package/dist/internal/init-project.d.ts.map +1 -1
- package/dist/internal/init-project.js +7 -5
- package/dist/internal/reminder-runner.js +1 -1
- package/dist/internal/session-engine.js +1 -1
- package/dist/internal/shallow-clone.js +1 -1
- package/dist/playground/assets/index-D6mVn9og.js +62 -0
- package/dist/playground/assets/index-DlALM6gr.css +1 -0
- package/dist/playground/index.html +2 -2
- package/dist/types.d.ts +4 -17
- package/dist/types.d.ts.map +1 -1
- package/docs/README.md +49 -83
- package/docs/building-with-agents.md +11 -104
- package/docs/changelog.md +6 -156
- package/docs/deployment.md +83 -262
- package/docs/evals.md +34 -130
- package/docs/guides/agent-to-agent.md +27 -64
- package/docs/guides/bitbucket.md +73 -134
- package/docs/guides/cloud-agents.md +23 -53
- package/docs/guides/convert-automation.md +31 -115
- package/docs/guides/github.md +49 -131
- package/docs/guides/gitlab.md +104 -184
- package/docs/guides/improve.md +24 -90
- package/docs/guides/jev.md +53 -160
- package/docs/guides/mcp-oauth.md +33 -67
- package/docs/guides/migrate.md +56 -130
- package/docs/guides/opentelemetry.md +37 -27
- package/docs/guides/pagerduty.md +68 -200
- package/docs/guides/slack.md +76 -204
- package/docs/guides/webhooks.md +64 -146
- package/docs/hillclimbing.md +41 -103
- package/docs/quickstart.md +91 -180
- package/docs/reference/access.md +7 -12
- package/docs/reference/agent-config.md +91 -174
- package/docs/reference/artifacts.md +38 -62
- package/docs/reference/channels.md +102 -151
- package/docs/reference/cli.md +232 -697
- package/docs/reference/connections.md +83 -164
- package/docs/reference/evals.md +75 -141
- package/docs/reference/extensions.md +37 -70
- package/docs/reference/hooks.md +61 -132
- package/docs/reference/http-api.md +66 -118
- package/docs/reference/instructions.md +20 -30
- package/docs/reference/limits.md +10 -22
- package/docs/reference/memory.md +38 -75
- package/docs/reference/playground.md +14 -22
- package/docs/reference/project-layout.md +38 -84
- package/docs/reference/schedules.md +59 -90
- package/docs/reference/sessions.md +66 -113
- package/docs/reference/skills.md +12 -32
- package/docs/reference/subagents.md +17 -31
- package/docs/reference/tools.md +48 -130
- package/docs/templates/agentic-owners.md +50 -74
- package/docs/templates/reviews.md +76 -0
- package/docs/troubleshooting.md +48 -101
- package/package.json +2 -2
- package/skills/deploy/SKILL.md +1 -1
- package/skills/migrate-v2/SKILL.md +0 -1
- package/dist/docs/assets/building-with-agents.md.Bf1yH2tG.js +0 -9
- package/dist/docs/assets/changelog.md.DrLFQUlu.js +0 -1
- package/dist/docs/assets/changelog.md.DrLFQUlu.lean.js +0 -1
- package/dist/docs/assets/chunks/@localSearchIndexroot.Dpd_wxVU.js +0 -1
- package/dist/docs/assets/chunks/channel._fZX_hvU.js +0 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.eClS1Q0E.js +0 -1
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.eClS1Q0E.js +0 -1
- package/dist/docs/assets/chunks/clone.W1Phdw9P.js +0 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.77yf4kRr.js +0 -1
- package/dist/docs/assets/deployment.md.KW0Ni_rY.js +0 -31
- package/dist/docs/assets/evals.md.DiljU__Z.js +0 -68
- package/dist/docs/assets/evals.md.DiljU__Z.lean.js +0 -1
- package/dist/docs/assets/guides_agent-to-agent.md.D1D5f6Jc.lean.js +0 -1
- package/dist/docs/assets/guides_cloud-agents.md.Ceyjv0ul.js +0 -9
- package/dist/docs/assets/guides_convert-automation.md.BjraCvok.js +0 -43
- package/dist/docs/assets/guides_hooks.md.BjeEiM7s.js +0 -54
- package/dist/docs/assets/guides_hooks.md.BjeEiM7s.lean.js +0 -1
- package/dist/docs/assets/guides_improve.md.BFYtrtLE.js +0 -21
- package/dist/docs/assets/guides_migrate.md.RS9Eu-Xh.js +0 -8
- package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.js +0 -28
- package/dist/docs/assets/guides_opentelemetry.md.CoZ1kNyd.lean.js +0 -1
- package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.js +0 -60
- package/dist/docs/assets/guides_pagerduty.md.mnKXe9U0.lean.js +0 -1
- package/dist/docs/assets/guides_slack.md.BwXHURvY.js +0 -88
- package/dist/docs/assets/hillclimbing.md.By61f3uq.js +0 -7
- package/dist/docs/assets/hillclimbing.md.By61f3uq.lean.js +0 -1
- package/dist/docs/assets/index.md.CAruw_rp.js +0 -26
- package/dist/docs/assets/quickstart.md.CljDaJBi.js +0 -170
- package/dist/docs/assets/reference_access.md.CEtibb4i.js +0 -1
- package/dist/docs/assets/reference_access.md.CEtibb4i.lean.js +0 -1
- package/dist/docs/assets/reference_agent-config.md.Ck29qYNj.js +0 -40
- package/dist/docs/assets/reference_artifacts.md.C-hKR2hp.js +0 -18
- package/dist/docs/assets/reference_channels.md.DsJfGSBJ.js +0 -22
- package/dist/docs/assets/reference_cli.md.BkdLRbXg.js +0 -99
- package/dist/docs/assets/reference_cli.md.BkdLRbXg.lean.js +0 -1
- package/dist/docs/assets/reference_connections.md.BoAotr7_.js +0 -66
- package/dist/docs/assets/reference_evals.md.2BXeMiO2.js +0 -76
- package/dist/docs/assets/reference_hooks.md.B-bwJuiG.js +0 -51
- package/dist/docs/assets/reference_hooks.md.B-bwJuiG.lean.js +0 -1
- package/dist/docs/assets/reference_http-api.md._RWELr3d.js +0 -11
- package/dist/docs/assets/reference_instructions.md.yL2hXLnl.js +0 -14
- package/dist/docs/assets/reference_instructions.md.yL2hXLnl.lean.js +0 -1
- package/dist/docs/assets/reference_limits.md.BCCnvt3o.js +0 -8
- package/dist/docs/assets/reference_limits.md.BCCnvt3o.lean.js +0 -1
- package/dist/docs/assets/reference_memory.md.Dd7cyV9V.js +0 -4
- package/dist/docs/assets/reference_playground.md.CQiJk9CM.js +0 -1
- package/dist/docs/assets/reference_project-layout.md.BamcPDUn.js +0 -25
- package/dist/docs/assets/reference_project-layout.md.BamcPDUn.lean.js +0 -1
- package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.js +0 -9
- package/dist/docs/assets/reference_prompt.md.BMjm1Jp3.lean.js +0 -1
- package/dist/docs/assets/reference_schedules.md.RC47aFm4.js +0 -47
- package/dist/docs/assets/reference_sessions.md.C7KFhWXV.js +0 -22
- package/dist/docs/assets/reference_subagents.md.CAhvW4yS.js +0 -10
- package/dist/docs/assets/reference_tools.md.DQr7Fnhu.js +0 -79
- package/dist/docs/assets/templates_agentic-owners.md.Dh2nDSqg.js +0 -13
- package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.js +0 -3
- package/dist/docs/assets/templates_security-reviewer.md.DnwXdnB5.lean.js +0 -1
- package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.js +0 -3
- package/dist/docs/assets/templates_thermo-quality-review.md.MJIdHkzE.lean.js +0 -1
- package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.js +0 -3
- package/dist/docs/assets/templates_thermo-review.md.DfN1OFOl.lean.js +0 -1
- package/dist/docs/assets/templates_triage.md.BYWMloV4.js +0 -9
- package/dist/docs/assets/templates_triage.md.BYWMloV4.lean.js +0 -1
- package/dist/docs/assets/troubleshooting.md.CGOdNVAL.js +0 -1
- package/dist/docs/guides/hooks.html +0 -113
- package/dist/docs/guides/hooks.md +0 -116
- package/dist/docs/package/skills/create-agent/SKILL.md +0 -178
- package/dist/docs/package/skills/evals/SKILL.md +0 -145
- package/dist/docs/package/skills/github/SKILL.md +0 -133
- package/dist/docs/package/skills/hillclimb/SKILL.md +0 -63
- package/dist/docs/package/skills/mcp-auth/SKILL.md +0 -60
- package/dist/docs/package/skills/migrate-v2/SKILL.md +0 -394
- package/dist/docs/package/skills/setup-slack/SKILL.md +0 -136
- package/dist/docs/reference/prompt.html +0 -68
- package/dist/docs/reference/prompt.md +0 -47
- package/dist/docs/templates/security-reviewer.html +0 -62
- package/dist/docs/templates/security-reviewer.md +0 -81
- package/dist/docs/templates/thermo-quality-review.html +0 -62
- package/dist/docs/templates/thermo-quality-review.md +0 -75
- package/dist/docs/templates/thermo-review.html +0 -62
- package/dist/docs/templates/thermo-review.md +0 -75
- package/dist/docs/templates/triage.html +0 -68
- package/dist/docs/templates/triage.md +0 -101
- package/dist/playground/assets/index-Cl9zvmmf.js +0 -62
- package/dist/playground/assets/index-F8b5WvWi.css +0 -1
- package/docs/guides/hooks.md +0 -121
- package/docs/reference/prompt.md +0 -52
- package/docs/templates/security-reviewer.md +0 -86
- package/docs/templates/thermo-quality-review.md +0 -80
- package/docs/templates/thermo-review.md +0 -80
- package/docs/templates/triage.md +0 -106
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,d,p,k,r){return e(),a("div",null,[...s[0]||(s[0]=[n(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to "Schedules and reminders""></a></h1><p>A schedule or a reminder lets an agent act without an inbound message.</p><h2 id="schedules-vs-reminders" tabindex="-1">Schedules vs reminders <a class="header-anchor" href="#schedules-vs-reminders" aria-label="Permalink to "Schedules vs reminders""></a></h2><table tabindex="0"><thead><tr><th></th><th>Schedule</th><th>Reminder</th></tr></thead><tbody><tr><td>Defined</td><td>At deploy time, in <code>bot/schedules/*</code></td><td>At runtime, with <code>createReminder</code> or <code>host.reminders</code></td></tr><tr><td>Scope</td><td>The whole agent</td><td>One conversation</td></tr><tr><td>Session</td><td>Starts a new task session, or hands off through <code>receive</code></td><td>Wakes an existing conversation</td></tr><tr><td>Cadence</td><td>5-field cron, in UTC, to the minute</td><td><code>every</code>, <code>cron</code>, <code>delay</code>, or <code>at</code></td></tr><tr><td>Dev mode</td><td>Manual dispatch only</td><td>Manual dispatch only, with timers off</td></tr></tbody></table><h2 id="schedules" tabindex="-1">Schedules <a class="header-anchor" href="#schedules" aria-label="Permalink to "Schedules""></a></h2><h3 id="markdown-schedules" tabindex="-1">Markdown schedules <a class="header-anchor" href="#markdown-schedules" aria-label="Permalink to "Markdown schedules""></a></h3><p>A Markdown file with <code>cron:</code> frontmatter is a fire-and-forget task:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">cron: "0 9 * * 1-5"</span></span>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;">---</span></span>
|
|
4
|
+
<span class="line"></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Pull open incidents and post a summary to the metrics endpoint.</span></span></code></pre></div><p>Each fire starts a task-mode session with the body as its prompt, and the session runs to <code>session.completed</code> or <code>session.failed</code> without follow-ups.</p><h3 id="schedule-handlers" tabindex="-1">Schedule handlers <a class="header-anchor" href="#schedule-handlers" aria-label="Permalink to "Schedule handlers""></a></h3><p>A <code>run</code> handler can call tools or hand work to a channel, whose delivery events then fire:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineSchedule } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/schedules"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
6
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> webhook </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "../channels/webhook.js"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
7
|
+
<span class="line"></span>
|
|
8
|
+
<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;"> defineSchedule</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cron: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"*/30 * * * *"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">receive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">appAuth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">host</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
|
|
11
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> receive</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(webhook, {</span></span>
|
|
13
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Report any new critical alerts."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
14
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> auth: appAuth,</span></span>
|
|
15
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
|
|
16
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> );</span></span>
|
|
17
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
18
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>defineSchedule</code> takes exactly one of <code>markdown</code> or <code>run</code>. <code>appAuth</code> is a schedule-scoped principal for work the agent does on its own behalf. The handler also receives <code>callTool</code>, for server-tool calls without a model turn, and <code>host</code>, which holds <code>host.mcp</code>, <code>host.github</code>, <code>host.slack</code>, and <code>host.reminders</code>.</p><h3 id="dispatch-a-schedule" tabindex="-1">Dispatch a schedule <a class="header-anchor" href="#dispatch-a-schedule" aria-label="Permalink to "Dispatch a schedule""></a></h3><p>Schedules fire on their cron cadence on Cursor hosting and under production <code>agent-sdk serve</code>. Run them in exactly one <code>serve</code> process per project, or pass <code>--no-schedules</code> to turn them off. <code>serve --dev</code> fires nothing on its own, so dispatch by hand:</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;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/dev/schedules/heartbeat</span></span></code></pre></div><p>The playground and <code>handle.dispatchSchedule("heartbeat")</code> dispatch the same way.</p><h3 id="schedules-on-cursor-hosting" tabindex="-1">Schedules on Cursor hosting <a class="header-anchor" href="#schedules-on-cursor-hosting" aria-label="Permalink to "Schedules on Cursor hosting""></a></h3><p>Each deploy replaces the hosted schedules with the ones in <code>bot/schedules/</code>, so a schedule you delete stops after your next deploy.</p><p>A <code>run</code> handler must finish in 26 minutes, including the work it passes to <code>receive</code> and <code>waitUntil</code>. Module memory doesn't carry over to the next fire, so keep state in <code>ctx.host.kv</code> or <code>ctx.host.files</code>. Each scheduled time starts at most one run, and a stopped deployment skips its fires.</p><p>A schedule's name is its path under <code>bot/schedules/</code> without the extension. On Cursor hosting, a name has 1 to 100 letters, digits, <code>.</code>, <code>_</code>, <code>-</code>, or <code>/</code>, and starts with a letter or digit. A deploy can hold at most 64 schedules, and <code>deploy</code> rejects one that breaks either rule.</p><h2 id="reminders" tabindex="-1">Reminders <a class="header-anchor" href="#reminders" aria-label="Permalink to "Reminders""></a></h2><p>A reminder belongs to one channel continuation, and it stays armed across restarts. A recurring reminder works like <code>setInterval</code>, and a one-shot reminder works like <code>setTimeout</code>.</p><p>Reminders take a prompt or a named handler. A prompt reminder sends <code>prompt</code> into the conversation when it fires, and <code>until</code> tells the model when to cancel it:</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;"> handle.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">createReminder</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
19
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> purpose: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ci_recheck"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
20
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> channelId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"drive"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
21
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"pr:acme/checkout#42"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
22
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> delay: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"2h"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
23
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> prompt: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Re-check CI. Only act if still failing."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
24
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> until: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Cancel once CI is green or the PR is merged."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
25
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>When host code must decide what happens on each tick, write a named handler. It starts a model turn only if it calls <code>followup</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/reminders/ci_recheck.ts</span></span>
|
|
26
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineReminder } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/reminders"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
27
|
+
<span class="line"></span>
|
|
28
|
+
<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;"> defineReminder</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
29
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> run</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">args</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">followup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
|
|
30
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> followup</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
31
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> message: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`Re-check CI for \${</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">String</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">(</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">args</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prUrl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">)</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.\`</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:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { action: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"delivered"</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 style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Pass its default export as <code>handler</code>, with serializable <code>args</code>:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ciRecheck </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "./bot/reminders/ci_recheck.js"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
36
|
+
<span class="line"></span>
|
|
37
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> handle.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">createReminder</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
38
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> purpose: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ci_recheck"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
39
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> channelId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"drive"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
40
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"pr:acme/checkout#42"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
41
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> every: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"30m"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
42
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> handler: ciRecheck,</span></span>
|
|
43
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> args: { prUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"https://github.com/acme/checkout/pull/42"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
44
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Channel handlers, tools, and schedule runs get the same API as <code>host.reminders</code>. <code>builtinTools: { reminders: true }</code> gives the model <code>reminders_create</code>, <code>reminders_list</code>, and <code>reminders_cancel</code> for the current conversation. See <a href="./agent-config.html#built-in-tools">built-in tools</a>.</p><p><code>--dev</code> doesn't fire reminders on its own. Dispatch one by hand, or call <code>handle.dispatchReminder(id)</code> from code:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/dev/reminders</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # list</span></span>
|
|
45
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -X</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> POST</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/dev/reminders/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">i</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # fire one</span></span></code></pre></div><p>Cancel a reminder when its subject ends, for example on <code>pull_request.closed</code>. Keep wake prompts generic so the agent re-reads live state.</p>`,33)])])}const E=i(t,[["render",h]]);export{c as __pageData,E as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as i,c as
|
|
1
|
+
import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,d,p,k,r){return e(),a("div",null,[...s[0]||(s[0]=[n("",33)])])}const E=i(t,[["render",h]]);export{c as __pageData,E as default};
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives.","frontmatter":{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives."},"headers":[],"relativePath":"reference/sessions.md","filePath":"reference/sessions.md"}'),n={name:"reference/sessions.md"};function d(o,e,r,l,h,c){return a(),t("div",null,[...e[0]||(e[0]=[i(`<h1 id="sessions-events-and-streaming" tabindex="-1">Sessions, events, and streaming <a class="header-anchor" href="#sessions-events-and-streaming" aria-label="Permalink to "Sessions, events, and streaming""></a></h1><p>A session keeps one conversation, its workspace, and an append-only record of every message and tool call.</p><h2 id="session-contents" tabindex="-1">Session contents <a class="header-anchor" href="#session-contents" aria-label="Permalink to "Session contents""></a></h2><p>Each session also has a channel, an authenticated caller, an NDJSON event stream, and state that survives a restart. Sessions belong to the principal that created them. Another caller gets <code>403</code> from that session's routes.</p><h2 id="session-identifiers" tabindex="-1">Session identifiers <a class="header-anchor" href="#session-identifiers" aria-label="Permalink to "Session identifiers""></a></h2><table tabindex="0"><thead><tr><th>Identifier</th><th>Use it for</th></tr></thead><tbody><tr><td><code>continuationToken</code></td><td>Continue a conversation through its channel</td></tr><tr><td><code>sessionId</code></td><td>Stream events, inspect state, or run a session-bound tool call</td></tr></tbody></table><p>Each channel picks its token format, such as a Slack thread or <code>pr:owner/repo#1</code>. The built-in HTTP API returns an opaque token and rotates it after each accepted follow-up, so a stale HTTP token returns <code>409</code>.</p><h2 id="session-modes" tabindex="-1">Session modes <a class="header-anchor" href="#session-modes" aria-label="Permalink to "Session modes""></a></h2><p>HTTP sessions, channel <code>send</code>, Slack, and MCP <code>ask</code> create <code>chat</code> sessions, which wait in <code>session.waiting</code> for follow-ups. Markdown schedules and fire-and-forget dispatch create <code>task</code> sessions, which end in <code>session.completed</code> or <code>session.failed</code>. A follow-up to a task session returns <code>409</code>.</p><h2 id="follow-ups" tabindex="-1">Follow-ups <a class="header-anchor" href="#follow-ups" aria-label="Permalink to "Follow-ups""></a></h2><p>A follow-up starts a turn right away on an idle session. On a busy one, the channel decides what happens.</p><table tabindex="0"><thead><tr><th>Path</th><th>Busy-session policy</th></tr></thead><tbody><tr><td>HTTP playground, <code>POST /v1/session/:id</code>, MCP <code>ask</code></td><td>Preempt (the default). Interrupts the running turn, then runs the new message</td></tr><tr><td>Slack mentions, DMs, alert-watch</td><td>Coalesce. The running turn may pick up the follow-up at a tool boundary, and the rest become one turn when it finishes</td></tr></tbody></table><p>Pass <code>admission: "coalesce"</code> on <code>send()</code> to use the Slack policy from other callers.</p><p><code>POST /v1/session/:id/stop</code> interrupts a turn without sending a message. The stream records <code>turn.failed</code> with <code>status: "cancelled"</code>, and the session can take another follow-up. A Slack message that is only <code>stop</code> or <code>@agent stop</code> does the same for its thread and clears pending coalesced follow-ups.</p><h3 id="track-which-follow-up-reached-the-agent" tabindex="-1">Track which follow-up reached the agent <a class="header-anchor" href="#track-which-follow-up-reached-the-agent" aria-label="Permalink to "Track which follow-up reached the agent""></a></h3><p>Every <code>send()</code> returns a <code>deliveryId</code>. Pass your own, such as a webhook delivery ID, or omit it to get a fresh <code>dlv_…</code> ID. A coalesced follow-up reaches the agent in one of two ways.</p><table tabindex="0"><thead><tr><th>Path</th><th>Event</th><th>Field</th></tr></thead><tbody><tr><td>Steered into the running turn</td><td><code>nudge.delivered</code></td><td><code>data.deliveryId</code></td></tr><tr><td>Fell back to the next turn</td><td>That turn's <code>message.received</code></td><td><code>data.deliveryIds</code></td></tr></tbody></table><p><code>message.received</code> lists every send its prompt carries in arrival order, so one turn can carry several IDs.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// In a route or channel hook: name the steer after the webhook delivery.</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">await</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;">\`Incident \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">incident</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">id</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">} was acknowledged.\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> continuationToken: incident.id,</span></span>
|
|
4
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> admission: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"coalesce"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> deliveryId: webhookId,</span></span>
|
|
6
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
|
|
7
|
+
<span class="line"></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// In the channel's \`events\` map:</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> steered</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Set</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"><</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">>();</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> prompted</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Set</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"><</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">>();</span></span>
|
|
11
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> events</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ChannelEventHandlers</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "nudge.delivered"</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;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
13
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (event.data.deliveryId </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>
|
|
14
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> steered.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">add</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(event.data.deliveryId);</span></span>
|
|
15
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
16
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
17
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "message.received"</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;">event</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
18
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> id</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> of</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> event.data.deliveryIds </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:#24292E;--shiki-dark:#E1E4E8;"> prompted.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">add</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(id);</span></span>
|
|
20
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
21
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
22
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">};</span></span></code></pre></div><p>In a local Slack session, a <code>nudge.delivered</code> event with no <code>deliveryId</code> came from a new Slack message, not from a <code>send()</code> call.</p><h2 id="stream-events" tabindex="-1">Stream events <a class="header-anchor" href="#stream-events" aria-label="Permalink to "Stream events""></a></h2><p>Each NDJSON line is a <code>{ type, index, sessionId, turnId?, at, data }</code> envelope. The <code>index</code> increases within one session, and <code>at</code> is an ISO-8601 timestamp.</p><table tabindex="0"><thead><tr><th>Phase</th><th>Events</th><th>What they tell you</th></tr></thead><tbody><tr><td>Session</td><td><code>session.started</code>, <code>session.waiting</code>, <code>session.completed</code>, <code>session.failed</code></td><td>Creation, readiness, and task completion</td></tr><tr><td>Input</td><td><code>message.received</code>, <code>nudge.delivered</code></td><td>A prompt was accepted or reached a running turn. Both carry <a href="#track-which-follow-up-reached-the-agent">delivery IDs</a></td></tr><tr><td>Turn</td><td><code>turn.queued</code>, <code>turn.started</code>, <code>turn.completed</code>, <code>turn.failed</code></td><td>Queueing under <a href="./agent-config.html#concurrency"><code>maxRunningTurns</code></a>, then status, result, and token usage</td></tr><tr><td>Steps</td><td><code>step.started</code>, <code>step.completed</code></td><td>Model step boundaries and duration</td></tr><tr><td>Reasoning</td><td><code>reasoning.appended</code>, <code>reasoning.completed</code></td><td>Streamed reasoning blocks</td></tr><tr><td>Reply</td><td><code>message.appended</code>, <code>message.completed</code></td><td>Text deltas and finished assistant messages</td></tr><tr><td>Tools</td><td><code>actions.requested</code>, <code>actions.completed</code>, <code>action.result</code>, <code>action.tool_retry</code></td><td>Tool names, arguments, outputs, and errors. <code>action.tool_retry</code> marks a read retried after a transient failure</td></tr><tr><td>Subagents</td><td><code>subagent.called</code>, <code>subagent.completed</code></td><td>Delegated work</td></tr><tr><td>Artifacts</td><td><code>artifact.tagged</code></td><td>An <a href="./artifacts.html">artifact</a> was tagged</td></tr></tbody></table><p><code>actions.requested</code> and <code>actions.completed</code> bracket each model step's tool batch, and <code>action.result</code> carries each call live. Read <code>turn.completed.data.usage</code> for token counts. <a href="./http-api.html#stream-or-replay-session-events">HTTP API</a> shows how to follow the stream.</p><h2 id="local-session-workspace" tabindex="-1">Local session workspace <a class="header-anchor" href="#local-session-workspace" aria-label="Permalink to "Local session workspace""></a></h2><p>Agent SDK creates a workspace before the first local turn.</p><table tabindex="0"><thead><tr><th>Source path</th><th>Lands as</th></tr></thead><tbody><tr><td><code>skills/*</code></td><td><code>.cursor/skills/<name>/SKILL.md</code></td></tr><tr><td>agent tools (<code>execution: "agent"</code>)</td><td>Scripts listed in the system prompt</td></tr><tr><td><code>sandbox/workspace/**</code></td><td>Seed files</td></tr><tr><td>per-send <code>workspaceFiles</code></td><td>Files written before the turn</td></tr></tbody></table><p>On a local turn, Agent SDK sends the instructions as the system prompt, and on a turn in the cloud it includes them in the first user message. Nothing is written into the session workspace as <code>AGENTS.md</code>. See <a href="./instructions.html">Instructions</a>.</p><p>A channel can give one session a different directory, such as a PR worktree. <a href="./agent-config.html#local-cwd">Agent config</a> covers what parent directories add.</p><h2 id="session-storage" tabindex="-1">Session storage <a class="header-anchor" href="#session-storage" aria-label="Permalink to "Session storage""></a></h2><p>Local session state lives under <code>--state-root</code>, in a subdirectory named for the slug on a slugged mount. Deleting a session directory removes the session from the server.</p><h2 id="inspect-a-saved-event-stream" tabindex="-1">Inspect a saved event stream <a class="header-anchor" href="#inspect-a-saved-event-stream" aria-label="Permalink to "Inspect a saved event stream""></a></h2><p><code>agent-sdk session get --file <state-root>/traces/<sessionId>.ndjson</code> prints a saved trace's tool calls, reply, and token usage in the same JSON shape as <code>run</code>. For a session on a running server, <code>agent-sdk session get <sessionId> --view events</code> prints the raw event list. The playground's <strong>Trace</strong> view shows a timeline.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to "Related""></a></h2><ul><li><a href="./http-api.html">HTTP API</a></li><li><a href="./hooks.html">Hooks</a></li><li><a href="./tools.html">Tools</a></li></ul>`,35)])])}const g=s(n,[["render",d]]);export{k as __pageData,g as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives.","frontmatter":{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives."},"headers":[],"relativePath":"reference/sessions.md","filePath":"reference/sessions.md"}'),n={name:"reference/sessions.md"};function o
|
|
1
|
+
import{_ as s,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives.","frontmatter":{"title":"Sessions, events, and streaming","description":"Understand how conversations continue, how events stream, and where session data lives."},"headers":[],"relativePath":"reference/sessions.md","filePath":"reference/sessions.md"}'),n={name:"reference/sessions.md"};function d(o,e,r,l,h,c){return a(),t("div",null,[...e[0]||(e[0]=[i("",35)])])}const g=s(n,[["render",d]]);export{k as __pageData,g as default};
|
package/dist/docs/assets/{reference_skills.md.Dej2zQxi.js → reference_skills.md.DzCPNPkG.js}
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import{_ as i,c as e,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),
|
|
2
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">
|
|
3
|
-
<span class="line"><span style="--shiki-light:#
|
|
1
|
+
import{_ as i,c as e,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),n={name:"reference/skills.md"};function l(h,s,r,o,d,k){return t(),e("div",null,[...s[0]||(s[0]=[a(`<h1 id="skills" tabindex="-1">Skills <a class="header-anchor" href="#skills" aria-label="Permalink to "Skills""></a></h1><p>A skill is an on-demand procedure in the <code>SKILL.md</code> convention. Agent SDK advertises each skill by its description, and the model loads a skill only when the task calls for it. Skills give an agent a multi-step workflow without carrying it in the always-on <a href="./instructions.html">instructions</a>.</p><h2 id="authoring-forms" tabindex="-1">Authoring forms <a class="header-anchor" href="#authoring-forms" aria-label="Permalink to "Authoring forms""></a></h2><table tabindex="0"><thead><tr><th>Form</th><th>Reach for it when</th></tr></thead><tbody><tr><td><code>bot/skills/<name>.md</code></td><td>Static Markdown. <code>description</code> frontmatter is optional and falls back to the first body line</td></tr><tr><td><code>bot/skills/<name>/SKILL.md</code> plus siblings</td><td>A packaged directory with reference files. Requires <code>description</code> frontmatter</td></tr><tr><td><code>bot/skills/<name>.ts</code></td><td>Generated content, with <code>defineSkill</code> from <code>@grok/agent-sdk/skills</code></td></tr></tbody></table><p>Use flat Markdown for static content:</p><div class="language-md vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">md</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">description</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Use when a pull request needs a structured approval checklist.</span></span>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
|
|
4
4
|
<span class="line"></span>
|
|
5
5
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-light-font-weight:bold;--shiki-dark:#79B8FF;--shiki-dark-font-weight:bold;"># PR review checklist</span></span>
|
|
6
6
|
<span class="line"></span>
|
|
@@ -12,4 +12,4 @@ import{_ as i,c as e,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c
|
|
|
12
12
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Research unfamiliar topics before answering."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
13
13
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> markdown: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Gather evidence first, then answer with the key facts."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
14
14
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> files: { </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"references/checklist.md"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"# Checklist</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">- Find sources.</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>
|
|
15
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="skill-delivery" tabindex="-1">Skill delivery <a class="header-anchor" href="#skill-delivery" aria-label="Permalink to "Skill delivery""></a></h2><p>
|
|
15
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="skill-delivery" tabindex="-1">Skill delivery <a class="header-anchor" href="#skill-delivery" aria-label="Permalink to "Skill delivery""></a></h2><p>Local sessions get each skill at <code>.cursor/skills/<name>/SKILL.md</code> in the session workspace, and the agent lists and loads them from there.</p><h2 id="skills-instructions-and-tools" tabindex="-1">Skills, instructions, and tools <a class="header-anchor" href="#skills-instructions-and-tools" aria-label="Permalink to "Skills, instructions, and tools""></a></h2><p>Instructions stay in context on every turn. Skills hold procedures, checklists, and house style that the model needs only sometimes. Put anything that must be correct every time in a typed <a href="./tools.html">tool</a>, where the model can't paraphrase it.</p><p>A description is a routing hint, so say when to use the skill, as the checklist example does. The model sees only the description before it decides to load the skill.</p>`,13)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as i,c as e,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),
|
|
1
|
+
import{_ as i,c as e,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms.","frontmatter":{"title":"Skills","description":"On-demand procedures the model loads only when relevant, in three authoring forms."},"headers":[],"relativePath":"reference/skills.md","filePath":"reference/skills.md"}'),n={name:"reference/skills.md"};function l(h,s,r,o,d,k){return t(),e("div",null,[...s[0]||(s[0]=[a("",13)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import{_ as s,c as t,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(d,e,r,l,c,p){return a(),t("div",null,[...e[0]||(e[0]=[n(`<h1 id="subagents" tabindex="-1">Subagents <a class="header-anchor" href="#subagents" aria-label="Permalink to "Subagents""></a></h1><p>A subagent is a specialist child agent the model can delegate to mid-turn. Each one lives under <code>bot/subagents/<id>/</code> with a required <code>agent.ts</code>.</p><p>Add <code>instructions.md</code>, or inline <code>instructions</code> in <code>agent.ts</code>, for a custom prompt. Omit <code>model</code> to inherit the parent's model.</p><p>The parent model reads <code>description</code> to decide whether to delegate, so write it the way you write a <a href="./skills.html#skills-instructions-and-tools">skill description</a>.</p><p>The parent delegates through the <code>task</code> tool. A parent that limits its <a href="./agent-config.html#harness-tools">built-in tools</a> must list <code>"task"</code>.</p><p>The stream records <code>subagent.called</code> and <code>subagent.completed</code>. <code>subagent.completed</code> has <code>isError: true</code> when the subagent failed or was cancelled.</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>bot/subagents/researcher/</span></span>
|
|
2
|
+
<span class="line"><span>├── agent.ts # description (required), model (optional)</span></span>
|
|
3
|
+
<span class="line"><span>└── instructions.md # optional custom system prompt</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/subagents/researcher/agent.ts</span></span>
|
|
4
|
+
<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>
|
|
5
|
+
<span class="line"></span>
|
|
6
|
+
<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>
|
|
7
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description:</span></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "Background research: climate history, records, comparisons across many cities."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // model: omit to inherit the parent's model</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="subagent-rules" tabindex="-1">Subagent rules <a class="header-anchor" href="#subagent-rules" aria-label="Permalink to "Subagent rules""></a></h2><p>Subagents inherit the parent's execution surface. Discovery warns about and ignores these directories inside a subagent: <code>tools/</code>, <code>skills/</code>, <code>extensions/</code>, <code>mcp-connections/</code>, <code>host-connections/</code>, <code>channels/</code>, <code>schedules/</code>, <code>reminders/</code>, <code>hooks/</code>, <code>sandbox/</code>, and nested <code>subagents/</code>.</p><p>The parent's <a href="./instructions.html">instructions</a> should say when to delegate, such as "When a request needs background research, delegate to the <code>researcher</code> subagent."</p><h2 id="subagents-and-peers" tabindex="-1">Subagents and peers <a class="header-anchor" href="#subagents-and-peers" aria-label="Permalink to "Subagents and peers""></a></h2><p>Subagents split one job into roles inside a single agent. When the specialist is independently useful, with its own tools, sessions, and playground, make it a full agent. See <a href="./../guides/agent-to-agent.html#peer-or-subagent">Peer agents</a>.</p>`,13)])])}const g=s(i,[["render",o]]);export{u as __pageData,g as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as s,c as
|
|
1
|
+
import{_ as s,c as t,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/.","frontmatter":{"title":"Subagents","description":"Specialist child agents the model delegates to mid-turn, each its own directory under bot/subagents/."},"headers":[],"relativePath":"reference/subagents.md","filePath":"reference/subagents.md"}'),i={name:"reference/subagents.md"};function o(d,e,r,l,c,p){return a(),t("div",null,[...e[0]||(e[0]=[n("",13)])])}const g=s(i,[["render",o]]);export{u as __pageData,g as default};
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import{_ as i,c as t,o as e,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, control their dry-run effects, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, control their dry-run effects, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,d,p,r){return e(),t("div",null,[...s[0]||(s[0]=[a(`<h1 id="tools" tabindex="-1">Tools <a class="header-anchor" href="#tools" aria-label="Permalink to "Tools""></a></h1><p>A tool is a typed action the model can call, such as hitting an API, running a query, or writing a file. Each file in <code>bot/tools/</code> defines one tool, and the filename is the name the model sees. Server tools run on the serving host, and agent tools run as scripts next to the agent.</p><h2 id="define-a-server-tool" tabindex="-1">Define a server tool <a class="header-anchor" href="#define-a-server-tool" aria-label="Permalink to "Define a server tool""></a></h2><p>By default, <code>execute</code> runs in-process on the serving host with full access to <code>process.env</code> and your <code>bot/lib/</code> code. <code>execution: "server"</code> is the default.</p><p>A tool needs a filename slug (the model-facing name), a <code>description</code> written for the model, an optional <code>inputSchema</code>, and the code that runs it. With a Zod schema, Agent SDK validates the input and infers its type. With plain JSON Schema, <code>execute</code> gets raw JSON.</p><p><code>prompt</code> from <code>@grok/agent-sdk</code> or <code>@grok/agent-sdk/prompt</code> dedents a template literal so a multi-line description, reminder, or error can sit indented in TypeScript. Blank lines and relative indentation stay. <code>prompt.lines</code> returns the same text as <code>string[]</code>, one entry per line.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">context</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: prompt.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">lines</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Merged PR detected: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">pr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">url</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">} by \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">author</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}.</span></span>
|
|
3
|
+
<span class="line"></span>
|
|
4
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Call plan_deploy, then follow its nextStep.</span></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span></code></pre></div><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { prompt } </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>
|
|
6
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineTool } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/tools"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
7
|
+
<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>
|
|
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;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">prompt</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span></span>
|
|
11
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Inspect a pull request before approval.</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Prefer this over guessing from the title alone.</span></span>
|
|
13
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> \`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
14
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ prUrl: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">url</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
|
|
15
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prUrl</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;"> { prUrl };</span></span>
|
|
17
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
18
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h3 id="tool-context" tabindex="-1">Tool context <a class="header-anchor" href="#tool-context" aria-label="Permalink to "Tool context""></a></h3><p><code>execute</code> receives a <code>ctx</code> with the runtime accessors:</p><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.toolCallId</code></td><td>The call id, matching the <code>actions.requested</code> / <code>action.result</code> stream events</td></tr><tr><td><code>ctx.session</code></td><td>Read-only session info: id, channel, mode, auth</td></tr><tr><td><code>ctx.approvedBy</code></td><td>Auth of whoever approved a <code>needsApproval</code> call, same shape as <code>ctx.session.auth</code>. On Slack, <code>attributes.user_id</code> is the person who clicked Approve. Unset when the call needed no approval</td></tr><tr><td><code>ctx.workspaceDir</code></td><td>The session's workspace directory</td></tr><tr><td><code>ctx.stateRoot</code></td><td>The agent's durable state root, shared across every session</td></tr><tr><td><code>ctx.host</code></td><td>Shared host services (see below)</td></tr><tr><td><code>ctx.send(channelId, message, options?)</code></td><td>Start or resume a session on any channel. <code>auth</code> defaults to this call's session principal</td></tr><tr><td><code>ctx.getSession(channelId, sessionId)</code></td><td>Look up a session on a channel</td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade: <code>tag</code> auto-fills the session</td></tr></tbody></table><p><code>ctx.host</code> has <code>mcp</code>, <code>github</code>, <code>slack</code>, <code>kv</code>, <code>files</code>, and <code>reminders</code>. Custom metrics use the <a href="./../guides/opentelemetry.html">OpenTelemetry</a> API.</p><h3 id="return-values" tabindex="-1">Return values <a class="header-anchor" href="#return-values" aria-label="Permalink to "Return values""></a></h3><p><code>execute</code> may return a string, a JSON-shaped value, or <code>{ content: [...], isError? }</code>. Use object literals or <code>type</code> aliases, since an <code>interface</code> return fails typecheck with no index signature. If <code>execute</code> throws, the model gets the error and the turn keeps going.</p><h3 id="declare-structured-output" tabindex="-1">Declare structured output <a class="header-anchor" href="#declare-structured-output" aria-label="Permalink to "Declare structured output""></a></h3><p>Set <code>outputSchema</code> when MCP clients need a structured result contract. Use a Zod schema or plain JSON Schema:</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;"> Weather</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><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>
|
|
19
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> city: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
|
|
20
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> temperatureF: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">number</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>
|
|
23
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
24
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Read the current weather."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
25
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ city: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
|
|
26
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> outputSchema: Weather,</span></span>
|
|
27
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">city</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
|
|
28
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { city, temperatureF: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">72</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
|
|
29
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
30
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Agent SDK advertises the schema and does not validate results against it. A plain object fills MCP <code>structuredContent</code>. An envelope must set <code>structuredContent</code> next to <code>content</code> and <code>isError</code>.</p><h3 id="control-dry-run-effects" tabindex="-1">Control dry-run effects <a class="header-anchor" href="#control-dry-run-effects" aria-label="Permalink to "Control dry-run effects""></a></h3><p>Set <code>effect</code> to <code>"read"</code>, <code>"write"</code>, <code>"idempotent"</code>, or a predicate over the validated input. A dry-run session runs reads and stubs writes and idempotent calls. A tool with no <code>effect</code> is a write. <code>"idempotent"</code> can change something outside the session, and repeating the same arguments has no further effect.</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;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
31
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Publish a release."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
32
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ version: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
|
|
33
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> effect: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"write"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
34
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> dryRunResult</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: ({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">version</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;"> ({ published: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, version }),</span></span>
|
|
35
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
|
|
36
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> publishRelease</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(version);</span></span>
|
|
37
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
38
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Set <code>dryRunResult</code> so a stubbed write returns the real shape. Without it, the write returns "Operation acknowledged." Traces mark the result as stubbed.</p><h3 id="retry-a-transient-read-or-idempotent-call" tabindex="-1">Retry a transient read or idempotent call <a class="header-anchor" href="#retry-a-transient-read-or-idempotent-call" aria-label="Permalink to "Retry a transient read or idempotent call""></a></h3><p>If a read or an idempotent call fails with a transient error, Agent SDK tries it up to 3 times before the model sees the error. It runs writes, and tools that don't declare an effect, only once. Agent SDK retries an MCP tool when the tool's annotations mark it read-only, or when the tool sets <code>idempotentHint: true</code> together with an explicit <code>destructiveHint</code>. If the call still fails, the tool error is the last attempt's message.</p><h3 id="bound-time-arguments-under-asof" tabindex="-1">Bound time arguments under <code>asOf</code> <a class="header-anchor" href="#bound-time-arguments-under-asof" aria-label="Permalink to "Bound time arguments under \`asOf\`""></a></h3><p><code>timeArgs</code> names the input fields that carry time bounds. In a session created with <code>asOf</code>, each named argument must be an absolute ISO-8601 instant with a timezone, no later than that frozen instant. A missing, relative, or later value is refused. Sessions without <code>asOf</code> ignore it.</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;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
39
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Query telemetry between two instants."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
40
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ since: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), until: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
|
|
41
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> effect: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"read"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
42
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> timeArgs: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"since"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"until"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
43
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> async</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> execute</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">since</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">until</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) {</span></span>
|
|
44
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> queryTelemetry</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(since, until);</span></span>
|
|
45
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
46
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Every name in <code>timeArgs</code> must exist in the input schema. A session with <code>asOf</code> refuses to start otherwise, because a misspelled name would check nothing.</p><h2 id="define-an-agent-tool" tabindex="-1">Define an agent tool <a class="header-anchor" href="#define-an-agent-tool" aria-label="Permalink to "Define an agent tool""></a></h2><p>Set <code>execution: "agent"</code> when the tool must run next to the checkout. The script receives JSON on stdin and prints its result on stdout.</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;"> defineTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
47
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Echo a message from the agent workspace."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
48
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> execution: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"agent"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
49
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> inputSchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ message: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() }),</span></span>
|
|
50
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> script: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`#!/usr/bin/env bash</span></span>
|
|
51
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">set -euo pipefail</span></span>
|
|
52
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">python3 -c 'import json,sys; print(json.load(sys.stdin)["message"])'</span></span>
|
|
53
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
54
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Agent SDK copies the scripts into the workspace and lists them in the system prompt.</p><h2 id="tools-from-an-mcp-connection-advertised-by-name" tabindex="-1">Tools from an MCP connection, advertised by name <a class="header-anchor" href="#tools-from-an-mcp-connection-advertised-by-name" aria-label="Permalink to "Tools from an MCP connection, advertised by name""></a></h2><p>Set <code>advertiseTools: true</code> on a connection to expose its MCP tools by name. Add per-session <code>auth</code> when credentials depend on the caller. Model calls and <a href="#call-a-tool-without-a-model-turn">direct tool calls</a> use the same exposed names. See <a href="./connections.html#advertise-tools">MCP connections</a> for the full contract.</p><h2 id="call-a-tool-without-a-model-turn" tabindex="-1">Call a tool without a model turn <a class="header-anchor" href="#call-a-tool-without-a-model-turn" aria-label="Permalink to "Call a tool without a model turn""></a></h2><p>You can call any server tool yourself, with your own input and no model turn. Validation and execution match a model-initiated call, and no Cursor API key is needed.</p><p>Over HTTP, with the same auth chain as the session API:</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;"> http://127.0.0.1:3000/</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">/v1/tools/inspect_pr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
55
|
+
<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>
|
|
56
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '{"input":{"prUrl":"https://github.com/acme/checkout/pull/42"}}'</span></span>
|
|
57
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># {"ok":true,"toolName":"inspect_pr","callId":"tool_inspect_pr_…",</span></span>
|
|
58
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># "isError":false,"result":{…},"durationMs":12}</span></span></code></pre></div><p>From the CLI. Without <code>--url</code>, this starts an ephemeral server:</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 tool call inspect_pr --dir . \\</span></span>
|
|
59
|
+
<span class="line"><span> --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'</span></span></code></pre></div><p>Programmatically, <code>callTool(toolName, input, options?)</code> is available on the serve handle, on channel route handlers and <code>onStart</code> args, and on schedule <code>run</code> handlers, so a channel can mix deterministic calls with model turns:</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;"> outcome</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;"> handle.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">callTool</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>
|
|
60
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> prUrl: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"https://github.com/acme/checkout/pull/42"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
61
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span>
|
|
62
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// { toolName, callId, isError, result, durationMs }</span></span></code></pre></div><p>Omit both identifiers to run against an ephemeral workspace that is removed when the call returns. Pass <code>sessionId</code> (HTTP body, <code>--session</code>, or <code>options.sessionId</code>) or <code>continuationToken</code> (<code><channelId>:<key></code> as <code>/v1/sessions</code> lists it) to bind the call. The two are mutually exclusive.</p><table tabindex="0"><thead><tr><th>Rule</th><th>What happens</th></tr></thead><tbody><tr><td>Existing <code>sessionId</code>, or a token that maps to an existing session</td><td>Session workspace, owner check, and event recording</td></tr><tr><td>Token with no matching session</td><td>Scratch workspace; the token's channel id and key are the call identity</td></tr><tr><td>Busy session, <code>effect: "read"</code> (or an advertised MCP tool marked read-only)</td><td>Runs alongside the turn, reading the workspace as the turn left it; recorded under its own <code>turnId</code></td></tr><tr><td>Busy session, write, idempotent, or undeclared</td><td><code>409 session_busy</code> until the turn finishes</td></tr><tr><td>Session workspace cannot be created, read</td><td>Scratch workspace; the outcome has <code>scratchWorkspace: true</code></td></tr><tr><td>Session workspace cannot be created, write</td><td><code>500 workspace_unavailable</code></td></tr></tbody></table><table tabindex="0"><thead><tr><th>Error</th><th>When</th></tr></thead><tbody><tr><td><code>404 unknown_tool</code></td><td>Name is not a callable server tool; the response lists available names</td></tr><tr><td><code>400 tool_not_callable</code></td><td>Agent-execution tools cannot run on the host</td></tr><tr><td><code>400 invalid_tool_input</code></td><td>Zod rejected the input before <code>execute</code>. Plain JSON Schema is forwarded unvalidated</td></tr><tr><td><code>400 invalid_continuation_token</code></td><td>Malformed token, or passed together with <code>sessionId</code></td></tr><tr><td><code>404 session_not_found</code></td><td><code>sessionId</code> does not exist</td></tr><tr><td><code>409 session_busy</code></td><td>Write-effect call while a model turn is running</td></tr><tr><td><code>500 workspace_unavailable</code></td><td>Write-effect call when the session workspace cannot be created</td></tr><tr><td><code>isError: true</code></td><td>The tool body threw; same envelope the model would see</td></tr></tbody></table><p>See also <a href="./connections.html">MCP connections</a>, <a href="./extensions.html">Extensions</a>, and <a href="./../evals.html">Evals</a>.</p>`,46)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
|
package/dist/docs/assets/{reference_tools.md.DQr7Fnhu.lean.js → reference_tools.md.B2OaR1Nb.lean.js}
RENAMED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as i,c as
|
|
1
|
+
import{_ as i,c as t,o as e,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Tools","description":"Define typed actions the model can call, control their dry-run effects, and call any server tool without a model turn.","frontmatter":{"title":"Tools","description":"Define typed actions the model can call, control their dry-run effects, and call any server tool without a model turn."},"headers":[],"relativePath":"reference/tools.md","filePath":"reference/tools.md"}'),n={name:"reference/tools.md"};function l(h,s,o,d,p,r){return e(),t("div",null,[...s[0]||(s[0]=[a("",46)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import{_ as s,c as i,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows.","frontmatter":{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."},"headers":[],"relativePath":"templates/agentic-owners.md","filePath":"templates/agentic-owners.md"}'),n={name:"templates/agentic-owners.md"};function o(l,e,r,h,d,p){return a(),i("div",null,[...e[0]||(e[0]=[t(`<h1 id="review-pull-requests-with-owners-policies" tabindex="-1">Review pull requests with owners policies <a class="header-anchor" href="#review-pull-requests-with-owners-policies" aria-label="Permalink to "Review pull requests with owners policies""></a></h1><p>This agent risk-tiers every pull request in your repository, requests the owners as reviewers, and approves what your policy allows. Rules live in <code>.agentic-owners/policy.yml</code> files at any depth. The closest policy to a changed file wins. The agent reads policies from the PR's base ref, so a PR can't exempt itself.</p><h2 id="scaffold-and-run" tabindex="-1">Scaffold and run <a class="header-anchor" href="#scaffold-and-run" aria-label="Permalink to "Scaffold and run""></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> init</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ./owners-agent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --template</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> agentic-owners</span></span></code></pre></div><p>Set your repositories in <code>bot/lib/config.ts</code> (<code>repos: ["acme/api"]</code>), then run:</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:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> owners-agent</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dev</span></span></code></pre></div><p>PR events stream through your Cursor account, so you don't need a webhook or GitHub App. The agent reviews a PR when it's opened, reopened, pushed to, marked ready for review, or retargeted, and skips drafts. Open a PR or replay a real one:</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;"> github</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> replay</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/acme/api/pull/123</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>Deploy with <code>agent-sdk deploy</code>.</p><h2 id="policies" tabindex="-1">Policies <a class="header-anchor" href="#policies" aria-label="Permalink to "Policies""></a></h2><p>With no policy files, the agent approves very-low and low risk PRs and holds medium and above with a comment. Commit policies to route reviews:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</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;"># .agentic-owners/policy.yml at any depth; the closest policy wins.</span></span>
|
|
4
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">version</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">policies</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
|
6
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">paths</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"docs/**"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
|
|
7
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> always_approve</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">paths</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"src/api/**"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> team</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">platform</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # bare slug in the repo's org; or acme/platform, or user: alice</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> prompt</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">api-review.md</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # optional extra rubric, same directory</span></span>
|
|
11
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">paths</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"src/billing/**"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> users</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">alice</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">bob</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]</span></span>
|
|
13
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> mode</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">hard</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # the agent never approves; a person must</span></span></code></pre></div><p><code>paths</code> are relative to the policy's parent directory, so <code>src/.agentic-owners/policy.yml</code> matches <code>api/**</code> against <code>src/api/**</code>. A leading <code>../</code> reaches a sibling tree inside the repo.</p><table tabindex="0"><thead><tr><th>Key</th><th>Meaning</th></tr></thead><tbody><tr><td><code>paths</code></td><td>Required globs</td></tr><tr><td><code>team</code>, <code>teams</code></td><td>Owner teams, as a slug in the repo's org or an <code>org/team</code> handle</td></tr><tr><td><code>user</code>, <code>users</code></td><td>Owner GitHub logins, without <code>@</code></td></tr><tr><td><code>prompt</code></td><td>Extra rubric file beside the policy</td></tr><tr><td><code>mode</code></td><td><code>advisory</code>, the default, approves low risk. <code>hard</code> requires a person to approve. <code>notify</code> never blocks and doesn't request its owners</td></tr><tr><td><code>human_review_required</code></td><td><code>true</code> is the older spelling of <code>mode: hard</code></td></tr><tr><td><code>self_review</code></td><td>A listed <code>user:</code> owner's own PRs clear this rule</td></tr><tr><td><code>always_approve</code></td><td>Satisfied at every risk tier. Allows no other key except <code>paths</code></td></tr></tbody></table><ul><li>A rule without owners must set <code>always_approve: true</code>.</li><li><code>global_exclusions</code> in the root policy opts paths out entirely.</li><li>The template rejects <code>delegated_automations</code>.</li></ul><h2 id="what-one-review-does" tabindex="-1">What one review does <a class="header-anchor" href="#what-one-review-does" aria-label="Permalink to "What one review does""></a></h2><ul><li>One model turn per PR head grades the diff against the base rubric and matched rule prompts, then calls <code>record_review</code> with <code>very_low</code>, <code>low</code>, <code>medium</code>, <code>medium_high</code>, or <code>high</code>. The model never writes to GitHub.</li><li>The host recomputes the policy from trusted state. It approves when every matched rule is <code>always_approve</code> or <code>notify</code>. Otherwise it approves only when the author's <code>self_review</code> clears every matched <code>hard</code> rule at very low or low risk, or every rule that can require review at medium and above.</li><li>When the agent holds, it requests up to two owners, never the author, and updates one status comment in place.</li><li>An approval binds to the head SHA. A later hold dismisses the agent's earlier approvals.</li><li>The agent holds when the PR edits <code>.agentic-owners/</code> or <code>CODEOWNERS</code>, or when the diff is empty or GitHub truncated the diff or file list. <code>self_review</code> never clears a governance edit.</li><li>A broken policy file fails closed and comments with the validation issues.</li></ul><h2 id="rubric" tabindex="-1">Rubric <a class="header-anchor" href="#rubric" aria-label="Permalink to "Rubric""></a></h2><p>Edit <code>bot/lib/owners/prompts/base-review.md</code> to change the risk tiers. Put per-area guidance in policy <code>prompt:</code> files.</p><h2 id="evals" tabindex="-1">Evals <a class="header-anchor" href="#evals" aria-label="Permalink to "Evals""></a></h2><p><code>agent-sdk eval</code> runs three smoke reviews without writing to GitHub. They cover a docs-only change, an auth deletion, and a prompt injection.</p>`,21)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as s,c as i,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows.","frontmatter":{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."},"headers":[],"relativePath":"templates/agentic-owners.md","filePath":"templates/agentic-owners.md"}'),
|
|
1
|
+
import{_ as s,c as i,o as a,a3 as t}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows.","frontmatter":{"title":"Review pull requests with owners policies","description":"Scaffold the agent, commit .agentic-owners policies, and let it risk-tier PRs, request the owners, and approve what the policy allows."},"headers":[],"relativePath":"templates/agentic-owners.md","filePath":"templates/agentic-owners.md"}'),n={name:"templates/agentic-owners.md"};function o(l,e,r,h,d,p){return a(),i("div",null,[...e[0]||(e[0]=[t("",21)])])}const u=s(n,[["render",o]]);export{k as __pageData,u as default};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import{_ as t,c as a,o as s,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Review and triage templates","description":"Scaffold a pull request reviewer or an issue triager, try it locally, and deploy it.","frontmatter":{"title":"Review and triage templates","description":"Scaffold a pull request reviewer or an issue triager, try it locally, and deploy it."},"headers":[],"relativePath":"templates/reviews.md","filePath":"templates/reviews.md"}'),n={name:"templates/reviews.md"};function o(r,e,d,l,p,c){return s(),a("div",null,[...e[0]||(e[0]=[i(`<h1 id="review-and-triage-templates" tabindex="-1">Review and triage templates <a class="header-anchor" href="#review-and-triage-templates" aria-label="Permalink to "Review and triage templates""></a></h1><p>Each template is one model turn. A review template reads the diff and posts one comment, and the triage template comments on a ticket you already filed.</p><table tabindex="0"><thead><tr><th>Template</th><th><code>--template</code> id</th><th>What it posts</th><th>Channel</th></tr></thead><tbody><tr><td>Security reviewer</td><td><code>security-reviewer</code></td><td>One comment on exploitable bugs, such as injection, authz bypass, secret leaks, SSRF, and RCE</td><td>GitHub</td></tr><tr><td>Thermo review</td><td><code>thermo-review</code></td><td>One comment on bugs, breaking side effects, and unintended feature exposure</td><td>GitHub</td></tr><tr><td>Thermo quality review</td><td><code>thermo-quality-review</code></td><td>One comment on structure, such as missing abstractions, deep nesting, and files past 1,000 lines</td><td>GitHub</td></tr><tr><td>Triage</td><td><code>triage-linear</code>, <code>triage-jira</code>, or <code>triage</code></td><td>A <code>Triage:</code> comment, a bug priority, and a duplicate link when titles match</td><td>Linear or Jira</td></tr></tbody></table><p><code>triage</code> is short for <code>triage-linear</code>. No review template comments on style, and the quality template doesn't argue about behavior.</p><p>The <a href="./agentic-owners.html">Agentic Approver</a> template is separate. It applies an owners policy instead of posting one findings comment.</p><h2 id="scaffold" tabindex="-1">Scaffold <a class="header-anchor" href="#scaffold" aria-label="Permalink to "Scaffold""></a></h2><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 init ./security-reviewer --template security-reviewer \\</span></span>
|
|
2
|
+
<span class="line"><span> --var repos=acme/api</span></span></code></pre></div><p>Swap the folder and the <code>--template</code> id for the row you want. <code>--var repos</code> is only for <code>security-reviewer</code>. Name repositories already connected in Cursor, separated by commas, and they must share one owner. <code>init</code> writes that list to <code>bot/lib/repos.ts</code>.</p><h2 id="try-it-locally" tabindex="-1">Try it locally <a class="header-anchor" href="#try-it-locally" aria-label="Permalink to "Try it locally""></a></h2><p>Connect GitHub in Cursor for the repositories you watch (Settings or <a href="https://cursor.com/dashboard" target="_blank" rel="noreferrer">cursor.com/dashboard</a>), then sign the host in with <code>agent-sdk login</code>. The <a href="./../guides/github.html">GitHub guide</a> covers <code>cursorAccount</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 dev --cursor-events --repo acme/api</span></span>
|
|
3
|
+
<span class="line"><span>agent-sdk github replay https://github.com/acme/api/pull/12 --dir .</span></span></code></pre></div><p>You need pull access to replay. The channel skips drafts, writes the diff to <code>pr/diff.patch</code>, and starts a turn. The model calls <code>post_findings</code> once, and that call writes the GitHub comment. Chat replies stay in the playground.</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</span></span></code></pre></div><p>Eval sessions skip the GitHub write. Edit <code>bot/instructions.md</code> for what counts as a finding, and edit <code>evals/review.eval.ts</code> for the smoke cases.</p><h2 id="deploy" tabindex="-1">Deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to "Deploy""></a></h2><p>From the agent's git checkout:</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>
|
|
4
|
+
<span class="line"><span>agent-sdk deploy --cursor-events-repo acme/api</span></span></code></pre></div><p>Repeat <code>--cursor-events-repo</code> for each repository, and every repository must share one owner. The deployment watches those repositories through your team's Cursor GitHub connection, and you can change the list later without a redeploy:</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 deployment update my-agent --event-repo acme/api --event-repo acme/web</span></span></code></pre></div><h2 id="triage-a-tracker" tabindex="-1">Triage a tracker <a class="header-anchor" href="#triage-a-tracker" aria-label="Permalink to "Triage a tracker""></a></h2><p>The template runs after someone files a ticket, so keep filing them as you do now. Connect Linear or Jira under MCP in the Cursor dashboard, then run <code>agent-sdk dev</code> and open <code>/queue/issue</code> in the playground.</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;"> http://127.0.0.1:3000/triage-agent/v1/channels/queue/issue</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
5
|
+
<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>
|
|
6
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '{</span></span>
|
|
7
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "identifier": "ENG-142",</span></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "title": "CSV export returns 500",</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "description": "Export has returned 500 since this morning."</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> }'</span></span></code></pre></div><p>For create webhooks, set <code>LINEAR_WEBHOOK_SECRET</code> or <code>JIRA_WEBHOOK_SECRET</code> and point the provider at <code>/v1/channels/webhook</code> on the deployed alias. <code>record_triage</code> comments on the issue that started the session. Edit <code>bot/skills/triage-rubric.md</code> for kinds and what <code>urgent</code> means on your team. Eval sessions skip tracker writes.</p>`,23)])])}const g=t(n,[["render",o]]);export{u as __pageData,g as default};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{_ as t,c as a,o as s,a3 as i}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Review and triage templates","description":"Scaffold a pull request reviewer or an issue triager, try it locally, and deploy it.","frontmatter":{"title":"Review and triage templates","description":"Scaffold a pull request reviewer or an issue triager, try it locally, and deploy it."},"headers":[],"relativePath":"templates/reviews.md","filePath":"templates/reviews.md"}'),n={name:"templates/reviews.md"};function o(r,e,d,l,p,c){return s(),a("div",null,[...e[0]||(e[0]=[i("",23)])])}const g=t(n,[["render",o]]);export{u as __pageData,g as default};
|