Adding files

You can provide files to your agent by uploading them through the Files API and mounting them in the session’s sandbox.

Managed Agents API requests require the managed-agents-2026-04-01 beta header, except memory store endpoints, which use agent-memory-2026-07-22 instead. The SDK sets the correct beta header automatically. See Beta headers.

Uploading files

First, upload a file using the Files API:

file=$(curl --fail-with-body -sS "${auth[@]}" \
  "${base_url}/files" \
  -F file=@data.csv)
file_id=$(jq -er '.id' <<<"${file}")
printf 'File ID: %s\n' "${file_id}"

FILE_ID=$(ant beta:files upload \
  --file data.csv \
  --transform id --raw-output)

file = client.beta.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")

const file = await client.beta.files.upload({
  file: await toFile(readFile("data.csv"), "data.csv", { type: "text/csv" }),
});
console.log(`File ID: ${file.id}`);

await using var stream = File.OpenRead(csvPath);
var file = await client.Beta.Files.Upload(new() { File = stream });
Console.WriteLine($"File ID: {file.ID}");

csvFile, err := os.Open("data.csv")
if err != nil {
    panic(err)
}
defer csvFile.Close()

file, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
    File: csvFile,
})
if err != nil {
    panic(err)
}
fmt.Printf("File ID: %s\n", file.ID)

var file = client.beta().files().upload(
    FileUploadParams.builder().file(dataCsv).build()
);
IO.println("File ID: " + file.id());

$file = $client->beta->files->upload(
    FileParam::fromResource(fopen($csvPath, 'r'), filename: 'data.csv', contentType: 'text/csv'),
);
echo "File ID: {$file->id}\n";

file = client.beta.files.upload(file: Pathname(csv_path))
puts "File ID: #{file.id}"

Mounting files in a session

Mount uploaded files into the sandbox by adding them to the resources array when creating a session:

The mount_path is optional, but make sure the uploaded file has a descriptive name so the agent can identify it.

session=$(
  jq -n \
    --arg agent_id "${agent_id}" \
    --arg environment_id "${environment_id}" \
    --arg file_id "${file_id}" \
    '{
      agent: $agent_id,
      environment_id: $environment_id,
      resources: [
        {
          type: "file",
          file_id: $file_id,
          mount_path: "/data.csv"
        }
      ]
    }' | curl --fail-with-body -sS "${auth[@]}" "${base_url}/sessions" --json @-
)
session_id=$(jq -er '.id' <<<"${session}")

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<EOF
resources:
  - type: file
    file_id: $FILE_ID
    mount_path: /data.csv
EOF
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": file.id,
            "mount_path": "/data.csv",
        },
    ],
)

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "file",
      file_id: file.id,
      mount_path: "/data.csv",
    },
  ],
});

var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    Resources =
    [
        new BetaManagedAgentsFileResourceParams
        {
            Type = "file",
            FileID = file.ID,
            MountPath = "/data.csv",
        },
    ],
});

session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
    Agent: anthropic.BetaSessionNewParamsAgentUnion{
        OfString: anthropic.String(agent.ID),
    },
    EnvironmentID: environment.ID,
    Resources: []anthropic.BetaSessionNewParamsResourceUnion{{
        OfFile: &anthropic.BetaManagedAgentsFileResourceParams{
            Type:      anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
            FileID:    file.ID,
            MountPath: anthropic.String("/data.csv"),
        },
    }},
})
if err != nil {
    panic(err)
}

var session = client.beta().sessions().create(
    SessionCreateParams.builder()
        .agent(agent.id())
        .environmentId(environment.id())
        .addResource(
            BetaManagedAgentsFileResourceParams.builder()
                .type(BetaManagedAgentsFileResourceParams.Type.FILE)
                .fileId(file.id())
                .mountPath("/data.csv")
                .build()
        )
        .build()
);

$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
    resources: [
        BetaManagedAgentsFileResourceParams::with(
            type: 'file',
            fileID: $file->id,
            mountPath: '/data.csv',
        ),
    ],
);

session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id,
  resources: [
    {
      type: "file",
      file_id: file.id,
      mount_path: "/data.csv"
    }
  ]
)

With the preceding mount_path, the agent reads the file at /mnt/session/uploads/data.csv (see File paths). A new file_id is created that references the instance of the file in the session. These copies do not count against your storage limits.

