用 C# 智能体框架简化发票处理
文章用 Microsoft Agent Framework 重写 PDF 发票智能体,保留供应商校验工具与结构化输出,将示例从约 320 行缩至 136 行。框架接管请求构造、工具循环和模式生成,同时讨论三个需要检查的默认行为。
AI 深度解读
把 PDF 发票交给模型,调用 C# 函数核对供应商,再把审核结果装进一个 record,这套流程可以手写,也可以交给 Microsoft Agent Framework。作者用同一个 GPT-6.1 Terra 示例做了两种实现,代码从约 320 行降到 136 行。
但少写代码不等于少做检查。工具名、严格模式和字段命名都有容易忽略的默认行为。更关键的是,作者验证了框架发出的请求格式,却没有用 Terra 的真实部署完成验证。读这篇最有价值的收获,是理解框架接管了什么,以及哪些责任仍在开发者手里。
从 320 行到 136 行,框架接管了什么
这个发票 Agent 的流程很明确:读取 PDF,让模型提取发票信息,调用 check_supplier 核对供应商,再返回结构化审核结果。规则包括:总额超过 5000,或者供应商未登记、状态不活跃,就需要审批;金额计算不一致、缺少 PO 编号等问题要列出来,没有问题则返回空列表。
手写 HttpClient 时,开发者需要自己拼 JSON、声明工具参数、执行工具调用、续接响应,再处理结果反序列化。Microsoft Agent Framework 把这些步骤封装起来,但底层仍然使用 Responses API 的请求结构。
作者通过本地替身服务检查了实际请求:PDF 作为 input_file 发送,内容使用 data:application/pdf URL;后续请求通过 previous_response_id 续接;C# 函数的执行结果以 function_call_output 回传。框架省掉的是这些协议处理代码。
在应用层,AsAIAgent 把客户端配置成 AIAgent,其中 model 填的是部署名。AIFunctionFactory.Create 从普通 C# 方法的参数和 [Description] 属性生成工具 schema,返回的 SupplierLookup record 也会序列化成 JSON,供模型继续处理。
最终调用 RunAsync<InvoiceReview> 时,框架从 InvoiceReview 生成 JSON Schema,通过 text.format 发给模型,再把结果放进 response.Result。属性上的描述也会进入 schema,例如告诉模型日期应采用 ISO 8601 格式。
PDF 则通过媒体类型为 application/pdf 的 DataContent 传入,Name 用来设置文件名。按原文说明,模型会接收提取出的文字和每页图像,因此 token 消耗高于只传文字。框架简化了接口,没有消除这笔成本。
包装起来以后,仍要看懂底层请求
安装依赖时,作者使用 dotnet new console -n GPT-6-1-Terra-AgentFramework-CSharp-Sample 创建项目,进入同名目录,再分别添加 Microsoft.Agents.AI.OpenAI、Azure.Identity、Microsoft.Extensions.Configuration.UserSecrets 和 Microsoft.Extensions.Configuration.EnvironmentVariables,最后执行 dotnet user-secrets init。
其中,Microsoft.Agents.AI.OpenAI 已经带入 OpenAI .NET SDK 和 Microsoft.Extensions.AI,无需重复添加。
作者遇到的兼容问题发生在另一条路径:Azure.AI.OpenAI 2.9.0-beta.1 与 Microsoft.Agents.AI.OpenAI 1.26.0 一起使用时能够编译,启动却在 GetResponsesClient() 抛出 MissingMethodException。作者将原因归结为前者依赖的 OpenAI SDK 与 Agent Framework 带入的较新版本不匹配。
他的处理方式是直接使用普通 OpenAI SDK 的 ResponsesClient,连接 Azure 的 https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1,绕过 Azure 专用客户端和这个 beta 包。
配置项仍是 AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_DEPLOYMENT 和可选的 AZURE_OPENAI_API_KEY,部署名示例为 gpt-6.1-terra。API key 通过 api-key 请求头发送;不配置 key 时,示例使用 DefaultAzureCredential 和 BearerTokenPolicy,令牌 scope 为 https://ai.azure.com/.default,本地可先执行 az login。
作者倾向于生产环境使用 Entra ID。不过,本地登录成功与生产身份配置完成是两件事,原文没有展开生产部署的身份安排。
项目可用 dotnet run 读取默认的 invoice.pdf,也支持 dotnet run -- path/to/your-invoice.pdf。需要留意,所提供原文的大段程序截断在 Console.WriteLine(,不能直接当成完整可运行源码。
三个默认行为,会让接口和预期错位
第一个是工具名。顶层程序中的局部函数 CheckSupplier,可能被 C# 编译成 _Main_g_CheckSupplier_0_0。模型仍可能调用它,但提示词、日志和实际请求里的名称不一致,移动代码还可能改变名称。
下面这段同时固定工具名,并要求适配器发送严格模式标记:
AIFunctionFactory.Create(CheckSupplier, new AIFunctionFactoryOptions
{
Name = "check_supplier",
AdditionalProperties = new Dictionary<string, object?> { ["strict"] = true }
})
要看的是 Name 和 AdditionalProperties 两行:函数在本地叫什么,与对模型暴露什么名字,可以明确分开。
第二个是严格模式。作者观察到,默认工具请求里的 "strict" 为 null,结果 schema 则没有 strict 标记。按照 schema 提示模型,与通过接口启用严格约束,不能混为一谈。
工具参数和最终输出的严格模式,需要分别配置。
工具侧设置还不够,运行时的 ChatOptions 也要设置。下面这段还展示了推理强度如何下传:
var options = new ChatClientAgentRunOptions(new ChatOptions
{
AdditionalProperties = new AdditionalPropertiesDictionary { ["strict"] = true },
RawRepresentationFactory = _ => new CreateResponseOptions
{
ReasoningOptions = new ResponseReasoningOptions { ReasoningEffortLevel = ResponseReasoningEffortLevel.Low }
}
});
其中,ChatOptions 没有推理强度的直接属性,所以要借助 RawRepresentationFactory 设置原始 Responses 选项。作者检查到的请求包含 "reasoning": {"effort": "low"}。这也说明,使用框架以后,仍可能需要接触底层 API 类型。
第三个是字段命名。框架从 InvoiceReview 生成的字段采用 camelCase,例如 supplierName、requiresApproval;作者前一版手写 schema 使用 snake_case。模型未必介意,日志对比、提示词和下游接口却可能受影响。作者因此让指令描述业务规则,避免直接绑定字段名。
我的判断
这篇最可靠的部分,是作者检查了框架实际发出的 JSON。工具名和 strict 配置属于可观察、可复查的行为,比只展示一份最终结果更有参考价值。
但验证边界必须说清:作者使用的是 Responses API 的本地替身,并未针对 Terra 真实部署测试。它能验证请求如何构造,不能证明目标部署一定支持严格结构化输出与工具调用的组合。
文末展示了供应商 Fabrikam Office Supplies、供应商编号 V-1042、状态 active,以及发票 INV-20481、日期 2026-10-12、采购单 PO-7734。金额为 6,545.96 USD,需要审批,问题列表还识别出文档自称代码演示样例、公司为虚构。
配套统计是 input=4292、cached=2113、output=134、reasoning=20、elapsed=4.8s。不过,原文没有交代这些数字与本地验证的关系,也没有提供真实部署的对照过程,不能据此判断 Terra 的稳定延迟或实际成本。
从约 320 行缩减到 136 行,能说明这个示例减少了样板代码,不能直接证明维护成本同步下降。框架也带来了依赖版本、序列化约定和适配器行为需要管理。
作者提出先用原始请求摸清模型,再迁移到框架,我认为适合接口探索和故障排查。至于增加第二个工具、人工审批或流式 UI 后,框架优势会更明显,这是合理的工程判断,但文中没有对应实现和对照数据,仍属于经验之谈。
能拿来做什么
- 给现有 Agent 做一次请求检查:确认实际工具名、工具与输出 schema 的 strict 标记,以及字段命名是否符合下游预期。前端或 Node 消费接口时,也应核对这些边界。
- 为文档审核流程保留业务校验。结构化输出能约束格式,金额阈值、供应商状态和审批条件仍应由确定性代码复核。
- 锁定依赖版本并主动升级。遇到编译通过、启动报
MissingMethodException的问题,先排查 SDK 依赖组合;原文列出的版本应视为故障样本。 - 在真实部署上验证 PDF、工具调用和严格输出能否共同工作。开发阶段记录请求有助于定位问题,但请求包含整份 PDF,按作者建议,上线前应关闭这类日志。