Files and Session Resources

Purpose and Scope

Managed Agent sessions often need durable inputs: spreadsheets, PDFs, datasets, generated artifacts, or other files that should be available to the agent without embedding the bytes in every event. In this SDK, that workflow is split into two related surfaces. The beta Files API stores or retrieves file objects at the account or scoped API level, while the beta session resources API attaches an uploaded file to a specific Managed Agent session so the running agent can see it at a mount path. This page explains how those surfaces fit together for TypeScript users working with client.beta.files and client.beta.sessions.resources.

Sources: tests/api-resources/beta/files.test.ts, tests/api-resources/beta/sessions/resources.test.ts, examples/agents-with-files.ts, api.md

The official Files API documentation describes a create-once, use-many-times model: upload a file, receive a file_id, and reference that identifier later instead of re-uploading the content. The session resource API adds a Managed Agents-specific layer on top of that idea. A session resource is the relationship between a session and a file, including the file_id, resource type, and the path where the file should be mounted inside the session environment. In practice, this lets the agent read file-backed context while keeping upload, session creation, and event streaming as separate steps in application code.

Relevant Source Files

• tests/api-resources/beta/files.test.ts - exercises the generated beta files resource, including list, delete, download, metadata retrieval, upload, request options, beta parameters, and response wrapper behavior.
• tests/api-resources/beta/sessions/resources.test.ts - documents the generated session resources client methods for retrieving, updating, listing, deleting, and adding resources to a session, including parameter names used by the TypeScript SDK.
• examples/agents-with-files.ts - provides the clearest end-to-end Managed Agents file workflow: create an environment, create an agent, upload a file, create a session with the file mounted, list resources, send a prompt, and stream events.
• api.md - serves as the generated API reference source for endpoint names, request shapes, and response models exposed by the SDK.

End-to-End Workflow

The runnable example starts with the same SDK pattern used throughout the repository: instantiate new Anthropic() and let the client read default configuration such as ANTHROPIC_API_KEY. It then creates a beta environment and a beta agent. The agent is configured with the built-in agent_toolset_20260401 toolset and an always_allow permission policy, which is useful for a file example because the agent needs to inspect mounted data without an additional permission prompt in the sample flow. Only after the environment and agent exist does the example upload the local data.csv file through client.beta.files.upload.

Sources: examples/agents-with-files.ts

After upload, the example creates a session and supplies a resources array directly in client.beta.sessions.create. The resource item has type: 'file', the uploaded file_id, and mount_path: 'data.csv'. This means the session is born with the file already attached, rather than requiring a separate add-resource call after creation. The example then calls client.beta.sessions.resources.list(session.id) to verify what the session sees and sends a user.message asking the agent to read the uploaded CSV. The final loop streams session events until session.status_idle, which is the same completion signal used in the simpler Managed Agents examples.

const file = await client.beta.files.upload({
  file: fs.createReadStream(path.join(__dirname, 'data.csv')),
});
 
const session = await client.beta.sessions.create({
  environment_id: environment.id,
  agent: { type: 'agent', id: agent.id, version: agent.version },
  resources: [{ type: 'file', file_id: file.id, mount_path: 'data.csv' }],
});
 
const resources = await client.beta.sessions.resources.list(session.id);

API Components

The files resource tests show the stable SDK calling conventions used by generated resources. client.beta.files.list() returns an SDK response promise that can be awaited for parsed data, converted to a raw Response with .asResponse(), or combined with transport metadata using .withResponse(). The same file demonstrates request option propagation by passing an override path that intentionally produces Anthropic.NotFoundError. List parameters include after_id, before_id, limit, scope_id, and betas, while file-specific methods include delete, download, retrieveMetadata, and upload. Upload accepts file-like input; the test uses toFile(Buffer.from('Example data'), 'README.md'), while the example uses fs.createReadStream.

Sources: tests/api-resources/beta/files.test.ts, examples/agents-with-files.ts

The session resources tests expose the resource-level methods below client.beta.sessions.resources. Even though the generated tests are skipped because the local Prism fixture cannot find beta-only endpoints, they still document the TypeScript method names and parameter shapes generated from the OpenAPI spec. The methods include retrieve(resourceId, { session_id }), update(resourceId, { session_id, authorization_token }), list(sessionId, params?, options?), and delete(resourceId, { session_id }). The request option tests also show pagination-like inputs on list, including limit, page, and betas, plus the same Anthropic.NotFoundError behavior when a request is deliberately routed to an unknown path.

Sources: tests/api-resources/beta/sessions/resources.test.ts

Compact Reference

The API reference describes adding a file resource as POST /v1/sessions/{session_id}/resources. The body uses type: 'file', file_id, and optional mount_path; when omitted, the documented default is under /mnt/session/uploads/<file_id>. The returned object is a BetaManagedAgentsFileResource with identifiers and timestamps plus file_id, mount_path, and type: 'file'. In SDK code, the session creation shortcut shown in examples/agents-with-files.ts is often the most convenient path when the required files are known up front. Use the separate session resources methods when files must be added, inspected, changed, or removed after a session already exists.

Sources: tests/api-resources/beta/sessions/resources.test.ts, examples/agents-with-files.ts, api.md

Implementation Details and Constraints

A useful mental model is that uploaded files are not automatically visible to every Managed Agent session. Uploading creates file storage state; attaching creates session runtime state. That distinction matters for lifecycle and cleanup. You may list or delete files through client.beta.files, but a session can only use a file after it is included in the session resources array or added through the session resources endpoint. Conversely, listing session resources answers a narrower question than listing files: it tells you what that particular session has mounted, not every file the account has uploaded.

The example’s prompt asks the agent to read /uploads/data.csv, while the session creation request uses mount_path: 'data.csv'. Keep mount paths consistent with the execution environment conventions used by your agent tools and prompts. The official API reference notes a default mount location when mount_path is omitted, but application code should prefer an explicit path when the prompt, tools, or scripts depend on a stable filename. This also makes debugging easier because the resource list can be compared directly with the paths mentioned in user messages and generated tool calls.

Testing Signals

The tests give two important maintenance signals for SDK users and contributors. First, the beta files resource is exercised with normal, non-skipped tests for parsed responses, raw responses, response metadata, request parameters, and request options. That indicates the generated files client follows the same response-promise contract as other SDK resources. Second, the session resources tests are intentionally marked skipped because the local Prism test server cannot resolve a beta-only endpoint. Treat those tests as generated surface documentation rather than local integration proof for the remote service behavior.

Sources: tests/api-resources/beta/files.test.ts, tests/api-resources/beta/sessions/resources.test.ts

For application code, the safest next step is to reproduce the example flow with a small local file: upload it, mount it during session creation, list the session resources, and ask the agent to read a known value from the file while streaming events. Once that works, decide whether your product needs post-creation resource management. If it does, use the client.beta.sessions.resources methods and keep the parent session_id explicit in retrieve, update, and delete calls. Related topics to read next are Managed Agent Sessions, Session Event Streaming, Cloud Environments and Work, and the Files Resource Reference.