如何限制 Agent 的文件访问范围，防止越权访问

大家好，今天介绍如何在 Microsoft Agent Framework 中使用 FileAccessProvider，为 Agent 提供本地文件访问能力，并控制文件访问范围和操作权限。

本文通过一个完整示例，介绍如何使用 FileSystemAgentFileStore 指定文件访问目录，以及如何通过 FileAccessProvider 将文件访问能力接入 Agent，实现销售数据的自动分析。

一、FileAccessProvider 是什么

FileAccessProvider 是 Microsoft Agent Framework 提供的上下文提供程序（AI Context Provider），可以为 Agent 提供文件访问工具，而不需要我们自己实现文件读写功能。

它支持以下操作：

这些工具由 Framework 提供，我们只需要配置 FileAccessProvider，就可以将相应的能力交给 Agent。

同时，还可以根据业务需求控制文件操作权限。例如，数据分析场景通常只需要读取文件，我们就可以禁用写入工具，避免 Agent 修改原始数据。

二、准备测试数据

首先，准备一份 CSV 文件，命名为 sales.csv。

product,quantity,unit_price
Laptop,2,5000
Mouse,10,80
Keyboard,5,200
Monitor,3,1500

其中，product 表示商品名称，quantity 表示销售数量，unit_price 表示商品单价。

我们希望 Agent 读取文件后，按照 quantity × unit_price 计算每个商品的销售额，并汇总总销售额。

将文件放在应用程序输出目录下的 working 文件夹中：

应用程序输出目录
└── working
    └── sales.csv

后续将这个目录配置为 Agent 的文件访问根目录。

三、创建 FileAccessProvider

首先，通过 FileSystemAgentFileStore 指定文件存储位置，并创建 FileAccessProvider。

var workingDirectory = Path.Combine(AppContext.BaseDirectory, "working");
var salesFile = Path.Combine(workingDirectory, "sales.csv");

if (!File.Exists(salesFile))
{
    thrownew FileNotFoundException(
        "未找到示例数据。请确认 sales.csv 已复制到输出目录的 working 文件夹。",
        salesFile);
}

#pragma warning disable MAAI001
using FileAccessProvider fileAccessProvider = new(
    new FileSystemAgentFileStore(workingDirectory),
    new FileAccessProviderOptions
    {
        DisableWriteTools = true,
        DisableReadOnlyToolApproval = true,
    });
#pragma warning restore MAAI001

这里主要关注三个配置。

1. FileSystemAgentFileStore

FileSystemAgentFileStore 是基于本地文件系统的存储实现，通过 workingDirectory 指定 Agent 可以访问的文件存储根目录。

示例中还通过 File.Exists() 检查 sales.csv 是否存在，避免文件缺失导致后续分析失败。

2. DisableWriteTools

DisableWriteTools = true,

禁用写入相关工具，Agent 无法通过该 Provider 创建、修改或删除文件，适合只读数据分析场景。

3. DisableReadOnlyToolApproval

DisableReadOnlyToolApproval = true,

关闭只读工具的审批要求，让 Agent 可以直接执行文件列表、读取和搜索操作。

通过这两个选项，我们就为 Agent 配置了一套无需逐次审批的只读文件访问能力。

四、将 FileAccessProvider 添加到 Agent

接下来使用 Microsoft Foundry 创建 Agent。

首先初始化 AIProjectClient：

AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());

然后创建 Agent，并将 FileAccessProvider 添加到 AIContextProviders：

#pragma warning disable MAAI001, OPENAI001
AIAgent agent = aiProjectClient
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClientWithStoredOutputDisabled(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "FileAccessDataAnalyst",
        Description = "读取受限 working 目录中的文件并分析销售数据。",
        ChatOptions = new ChatOptions
        {
            ModelId = deploymentName,
            Instructions =
                """
                你是一名销售数据分析助手，只能访问 file_access_* 工具公开的文件。
                回答前必须先列出可用文件，再读取相关文件。
                只能根据实际读取到的文件内容回答，不要编造数据。
                """,
        },
        AIContextProviders = [fileAccessProvider],
    });
#pragma warning restore MAAI001, OPENAI001

这里最关键的是：

AIContextProviders = [fileAccessProvider],

通过这个配置，Agent 就获得了 FileAccessProvider 提供的文件访问工具。

另外，我们在 Instructions 中要求 Agent 先列出文件，再读取相关内容，确保分析基于实际文件数据。

需要注意的是，Instructions 只是行为指导，真正的文件访问范围和操作权限仍然由 File Store 及 Provider 配置控制。

最后，通过 RunAsync() 提交分析任务：

Console.WriteLine($"允许访问的目录：{workingDirectory}");
Console.WriteLine("正在分析 sales.csv...\n");

AgentResponse response = await agent.RunAsync(
    """
    请先列出可用文件，再读取 sales.csv。
    按商品计算销售额（quantity * unit_price），最后给出全部商品的总销售额。
    请使用简洁的表格展示计算过程和结果。
    """);

Console.WriteLine(response);

整个过程中，我们没有提前读取 CSV 内容，而是由 Agent 自主调用文件工具，获取数据并完成分析。

五、为什么不直接把文件内容传给 Agent

可能有人会问，为什么不直接在应用程序中读取文件，再将内容传给 Agent？

对于少量文件，这种方式确实更加简单。

但如果有几十个甚至几百个文件，将所有内容提前放进 Prompt，不仅会增加 Token 消耗，也会引入大量与当前任务无关的信息。

FileAccessProvider 则允许 Agent 按需访问文件。

例如，分析 sales.csv 时读取指定文件；查找关键词时，通过搜索工具定位相关内容。

这样，应用程序不需要提前准备所有文件内容，而是由 Agent 根据任务决定需要获取哪些信息。

六、FileAccessProvider 和自定义 Function Tool 有什么区别

在 Microsoft Agent Framework 中，我们也可以通过 Function Tool 实现文件读取。

例如，自定义一个读取销售数据的方法，再将其注册为工具，Agent 同样可以读取文件内容。

两者的区别主要在于用途。

Function Tool 更适合封装查询订单、获取客户信息、调用业务 API 等特定操作。

而 FileAccessProvider 已经提供了通用文件访问工具，不需要重复开发。

两者也可以组合使用。例如，让 Agent 先读取本地 CSV，再调用业务工具查询数据库，最后汇总分析结果。

七、总结

通过 FileAccessProvider，我们可以方便地为 Microsoft Agent Framework 中的 Agent 添加文件访问能力。

实现方式主要分为三步：

1. 使用 FileSystemAgentFileStore 指定文件存储根目录。
2. 通过 FileAccessProviderOptions 配置文件操作权限。
3. 将 FileAccessProvider 添加到 Agent 的 AIContextProviders 中。

相比直接将文件内容传给模型，FileAccessProvider 可以让 Agent 根据任务按需读取文件，同时控制可用的文件操作能力。

对于文档分析、日志检索、报表生成等需要访问本地文件的 Agent 应用，这是一个比较实用的功能。

源代码地址

https://github.com/bingbing-gui/dotnet-agent-playbook/tree/master/src/ai-agent/Agent-Framework/67-FileAccessProvider