Multiple files

Mount multiple files by adding entries to the resources array:

"resources": [
  { "type": "file", "file_id": "file_abc123", "mount_path": "/data.csv" },
  { "type": "file", "file_id": "file_def456", "mount_path": "/config.json" },
  { "type": "file", "file_id": "file_ghi789", "mount_path": "/src/main.py" }
]

resources:
  - type: file
    file_id: file_abc123
    mount_path: /data.csv
  - type: file
    file_id: file_def456
    mount_path: /config.json
  - type: file
    file_id: file_ghi789
    mount_path: /src/main.py

resources = [
    {"type": "file", "file_id": "file_abc123", "mount_path": "/data.csv"},
    {"type": "file", "file_id": "file_def456", "mount_path": "/config.json"},
    {"type": "file", "file_id": "file_ghi789", "mount_path": "/src/main.py"},
]

resources: [
  { type: "file", file_id: "file_abc123", mount_path: "/data.csv" },
  { type: "file", file_id: "file_def456", mount_path: "/config.json" },
  { type: "file", file_id: "file_ghi789", mount_path: "/src/main.py" }
]

using Anthropic.Models.Beta.Sessions;

var resources = new[]
{
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_abc123", MountPath = "/data.csv" },
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_def456", MountPath = "/config.json" },
    new BetaManagedAgentsFileResourceParams { Type = BetaManagedAgentsFileResourceParamsType.File, FileID = "file_ghi789", MountPath = "/src/main.py" },
};

