@grok/agent-sdk 0.7.0 → 0.7.1
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/github/cursor-account.d.ts +1 -0
- package/dist/channels/github/cursor-account.d.ts.map +1 -1
- package/dist/channels/github/cursor-account.js +8 -2
- package/dist/channels/origin/cursor-account.d.ts +6 -0
- package/dist/channels/origin/cursor-account.d.ts.map +1 -1
- package/dist/channels/origin/cursor-account.js +17 -0
- package/dist/docs/404.html +2 -2
- package/dist/docs/assets/{app.Ch-048af.js → app.CpLKJnOA.js} +4 -4
- package/dist/docs/assets/changelog.md.DoOgjnPC.js +1 -0
- package/dist/docs/assets/{changelog.md.SoN0MK7o.lean.js → changelog.md.DoOgjnPC.lean.js} +1 -1
- package/dist/docs/assets/chunks/@localSearchIndexroot.BJ_1eI6D.js +1 -0
- package/dist/docs/assets/chunks/{VPLocalSearchBox.D7BIa9Su.js → VPLocalSearchBox.Cr1HJ_9k.js} +1 -1
- package/dist/docs/assets/chunks/{arc.BIzu7OVF.js → arc.BjpgGAMM.js} +1 -1
- package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.DNznI0Sn.js → architectureDiagram-Q4EWVU46.CKdhNPPk.js} +1 -1
- package/dist/docs/assets/chunks/{baseUniq.B4y6Y5eG.js → baseUniq.iovoEQbg.js} +1 -1
- package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.BudnBsgw.js → blockDiagram-DXYQGD6D.BYQIeDre.js} +1 -1
- package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY._bB00GdB.js → c4Diagram-AHTNJAMY.gbWi2q8N.js} +1 -1
- package/dist/docs/assets/chunks/channel.BP0n324b.js +1 -0
- package/dist/docs/assets/chunks/{chunk-4BX2VUAB.CRftnUwS.js → chunk-4BX2VUAB.1Mem4UG9.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-4TB4RGXK.CSx1x2Ob.js → chunk-4TB4RGXK.Dn3H-X_H.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-55IACEB6.KkLHAAbH.js → chunk-55IACEB6.BkpSDZwX.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-EDXVE4YY.DDeKCCtX.js → chunk-EDXVE4YY.BScqy1zP.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-FMBD7UC4.DrLlsD9m.js → chunk-FMBD7UC4.Cp394LWf.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-OYMX7WX6.DeVYOGcT.js → chunk-OYMX7WX6.BDv9LhoL.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-QZHKN3VN.Cz4_bS6p.js → chunk-QZHKN3VN.CsgCcrKO.js} +1 -1
- package/dist/docs/assets/chunks/{chunk-YZCP3GAM.CwrYtDVo.js → chunk-YZCP3GAM.BKBpIC5O.js} +1 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.BhTtyWMA.js +1 -0
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.BhTtyWMA.js +1 -0
- package/dist/docs/assets/chunks/clone.BVK2rFqj.js +1 -0
- package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.3d8hflz6.js → cose-bilkent-S5V4N54A.Bs3ZS9PC.js} +1 -1
- package/dist/docs/assets/chunks/{dagre-KV5264BT.BVEgjiPg.js → dagre-KV5264BT.CgWi0tY2.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-5BDNPKRD.j7dZpUK_.js → diagram-5BDNPKRD.rn6qIo9N.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.4flIgIon.js → diagram-G4DWMVQ6.ChhW8oww.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-MMDJMWI5.BlJiFh-S.js → diagram-MMDJMWI5.C0wH5KSk.js} +1 -1
- package/dist/docs/assets/chunks/{diagram-TYMM5635.DHAOHEyM.js → diagram-TYMM5635.CNEcrwA0.js} +1 -1
- package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.DkmyG7xK.js → erDiagram-SMLLAGMA.DCsnKO-7.js} +1 -1
- package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.L_WiaAU6.js → flowDiagram-DWJPFMVM.WCMkfvP0.js} +1 -1
- package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CT6kOI2a.js → ganttDiagram-T4ZO3ILL.BUb1Sxfr.js} +1 -1
- package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.D8CRlLqh.js → gitGraphDiagram-UUTBAWPF._kORbCzm.js} +1 -1
- package/dist/docs/assets/chunks/{graph.CdOyJvsX.js → graph.PrGRm4KW.js} +1 -1
- package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.DcmXeSos.js → infoDiagram-42DDH7IO.BxhCjiQM.js} +1 -1
- package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.BBjY4mxr.js → ishikawaDiagram-UXIWVN3A.5ddTis2y.js} +1 -1
- package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.BrXteAB6.js → journeyDiagram-VCZTEJTY.BUStU27-.js} +1 -1
- package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.OlHsUJVV.js → kanban-definition-6JOO6SKY.CJd1psl3.js} +1 -1
- package/dist/docs/assets/chunks/{layout.DDwvoQlY.js → layout.DqvbZSML.js} +1 -1
- package/dist/docs/assets/chunks/{linear.BRXPDWj3.js → linear.DOmz-1UB.js} +1 -1
- package/dist/docs/assets/chunks/{min.3YwC0t3o.js → min.33k2v8dM.js} +1 -1
- package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.mPHnT2lN.js → mindmap-definition-QFDTVHPH.iISCqCXC.js} +1 -1
- package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.DEK2--em.js → pieDiagram-DEJITSTG.BHvVgzmD.js} +1 -1
- package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.NCdRAOzK.js → quadrantDiagram-34T5L4WZ.CY3w_-Cn.js} +1 -1
- package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.DLAocFWZ.js → requirementDiagram-MS252O5E.CHXKQS1v.js} +1 -1
- package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.afIOqpyT.js → sankeyDiagram-XADWPNL6.DTtRoGss.js} +1 -1
- package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.DXBjvkkE.js → sequenceDiagram-FGHM5R23.NnPcQ3eY.js} +1 -1
- package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.B_SGgvgs.js → stateDiagram-FHFEXIEX.D8DFciH7.js} +1 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.ESAwmMws.js +1 -0
- package/dist/docs/assets/chunks/{theme.bNyH5NPA.js → theme.CwkiT-Fo.js} +2 -2
- package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.CE6S1iSb.js → timeline-definition-GMOUNBTQ._wIWkMU6.js} +1 -1
- package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.Blk7wb8V.js → vennDiagram-DHZGUBPP.NLVv7R6r.js} +1 -1
- package/dist/docs/assets/chunks/{wardley-RL74JXVD.DQqE3WF8.js → wardley-RL74JXVD.DbsCXUZp.js} +1 -1
- package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.MUEQyRnz.js → wardleyDiagram-NUSXRM2D.Dp5uAVDl.js} +1 -1
- package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.DnJA2aXp.js → xychartDiagram-5P7HB3ND.eOEBq4rX.js} +1 -1
- package/dist/docs/assets/{deployment.md.N9S5KC5R.js → deployment.md.CIRydNl3.js} +2 -2
- package/dist/docs/assets/{deployment.md.N9S5KC5R.lean.js → deployment.md.CIRydNl3.lean.js} +1 -1
- package/dist/docs/assets/guides_workload-identity.md.DBV6YkXX.js +82 -0
- package/dist/docs/assets/guides_workload-identity.md.DBV6YkXX.lean.js +1 -0
- package/dist/docs/assets/{reference_agent-config.md.Bbqf0lgS.js → reference_agent-config.md.CfM1S6Ac.js} +2 -2
- package/dist/docs/assets/{reference_agent-config.md.Bbqf0lgS.lean.js → reference_agent-config.md.CfM1S6Ac.lean.js} +1 -1
- package/dist/docs/building-with-agents.html +35 -35
- package/dist/docs/changelog.html +36 -36
- package/dist/docs/changelog.md +8 -0
- package/dist/docs/deployment.html +38 -38
- package/dist/docs/deployment.md +4 -0
- package/dist/docs/evals.html +35 -35
- package/dist/docs/guides/agent-to-agent.html +35 -35
- 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 +35 -35
- 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 +35 -35
- package/dist/docs/guides/migrate.html +36 -36
- package/dist/docs/guides/opentelemetry.html +35 -35
- package/dist/docs/guides/pagerduty.html +35 -35
- package/dist/docs/guides/slack.html +35 -35
- package/dist/docs/guides/teams.html +35 -35
- package/dist/docs/guides/webhooks.html +35 -35
- package/dist/docs/guides/workload-identity.html +141 -0
- package/dist/docs/guides/workload-identity.md +227 -0
- package/dist/docs/hashmap.json +1 -1
- package/dist/docs/hillclimbing.html +35 -35
- package/dist/docs/index.html +35 -35
- package/dist/docs/llms-full.txt +245 -1
- package/dist/docs/llms.txt +1 -0
- package/dist/docs/quickstart.html +35 -35
- package/dist/docs/reference/access.html +35 -35
- package/dist/docs/reference/agent-config.html +37 -37
- package/dist/docs/reference/agent-config.md +1 -1
- package/dist/docs/reference/artifacts.html +35 -35
- package/dist/docs/reference/channels.html +35 -35
- package/dist/docs/reference/cli.html +35 -35
- 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 +35 -35
- 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 +35 -35
- 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/internal/cli-ax.d.ts.map +1 -1
- package/dist/internal/cli-ax.js +6 -3
- package/dist/internal/cursor-account-mcp-auth.d.ts +7 -1
- package/dist/internal/cursor-account-mcp-auth.d.ts.map +1 -1
- package/dist/internal/cursor-account-mcp-auth.js +20 -5
- package/dist/internal/discovery/agent.d.ts.map +1 -1
- package/dist/internal/discovery/agent.js +2 -1
- package/dist/internal/discovery/connections.d.ts +5 -0
- package/dist/internal/discovery/connections.d.ts.map +1 -1
- package/dist/internal/discovery/connections.js +18 -1
- package/dist/internal/host-kv-cas.d.ts.map +1 -1
- package/dist/internal/host-kv-cas.js +21 -3
- package/dist/internal/hosted-delivery-protocol.d.ts +1 -0
- package/dist/internal/hosted-delivery-protocol.d.ts.map +1 -1
- package/dist/internal/hosted-delivery-protocol.js +4 -2
- package/dist/internal/hosted-delivery.d.ts +4 -1
- package/dist/internal/hosted-delivery.d.ts.map +1 -1
- package/dist/internal/hosted-delivery.js +3 -1
- package/dist/internal/ids.d.ts +2 -0
- package/dist/internal/ids.d.ts.map +1 -1
- package/dist/internal/ids.js +5 -0
- package/dist/internal/schedule-runner.d.ts +1 -0
- package/dist/internal/schedule-runner.d.ts.map +1 -1
- package/dist/internal/schedule-runner.js +10 -1
- package/dist/internal/server.d.ts.map +1 -1
- package/dist/internal/server.js +8 -4
- package/dist/internal/session-engine.d.ts +4 -1
- package/dist/internal/session-engine.d.ts.map +1 -1
- package/dist/internal/session-engine.js +3 -1
- package/dist/oidc-token.d.ts +4 -0
- package/dist/oidc-token.d.ts.map +1 -1
- package/dist/playground/assets/chunk-YOKDWASO-BPO_8GRX.js +115 -0
- package/dist/playground/assets/highlighted-body-KPVGNVTW-CxEV-T_f.js +1 -0
- package/dist/playground/assets/index-CjFJhCtb.js +62 -0
- package/dist/playground/assets/index-vwUVwmk8.css +1 -0
- package/dist/playground/assets/mermaid-HWGCJPDP-eK-fpbFn.js +1 -0
- package/dist/playground/index.html +2 -2
- package/docs/changelog.md +8 -0
- package/docs/deployment.md +4 -0
- package/docs/guides/workload-identity.md +232 -0
- package/docs/reference/agent-config.md +1 -1
- package/package.json +3 -1
- package/skills/deploy/SKILL.md +1 -1
- package/dist/docs/assets/changelog.md.SoN0MK7o.js +0 -1
- package/dist/docs/assets/chunks/@localSearchIndexroot.BdYoBKxY.js +0 -1
- package/dist/docs/assets/chunks/channel.CgxlmuBS.js +0 -1
- package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.DWroREP-.js +0 -1
- package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.DWroREP-.js +0 -1
- package/dist/docs/assets/chunks/clone.F824-PNx.js +0 -1
- package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.OKAy5Bz7.js +0 -1
- package/dist/playground/assets/index-BaBSZXki.css +0 -1
- package/dist/playground/assets/index-BkAF8YlO.js +0 -62
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import{_ as i,c as e,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Workload identity (OIDC)","description":"Mint short-lived OIDC tokens from a deployed Agent SDK agent to authenticate with cloud providers and external services without static keys.","frontmatter":{"title":"Workload identity (OIDC)","description":"Mint short-lived OIDC tokens from a deployed Agent SDK agent to authenticate with cloud providers and external services without static keys."},"headers":[],"relativePath":"guides/workload-identity.md","filePath":"guides/workload-identity.md"}'),n={name:"guides/workload-identity.md"};function d(o,s,l,h,r,p){return t(),e("div",null,[...s[0]||(s[0]=[a(`<h1 id="authenticate-deployed-agents-with-oidc" tabindex="-1">Authenticate deployed agents with OIDC <a class="header-anchor" href="#authenticate-deployed-agents-with-oidc" aria-label="Permalink to "Authenticate deployed agents with OIDC""></a></h1><p>A deployed Agent SDK agent can mint short-lived OIDC JWTs signed by Cursor and exchange them for temporary cloud credentials or service tokens without storing static access keys in deployment secrets.</p><p>Agent SDK tokens share the <code>https://api.cursor.com</code> issuer, discovery endpoints, signing keys, 5-minute lifetime, socket path, and per-pod rate limits documented in <a href="https://cursor.com/docs/cloud-agent/identity" target="_blank" rel="noreferrer">Cloud Agents OIDC tokens</a>. They differ in four ways:</p><table tabindex="0"><thead><tr><th>Aspect</th><th>Cloud Agents</th><th>Agent SDK deployments</th></tr></thead><tbody><tr><td>Audience allowlist</td><td>Any valid <code>aud</code> string</td><td>Must be declared in <code>hosting.oidc.audiences</code>; undeclared audiences return HTTP <code>400</code>.</td></tr><tr><td>Subject (<code>sub</code>)</td><td><code>cloud_agent_id:<id></code> (or projected <code>team_id:<id></code> via <code>sub_claim</code>)</td><td>Always <code>agent_sdk_deployment_id:<deployment-id></code>. Sending <code>sub_claim</code> returns HTTP <code>400</code>.</td></tr><tr><td>Runtime claim (<code>agent_runtime</code>)</td><td><code>"managed"</code> or <code>"self_hosted"</code></td><td><code>"agent_sdk"</code>.</td></tr><tr><td>Additional claims</td><td>Includes owner, team, repository, branch, and turn claims</td><td>See <a href="#token-claims">Token claims</a>. No owner, team, repository, or session claims.</td></tr></tbody></table><h2 id="declare-allowed-audiences" tabindex="-1">Declare allowed audiences <a class="header-anchor" href="#declare-allowed-audiences" aria-label="Permalink to "Declare allowed audiences""></a></h2><p>A deployed agent can only mint tokens for audiences declared in <code>hosting.oidc.audiences</code> in <code>bot/agent.ts</code>. If you omit <code>hosting.oidc.audiences</code>, every mint request fails with HTTP <code>400</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/agent.ts</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { 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>
|
|
3
|
+
<span class="line"></span>
|
|
4
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineAgent</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> hosting: {</span></span>
|
|
6
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> egressDomains: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"sts.amazonaws.com"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
7
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> oidc: {</span></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> audiences: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"sts.amazonaws.com"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
10
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
11
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Minting talks to a local Unix socket, so minting itself needs no egress entry. Calling the relying party to exchange the token still requires its hostname in <code>hosting.egressDomains</code>, such as <code>sts.amazonaws.com</code> (and any AWS service host your agent calls afterward).</p><p>Audience rules:</p><ul><li>List exact audience strings only. Wildcards (<code>*</code>) are rejected.</li><li>Declare at most 8 audiences per deployment.</li><li>Each audience must be 1 to 512 printable ASCII characters with no spaces or control characters.</li><li>Cursor-reserved audiences (such as <code>cursor.com</code> hosts) are rejected at deploy time and at mint time.</li><li>Cursor saves <code>hosting.oidc.audiences</code> when you deploy. Redeploy to add or remove an audience.</li></ul><h2 id="mint-a-token-with-getoidctoken" tabindex="-1">Mint a token with <code>getOidcToken</code> <a class="header-anchor" href="#mint-a-token-with-getoidctoken" aria-label="Permalink to "Mint a token with \`getOidcToken\`""></a></h2><p>Import <code>getOidcToken</code> from <code>@grok/agent-sdk</code> and call it inside a tool, channel handler, or callback when your agent needs a token.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/tools/assume_aws_role.ts</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { getOidcToken, OidcTokenError } </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>
|
|
13
|
+
<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>
|
|
14
|
+
<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>
|
|
15
|
+
<span class="line"></span>
|
|
16
|
+
<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>
|
|
17
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Exchange an OIDC token for temporary AWS credentials."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
18
|
+
<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;">({}),</span></span>
|
|
19
|
+
<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>
|
|
20
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> let</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> token</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
|
21
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> try</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
22
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> result</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> getOidcToken</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"sts.amazonaws.com"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
|
23
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> token </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> result.token;</span></span>
|
|
24
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">catch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (error) {</span></span>
|
|
25
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (error </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">instanceof</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> OidcTokenError</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) {</span></span>
|
|
26
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
27
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ok: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
28
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> code: error.code,</span></span>
|
|
29
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> status: error.status </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">??</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
30
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> reason: error.reason </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">??</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
31
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
|
|
32
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
33
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> throw</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> error;</span></span>
|
|
34
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
35
|
+
<span class="line"></span>
|
|
36
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> body</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;"> URLSearchParams</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
37
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Action: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"AssumeRoleWithWebIdentity"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
38
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Version: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"2011-06-15"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
39
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> RoleArn: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"arn:aws:iam::123456789012:role/my-agent-role"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
40
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> RoleSessionName: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"agent-sdk-session"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
41
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> WebIdentityToken: token,</span></span>
|
|
42
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
|
|
43
|
+
<span class="line"></span>
|
|
44
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> response</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fetch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"https://sts.amazonaws.com/"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
|
|
45
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> method: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"POST"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
46
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> headers: {</span></span>
|
|
47
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "content-type"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"application/x-www-form-urlencoded"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
48
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> accept: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"application/json"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
49
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
50
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> body,</span></span>
|
|
51
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
|
|
52
|
+
<span class="line"></span>
|
|
53
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">response.ok) {</span></span>
|
|
54
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { ok: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, stsStatus: response.status };</span></span>
|
|
55
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
56
|
+
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { ok: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> };</span></span>
|
|
57
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
58
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Call <code>getOidcToken</code> inside a tool, handler, or callback, not at module load time.</p><h3 id="return-value-and-caching" tabindex="-1">Return value and caching <a class="header-anchor" href="#return-value-and-caching" aria-label="Permalink to "Return value and caching""></a></h3><p><code>getOidcToken(audience: string)</code> returns <code>Promise<OidcToken></code>:</p><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>token</code></td><td><code>string</code></td><td>Compact RS256-signed JWT. Never log it.</td></tr><tr><td><code>expiresAt</code></td><td><code>Date</code></td><td>Token expiration timestamp from the socket's <code>expires_at</code> field.</td></tr></tbody></table><p><code>getOidcToken</code> caches one token per audience in memory and refreshes it 60 seconds before <code>expiresAt</code>. Concurrent callers for the same audience share a single in-flight mint request. Each mint request times out after 20 seconds.</p><h3 id="error-handling" tabindex="-1">Error handling <a class="header-anchor" href="#error-handling" aria-label="Permalink to "Error handling""></a></h3><p><code>getOidcToken</code> throws <code>OidcTokenError</code> (a subclass of <code>Error</code> with <code>name === "OidcTokenError"</code>) on failure:</p><table tabindex="0"><thead><tr><th>Field</th><th>Type</th><th>Meaning</th></tr></thead><tbody><tr><td><code>code</code></td><td><code>OidcTokenErrorCode</code></td><td>Failure category listed below.</td></tr><tr><td><code>status</code></td><td><code>number | undefined</code></td><td>HTTP status code from the identity socket when an HTTP response was received.</td></tr><tr><td><code>reason</code></td><td><code>string | undefined</code></td><td>Machine-readable <code>error</code> string from the socket's JSON error body, when present.</td></tr></tbody></table><p><code>OidcTokenErrorCode</code> values:</p><table tabindex="0"><thead><tr><th><code>code</code></th><th>Typical <code>status</code></th><th>Cause</th><th>What to do</th></tr></thead><tbody><tr><td><code>"not_hosted"</code></td><td><code>undefined</code></td><td>No identity socket exists (for example, during local <code>agent-sdk dev</code> or <code>agent-sdk serve</code>).</td><td>Use local credentials in development or skip OIDC locally.</td></tr><tr><td><code>"refused"</code></td><td><code>403</code></td><td>The deployment is not running (stopped or deleted) or OIDC minting is disabled for this deployment.</td><td>Treat as non-retryable. Check deployment status.</td></tr><tr><td><code>"rate_limited"</code></td><td><code>429</code></td><td>The per-pod mint rate limit was exceeded.</td><td>Back off and retry. Prefer <code>getOidcToken</code> caching over repeated raw calls.</td></tr><tr><td><code>"timeout"</code></td><td><code>undefined</code></td><td>The mint request did not finish within 20 seconds.</td><td>Retry with backoff.</td></tr><tr><td><code>"malformed"</code></td><td><code>undefined</code></td><td>The socket returned HTTP <code>200</code> with invalid JSON, missing <code>token</code> or <code>expires_at</code>, or a body larger than 64 KiB.</td><td>Retry or inspect runtime logs.</td></tr><tr><td><code>"failed"</code></td><td><code>400</code>, <code>5xx</code>, or <code>undefined</code></td><td>Another HTTP error or socket transport failure.</td><td>Check <code>status</code>. HTTP <code>400</code> means fix the request or declare the audience in <code>hosting.oidc.audiences</code>; <code>5xx</code> errors are retryable.</td></tr></tbody></table><p>When you request an audience that is not listed in <code>hosting.oidc.audiences</code>, the socket returns HTTP <code>400</code> and <code>getOidcToken</code> throws <code>OidcTokenError</code> with <code>code: "failed"</code> and <code>status: 400</code>. Branch on <code>code</code> and <code>status</code> rather than matching <code>reason</code>, which can change.</p><h2 id="call-the-identity-socket-directly" tabindex="-1">Call the identity socket directly <a class="header-anchor" href="#call-the-identity-socket-directly" aria-label="Permalink to "Call the identity socket directly""></a></h2><p>Use the local Unix domain socket directly from shell scripts, non-JavaScript tools, or when you need a <code>nonce</code> claim (which <code>getOidcToken</code> does not accept).</p><p>The socket path is in <code>$CURSOR_AGENT_SOCKET</code>, defaulting to <code>/run/cursor/api.sock</code>. Send <code>POST /v1/tokens/oidc</code> with <code>Content-Type: application/json</code> (maximum body size 4 KB):</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;"> --silent</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --show-error</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --fail-with-body</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
59
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --unix-socket</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">CURSOR_AGENT_SOCKET</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:-/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">cursor</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">/</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">api</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">sock</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}"</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
60
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -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>
|
|
61
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -d</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '{"aud":"sts.amazonaws.com"}'</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
62
|
+
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> http://localhost/v1/tokens/oidc</span></span></code></pre></div><p>Request fields:</p><ul><li><code>aud</code> (required string): exact audience declared in <code>hosting.oidc.audiences</code>.</li><li><code>nonce</code> (optional string): opaque printable ASCII string with no spaces, up to 512 characters, echoed into the JWT <code>nonce</code> claim.</li></ul><p>Success response (<code>200 OK</code>):</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
|
63
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "token"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiIsInR5cCI6IkpXVCJ9..."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
64
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "expires_at"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1785500000</span></span>
|
|
65
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p><code>expires_at</code> is the token expiration in Unix seconds and matches the JWT <code>exp</code> claim.</p><p>An undeclared audience, a Cursor-reserved audience, an invalid <code>aud</code>, or a <code>sub_claim</code> field returns HTTP <code>400</code> with a JSON error object whose <code>error</code> string can change.</p><p>See <a href="https://cursor.com/docs/cloud-agent/identity" target="_blank" rel="noreferrer">Cloud Agents OIDC tokens</a> for the full socket HTTP status code table and per-pod rate limits.</p><h2 id="token-claims" tabindex="-1">Token claims <a class="header-anchor" href="#token-claims" aria-label="Permalink to "Token claims""></a></h2><p>Tokens are signed with <code>RS256</code> and include <code>alg</code>, <code>kid</code>, and <code>typ: "JWT"</code> in the header. Every Agent SDK token carries these claims:</p><table tabindex="0"><thead><tr><th>Claim</th><th>Value</th><th>Notes</th></tr></thead><tbody><tr><td><code>iss</code></td><td><code>https://api.cursor.com</code></td><td>Same issuer as Cloud Agents.</td></tr><tr><td><code>sub</code></td><td><code>agent_sdk_deployment_id:<deployment-id></code></td><td><code><deployment-id></code> is the deployment public ID (<code>asd_</code> followed by 32 lowercase hex characters).</td></tr><tr><td><code>aud</code></td><td>Requested audience string</td><td>Always a single string matching an entry in <code>hosting.oidc.audiences</code>.</td></tr><tr><td><code>iat</code></td><td>Unix seconds</td><td>Issued-at time.</td></tr><tr><td><code>nbf</code></td><td><code>iat - 5</code></td><td>Allows 5 seconds of clock skew.</td></tr><tr><td><code>exp</code></td><td><code>iat + 300</code></td><td>Valid for 5 minutes.</td></tr><tr><td><code>jti</code></td><td>UUID</td><td>Unique token ID per mint.</td></tr><tr><td><code>agent_runtime</code></td><td><code>"agent_sdk"</code></td><td>Identifies an Agent SDK deployment token.</td></tr><tr><td><code>nonce</code></td><td>Optional string</td><td>Present only when sent on a raw socket request.</td></tr></tbody></table><h2 id="configure-an-aws-iam-trust-policy" tabindex="-1">Configure an AWS IAM trust policy <a class="header-anchor" href="#configure-an-aws-iam-trust-policy" aria-label="Permalink to "Configure an AWS IAM trust policy""></a></h2><ol><li>In AWS IAM, add <code>https://api.cursor.com</code> as an OpenID Connect identity provider with <code>sts.amazonaws.com</code> as an audience (if your AWS account does not already have one).</li><li>Declare <code>"sts.amazonaws.com"</code> in <code>hosting.oidc.audiences</code> and <code>hosting.egressDomains</code>, then deploy your agent.</li><li>Find your deployment's exact <code>sub</code> claim (<code>agent_sdk_deployment_id:asd_<32 hex chars></code>). You can read <code>sub</code> from the JWT payload of a minted token during initial setup. Redeploying the same slug keeps the same deployment public ID; deleting and recreating a deployment generates a new one.</li><li>Attach a trust policy to your IAM role that pins both <code>api.cursor.com:aud</code> and <code>api.cursor.com:sub</code> with <code>StringEquals</code>:</li></ol><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
|
66
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "Version"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"2012-10-17"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
67
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "Statement"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span></span>
|
|
68
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
69
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "Effect"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Allow"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
70
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "Principal"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
|
|
71
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "Federated"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"arn:aws:iam::123456789012:oidc-provider/api.cursor.com"</span></span>
|
|
72
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
|
73
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "Action"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"sts:AssumeRoleWithWebIdentity"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
74
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "Condition"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
|
|
75
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "StringEquals"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
|
|
76
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "api.cursor.com:aud"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"sts.amazonaws.com"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
77
|
+
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "api.cursor.com:sub"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"agent_sdk_deployment_id:asd_3f9c0a7b1d2e4f60a9b8c7d6e5f40312"</span></span>
|
|
78
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
79
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
80
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
|
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>Never replace the <code>sub</code> value with a wildcard such as <code>agent_sdk_deployment_id:*</code>. A wildcard trusts every Agent SDK deployment on Cursor.</p><h2 id="verification-rate-limits-and-trust-model" tabindex="-1">Verification, rate limits, and trust model <a class="header-anchor" href="#verification-rate-limits-and-trust-model" aria-label="Permalink to "Verification, rate limits, and trust model""></a></h2><p>For OIDC discovery (<code>https://api.cursor.com/.well-known/openid-configuration</code>), JWKS (<code>https://api.cursor.com/keys</code>), JWT signature verification steps, and per-pod rate limits, see <a href="https://cursor.com/docs/cloud-agent/identity" target="_blank" rel="noreferrer">Cloud Agents OIDC tokens</a>.</p><p>Keep the deployment trust boundary in mind when scoping external roles:</p><ul><li>Any code or tool running inside the deployment pod that can reach the identity socket can mint tokens for any audience declared in <code>hosting.oidc.audiences</code>.</li><li>The platform sets <code>sub</code> from the deployment identity, so one deployment cannot impersonate another.</li><li>Tokens represent the deployment as a whole, not a single session, tool, or end user. Grant the external role only the permissions that the deployment should hold.</li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to "Related""></a></h2><ul><li><a href="./../deployment.html">Deployment</a></li><li><a href="./../reference/agent-config.html">Agent config</a></li><li><a href="https://cursor.com/docs/cloud-agent/identity" target="_blank" rel="noreferrer">Cloud Agents OIDC tokens</a></li></ul>`,48)])])}const E=i(n,[["render",d]]);export{c as __pageData,E as default};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{_ as i,c as e,o as t,a3 as a}from"./chunks/framework.BNw1pucY.js";const c=JSON.parse('{"title":"Workload identity (OIDC)","description":"Mint short-lived OIDC tokens from a deployed Agent SDK agent to authenticate with cloud providers and external services without static keys.","frontmatter":{"title":"Workload identity (OIDC)","description":"Mint short-lived OIDC tokens from a deployed Agent SDK agent to authenticate with cloud providers and external services without static keys."},"headers":[],"relativePath":"guides/workload-identity.md","filePath":"guides/workload-identity.md"}'),n={name:"guides/workload-identity.md"};function d(o,s,l,h,r,p){return t(),e("div",null,[...s[0]||(s[0]=[a("",48)])])}const E=i(n,[["render",d]]);export{c as __pageData,E as default};
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving.","frontmatter":{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),o={name:"reference/agent-config.md"};function n(
|
|
1
|
+
import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving.","frontmatter":{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),o={name:"reference/agent-config.md"};function n(d,s,l,r,h,c){return a(),t("div",null,[...s[0]||(s[0]=[i(`<h1 id="agent-config" tabindex="-1">Agent config <a class="header-anchor" href="#agent-config" aria-label="Permalink to "Agent config""></a></h1><p><code>bot/agent.ts</code> default-exports <code>defineAgent(config)</code>, which sets the model that runs the agent and the defaults for a local run. Every field is optional on the root agent.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">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>
|
|
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>
|
|
@@ -8,7 +8,7 @@ import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k
|
|
|
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.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
|
|
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?, oidc? }</code></td><td>The egress allowlist, expected secret names, and <a href="./../guides/workload-identity.html">OIDC token audiences</a> that <code>agent-sdk deploy</code> reads. Mounted <a href="./extensions.html#build-an-extension">extensions</a> add their own egress hosts and secrets.</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>workspace</code></td><td>string</td><td>With <code>fs</code>, the folder inside the tree the agent works in, and where project rules load from. Defaults to <code>/</code>. For a sandboxed agent without shell, where its session workspace is mounted, <code>/workspace</code> by default.</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>With <code>local.sandbox</code> on, shell commands run without network access, writes and deletes outside the session workspace are refused, and a tool call that needs approval, such as an external MCP call, fails closed. What the agent can read depends on its <code>tools</code>:</p><ul><li><strong>With shell</strong> (or with <code>tools</code> omitted, which includes it), the agent runs on the host disk. Shell commands and the file tools (<code>read</code>, <code>grep</code>, <code>glob</code>, <code>ls</code>) can read any file the serve process can, including credentials on the host.</li><li><strong>With file tools and no shell</strong>, such as <code>tools: ["read", "grep"]</code>, the agent runs on its session workspace as a tree, mounted at <code>/workspace</code>. Set <a href="#custom-filesystem"><code>workspace</code></a> to mount it elsewhere. Every file tool sees only the workspace and refuses a path outside it, including through a symlink. Running on a tree also turns off what only the host disk provides: Cursor hooks don't run, so a Slack follow-up waits for the turn to end instead of reaching the running turn; <code>.cursor/mcp.json</code> from the workspace or an enclosing checkout isn't loaded (connections in <code>bot/</code> still are); host git status doesn't reach the model; and skills are at <code>/agent/skills</code> instead of <code>.cursor/skills</code>. <code>AGENTS.md</code> and <code>.cursor/rules/</code> in the workspace still load. Tools a tree can't run, such as <code>readLints</code>, are left out with a warning.</li></ul><p>To keep an agent's reads inside a tree you choose, give it <a href="#custom-filesystem"><code>fs</code></a> instead.</p><p>A <a href="./tools.html#call-a-tool-without-a-model-turn">direct tool call</a> on a host-disk agent refuses a path outside the session workspace, after symlinks, with <code>Path is outside the workspace</code>, whether or not <code>local.sandbox</code> is on.</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>Set <code>fs</code> and the agent's file tools (Read, Write, StrReplace, LS, Grep, Glob, Delete) and its subagents work on your tree instead of the host disk. Build it with <code>tempFs</code>, <code>unionFs</code>, <code>overlayFs</code>, <code>readOnlyFs</code>, or your own <code>FileSystem</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;"> { defineAgent, readOnlyFs, tempFs, unionFs } </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>
|
|
12
12
|
<span class="line"></span>
|
|
13
13
|
<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>
|
|
14
14
|
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> fs: </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">unionFs</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving.","frontmatter":{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),o={name:"reference/agent-config.md"};function n(
|
|
1
|
+
import{_ as e,c as t,o as a,a3 as i}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving.","frontmatter":{"title":"Agent config","description":"defineAgent at bot/agent.ts: the model, local workspace, and programmatic serving."},"headers":[],"relativePath":"reference/agent-config.md","filePath":"reference/agent-config.md"}'),o={name:"reference/agent-config.md"};function n(d,s,l,r,h,c){return a(),t("div",null,[...s[0]||(s[0]=[i("",57)])])}const u=e(o,[["render",n]]);export{k as __pageData,u as default};
|