@grok/agent-sdk 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/channels/slack/slack-channel.d.ts.map +1 -1
- package/dist/channels/slack/slack-channel.js +27 -14
- package/dist/docs/404.html +2 -2
- package/dist/docs/assets/{app.BzTUBOAD.js → app.BSH__xV4.js} +4 -4
- package/dist/docs/assets/{building-with-agents.md.BqJ7AAjG.js → building-with-agents.md.Bo3ct-rf.js} +1 -1
- package/dist/docs/assets/changelog.md.b6H_ea44.js +1 -0
- package/dist/docs/assets/{changelog.md.BWhC6DET.lean.js → changelog.md.b6H_ea44.lean.js} +1 -1
- package/dist/docs/assets/chunks/@localSearchIndexroot.CiRGcfZg.js +1 -0
- package/dist/docs/assets/chunks/{VPLocalSearchBox.DsnRlUT5.js → VPLocalSearchBox.Cadl7A0k.js} +1 -1
- package/dist/docs/assets/chunks/{arc.DH8GOhiv.js → arc.K7t9nNY6.js} +1 -1
- package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.9m9ObyuE.js → architectureDiagram-Q4EWVU46.SlHEknkX.js} +1 -1
- package/dist/docs/assets/chunks/{baseUniq.BXHpx1lE.js → baseUniq.DJLRMLkz.js} +1 -1
- package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.xY3EX59q.js → blockDiagram-DXYQGD6D.Bs6XxFpe.js} +1 -1
- package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.DnqgMVgc.js → c4Diagram-AHTNJAMY.CyLg6Ovc.js} +1 -1
- package/dist/docs/assets/chunks/channel.CVTdqYx0.js +1 -0
- package/dist/docs/assets/chunks/{chunk-4BX2VUAB.BjFxK2A3.js → chunk-4BX2VUAB.DTQ4TinT.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-4TB4RGXK.BujS_Spt.js → chunk-4TB4RGXK.Es84IgcH.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-55IACEB6.YbTjhdaM.js → chunk-55IACEB6.Clm3cGPQ.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-EDXVE4YY.DnQ8t4GC.js → chunk-EDXVE4YY.DE4CRkS5.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-FMBD7UC4.B67AwAmj.js → chunk-FMBD7UC4.Bf8HCvqp.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-OYMX7WX6.DrZIAFOm.js → chunk-OYMX7WX6.eub-7nSx.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-QZHKN3VN.BLmmydkn.js → chunk-QZHKN3VN.WyP9VAS_.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-YZCP3GAM.DaoOfw0O.js → chunk-YZCP3GAM.LO9ohhDE.js} +1 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.CsJJyx6-.js +1 -0
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.CsJJyx6-.js +1 -0
- package/dist/docs/assets/chunks/clone.Dk8KvtOB.js +1 -0
- package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.DMQuNhM5.js → cose-bilkent-S5V4N54A.D5za6aH0.js} +1 -1
- package/dist/docs/assets/chunks/{dagre-KV5264BT.CZoGVuUf.js → dagre-KV5264BT.Dq1daUru.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-5BDNPKRD.CLt9uOyL.js → diagram-5BDNPKRD.j1YL5BKS.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.DpczEm1G.js → diagram-G4DWMVQ6.Bi1aLdhC.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-MMDJMWI5.D4r13DvJ.js → diagram-MMDJMWI5.BOzMEkAr.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-TYMM5635.CYU9eGFu.js → diagram-TYMM5635.Dx2FVhCr.js} +1 -1
- package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.QA9naWEw.js → erDiagram-SMLLAGMA.DI4TNkye.js} +1 -1
- package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.BbNoVZYd.js → flowDiagram-DWJPFMVM.C58Z9uPK.js} +1 -1
- package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.IHjDoG7r.js → ganttDiagram-T4ZO3ILL.DXSpW809.js} +1 -1
- package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.B21VMdf5.js → gitGraphDiagram-UUTBAWPF.B955oaFl.js} +1 -1
- package/dist/docs/assets/chunks/{graph.DgJ4L-8V.js → graph.BQXhKtxS.js} +1 -1
- package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.CQjrcthc.js → infoDiagram-42DDH7IO.Dozj_-Gm.js} +1 -1
- package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.D4tPGtVo.js → ishikawaDiagram-UXIWVN3A.D2140OzH.js} +1 -1
- package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.BD3WaNbQ.js → journeyDiagram-VCZTEJTY.DrqrMhCk.js} +1 -1
- package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.Ca0o4Tqz.js → kanban-definition-6JOO6SKY.Dv-LTrlw.js} +1 -1
- package/dist/docs/assets/chunks/{layout.DXXqX4MQ.js → layout.CGtHp49X.js} +1 -1
- package/dist/docs/assets/chunks/{linear.5c61gNw4.js → linear.CHZLYB52.js} +1 -1
- package/dist/docs/assets/chunks/{min.B1-NAjHX.js → min.D4Vt3eIy.js} +1 -1
- package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.BELznv3-.js → mindmap-definition-QFDTVHPH.BBfpYTea.js} +1 -1
- package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.qPzO1mq5.js → pieDiagram-DEJITSTG.BVYvElmY.js} +1 -1
- package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.CxIvzbjX.js → quadrantDiagram-34T5L4WZ.C6Gc2mdY.js} +1 -1
- package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.CqA0iJx8.js → requirementDiagram-MS252O5E.DWa8b4cn.js} +1 -1
- package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.XRTutBnb.js → sankeyDiagram-XADWPNL6.Bi-g4ajv.js} +1 -1
- package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.E--7bRLQ.js → sequenceDiagram-FGHM5R23.DlU3vVN9.js} +1 -1
- package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.C4vGu8zq.js → stateDiagram-FHFEXIEX.CeqJRqnU.js} +1 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.DE0BnUZh.js +1 -0
- package/dist/docs/assets/chunks/{theme.DMj_7q3B.js → theme.DGq7D4tt.js} +2 -2
- package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.C7LgNVAL.js → timeline-definition-GMOUNBTQ.Cqf2kjq9.js} +1 -1
- package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.HUwoZcy_.js → vennDiagram-DHZGUBPP.BeOpE_lM.js} +1 -1
- package/dist/docs/assets/chunks/{wardley-RL74JXVD.BxFEFYZS.js → wardley-RL74JXVD.FMQXA-6q.js} +1 -1
- package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.B2pSo5rB.js → wardleyDiagram-NUSXRM2D.BXS65dAC.js} +1 -1
- package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.NQhMiOOL.js → xychartDiagram-5P7HB3ND.haEiSxqc.js} +1 -1
- package/dist/docs/assets/{deployment.md.BtqJrHhp.js → deployment.md.DJtuDVLh.js} +3 -3
- package/dist/docs/assets/{deployment.md.BtqJrHhp.lean.js → deployment.md.DJtuDVLh.lean.js} +1 -1
- package/dist/docs/assets/{guides_agent-to-agent.md.BcmSqL2z.js → guides_agent-to-agent.md.DcB3nhOz.js} +1 -1
- package/dist/docs/assets/{guides_github.md.6jiEH7dg.js → guides_github.md.CcuZ7keS.js} +1 -1
- package/dist/docs/assets/{guides_mcp-oauth.md.C-Sx_IPa.js → guides_mcp-oauth.md.GVPMKcYl.js} +1 -1
- package/dist/docs/assets/{guides_migrate.md.BbhHYeCr.js → guides_migrate.md.B8CZxnnX.js} +1 -1
- package/dist/docs/assets/{guides_slack.md.BgIGG9ur.js → guides_slack.md.D7Rwyva4.js} +1 -1
- package/dist/docs/assets/{hillclimbing.md.3TkdF79A.js → hillclimbing.md.M51bF-oT.js} +1 -1
- package/dist/docs/assets/index.md.DnJPj_B6.js +14 -0
- package/dist/docs/assets/index.md.DnJPj_B6.lean.js +1 -0
- package/dist/docs/assets/{reference_agent-config.md.C0Tp_Fk9.js → reference_agent-config.md.BSNp2uJ7.js} +3 -3
- package/dist/docs/assets/{reference_cli.md.B8GdpaRj.js → reference_cli.md.DHm6DmYk.js} +2 -2
- package/dist/docs/assets/{reference_hooks.md.CSWmOwMM.js → reference_hooks.md.vbIM394-.js} +2 -2
- package/dist/docs/assets/{reference_hooks.md.CSWmOwMM.lean.js → reference_hooks.md.vbIM394-.lean.js} +1 -1
- package/dist/docs/assets/{reference_schedules.md.RhQ9ZLo1.js → reference_schedules.md.Dd8_d0WG.js} +3 -3
- package/dist/docs/building-with-agents.html +36 -36
- package/dist/docs/building-with-agents.md +3 -3
- package/dist/docs/changelog.html +36 -36
- package/dist/docs/changelog.md +20 -1
- package/dist/docs/deployment.html +37 -37
- package/dist/docs/deployment.md +22 -16
- package/dist/docs/evals.html +35 -35
- package/dist/docs/guides/agent-to-agent.html +37 -37
- package/dist/docs/guides/agent-to-agent.md +4 -2
- package/dist/docs/guides/bitbucket.html +35 -35
- package/dist/docs/guides/cloud-agents.html +35 -35
- package/dist/docs/guides/convert-automation.html +35 -35
- package/dist/docs/guides/github.html +37 -37
- package/dist/docs/guides/github.md +1 -1
- package/dist/docs/guides/gitlab.html +35 -35
- package/dist/docs/guides/improve.html +35 -35
- package/dist/docs/guides/jev.html +35 -35
- package/dist/docs/guides/mcp-oauth.html +37 -37
- package/dist/docs/guides/mcp-oauth.md +1 -1
- package/dist/docs/guides/migrate.html +37 -37
- package/dist/docs/guides/migrate.md +1 -1
- package/dist/docs/guides/opentelemetry.html +35 -35
- package/dist/docs/guides/pagerduty.html +35 -35
- package/dist/docs/guides/slack.html +37 -37
- package/dist/docs/guides/slack.md +1 -1
- package/dist/docs/guides/webhooks.html +35 -35
- package/dist/docs/hashmap.json +1 -1
- package/dist/docs/hillclimbing.html +36 -36
- package/dist/docs/hillclimbing.md +1 -1
- package/dist/docs/index.html +42 -48
- package/dist/docs/index.md +8 -14
- package/dist/docs/llms-full.txt +70 -50
- package/dist/docs/quickstart.html +35 -35
- package/dist/docs/reference/access.html +35 -35
- package/dist/docs/reference/agent-config.html +39 -39
- package/dist/docs/reference/agent-config.md +5 -6
- package/dist/docs/reference/artifacts.html +35 -35
- package/dist/docs/reference/channels.html +35 -35
- package/dist/docs/reference/cli.html +38 -38
- package/dist/docs/reference/cli.md +2 -2
- package/dist/docs/reference/connections.html +35 -35
- package/dist/docs/reference/evals.html +35 -35
- package/dist/docs/reference/extensions.html +35 -35
- package/dist/docs/reference/hooks.html +37 -37
- package/dist/docs/reference/hooks.md +1 -1
- package/dist/docs/reference/http-api.html +35 -35
- package/dist/docs/reference/instructions.html +35 -35
- package/dist/docs/reference/limits.html +35 -35
- package/dist/docs/reference/memory.html +35 -35
- package/dist/docs/reference/playground.html +35 -35
- package/dist/docs/reference/project-layout.html +35 -35
- package/dist/docs/reference/schedules.html +38 -38
- package/dist/docs/reference/sessions.html +35 -35
- package/dist/docs/reference/skills.html +35 -35
- package/dist/docs/reference/subagents.html +35 -35
- package/dist/docs/reference/tools.html +35 -35
- package/dist/docs/templates/agentic-owners.html +35 -35
- package/dist/docs/templates/reviews.html +35 -35
- package/dist/docs/troubleshooting.html +35 -35
- package/dist/filesystem.d.ts +7 -320
- package/dist/filesystem.d.ts.map +1 -1
- package/dist/filesystem.js +10 -691
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/internal/authored-alias-hooks.d.ts +6 -0
- package/dist/internal/authored-alias-hooks.d.ts.map +1 -1
- package/dist/internal/authored-alias-hooks.js +12 -0
- package/dist/internal/authored-loaders.js +10 -1
- package/dist/internal/cli/commands/scaffold.js +1 -1
- package/dist/internal/continuation-session-ids.d.ts +15 -0
- package/dist/internal/continuation-session-ids.d.ts.map +1 -0
- package/dist/internal/continuation-session-ids.js +43 -0
- package/dist/internal/filesystem/walk.d.ts +1 -5
- package/dist/internal/filesystem/walk.d.ts.map +1 -1
- package/dist/internal/filesystem/walk.js +1 -9
- package/dist/internal/hosted-catch-protocol.d.ts +3 -3
- package/dist/internal/hosted-catch-protocol.js +3 -3
- package/dist/internal/hosted-fetch.d.ts +7 -0
- package/dist/internal/hosted-fetch.d.ts.map +1 -0
- package/dist/internal/hosted-fetch.js +26 -0
- package/dist/internal/install-cursor-skills.d.ts +5 -6
- package/dist/internal/install-cursor-skills.d.ts.map +1 -1
- package/dist/internal/install-cursor-skills.js +19 -4
- package/dist/internal/mcp-endpoint.js +4 -4
- package/dist/internal/model-config.d.ts.map +1 -1
- package/dist/internal/model-config.js +11 -4
- package/dist/internal/platform-timers.d.ts +3 -7
- package/dist/internal/platform-timers.d.ts.map +1 -1
- package/dist/internal/platform-timers.js +10 -51
- package/dist/internal/server.d.ts.map +1 -1
- package/dist/internal/server.js +6 -1
- package/dist/internal/session-engine.d.ts +3 -0
- package/dist/internal/session-engine.d.ts.map +1 -1
- package/dist/internal/session-engine.js +12 -3
- package/dist/playground/assets/index-Bno25Cg0.css +1 -0
- package/dist/playground/assets/index-SGKsaznh.js +62 -0
- package/dist/playground/index.html +2 -2
- package/dist/types.d.ts +2 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +2 -2
- package/docs/README.md +8 -14
- package/docs/building-with-agents.md +3 -3
- package/docs/changelog.md +20 -1
- package/docs/deployment.md +22 -16
- package/docs/guides/agent-to-agent.md +4 -2
- package/docs/guides/github.md +1 -1
- package/docs/guides/mcp-oauth.md +1 -1
- package/docs/guides/migrate.md +1 -1
- package/docs/guides/slack.md +1 -1
- package/docs/hillclimbing.md +1 -1
- package/docs/reference/agent-config.md +5 -6
- package/docs/reference/cli.md +2 -2
- package/docs/reference/hooks.md +1 -1
- package/package.json +3 -3
- package/skills/cli/SKILL.md +1 -1
- package/skills/create-agent/SKILL.md +61 -7
- package/skills/debug/SKILL.md +1 -1
- package/skills/deploy/SKILL.md +3 -3
- package/skills/evals/SKILL.md +1 -1
- package/skills/framework-map/SKILL.md +2 -2
- package/skills/github/SKILL.md +1 -1
- package/skills/hillclimb/SKILL.md +1 -1
- package/skills/mcp-auth/SKILL.md +1 -1
- package/skills/migrate-v2/SKILL.md +2 -2
- package/skills/otel/SKILL.md +1 -1
- package/skills/setup-slack/SKILL.md +2 -2
- package/dist/docs/assets/changelog.md.BWhC6DET.js +0 -1
- package/dist/docs/assets/chunks/@localSearchIndexroot.CWxwVoCG.js +0 -1
- package/dist/docs/assets/chunks/channel.Cctv0f7X.js +0 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DU5sqchW.js +0 -1
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DU5sqchW.js +0 -1
- package/dist/docs/assets/chunks/clone.B9rdNt6j.js +0 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ECMu2BdJ.js +0 -1
- package/dist/docs/assets/index.md.DRfaoRCZ.js +0 -20
- package/dist/docs/assets/index.md.DRfaoRCZ.lean.js +0 -1
- package/dist/internal/filesystem/errors.d.ts +0 -64
- package/dist/internal/filesystem/errors.d.ts.map +0 -1
- package/dist/internal/filesystem/errors.js +0 -180
- package/dist/internal/filesystem/merge.d.ts +0 -34
- package/dist/internal/filesystem/merge.d.ts.map +0 -1
- package/dist/internal/filesystem/merge.js +0 -154
- package/dist/playground/assets/index-D6mVn9og.js +0 -62
- package/dist/playground/assets/index-DlALM6gr.css +0 -1
- /package/dist/docs/assets/{building-with-agents.md.BqJ7AAjG.lean.js → building-with-agents.md.Bo3ct-rf.lean.js} +0 -0
- /package/dist/docs/assets/{guides_agent-to-agent.md.BcmSqL2z.lean.js → guides_agent-to-agent.md.DcB3nhOz.lean.js} +0 -0
- /package/dist/docs/assets/{guides_github.md.6jiEH7dg.lean.js → guides_github.md.CcuZ7keS.lean.js} +0 -0
- /package/dist/docs/assets/{guides_mcp-oauth.md.C-Sx_IPa.lean.js → guides_mcp-oauth.md.GVPMKcYl.lean.js} +0 -0
- /package/dist/docs/assets/{guides_migrate.md.BbhHYeCr.lean.js → guides_migrate.md.B8CZxnnX.lean.js} +0 -0
- /package/dist/docs/assets/{guides_slack.md.BgIGG9ur.lean.js → guides_slack.md.D7Rwyva4.lean.js} +0 -0
- /package/dist/docs/assets/{hillclimbing.md.3TkdF79A.lean.js → hillclimbing.md.M51bF-oT.lean.js} +0 -0
- /package/dist/docs/assets/{reference_agent-config.md.C0Tp_Fk9.lean.js → reference_agent-config.md.BSNp2uJ7.lean.js} +0 -0
- /package/dist/docs/assets/{reference_cli.md.B8GdpaRj.lean.js → reference_cli.md.DHm6DmYk.lean.js} +0 -0
- /package/dist/docs/assets/{reference_schedules.md.RhQ9ZLo1.lean.js → reference_schedules.md.Dd8_d0WG.lean.js} +0 -0
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Migrate an early-alpha project","description":"Move a hosted Agent SDK architecture v1 project to v2 through a reviewed pull request.","frontmatter":{"title":"Migrate an early-alpha project","description":"Move a hosted Agent SDK architecture v1 project to v2 through a reviewed pull request."},"headers":[],"relativePath":"guides/migrate.md","filePath":"guides/migrate.md"}'),i={name:"guides/migrate.md"};function r(n,e,l,d,h,c){return s(),a("div",null,[...e[0]||(e[0]=[o(`<h1 id="migrate-an-early-alpha-project-to-architecture-v2" tabindex="-1">Migrate an early-alpha project to architecture v2 <a class="header-anchor" href="#migrate-an-early-alpha-project-to-architecture-v2" aria-label="Permalink to "Migrate an early-alpha project to architecture v2""></a></h1><p>Use this guide only for an Agent SDK project deployed on architecture v1 during the early alpha. Every other project already runs on v2.</p><h2 id="check-whether-your-project-needs-migration" tabindex="-1">Check whether your project needs migration <a class="header-anchor" href="#check-whether-your-project-needs-migration" aria-label="Permalink to "Check whether your project needs migration""></a></h2><p>Your project needs migration if any of these is true:</p><ul><li><code>package.json</code> depends on <code>@cursor/july</code>.</li><li>A script or CI job runs the early-alpha CLI.</li><li>The agent sets <code>architecture: "v1"</code> or <code>runtime: "grokbot"</code>.</li><li>The project has <code>bot/storage.ts</code> or <code>agent/storage.ts</code>.</li><li>An SCM channel credential is a literal value.</li><li>Code uses a <code>/v1</code> continuation selector.</li><li>A reminder uses an anonymous <code>run</code> or <code>until</code> function.</li><li>A peer connection reads its URL from a <code>*_MCP_URL</code> secret.</li><li><code>agent-sdk deployment get <slug></code> doesn't print <code>architecture: v2</code>.</li></ul><p><code>agent-sdk migrate</code> checks the source for these signals and prints <code>Nothing to migrate.</code> when it finds none. It doesn't check scripts, CI jobs, or the hosted deployment.</p><p>To swap the early-alpha package, 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:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> uninstall</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @cursor/july</span></span>
|
|
2
2
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @grok/agent-sdk@latest</span></span></code></pre></div><p>An existing <code>agent/</code> folder still works.</p><h2 id="start-the-migration" tabindex="-1">Start the migration <a class="header-anchor" href="#start-the-migration" aria-label="Permalink to "Start the migration""></a></h2><p>Commit and push the source first. <code>agent-sdk migrate</code> starts a Cursor cloud agent on that pushed ref, and the agent opens a pull request without deploying.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> login</span></span>
|
|
3
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> migrate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>To migrate a pushed source outside your checkout, pass <code>--repo</code>, <code>--ref</code>, and <code>--path</code>. The <a href="./../reference/cli.html#migrate">CLI reference</a> lists every flag.</p><p>You can also ask a coding agent in your checkout to follow the bundled <code>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> migrate</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span></span></code></pre></div><p>To migrate a pushed source outside your checkout, pass <code>--repo</code>, <code>--ref</code>, and <code>--path</code>. The <a href="./../reference/cli.html#migrate">CLI reference</a> lists every flag.</p><p>You can also ask a coding agent in your checkout to follow the bundled <code>agent-sdk-migrate-v2</code> skill. If the project relies on a v1 capability that has no v2 path, the agent stops and names the blocker.</p><h2 id="review-the-pull-request" tabindex="-1">Review the pull request <a class="header-anchor" href="#review-the-pull-request" aria-label="Permalink to "Review the pull request""></a></h2><p>Before you merge, check that the pull request:</p><ul><li>Uses <code>@grok/agent-sdk</code> and <code>agent-sdk</code>, and removes <code>architecture: "v1"</code>.</li><li>Moves durable state to <code>ctx.host.kv</code> or <code>ctx.host.files</code>, reads secrets inside the handler that needs them, and expects hosted routes to return <code>202</code>.</li><li>Passes every SCM credential as <code>{ secretName: "NAME" }</code>. <code>agent-sdk validate</code> warns about a literal or <code>process.env</code> getter while <code>architecture: "v1"</code> is set, and fails once you remove it.</li><li>Replaces each peer URL secret, such as <code>BUILDER_MCP_URL</code>, with <code>defineConnection({ agent: "<slug>" })</code>. Check each slug and any TODO the agent left.</li><li>Lists unsupported behavior, follow-ups, and the checks it ran or handed off.</li></ul><h2 id="choose-a-cutover" tabindex="-1">Choose a cutover <a class="header-anchor" href="#choose-a-cutover" aria-label="Permalink to "Choose a cutover""></a></h2><table tabindex="0"><thead><tr><th>Cutover</th><th>What happens</th><th>Choose it when</th></tr></thead><tbody><tr><td>Same slug</td><td>v2 copies the v1 secrets and replaces v1 once it starts. You can't undo it, and it deletes v1's hosted sessions, KV, files, and eval runs.</td><td>A short outage and an empty v2 state are fine.</td></tr><tr><td>New slug</td><td>v1 keeps serving while you test v2. Move senders to the new URL, then delete v1.</td><td>You use Slack, webhooks, or hosted state.</td></tr></tbody></table><p>With a new slug, point the trial at a test repository so the two deployments don't both act on the same events.</p><h2 id="deploy-after-merge" tabindex="-1">Deploy after merge <a class="header-anchor" href="#deploy-after-merge" aria-label="Permalink to "Deploy after merge""></a></h2><p>Deploy from the merged, pushed ref. Reuse every <code>--cursor-events-repo</code> value from v1, and move every <code>--allow-domain</code> value into <code>hosting.egressDomains</code>.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">agent-sdk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dir</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --slug</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">existing-or-new-slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><p>Then follow the checklist that <code>agent-sdk migrate</code> printed:</p><ol><li>Deploy each agent folder separately by running <code>agent-sdk deploy --dir <agent-folder></code> once for each one.</li><li>For each Slack agent, run <code>agent-sdk slack create --env prod --dir <agent-folder></code>. Then uninstall the old app and invite the new bot to its channels.</li><li>For a <a href="./agent-to-agent.html">peer connection</a>, deploy both agents to the same team. Then delete each peer URL secret the pull request lists with <code>agent-sdk secret delete <slug> NAME</code>.</li><li>For a new slug, add each secret with <code>agent-sdk secret set <slug> NAME</code>. It applies without a redeploy.</li></ol><p>Finally, <a href="./../deployment.html">verify a hosted turn</a>.</p>`,26)])])}const g=t(i,[["render",r]]);export{u as __pageData,g as default};
|
|
@@ -79,4 +79,4 @@ import{_ as a,c as i,o as e,a3 as t}from"./chunks/framework.BNw1pucY.js";const c
|
|
|
79
79
|
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "reactions:read"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
80
80
|
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "pins:read"</span></span>
|
|
81
81
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ]</span></span>
|
|
82
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Then run <code>agent-sdk slack create</code> again (add <code>--env prod</code> for the production app), and Slack updates and reinstalls the app.</p><ul><li>The list must include <code>app_mentions:read</code>, <code>assistant:write</code>, <code>channels:history</code>, <code>chat:write</code>, <code>groups:history</code>, <code>im:history</code>, and <code>reactions:read</code>.</li><li>Cursor rejects scopes in the Slack Marketplace forbidden families: <code>admin.*</code>, <code>identity.*</code>, <code>search:read*</code>, <code>triggers:*</code>, <code>apps_configuration:*</code>, and <code>workflow.steps:execute</code>.</li></ul><p>The person who runs <code>slack create</code> grants Cursor three user scopes on their own account so it can create and install the app, and <code>botScopes</code> doesn't change them.</p><p>If you already own the Slack app, run <code>agent-sdk slack init --manual --dir . --name "Triage"</code> and follow the <code>
|
|
82
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>Then run <code>agent-sdk slack create</code> again (add <code>--env prod</code> for the production app), and Slack updates and reinstalls the app.</p><ul><li>The list must include <code>app_mentions:read</code>, <code>assistant:write</code>, <code>channels:history</code>, <code>chat:write</code>, <code>groups:history</code>, <code>im:history</code>, and <code>reactions:read</code>.</li><li>Cursor rejects scopes in the Slack Marketplace forbidden families: <code>admin.*</code>, <code>identity.*</code>, <code>search:read*</code>, <code>triggers:*</code>, <code>apps_configuration:*</code>, and <code>workflow.steps:execute</code>.</li></ul><p>The person who runs <code>slack create</code> grants Cursor three user scopes on their own account so it can create and install the app, and <code>botScopes</code> doesn't change them.</p><p>If you already own the Slack app, run <code>agent-sdk slack init --manual --dir . --name "Triage"</code> and follow the <code>agent-sdk-setup-slack</code> skill for installation and tokens.</p>`,51)])])}const E=a(n,[["render",h]]);export{c as __pageData,E as default};
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import{_ as a,c as t,o as i,a3 as s}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Hillclimbing","description":"Iteratively improve agent behavior with evals","frontmatter":{"title":"Hillclimbing","description":"Iteratively improve agent behavior with evals"},"headers":[],"relativePath":"hillclimbing.md","filePath":"hillclimbing.md"}'),n={name:"hillclimbing.md"};function o(l,e,h,r,p,d){return i(),t("div",null,[...e[0]||(e[0]=[s(`<h1 id="hillclimbing" tabindex="-1">Hillclimbing <a class="header-anchor" href="#hillclimbing" aria-label="Permalink to "Hillclimbing""></a></h1><p>Hillclimbing improves an agent one measured change at a time. Hold the inputs fixed, change one thing, and keep it only when the same run gets better without moving the behavior you froze.</p><p>A coding agent in your checkout can run this loop by following the <code>
|
|
1
|
+
import{_ as a,c as t,o as i,a3 as s}from"./chunks/framework.BNw1pucY.js";const u=JSON.parse('{"title":"Hillclimbing","description":"Iteratively improve agent behavior with evals","frontmatter":{"title":"Hillclimbing","description":"Iteratively improve agent behavior with evals"},"headers":[],"relativePath":"hillclimbing.md","filePath":"hillclimbing.md"}'),n={name:"hillclimbing.md"};function o(l,e,h,r,p,d){return i(),t("div",null,[...e[0]||(e[0]=[s(`<h1 id="hillclimbing" tabindex="-1">Hillclimbing <a class="header-anchor" href="#hillclimbing" aria-label="Permalink to "Hillclimbing""></a></h1><p>Hillclimbing improves an agent one measured change at a time. Hold the inputs fixed, change one thing, and keep it only when the same run gets better without moving the behavior you froze.</p><p>A coding agent in your checkout can run this loop by following the <code>agent-sdk-hillclimb</code> skill.</p><h2 id="run-one-measured-round" tabindex="-1">Run one measured round <a class="header-anchor" href="#run-one-measured-round" aria-label="Permalink to "Run one measured round""></a></h2><p>First agree on the agent, one to three fixed inputs, the metric to improve, and the behavior that must not change, such as the output shape, side effects, and existing evals.</p><p>Then run one round:</p><ol><li>Run the agent the way a user would, on saved or local inputs, without deploying or posting live.</li><li>Read the trajectory and name the main failure in one sentence.</li><li>Change one lever.</li><li>Rerun the same fixtures.</li><li>Compare correctness, efficiency, and contract fit.</li><li>Keep, revert, or narrow the change.</li></ol><p>Don't swap a fixture mid-round, or the comparison means nothing.</p><h2 id="choose-the-smallest-lever" tabindex="-1">Choose the smallest lever <a class="header-anchor" href="#choose-the-smallest-lever" aria-label="Permalink to "Choose the smallest lever""></a></h2><p>Start with the earliest place that can remove the failure. Prepare evidence on the host before the turn, then change the shape of that evidence, then the instructions or skills, then remove or gate tools that invite wandering, and change the framework only when the agent can't express the fix.</p><p>Fixing the host or evidence often improves quality and latency together, because the model searches less for ground truth.</p><h2 id="match-the-fix-to-the-failure" tabindex="-1">Match the fix to the failure <a class="header-anchor" href="#match-the-fix-to-the-failure" aria-label="Permalink to "Match the fix to the failure""></a></h2><p>When the agent picks the wrong tool, such as a PR reviewer that calls <code>approve_pr</code> before <code>inspect_pr</code>, pin one PR and tighten only the instruction that owns that decision, so you know which edit fixed 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:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">calledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"inspect_pr"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
2
2
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">t.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">notCalledTool</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"approve_pr"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><p>When a run wanders or runs long, it often repeats reads or makes the model find evidence the host already has. Move that preparation ahead of the turn, and keep the change only if the answer still finds the same issue.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>before: 14 tool calls, 92 seconds, 6 repeated reads</span></span>
|
|
3
3
|
<span class="line"><span>after: 5 tool calls, 31 seconds, 0 repeated reads</span></span></code></pre></div><p>When the answer is weak, freeze the public shape, compare both runs against known-good findings, and edit the instruction or skill that owns the missing judgment.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>fixture: saved checkout PR diff</span></span>
|
|
4
4
|
<span class="line"><span>success: report both gold findings with file paths</span></span>
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import{_ as e,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const o="/docs/architecture.svg",u=JSON.parse('{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK.","frontmatter":{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function r(d,t,l,h,p,c){return s(),a("div",null,[...t[0]||(t[0]=[n(`<h1 id="agent-sdk" tabindex="-1">Agent SDK <a class="header-anchor" href="#agent-sdk" aria-label="Permalink to "Agent SDK""></a></h1><p>Agent SDK lets you define, test, evaluate, and deploy agents as code. It uses the Cursor SDK harness that powers Bugbot, Security Review, Approval Bot, and Rollouts.</p><p>An Agent's behavior is defined in a folder of Markdown and TypeScript that combines deterministic code with model judgment. Agent SDK makes it easy to build useful agents, with APIs to interact on Slack, pull requests, issue trackers, Cursor, and the other places where you get work done.</p><p>After you deploy an agent, open <a href="https://cursor.com/dashboard/deployed-agents" target="_blank" rel="noreferrer">Deployed Agents</a> to manage it.</p><h2 id="get-started-with-your-coding-agent" tabindex="-1">Get Started with your Coding Agent <a class="header-anchor" href="#get-started-with-your-coding-agent" aria-label="Permalink to "Get Started with your Coding Agent""></a></h2><p>Paste this prompt into your coding agent. It installs the CLI, asks what your agent is for, scaffolds and checks a first project, and tells you how to test and deploy it.</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>Set up my first Agent SDK project.</span></span>
|
|
2
|
+
<span class="line"><span></span></span>
|
|
3
|
+
<span class="line"><span>Read https://cursor.com/docs/agent-sdk.md. Add .md to any page under</span></span>
|
|
4
|
+
<span class="line"><span>https://cursor.com/docs/agent-sdk/ to read it as Markdown.</span></span>
|
|
5
|
+
<span class="line"><span></span></span>
|
|
6
|
+
<span class="line"><span>1. Check that Node is 22.13 or newer, then run:</span></span>
|
|
7
|
+
<span class="line"><span> npm install --global @grok/agent-sdk</span></span>
|
|
8
|
+
<span class="line"><span>2. Follow the agent-sdk-create-agent skill at</span></span>
|
|
9
|
+
<span class="line"><span> "$(npm root -g)/@grok/agent-sdk/skills/create-agent/SKILL.md".</span></span>
|
|
10
|
+
<span class="line"><span>3. Do not deploy or push until I ask. End by telling me what the agent</span></span>
|
|
11
|
+
<span class="line"><span> does, how to test it locally, and how to deploy it.</span></span></code></pre></div><h2 id="why-agent-sdk" tabindex="-1">Why Agent SDK <a class="header-anchor" href="#why-agent-sdk" aria-label="Permalink to "Why Agent SDK""></a></h2><p>Your instructions, tools, and evals are files you review, test, and version like the rest of your code. You write the instructions and tools, and Cursor runs the model loop that calls them.</p><h2 id="when-to-use-agent-sdk" tabindex="-1">When to use Agent SDK <a class="header-anchor" href="#when-to-use-agent-sdk" aria-label="Permalink to "When to use Agent SDK""></a></h2><table tabindex="0"><thead><tr><th></th><th>Cursor Automations</th><th>Grok Bot</th><th>Agent SDK</th></tr></thead><tbody><tr><td><strong>You define</strong></td><td>A prompt, model, and trigger in the dashboard</td><td>Instructions, skills, and connected tools in the app</td><td>A versioned Markdown and TypeScript project</td></tr><tr><td><strong>Where it runs</strong></td><td>Cursor-managed</td><td>Cursor-managed</td><td>Cursor-managed hosting or your infrastructure</td></tr><tr><td><strong>Choose it when</strong></td><td>The job fits a schedule or event trigger</td><td>You want to configure and talk to an agent without writing code</td><td>You want code around model judgment that your team can version control, review, test and hillclimb</td></tr></tbody></table><h2 id="get-started" tabindex="-1">Get started <a class="header-anchor" href="#get-started" aria-label="Permalink to "Get started""></a></h2><p>Install <code>@grok/agent-sdk</code>, then scaffold and run a project. The package was <code>@cursor/bdk</code> before.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --global</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @grok/agent-sdk</span></span>
|
|
12
|
+
<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;"> ./my-bot</span></span>
|
|
13
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">cd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> my-bot</span></span>
|
|
14
|
+
<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><a href="./reference/project-layout.html">Project layout</a> explains every folder under <code>bot/</code>.</p><h2 id="next-steps" tabindex="-1">Next steps <a class="header-anchor" href="#next-steps" aria-label="Permalink to "Next steps""></a></h2><ul><li><a href="./quickstart.html">Build your first PR reviewer agent</a> step by step.</li><li>Start from a <a href="./templates/reviews.html">review or triage template</a> or the <a href="./templates/agentic-owners.html">owners-policy approver</a>.</li><li><a href="./guides/convert-automation.html">Convert a Cursor Automation</a> into an Agent SDK project.</li><li><a href="./building-with-agents.html">Build agents with agents</a> using a coding agent.</li><li>Look up commands in the <a href="./reference/cli.html">CLI reference</a> and deployed-agent roles in <a href="./reference/access.html">Access</a>.</li></ul><h2 id="architecture" tabindex="-1">Architecture <a class="header-anchor" href="#architecture" aria-label="Permalink to "Architecture""></a></h2><p><img src="`+o+'" alt="Agent SDK architecture"></p>',19)])])}const k=e(i,[["render",r]]);export{u as __pageData,k as default};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{_ as e,c as a,o as s,a3 as n}from"./chunks/framework.BNw1pucY.js";const o="/docs/architecture.svg",u=JSON.parse('{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK.","frontmatter":{"title":"Agent SDK","description":"Build, test, and deploy bots and agents as code with the Agent SDK."},"headers":[],"relativePath":"index.md","filePath":"README.md"}'),i={name:"index.md"};function r(d,t,l,h,p,c){return s(),a("div",null,[...t[0]||(t[0]=[n("",19)])])}const k=e(i,[["render",r]]);export{u as __pageData,k as default};
|
|
@@ -2,13 +2,13 @@ import{_ as e,c as t,o as i,a3 as a}from"./chunks/framework.BNw1pucY.js";const k
|
|
|
2
2
|
<span class="line"></span>
|
|
3
3
|
<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>
|
|
4
4
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> model: {</span></span>
|
|
5
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"grok-4.
|
|
5
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"grok-4.7"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
6
6
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> params: [</span></span>
|
|
7
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"
|
|
7
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"reasoning_effort"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"high"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
8
8
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { id: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"fast"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, value: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"true"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
9
9
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
|
|
10
10
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// optional; this is the default</span></span>
|
|
11
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="agent-fields" tabindex="-1">Agent fields <a class="header-anchor" href="#agent-fields" aria-label="Permalink to "Agent fields""></a></h2><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.
|
|
11
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="agent-fields" tabindex="-1">Agent fields <a class="header-anchor" href="#agent-fields" aria-label="Permalink to "Agent fields""></a></h2><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>model</code></td><td>string or <code>{ id, params }</code></td><td>Cursor model for turns. Defaults to <code>grok-4.7</code> with <code>reasoning_effort=high</code> and <code>fast=true</code>. Subagents omit it to inherit.</td></tr><tr><td><code>name</code></td><td>string</td><td>Display name. Defaults to the package or directory name.</td></tr><tr><td><code>description</code></td><td>string</td><td>What the agent is for. Required on subagents, where the parent model reads it to decide when to delegate.</td></tr><tr><td><code>instructions</code></td><td>string</td><td>Inline instructions for subagents and generated configs. Prefer <code>instructions.md</code>.</td></tr><tr><td><code>local</code></td><td><code>{ cwd?, workspaceDir?, sandbox? }</code></td><td>Defaults for a local run. See <a href="#local-options">Local options</a>.</td></tr><tr><td><code>hosting</code></td><td><code>{ egressDomains?, secretNames? }</code></td><td>The egress allowlist and expected secret names that <code>agent-sdk deploy</code> reads. Mounted <a href="./extensions.html#build-an-extension">extensions</a> add their own.</td></tr><tr><td><code>concurrency</code></td><td><code>{ maxRunningTurns? }</code></td><td>Agent-wide limit on concurrent turns. See <a href="#concurrency">Concurrency</a>.</td></tr><tr><td><code>builtinTools</code></td><td><code>{ reminders? }</code></td><td>Opt-in tools that Agent SDK provides. See <a href="#built-in-tools">Built-in tools</a>.</td></tr><tr><td><code>tools</code></td><td><code>ToolName[]</code></td><td>Allowlist of built-in tools. Omit it for the full standard toolset. See <a href="#harness-tools">Harness tools</a>.</td></tr><tr><td><code>fs</code></td><td><code>FileSystem</code> or <code>(ctx) => FileSystem</code></td><td>Custom file tree for the session. <code>root</code> is the deprecated name. See <a href="#custom-filesystem">Custom filesystem</a>.</td></tr><tr><td><code>skills</code></td><td><code>false</code> or <code>(ctx) => FileSystem</code></td><td>Replaces the skills tree mounted at <code>/agent/skills</code>, or turns that mount off.</td></tr></tbody></table><p>The <code>persistent</code> field was removed. Discovery rejects a config that still sets it, and the error is <code>persistent was removed. Delete it from defineAgent.</code>, so <code>validate</code>, <code>dev</code>, and <code>deploy</code> fail until you delete the field. A deployment that is already running keeps serving until you stop or delete it.</p><h2 id="model" tabindex="-1">Model <a class="header-anchor" href="#model" aria-label="Permalink to "Model""></a></h2><p>Set effort and speed with params, not in the id. Use the object form shown above to set params, or a plain string when you don't need any:</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;">model</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"composer-2.5"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span></code></pre></div><h2 id="local-options" tabindex="-1">Local options <a class="header-anchor" href="#local-options" aria-label="Permalink to "Local options""></a></h2><p><code>local.workspaceDir</code> points every session at one shared working directory, for agents that work inside an existing checkout. It takes precedence over <code>cwd</code>, and a per-send <code>workspaceDir</code> wins over both. Sessions share that tree, so one turn's files are visible to the next.</p><p><code>local.sandbox</code> runs the agent inside Cursor's local sandbox. It's off by default, so shell commands auto-approve and inherit the serve process environment, including the host's credentials. Turn it on when turns read untrusted input, such as webhook payloads, PR diffs, or inbound chat. The sandbox limits the tools themselves, so an injected prompt can't talk the model past it.</p><p>Agent SDK runs the file tools (<code>read</code>, <code>edit</code>, <code>delete</code>, <code>grep</code>, <code>glob</code>, <code>ls</code>) in the serve process, outside the sandbox. With <code>local.sandbox</code> on, they refuse a path outside the session workspace with <code>Path is outside the workspace</code>. With it off, they can reach any path the serve process can.</p><h3 id="local-cwd" tabindex="-1">Local cwd <a class="header-anchor" href="#local-cwd" aria-label="Permalink to "Local cwd""></a></h3><p><code>local.cwd</code> sets the parent directory for local session workspaces. Each session uses <code><cwd>/<sessionId></code> unless a per-send <code>workspaceDir</code> overrides it.</p><p>Session workspaces are real Cursor project directories, so the local agent reads <code>AGENTS.md</code> and <code>.cursor</code> config from every ancestor directory. When you omit <code>cwd</code> and the agent sits inside another git repo, such as a monorepo package, Agent SDK uses a per-project directory under <code>~/.cache</code> instead, so the enclosing checkout's rules, skills, and MCP servers stay out of the turn. An agent at its own git root keeps its workspaces inside the project. Point <code>cwd</code> at a checkout only when the agent should inherit that tree.</p><h2 id="custom-filesystem" tabindex="-1">Custom filesystem <a class="header-anchor" href="#custom-filesystem" aria-label="Permalink to "Custom filesystem""></a></h2><p><code>fs</code> is mounted at <code>/</code>, and Agent SDK mounts <code>/tmp</code> and <code>/agent/skills</code> over it. Set <code>fs</code> or the deprecated <code>root</code>, not both. A tree that already has <code>/agent/skills</code> fails session start unless <code>skills</code> is <code>false</code>.</p><h2 id="harness-tools" tabindex="-1">Harness tools <a class="header-anchor" href="#harness-tools" aria-label="Permalink to "Harness tools""></a></h2><p>Use <code>tools</code> to limit which built-in Cursor tools the model can call. When you set it, the model gets only the tools you list. An empty list turns off every built-in tool, and new platform tools stay off until you add them.</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;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
12
12
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> model: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"composer-2.5"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
13
13
|
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Read-only triage: no shell, no edits, no subagents.</span></span>
|
|
14
14
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tools: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"read"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"grep"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"glob"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"ls"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
@@ -36,8 +36,8 @@ import{_ as t,c as a,o as s,a3 as o}from"./chunks/framework.BNw1pucY.js";const g
|
|
|
36
36
|
<span class="line"><span>agent-sdk eval get <evalId> --url <baseUrl></span></span>
|
|
37
37
|
<span class="line"><span>agent-sdk eval cancel <evalId> --url <baseUrl></span></span></code></pre></div><p><code>eval get</code> exits <code>3</code> while the batch runs and <code>1</code> when it failed or was cancelled.</p><h2 id="projects" tabindex="-1">Projects <a class="header-anchor" href="#projects" aria-label="Permalink to "Projects""></a></h2><h3 id="init" tabindex="-1">Scaffold a project <a class="header-anchor" href="#init" aria-label="Permalink to "Scaffold a project {#init}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk init [directory] [--template <name>] [--var id=value]... [--json] [--dry-run]</span></span>
|
|
38
38
|
<span class="line"><span>agent-sdk init [directory] --from automation:<url-or-uuid> [--dry-run] [--json]</span></span></code></pre></div><p>Without a directory, <code>init</code> prints the setup guide. With one, it adds missing scaffold files, installs dependencies, and tries to put <code>agent-sdk</code> on <code>PATH</code>. On a TTY, it also asks the template's questions and starts login when needed.</p><p><code>--template</code> takes <code>agentic-owners</code>, <code>agents-md</code>, <code>code-wiki</code>, <code>demo</code>, <code>security-help</code>, <code>security-reviewer</code>, <code>thermo-quality-review</code>, <code>thermo-review</code>, <code>triage-jira</code>, or <code>triage-linear</code>. <code>triage</code> selects <code>triage-linear</code>. <code>--var id=value</code> answers a template question without a prompt. <code>--dry-run</code> lists the files without writing them.</p><h4 id="convert-automation" tabindex="-1">Convert an Automation <a class="header-anchor" href="#convert-automation" aria-label="Permalink to "Convert an Automation {#convert-automation}""></a></h4><p><code>--from automation:</code> takes a Cursor Automation dashboard URL or UUID and writes to <code>./<automation-name></code> unless you name a directory. Generated files don't overwrite existing paths, but the <code>npm install</code> that follows can run lifecycle scripts from an existing <code>package.json</code>. See <a href="./../guides/convert-automation.html">Convert a Cursor Automation</a>.</p><h3 id="migrate" tabindex="-1">Migrate an early-alpha project <a class="header-anchor" href="#migrate" aria-label="Permalink to "Migrate an early-alpha project {#migrate}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk migrate [--dir <path>] [--repo <https-url>] [--ref <git-ref>]</span></span>
|
|
39
|
-
<span class="line"><span> [--path <agent-path>] [--no-wait] [--json] [--api-key <key>]</span></span></code></pre></div><p><code>migrate</code> applies only to projects that deployed with <code>architecture: "v1"</code> during the early alpha. It starts a Cursor cloud agent on a pushed Git ref with the bundled <code>
|
|
40
|
-
<span class="line"><span>agent-sdk skills list [--json [--fields <a,b.c>]] [--limit <n>] [--page-token <token>]</span></span></code></pre></div><p>Package installation copies the bundled skills, <code>skills install</code> replaces the installed copies and removes stale ones, and <code>skills list</code> prints each skill's bundled and installed versions. The <code>
|
|
39
|
+
<span class="line"><span> [--path <agent-path>] [--no-wait] [--json] [--api-key <key>]</span></span></code></pre></div><p><code>migrate</code> applies only to projects that deployed with <code>architecture: "v1"</code> during the early alpha. It starts a Cursor cloud agent on a pushed Git ref with the bundled <code>agent-sdk-migrate-v2</code> skill, and the agent opens a pull request with the source changes. The command never deploys or changes secrets.</p><p>With nothing to change, it prints <code>Nothing to migrate.</code> and exits <code>0</code>, and it exits <code>1</code> if the run ends without a pull request. <code>deploy</code> refuses a project that sets <code>architecture: "v1"</code> and points to <code>migrate</code>. See <a href="./../guides/migrate.html">Migrate an early-alpha project</a>.</p><h3 id="skills-install" tabindex="-1">Install and list coding-agent skills <a class="header-anchor" href="#skills-install" aria-label="Permalink to "Install and list coding-agent skills {#skills-install}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk skills install [--dry-run] [--json]</span></span>
|
|
40
|
+
<span class="line"><span>agent-sdk skills list [--json [--fields <a,b.c>]] [--limit <n>] [--page-token <token>]</span></span></code></pre></div><p>Package installation copies the bundled skills, <code>skills install</code> replaces the installed copies and removes stale ones, and <code>skills list</code> prints each skill's bundled and installed versions. The <code>agent-sdk-cli</code> skill teaches agents to run <code>agent-sdk</code> safely.</p><h3 id="info" tabindex="-1">Inspect a project <a class="header-anchor" href="#info" aria-label="Permalink to "Inspect a project {#info}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk info [--dir <path>] [--view info|manifest] [--json [--fields <a,b.c>]]</span></span></code></pre></div><p>Text output lists what discovery found, such as tools, channels, and diagnostics. <code>--view manifest</code> summarizes one project's deployment metadata without a network request.</p><h3 id="validate" tabindex="-1">Validate a project <a class="header-anchor" href="#validate" aria-label="Permalink to "Validate a project {#validate}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk validate [--dir <path>]</span></span></code></pre></div><p><code>validate</code> prints every discovered project's diagnostics and exits <code>1</code> when any diagnostic has error severity. <code>validate</code> fails when an SCM webhook secret or GitHub credential is a literal or a getter, and the error message shows the <code>{ secretName }</code> form to use. A project that still sets <code>architecture: "v1"</code> gets the same finding as a warning.</p><h2 id="credentials-and-versions" tabindex="-1">Credentials and versions <a class="header-anchor" href="#credentials-and-versions" aria-label="Permalink to "Credentials and versions""></a></h2><h3 id="login-logout-whoami" tabindex="-1">Manage credentials <a class="header-anchor" href="#login-logout-whoami" aria-label="Permalink to "Manage credentials {#login-logout-whoami}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk login [--api-key <key>] [--key-name <name>]</span></span>
|
|
41
41
|
<span class="line"><span>agent-sdk whoami [--json]</span></span>
|
|
42
42
|
<span class="line"><span>agent-sdk logout</span></span></code></pre></div><p><code>login</code> stores a supplied API key, or opens browser sign-in and stores the key it creates. <code>whoami</code> shows the active credential and its source. <code>logout</code> removes the stored credential but doesn't revoke the key, so revoke it in the Cursor dashboard.</p><h3 id="version" tabindex="-1">Print the version <a class="header-anchor" href="#version" aria-label="Permalink to "Print the version {#version}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk version [--json]</span></span>
|
|
43
43
|
<span class="line"><span>agent-sdk --version</span></span></code></pre></div><h3 id="update" tabindex="-1">Update the CLI <a class="header-anchor" href="#update" aria-label="Permalink to "Update the CLI {#update}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk update</span></span></code></pre></div><p><code>update</code> upgrades a recognized global or project install to npm's <code>latest</code> tag, or prints a manual upgrade command. Published installs check for updates daily unless an <a href="#environment-variables">update-check variable</a> is set.</p><h2 id="managed-hosting" tabindex="-1">Managed hosting <a class="header-anchor" href="#managed-hosting" aria-label="Permalink to "Managed hosting""></a></h2><p>Every command here that changes a deployment takes <code>--dry-run</code>, which runs the reads, stops at the first change, prints that request with secrets redacted, and exits <code>0</code>.</p><p><code>secret delete</code>, <code>image delete</code>, <code>slack destroy</code>, and the <code>deployment</code> commands marked No in the <a href="#deployment-lifecycle">lifecycle table</a> can't be undone. On a terminal they ask you to type the slug or name, and a mismatch exits <code>1</code>. Without a terminal, they exit <code>2</code> unless you pass <code>--yes</code>.</p><h3 id="deploy" tabindex="-1">Deploy agents <a class="header-anchor" href="#deploy" aria-label="Permalink to "Deploy agents {#deploy}""></a></h3><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]</span></span>
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Hooks","description":"Run code after session events for audit logs, metrics, and transcript mirrors.","frontmatter":{"title":"Hooks","description":"Run code after session events for audit logs, metrics, and transcript mirrors."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,l,r,
|
|
1
|
+
import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Hooks","description":"Run code after session events for audit logs, metrics, and transcript mirrors.","frontmatter":{"title":"Hooks","description":"Run code after session events for audit logs, metrics, and transcript mirrors."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,l,r,p){return a(),t("div",null,[...s[0]||(s[0]=[i(`<h1 id="hooks" tabindex="-1">Hooks <a class="header-anchor" href="#hooks" aria-label="Permalink to "Hooks""></a></h1><p>A hook subscribes to selected session events and can run a side effect after each matching event is recorded. Hooks run in the serving process for every session of the agent. They cannot change the turn, the prompt, or the reply. A handler that throws is logged and skipped.</p><p>Treat the event as read-only. Later subscribers see the same object. A hook is the wrong surface for anything that must run before the model or must fail a turn. See <a href="#hook-boundaries">Hook boundaries</a>.</p><p><code>defineHook</code> is unrelated to <a href="https://cursor.com/docs/agent/hooks" target="_blank" rel="noreferrer">Cursor Agent hooks</a>, the <code>.cursor/hooks.json</code> scripts that can observe, block, or modify the agent loop. Those still run inside a local session workspace.</p><h2 id="author-a-hook" tabindex="-1">Author a hook <a class="header-anchor" href="#author-a-hook" aria-label="Permalink to "Author a hook""></a></h2><p>Author <code>bot/hooks/<name>.ts</code> with <code>defineHook</code> from <code>@grok/agent-sdk/hooks</code>. This hook meters tokens and pages on failure:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/hooks/usage.ts</span></span>
|
|
2
2
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { metrics } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@opentelemetry/api"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
3
3
|
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineHook } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "@grok/agent-sdk/hooks"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
4
4
|
<span class="line"></span>
|
|
@@ -36,4 +36,4 @@ import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c
|
|
|
36
36
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
|
|
37
37
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
38
38
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
39
|
-
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Any module under <code>bot/hooks/</code> is a hook named by its path without the extension. <code>*.test.ts</code> and <code>*.spec.ts</code> are skipped. The default export must be <code>defineHook(...)</code>, names can't contain <code>__</code>, and an empty <code>events</code> map is skipped with a warning. <code>agent-sdk validate</code> reports all three. An extension mounts its hooks as <code><ns>__<name></code>, and <code>disableHook()</code> removes one. See <a href="./extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>.</p><p><code>agent-sdk init</code> scaffolds <code>bot/hooks/memory.ts</code>. Delete it to opt out of the journal. See <a href="./memory.html">Memory</a>.</p><p>Read hosted secrets inside the handler, not at module scope. See <a href="./../deployment.html#add-egress-and-secrets">Add egress and secrets</a>. Give outbound calls a timeout, because a stalled request blocks later handlers on that session.</p><h2 id="events-and-payloads" tabindex="-1">Events and payloads <a class="header-anchor" href="#events-and-payloads" aria-label="Permalink to "Events and payloads""></a></h2><p>Keys are event types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>"*"</code> for every event. A typed key narrows <code>event.data</code>, a <code>"*"</code> handler receives the union so you switch on <code>event.type</code>, and every event carries <code>{ type, index, sessionId, turnId?, at, data }</code>. Skip <code>*.appended</code> deltas when you want the final text.</p><table tabindex="0"><thead><tr><th>Event</th><th><code>event.data</code></th></tr></thead><tbody><tr><td><code>message.received</code></td><td><code>{ text }</code></td></tr><tr><td><code>turn.completed</code></td><td><code>{ result?, usage?, cost? }</code>. <code>usage</code> has <code>inputTokens</code>, <code>outputTokens</code>, <code>cacheReadTokens</code>, <code>cacheWriteTokens</code>, and optional <code>reasoningTokens</code>. <code>cost</code> has <code>totalUsd</code> and the <code>model</code> it was priced against</td></tr><tr><td><code>turn.failed</code></td><td><code>{ message, status? }</code>. <code>status</code> is <code>"error"</code> or <code>"cancelled"</code> when present</td></tr><tr><td><code>actions.requested</code></td><td><code>{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }</code>. One envelope per model step. <code>parentCallId</code> marks subagent work</td></tr><tr><td><code>actions.completed</code></td><td><code>{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }</code>. Emitted when every call in that batch has a result</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed?, parentCallId? }</code>. Live per-call envelope. <code>stubbed</code> means a dry-run session answered a write without running it</td></tr><tr><td><code>action.tool_retry</code></td><td><code>{ callId, toolName, attempt, reason, connection? }</code>. A read is running again after a transient failure. <code>attempt</code> is the try about to run</td></tr></tbody></table><p>The types are <code>SessionEvent</code>, <code>SessionEventType</code>, and <code>HookContext</code>, exported from <code>@grok/agent-sdk</code>.</p><h2 id="handler-context" tabindex="-1">Handler context <a class="header-anchor" href="#handler-context" aria-label="Permalink to "Handler context""></a></h2><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: <code>id</code>, <code>channelId</code>, <code>mode</code> (<code>chat</code> or <code>task</code>), <code>purpose</code> (<code>live</code> or <code>eval</code>), <code>auth</code>, plus <code>title</code> and <code>sdkAgentId</code> when set</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code>. The token is <code>null</code> when the session can't take follow-ups</td></tr><tr><td><code>ctx.host.kv</code></td><td>Durable JSON, shared by every session of the agent. Prefix keys with <code>ctx.session.id</code> for per-session state</td></tr><tr><td><code>ctx.host.files</code></td><td>Durable files, bound to this session. Pass <code>{ scope: "deployment" }</code> for agent-wide files</td></tr><tr><td><code>ctx.host.mcp</code>, <code>ctx.host.github</code>, <code>ctx.host.slack</code></td><td>The same shared clients tools get</td></tr><tr><td><code>ctx.host.reminders</code></td><td>Per-session <a href="./schedules.html#reminders">reminders</a></td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade. <code>tag</code> fills in <code>sessionId</code> and <code>turnId</code></td></tr><tr><td><code>ctx.stateRoot</code></td><td>Absolute path of the local state root. It resets when a hosted deployment is replaced. Keep derived state in <code>kv</code> or <code>files</code></td></tr></tbody></table><h2 id="hook-dispatch" tabindex="-1">Hook dispatch <a class="header-anchor" href="#hook-dispatch" aria-label="Permalink to "Hook dispatch""></a></h2><p>A hook runs after the event is recorded. It never delays the model.</p><table tabindex="0"><thead><tr><th>Rule</th><th>What happens</th></tr></thead><tbody><tr><td>Same session</td><td>Events dispatch one at a time</td></tr><tr><td>Eval sessions</td><td>The same stream fires. Skip metering or paging when <code>ctx.session.purpose === "eval"</code></td></tr><tr><td>Host restart</td><td>Recorded events are not replayed into hooks, so a mirror needs no dedupe</td></tr><tr><td>Slow handler</td><td>Holds the next event's handlers on that session, not the model. Keep handlers short and queue anything slow</td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to "Hook boundaries""></a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel's <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel's <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>. See <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td>Observe every session for audit, metrics, or a transcript mirror</td><td>A hook</td></tr></tbody></table><p>To act on a turn's decision, such as a label or a ticket, have the model record it with an authored <a href="./tools.html">tool</a>. A <code>turn.completed</code> hook then reads the recorded decision and acts on it through <code>ctx.host</code>.</p><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to "Test a hook""></a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events["turn.completed"]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>agent-sdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>agent-sdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>agent-sdk run --dir . --message "…"</code></td><td>Serve log on stderr, including <code>hook "<name>" handler for <event> threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>agent-sdk logs</code></a>.</p><p>See also <a href="./sessions.html#stream-events">Sessions</a>, <a href="./../guides/opentelemetry.html">OpenTelemetry</a>, and <a href="./channels.html#events">Channels</a>.</p>`,27)])])}const E=e(n,[["render",o]]);export{c as __pageData,E as default};
|
|
39
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Any module under <code>bot/hooks/</code> is a hook named by its path without the extension. <code>*.test.ts</code> and <code>*.spec.ts</code> are skipped. The default export must be <code>defineHook(...)</code>, names can't contain <code>__</code>, and an empty <code>events</code> map is skipped with a warning. <code>agent-sdk validate</code> reports all three. An extension mounts its hooks as <code><ns>__<name></code>, and <code>disableHook()</code> removes one. See <a href="./extensions.html#adjust-a-mounted-extension">Adjust a mounted extension</a>.</p><p><code>agent-sdk init</code> scaffolds <code>bot/hooks/memory.ts</code>. Delete it to opt out of the journal. See <a href="./memory.html">Memory</a>.</p><p>Read hosted secrets inside the handler, not at module scope. See <a href="./../deployment.html#add-egress-and-secrets">Add egress and secrets</a>. Give outbound calls a timeout, because a stalled request blocks later handlers on that session.</p><h2 id="events-and-payloads" tabindex="-1">Events and payloads <a class="header-anchor" href="#events-and-payloads" aria-label="Permalink to "Events and payloads""></a></h2><p>Keys are event types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>"*"</code> for every event. A typed key narrows <code>event.data</code>, a <code>"*"</code> handler receives the union so you switch on <code>event.type</code>, and every event carries <code>{ type, index, sessionId, turnId?, at, data }</code>. Skip <code>*.appended</code> deltas when you want the final text.</p><table tabindex="0"><thead><tr><th>Event</th><th><code>event.data</code></th></tr></thead><tbody><tr><td><code>message.received</code></td><td><code>{ text }</code></td></tr><tr><td><code>turn.completed</code></td><td><code>{ result?, usage?, cost? }</code>. <code>usage</code> has <code>inputTokens</code>, <code>outputTokens</code>, <code>cacheReadTokens</code>, <code>cacheWriteTokens</code>, and optional <code>reasoningTokens</code>. <code>cost</code> has <code>totalUsd</code> and the <code>model</code> it was priced against</td></tr><tr><td><code>turn.failed</code></td><td><code>{ message, status?, code? }</code>. <code>status</code> is <code>"error"</code> or <code>"cancelled"</code> when present. <code>code</code> is the runner's stable error code, such as a Cursor SDK <code>RunError.code</code>, when the failure supplied one</td></tr><tr><td><code>actions.requested</code></td><td><code>{ calls: [{ callId, toolName, args?, parentCallId? }], parentCallId? }</code>. One envelope per model step. <code>parentCallId</code> marks subagent work</td></tr><tr><td><code>actions.completed</code></td><td><code>{ results: [{ callId, toolName, output?, isError, stubbed?, parentCallId? }], parentCallId? }</code>. Emitted when every call in that batch has a result</td></tr><tr><td><code>action.result</code></td><td><code>{ callId, toolName, output?, isError, stubbed?, parentCallId? }</code>. Live per-call envelope. <code>stubbed</code> means a dry-run session answered a write without running it</td></tr><tr><td><code>action.tool_retry</code></td><td><code>{ callId, toolName, attempt, reason, connection? }</code>. A read is running again after a transient failure. <code>attempt</code> is the try about to run</td></tr></tbody></table><p>The types are <code>SessionEvent</code>, <code>SessionEventType</code>, and <code>HookContext</code>, exported from <code>@grok/agent-sdk</code>.</p><h2 id="handler-context" tabindex="-1">Handler context <a class="header-anchor" href="#handler-context" aria-label="Permalink to "Handler context""></a></h2><table tabindex="0"><thead><tr><th>Member</th><th>What it is</th></tr></thead><tbody><tr><td><code>ctx.session</code></td><td>Read-only session info: <code>id</code>, <code>channelId</code>, <code>mode</code> (<code>chat</code> or <code>task</code>), <code>purpose</code> (<code>live</code> or <code>eval</code>), <code>auth</code>, plus <code>title</code> and <code>sdkAgentId</code> when set</td></tr><tr><td><code>ctx.agent</code></td><td><code>{ name }</code> of the agent the event belongs to</td></tr><tr><td><code>ctx.channel</code></td><td><code>{ id, continuationToken }</code>. The token is <code>null</code> when the session can't take follow-ups</td></tr><tr><td><code>ctx.host.kv</code></td><td>Durable JSON, shared by every session of the agent. Prefix keys with <code>ctx.session.id</code> for per-session state</td></tr><tr><td><code>ctx.host.files</code></td><td>Durable files, bound to this session. Pass <code>{ scope: "deployment" }</code> for agent-wide files</td></tr><tr><td><code>ctx.host.mcp</code>, <code>ctx.host.github</code>, <code>ctx.host.slack</code></td><td>The same shared clients tools get</td></tr><tr><td><code>ctx.host.reminders</code></td><td>Per-session <a href="./schedules.html#reminders">reminders</a></td></tr><tr><td><code>ctx.artifacts</code></td><td>Session-bound <a href="./artifacts.html">artifacts</a> facade. <code>tag</code> fills in <code>sessionId</code> and <code>turnId</code></td></tr><tr><td><code>ctx.stateRoot</code></td><td>Absolute path of the local state root. It resets when a hosted deployment is replaced. Keep derived state in <code>kv</code> or <code>files</code></td></tr></tbody></table><h2 id="hook-dispatch" tabindex="-1">Hook dispatch <a class="header-anchor" href="#hook-dispatch" aria-label="Permalink to "Hook dispatch""></a></h2><p>A hook runs after the event is recorded. It never delays the model.</p><table tabindex="0"><thead><tr><th>Rule</th><th>What happens</th></tr></thead><tbody><tr><td>Same session</td><td>Events dispatch one at a time</td></tr><tr><td>Eval sessions</td><td>The same stream fires. Skip metering or paging when <code>ctx.session.purpose === "eval"</code></td></tr><tr><td>Host restart</td><td>Recorded events are not replayed into hooks, so a mirror needs no dedupe</td></tr><tr><td>Slow handler</td><td>Holds the next event's handlers on that session, not the model. Keep handlers short and queue anything slow</td></tr></tbody></table><h2 id="hook-boundaries" tabindex="-1">Hook boundaries <a class="header-anchor" href="#hook-boundaries" aria-label="Permalink to "Hook boundaries""></a></h2><table tabindex="0"><thead><tr><th>You want to</th><th>Use instead</th></tr></thead><tbody><tr><td>Add context before the model runs</td><td>The channel's <code>send</code> message and <code>workspaceFiles</code>, <code>instructions.md</code>, skills, or <code>sandbox/workspace/</code> seed files</td></tr><tr><td>Reply on Slack, comment on a PR, or post any other delivery</td><td>The channel's <code>events</code> map, or the Slack and GitHub packs</td></tr><tr><td>Show PR progress (merge-box check, sticky banner)</td><td><code>githubChannel({ progress: { commitStatus, banner } })</code>. See <a href="./../guides/github.html">GitHub agents</a></td></tr><tr><td>Gate a change on behavior</td><td><a href="./../evals.html">Evals</a></td></tr><tr><td>Observe every session for audit, metrics, or a transcript mirror</td><td>A hook</td></tr></tbody></table><p>To act on a turn's decision, such as a label or a ticket, have the model record it with an authored <a href="./tools.html">tool</a>. A <code>turn.completed</code> hook then reads the recorded decision and acts on it through <code>ctx.host</code>.</p><h2 id="test-a-hook" tabindex="-1">Test a hook <a class="header-anchor" href="#test-a-hook" aria-label="Permalink to "Test a hook""></a></h2><p>A hook definition is a plain object, so a unit test calls <code>hook.events["turn.completed"]</code> directly with an event and a stub <code>HookContext</code>. Discovery skips <code>*.test.ts</code>, so the test can live next to the hook.</p><table tabindex="0"><thead><tr><th>Command</th><th>What it reports</th></tr></thead><tbody><tr><td><code>agent-sdk validate --dir .</code></td><td>Discovery errors and the empty-handlers warning</td></tr><tr><td><code>agent-sdk info --dir . --json</code></td><td>Loaded hooks under <code>agents[].hooks</code></td></tr><tr><td><code>agent-sdk run --dir . --message "…"</code></td><td>Serve log on stderr, including <code>hook "<name>" handler for <event> threw: …</code></td></tr></tbody></table><p>On hosting, read the same log with <a href="./cli.html#logs"><code>agent-sdk logs</code></a>.</p><p>See also <a href="./sessions.html#stream-events">Sessions</a>, <a href="./../guides/opentelemetry.html">OpenTelemetry</a>, and <a href="./channels.html#events">Channels</a>.</p>`,27)])])}const E=e(n,[["render",o]]);export{c as __pageData,E as default};
|
package/dist/docs/assets/{reference_hooks.md.CSWmOwMM.lean.js → reference_hooks.md.vbIM394-.lean.js}
RENAMED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Hooks","description":"Run code after session events for audit logs, metrics, and transcript mirrors.","frontmatter":{"title":"Hooks","description":"Run code after session events for audit logs, metrics, and transcript mirrors."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,l,r,
|
|
1
|
+
import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Hooks","description":"Run code after session events for audit logs, metrics, and transcript mirrors.","frontmatter":{"title":"Hooks","description":"Run code after session events for audit logs, metrics, and transcript mirrors."},"headers":[],"relativePath":"reference/hooks.md","filePath":"reference/hooks.md"}'),n={name:"reference/hooks.md"};function o(d,s,h,l,r,p){return a(),t("div",null,[...s[0]||(s[0]=[i("",27)])])}const E=e(n,[["render",o]]);export{c as __pageData,E as default};
|
package/dist/docs/assets/{reference_schedules.md.RhQ9ZLo1.js → reference_schedules.md.Dd8_d0WG.js}
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import{_ as i,c as a,o as e,a3 as n}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime.","frontmatter":{"title":"Schedules & reminders","description":"Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."},"headers":[],"relativePath":"reference/schedules.md","filePath":"reference/schedules.md"}'),t={name:"reference/schedules.md"};function h(l,s,d,p,k,r){return e(),a("div",null,[...s[0]||(s[0]=[n(`<h1 id="schedules-and-reminders" tabindex="-1">Schedules and reminders <a class="header-anchor" href="#schedules-and-reminders" aria-label="Permalink to "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:#
|
|
2
|
-
<span class="line"><span style="--shiki-light:#
|
|
3
|
-
<span class="line"><span style="--shiki-light:#
|
|
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:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">cron</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"0 9 * * 1-5"</span></span>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">---</span></span>
|
|
4
4
|
<span class="line"></span>
|
|
5
5
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">Pull open incidents and post a summary to the metrics endpoint.</span></span></code></pre></div><p>Each fire starts a task-mode session with the body as its prompt, and the session runs to <code>session.completed</code> or <code>session.failed</code> without follow-ups.</p><h3 id="schedule-handlers" tabindex="-1">Schedule handlers <a class="header-anchor" href="#schedule-handlers" aria-label="Permalink to "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
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>
|