---
changelog:
  category: Release
  version: files-sdk@1.2.0
date: '2026-05-10T20:43:40Z'
seo:
  description: >-
    Add AI SDK tools subpath (files-sdk/ai-sdk) exporting createFileTools(...) —
    wraps a configured Files instance as a set of Vercel AI SDK tools
    (listFiles…
title: files-sdk@1.2.0
type: changelog
---
### Minor Changes

-   9758347: Add AI SDK tools subpath (`files-sdk/ai-sdk`) exporting `createFileTools(...)` — wraps a configured `Files` instance as a set of Vercel AI SDK tools (`listFiles`, `getFileMetadata`, `downloadFile`, `getFileUrl`, `uploadFile`, `deleteFile`, `copyFile`, `signUploadUrl`) ready to plug into `generateText` / `streamText` / any agent. Mirrors `@github-tools/sdk`'s ergonomics: write tools require approval by default (configurable globally or per-tool via `requireApproval`), `readOnly: true` strips writes entirely, and `overrides` lets callers patch tool descriptions/titles/etc. without touching `execute`. Individual tool factories (`uploadFile`, `downloadFile`, …) are also exported for cherry-picking. `ai` and `zod` are optional peer dependencies — only required when consuming the new subpath.

-   2d811b1: Add Claude Agent SDK tools subpath (`files-sdk/claude`) exporting `createClaudeFileTools(...)` — wraps a configured `Files` instance as an in-process MCP server ready to drop into `query()` from [`@anthropic-ai/claude-agent-sdk`](https://docs.claude.com/en/api/agent-sdk/overview) (the renamed Claude Code SDK).

    The Claude Agent SDK consumes tools differently than the OpenAI/Vercel adapters: tools are bundled into an `SdkMcpServer` and surfaced to the agent via `mcpServers` + `allowedTools`, with approval enforced through a top-level `canUseTool` callback. The factory returns all four pieces:

    ```ts
    const tools = createClaudeFileTools({ files });

    for await (const msg of query({
      prompt: "List my files.",
      options: {
        mcpServers: tools.mcpServers,
        allowedTools: tools.allowedTools,
        canUseTool: tools.canUseTool,
      },
    })) {
      /* ... */
    }
    ```

    Same eight file operations as the other AI subpaths (`listFiles`, `getFileMetadata`, `downloadFile`, `getFileUrl`, `uploadFile`, `deleteFile`, `copyFile`, `signUploadUrl`) with the same approval-gating defaults, `readOnly` mode, and per-tool `overrides` (description + MCP `annotations`). The bundled `canUseTool` denies approval-gated writes; compose your own using `tools.needsApproval(name)` for human-in-the-loop UX — it accepts both bare names (`"uploadFile"`) and the MCP-prefixed form (`"mcp__files__uploadFile"`) the SDK passes in. The MCP server name defaults to `"files"` and is configurable via `serverName`, which also flows through to the `mcp__<server>__*` strings in `allowedTools`. Read tools get a `readOnlyHint` annotation; writes get `destructiveHint` (`copyFile` / `signUploadUrl` use `idempotentHint` instead).

    Individual tool factories (`claudeUploadFile`, `claudeDownloadFile`, …) are also exported as `SdkMcpToolDefinition` instances for callers that want to compose their own `createSdkMcpServer` rather than use the bundled one. `@anthropic-ai/claude-agent-sdk` and `zod` are optional peer dependencies — only required when consuming the new subpath.

-   d6adeae: Add OpenAI tools subpath (`files-sdk/openai`) with two factories:

    -   `createResponsesFileTools(...)` — for OpenAI's native [Responses API](https://platform.openai.com/docs/api-reference/responses). Returns `{ definitions, execute, needsApproval }`. `definitions` is the array of function-tool specs to pass into `openai.responses.create({ tools })`. `execute(call)` runs a `function_call` item and returns a `function_call_output` ready to push into the next turn's input — JSON parse failures and Zod validation errors come back as the tool's output so the model can self-correct.
    -   `createAgentsFileTools(...)` — for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) (`@openai/agents`). Returns a record of `tool()` outputs ready to spread into `new Agent({ tools })`.

    Both wrap the same eight file operations as `files-sdk/ai-sdk` (`listFiles`, `getFileMetadata`, `downloadFile`, `getFileUrl`, `uploadFile`, `deleteFile`, `copyFile`, `signUploadUrl`) with the same approval-gating defaults, `readOnly` mode, and per-tool overrides. Schemas + execute logic are extracted to a shared internal module so the three subpaths can't drift apart.

    `openai` and `@openai/agents` are optional peer dependencies — install only the one(s) you use. The subpath requires Zod 4.