local.fs に木を渡すと、Read、Write、StrReplace、Grep、Glob、LS、Delete、Task はその木の上で動く。モデルから見えるツール名はそのまま。fs を省くとホストのディスクで動く。

ts
import { Agent, tempFs, unionFs } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: { id: "composer-2" },
  local: {
    fs: unionFs({
      "/repo": tempFs({
        "/AGENTS.md": "Answer in one paragraph.",
        "/src/greet.ts": 'export const greeting = "hello";\n',
      }),
      "/notes": tempFs(),
    }),
    reportedWorkspacePath: "/repo",
    settingSources: ["project"],
  },
});

木を組むヘルパーは tempFs、unionFs、overlayFs、readOnlyFs、childOverlayFs、emptyFs。fs に関数を渡すと実行ごとに { agentId, sessionId } で新しい木を作る。

相対パスの基準は local.reportedWorkspacePath。未指定なら /。プロジェクトルールは木の中の AGENTS.md と .cursor/rules 以下の .mdc だけで、settingSources に "project" があるときだけ読む。ネストした AGENTS.md と skills は探索しない。local.cwd は状態とトランスクリプトを置くホスト側のディレクトリのままで、モデルが見る範囲は変わらない。

Grep のパターンは JavaScript の RegExp ソース。LS と Glob は 1,000 件で止まる。Shell、ReadLints、SemanticSearch は使えず、tools に名前を書くと ConfigurationError。実行ごとに空の /tmp が乗り、20KB を超える WebFetch と WebSearch、40KB を超える MCP、GenerateImage のファイルはそこへ書く。実行が終わると /tmp は捨てる。

クラウドエージェントへ fs を付けると ConfigurationError。Python SDK には無い。local.subagentInherit と local.resourceProviderOptions とは併用できない。fs 付きで作ったエージェントの再開にも fs が要る。LocalSendOptions.fs はその送信だけ木を差し替える。

#参考文献