resources := []anthropic.BetaSessionNewParamsResourceUnion{
    {OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_abc123", MountPath: anthropic.String("/data.csv")}},
    {OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_def456", MountPath: anthropic.String("/config.json")}},
    {OfFile: &anthropic.BetaManagedAgentsFileResourceParams{Type: "file", FileID: "file_ghi789", MountPath: anthropic.String("/src/main.py")}},
}

import com.anthropic.models.beta.sessions.*;
import java.util.List;

var resources = List.of(
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_abc123").mountPath("/data.csv").build(),
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_def456").mountPath("/config.json").build(),
    BetaManagedAgentsFileResourceParams.builder()
        .type(BetaManagedAgentsFileResourceParams.Type.FILE).fileId("file_ghi789").mountPath("/src/main.py").build()
);

$resources = [
    ['type' => 'file', 'file_id' => 'file_abc123', 'mount_path' => '/data.csv'],
    ['type' => 'file', 'file_id' => 'file_def456', 'mount_path' => '/config.json'],
    ['type' => 'file', 'file_id' => 'file_ghi789', 'mount_path' => '/src/main.py'],
];

resources = [
  {type: "file", file_id: "file_abc123", mount_path: "/data.csv"},
  {type: "file", file_id: "file_def456", mount_path: "/config.json"},
  {type: "file", file_id: "file_ghi789", mount_path: "/src/main.py"}
]

A maximum of 500 files is supported per session.

Managing files on a running session

You can add or remove files from a session after creation using the session resources API. Each resource has an id returned when it is added (or listed), which you use for deletes.

resource=$(
  jq -n --arg file_id "${file_id}" '{type: "file", file_id: $file_id}' \
    | curl --fail-with-body -sS "${auth[@]}" \
        "${base_url}/sessions/${session_id}/resources" --json @-
)
resource_id=$(jq -er '.id' <<<"${resource}")
printf '%s\n' "${resource_id}"  # "sesrsc_01ABC..."

RESOURCE_ID=$(ant beta:sessions:resources add \
  --session-id "$SESSION_ID" \
  --type file \
  --file-id "$FILE_ID" \
  --transform id --raw-output)

resource = client.beta.sessions.resources.add(
    session.id,
    type="file",
    file_id=file.id,
)
print(resource.id)  # "sesrsc_01ABC..."

const resource = await client.beta.sessions.resources.add(session.id, {
  type: "file",
  file_id: file.id,
});
if (resource.type !== "file") {
  throw new Error(`Unexpected resource type: ${resource.type}`);
}
console.log(resource.id); // "sesrsc_01ABC..."

var resource = await client.Beta.Sessions.Resources.Add(session.ID, new()
{
    Type = "file",
    FileID = file.ID,
});
Console.WriteLine(resource.ID);  // "sesrsc_01ABC..."

resource, err := client.Beta.Sessions.Resources.Add(ctx, session.ID, anthropic.BetaSessionResourceAddParams{
    BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{
        Type:   anthropic.BetaManagedAgentsFileResourceParamsTypeFile,
        FileID: file.ID,
    },
})
if err != nil {
    panic(err)
}
fmt.Println(resource.ID) // "sesrsc_01ABC..."

var resource = client.beta().sessions().resources().add(
    session.id(),
    ResourceAddParams.builder()
        .betaManagedAgentsFileResourceParams(
            BetaManagedAgentsFileResourceParams.builder()
                .type(BetaManagedAgentsFileResourceParams.Type.FILE)
                .fileId(file.id())
                .build()
        )
        .build()
);
IO.println(resource.id()); // "sesrsc_01ABC..."

$resource = $client->beta->sessions->resources->add(
    $session->id,
    type: 'file',
    fileID: $file->id,
);
echo "{$resource->id}\n";  // "sesrsc_01ABC..."

resource = client.beta.sessions.resources.add(
  session.id,
  type: "file",
  file_id: file.id
)
puts resource.id # "sesrsc_01ABC..."

List all resources on a session with resources.list. To remove a file, call resources.delete with the resource ID:

curl --fail-with-body -sS "${auth[@]}" \
  "${base_url}/sessions/${session_id}/resources" \
  | jq -r '.data[] | "\(.id) \(.type)"'

curl --fail-with-body -sS "${auth[@]}" -X DELETE \
  "${base_url}/sessions/${session_id}/resources/${resource_id}" >/dev/null

ant beta:sessions:resources list --session-id "$SESSION_ID"

ant beta:sessions:resources delete \
  --session-id "$SESSION_ID" \
  --resource-id "$RESOURCE_ID"

listed = client.beta.sessions.resources.list(session.id)
for entry in listed.data:
    print(entry.id, entry.type)

client.beta.sessions.resources.delete(resource.id, session_id=session.id)

const listed = await client.beta.sessions.resources.list(session.id);
for (const entry of listed.data) {
  if (entry.type !== "memory_store") {
    console.log(entry.id, entry.type);
  }
}

await client.beta.sessions.resources.delete(resource.id, {
  session_id: session.id,
});

var listed = await client.Beta.Sessions.Resources.List(session.ID);
await foreach (var entry in listed.Paginate())
{
    var type = entry.Match<string>(repo => repo.Type, fileRes => fileRes.Type, memoryStore => memoryStore.Type);
    Console.WriteLine($"{entry.ID} {type}");
}

await client.Beta.Sessions.Resources.Delete(resource.ID, new() { SessionID = session.ID });

listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{})
if err != nil {
    panic(err)
}
for _, entry := range listed.Data {
    fmt.Println(entry.ID, entry.Type)
}

if _, err := client.Beta.Sessions.Resources.Delete(ctx, resource.ID, anthropic.BetaSessionResourceDeleteParams{
    SessionID: session.ID,
}); err != nil {
    panic(err)
}

var listed = client.beta().sessions().resources().list(session.id());
for (var entry : listed.data()) {
    if (entry.isFile()) {
        var fileResource = entry.asFile();
        IO.println(fileResource.id() + " " + fileResource.type());
    } else if (entry.isGitHubRepository()) {
        var repoResource = entry.asGitHubRepository();
        IO.println(repoResource.id() + " " + repoResource.type());
    }
}

client.beta().sessions().resources().delete(
    resource.id(),
    ResourceDeleteParams.builder().sessionId(session.id()).build()
);

$listed = $client->beta->sessions->resources->list($session->id);
foreach ($listed->data as $entry) {
    echo "{$entry->id} {$entry->type}\n";
}

$client->beta->sessions->resources->delete($resource->id, sessionID: $session->id);

listed = client.beta.sessions.resources.list(session.id)
listed.data.each { puts "#{it.id} #{it.type}" }

client.beta.sessions.resources.delete(resource.id, session_id: session.id)

Listing and downloading session files

Use the Files API to list files scoped to a session and download them.

# List files associated with a session
curl -fsSL "http://localhost:38080/v1/files?scope_id=sesn_abc123" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

# Download a file
curl -fsSL "http://localhost:38080/v1/files/$FILE_ID/content" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -o output.txt

# List files associated with a session
ant beta:files list --scope-id sesn_abc123 \
  --beta managed-agents-2026-04-01

# Download a file
ant beta:files download --file-id "$FILE_ID" --output output.txt

# List files associated with a session
files = client.beta.files.list(
    scope_id="sesn_abc123",
    betas=["managed-agents-2026-04-01"],
)
for file in files:
    print(file.id, file.filename)

# Download a file
content = client.beta.files.download(files.data[0].id)
content.write_to_file("output.txt")

// List files associated with a session
const files = await client.beta.files.list({
  scope_id: "sesn_abc123",
  betas: ["managed-agents-2026-04-01"]
});
for (const file of files.data) {
  console.log(file.id, file.filename);
}

// Download a file
const content = await client.beta.files.download(files.data[0].id);
await content.writeToFile("output.txt");

// List files associated with a session
var files = await client.Beta.Files.List(new FileListParams
{
    ScopeID = "sesn_abc123",
    Betas = ["managed-agents-2026-04-01"],
});

// Download a file
byte[] content = await client.Beta.Files.Download(files.Data[0].ID);
await File.WriteAllBytesAsync("output.txt", content);

// List files associated with a session
files, err := client.Beta.Files.List(ctx, anthropic.BetaFileListParams{
    ScopeID: anthropic.String("sesn_abc123"),
    Betas:   []anthropic.AnthropicBeta{"managed-agents-2026-04-01"},
})
if err != nil {
    panic(err)
}

// Download a file
resp, err := client.Beta.Files.Download(ctx, files.Data[0].ID, anthropic.BetaFileDownloadParams{})
if err != nil {
    panic(err)
}
defer resp.Body.Close()
out, err := os.Create("output.txt")
if err != nil {
    panic(err)
}
defer out.Close()
if _, err := io.Copy(out, resp.Body); err != nil {
    panic(err)
}

// List files associated with a session
var files = client.beta().files().list(FileListParams.builder()
    .scopeId("sesn_abc123")
    .addBeta(AnthropicBeta.of("managed-agents-2026-04-01"))
    .build());

// Download a file
try (HttpResponse response = client.beta().files().download(files.data().get(0).id())) {
    try (InputStream body = response.body()) {
        Files.copy(body, Path.of("output.txt"), StandardCopyOption.REPLACE_EXISTING);
    }
}

// List files associated with a session
$files = $client->beta->files->list(
    scopeID: 'sesn_abc123',
    betas: ['managed-agents-2026-04-01'],
);

// Download a file
$content = $client->beta->files->download($files->data[0]->id);
file_put_contents('output.txt', $content);

# List files associated with a session
files = client.beta.files.list(
  scope_id: "sesn_abc123",
  betas: ["managed-agents-2026-04-01"]
)

# Download a file
content = client.beta.files.download(files.data[0].id)
File.binwrite("output.txt", content.read)

Supported file types

The agent can work with any file type, including:

Source code (.py, .js, .ts, .go, .rs, and others)
Data files (.csv, .json, .xml, .yaml)
Documents (.txt, .md)
Archives (.zip, .tar.gz) - the agent can extract these using bash
Binary files - the agent can process these with appropriate tools

File paths

Files mounted in the sandbox are read-only copies. The agent can read them but cannot modify the original uploaded file. To work with modified versions, the agent writes to new paths within the sandbox.

The path you specify is rooted under the session’s uploads directory: a mount_path of /data.csv places the file at /mnt/session/uploads/data.csv in the sandbox
If you omit mount_path, the file is placed at /mnt/session/uploads/<file_id>
Parent directories are created automatically
Paths should be absolute (starting with /)

First steps

Define your agent

Configure agent environment

Delegate work to your agent

Manage agent context

Advanced orchestration

Reference

Uploading files

Mounting files in a session

Multiple files

Managing files on a running session

Listing and downloading session files

Supported file types

File paths

​Uploading files

​Mounting files in a session

​Multiple files

​Managing files on a running session

​Listing and downloading session files

​Supported file types

​File paths

Uploading files

Mounting files in a session

Multiple files

Managing files on a running session

Listing and downloading session files

Supported file types

File paths