如何使用 C# 工具构建 AI 代理

主页 » Python » 如何使用 C# 工具构建 AI 代理

使用 C# 工具构建 AI 代理不再是遥不可及的未来梦想；它是一种非常实用的方法，可以自动化工作流程、分析数据并将 .NET 应用程序与大型语言模型 (LLM) 连接起来。借助正确的架构，您可以从简单的聊天客户端过渡到生产级代理，这些代理可以进行推理、调用 API、编排工作流并遵守企业约束，例如安全性、可观测性和成本控制。

本指南将引导您了解现代 AI 代理概念如何映射到 C# 技术栈，Azure OpenAI 和 OpenAI Assistants API 如何融入其中，以及如何将所有内容集成到强大的 .NET 软件工程实践中。我们还将这些想法与微软在 Visual Studio Code 中新兴的代理框架和 AI 工具联系起来，以便您能够从本地原型到可扩展的云部署获得完整的视图。

从聊天机器人到 C# 中的完整 AI 代理

从宏观层面来看，人工智能代理是一个追求目标而非仅仅回答单个提示的系统。这意味着智能体需要推理、工具、上下文感知和记忆的某种组合，以便决定下一步要做什么，而不仅仅是在当前回合中如何回应。

用 C# 的实际术语来说，您可以将代理视为 LLM 客户端之上的一个协调层，外加一组以 .NET 方法、API 或外部服务形式公开的工具。该模型负责推理和语言理解，而您的 C# 代码负责业务逻辑、数据访问、安全性和与现有系统的集成。

现代智能体通常依赖大型语言模型来进行决策、搜索算法或规划逻辑，但只有当它们与工具连接起来时，才能真正发挥作用。工具可能包括数据库查询、HTTP API、内部微服务、文件搜索或沙盒代码解释器，代理可以在其中安全地运行数据分析代码。

上下文感知是最后一个关键环节，它使智能体能够利用聊天记录、向量存储、企业数据或知识图谱进行推理。上下文可以像保存在内存中的简短对话日志一样简单，也可以像跨越多个代理和数据存储的分布式工作流状态一样复杂。

人工智能助手和代理的核心构建模块

OpenAI 和 Azure OpenAI Assistants API 提供了一组非常具体的 C# 基础组件，用于构建代理。与其手动创建状态机，不如使用定义明确的实体，这些实体与基于 LLM 的代理的思考和操作方式相匹配。

助手代表已配置的 AI 角色：它使用哪个模型、遵循哪些指令以及允许调用哪些工具。在 C# 中，这映射到一个你创建的对象，该对象具有名称、系统指令和工具定义列表等选项，这些定义描述了模型可以调用的内容。

对话线程是指用户与助手之间随着时间推移而建立的对话会话。该线程存储有序的消息列表，自动处理上下文截断以保持在令牌限制内，并作为该交互的代理记忆的骨干。

消息是指用户和助手之间传递的具体内容。在 Assistants API 中，消息可以包含纯文本、图像或其他文件。在 C# 中，您可以将它们作为集合中的对象来使用，并根据内容检查文本、注释或关联的文件 ID。

运行是指启动助手对线程内容进行推理的操作。一旦开始运行，助手就会应用其配置，读取消息，根据需要调用工具，然后将包含结果的新消息附加到同一线程中。

运行步骤记录了助手在运行过程中执行的详细操作顺序。通过检查这些日志，您可以查看调用了哪些工具、传递了哪些参数、生成了哪些消息以及代理如何得出最终结果。这对于企业环境中的调试、可观测性和审计来说极其宝贵。

除了这些基本功能之外，助手还可以并行使用多个工具来完成任务。典型的内置工具类型包括：可在沙盒运行时运行代码片段的代码解释器、自定义函数调用（将您自己的 .NET 函数公开为工具）以及利用外部知识扩展模型的文件搜索功能。

使用工具：代码执行、函数调用和文件搜索

工具可以将被动的语言模型转换为能够实际完成 .NET 应用程序内部任务的强大代理。该模型不仅可以返回文本，还可以根据用户请求的需要，选择调用函数、执行代码或搜索文件存储。

代码解释器工具允许智能体在隔离环境中编写和运行代码，以执行数据分析、可视化或基本模拟等任务。在 C# 中，您不能直接运行该代码；您需要配置助手以使其具备代码解释器功能，然后读取它生成的输出，例如生成的图像或结构化结果。

函数调用将您自己的领域逻辑作为工具公开出来，供模型选择和调用。您需要使用元数据描述每个函数：名称、用途和参数结构。然后，助手会根据用户输入和中间推理结果选择何时触发这些函数，而您的 C# 实现则负责处理验证、错误和超时。

文件搜索工具允许代理程序根据外部数据（例如文档、报告或知识库）做出响应。您上传文件、创建矢量存储库或索引，并授予助手访问权限。之后，模型可以检索相关内容片段并将其整合到答案中，从而提高事实准确性和可追溯性。

关键的设计原则是，工具必须安全可靠，具备强大的输入验证、错误处理机制和明确的资源限制。即使 LLM 选择何时调用它们，您的 C# 代码仍然完全负责执行业务规则、速率限制和数据访问策略。

使用 Azure OpenAI 创建一个最小的 .NET 控制台应用程序代理

为了具体化所有这些，您可以从一个简单的 .NET 控制台应用程序入手，该应用程序可以与 OpenAI 或 Azure OpenAI Assistants API 通信。这种极简项目非常适合完全以代码形式存在的概念验证代理，但它们已经使用了工具、文件和对话线程。

第一步是创建 .NET 控制台项目，并添加必要的 SDK 包，以便访问 OpenAI 和 Azure OpenAI 客户端。有了这些就绪，您可以使用 API 密钥实例化一个通用的 OpenAI 客户端，或者使用指向 Azure OpenAI 终结点并使用 DefaultAzureCredential 等凭据实例化一个 Azure 特定的客户端。

从通用客户端可以衍生出各种专用客户端：例如用于管理助手、线程和运行的助手客户端，以及用于上传和下载文件的文件客户端。这种分离可以清楚地区分哪些操作是关于配置和编排的，哪些是关于原始文件处理的。

然后，您可以直接在 C# 代码中创建内存文档流来模拟真实的业务数据。例如，您可以定义一个包含不同产品 ID 的月度销售指标的小型 JSON 文档，并将其转换为文件客户端可以上传的流。

文件上传供助手使用后，平台会返回一个文件标识符，您可以将其链接到新的矢量图库，并将其作为文件搜索资源附加到助手。在同一助手配置中，您还可以启用代码解释器，以便代理不仅可以查找值，还可以生成图表或更高级的分析。

在准备好助手选项（包括名称、指令和工具定义）后，您可以创建基于 gpt-4o 等模型的助手。您还可以配置一个包含初始用户消息的线程，例如询问特定产品随时间推移的性能并请求可视化。

辅助客户端允许您创建线程并在一次调用中立即启动运行，然后轮询运行状态，直到运行达到终止状态。这种轮询循环对于命令行工具来说简单有效；在 Web 或后台服务环境中，您可以改用事件驱动或异步模式。

运行完成后，按升序将线程中的消息流式传输回控制台，并将助手回复打印出来。对于每条内容，您可以检查文本、引用输入或输出文件的注释，以及代码解释器生成的任何图像，然后将其保存到磁盘并在控制台输出中使用简单的占位符标签记录。

状态管理、记忆和会话设计

一旦你不再局限于玩具示例，状态和内存就会成为 C# 代理设计中的核心问题。挑战在于对话历史记录会无限增长，而模型有严格的令牌限制，而且您还需要保留数据以用于合规性、分析或调试。

一种常见的策略是为每个用户或用例维护单独的线程或会话，并定期总结对话内容，以便仅保留最相关的上下文。摘要可以由模型本身生成，然后与结构化元数据一起存储在数据库或向量存储中。

更高级的方法在决定保留、压缩或丢弃哪些内容时，会考虑语义重要性。与其简单地删除最旧的消息，不如按主题、实体或业务流程标记或索引内容，并运行有针对性的查询，以重建新运行所需的上下文。

在 C# 中，内存通常通过进程内缓存（用于快速访问）和持久化存储（用于持久性和可审计性）的组合来实现。这可能意味着将用于结构化元数据的关系数据库与用于跨非结构化内容进行语义搜索的向量数据库配对，所有这些都隐藏在存储库接口之后，您的代理可以调用​​这些接口而无需关心底层技术。

精心设计的对话也至关重要：您应该编写系统说明、工具描述和用户提示，以便语言学习者能够在您的领域范围内有效推理。这包括明确代理何时应该提出澄清问题，何时应该调用工具，以及何时应该拒绝超出其允许范围的请求。

工具包括 C# 函数、API 和外部服务

在实际应用中，最强大的工具是您自己的领域函数，将其公开，以便代理可以协调跨内部系统的工作。这些操作可能包括创建工单、查询客户记录、运行财务计算或触发现有微服务中的工作流等。

对于每个工具，您都需要提供丰富的元数据，描述其功能、所需输入和返回值，理想情况下，应采用机器可读的模式。这有助于法学硕士选择合适的工具，构建有效的论点，并正确解释结果，从而减少错觉和失误。

在实现方面，C# 中的每个工具处理器都需要防御性编程：严格的输入验证、强大的异常处理和合理的超时机制。代理可能会尝试一些没有商业意义的事情；你的代码必须强制执行策略，而不是假设模型总是以可预测的方式运行。

此外，最好记录每次工具调用，包括调用用户、触发提示信息以及结果。这样可以为您提供清晰的审计跟踪，支持安全审查，并使您能够调整哪些工具最有效或需要额外的防护措施。

.NET 中的多代理编排和工作流

随着场景变得越来越复杂，您可能会发现单个代理不足以应对，需要多个专业代理协同工作。例如，一个代理人可能专注于研究和数据收集，另一个专注于分析，第三个专注于编写用户友好的输出文件。

从概念上讲，这与 .NET 开发人员已经熟悉的工作流程模式非常吻合：顺序步骤、并行分支、交接和主管角色代理之间不是使用硬编码逻辑，而是通过结构化消息和共享工作区进行协调，但其协调模式却让人感到熟悉。

顺序工作流将一个代理的输出直接传递给下一个代理，非常适合需求收集、设计、实现和审查等线性任务。并行工作流允许多个代理同时处理问题的不同方面，然后在后续步骤中合并它们的结果。

交接模式允许根据置信度阈值、内容类别或用户操作等条件，将责任从一个代理转移到另一个代理。群聊式设置将多个客服人员置于同一个对话环境中，他们可以在对话中讨论各种方案，交流见解，并实时达成解决方案。

监督式或层级式架构引入了一个管理代理，负责审查中间结果、分配任务和解决冲突。在 .NET 中，您可以使用后台工作程序、消息队列或工作流引擎来表示这种编排，而代理本身则通过 Assistants API 或相关抽象进行通信。

Microsoft.Extensions.AI、VectorData 和 Agent Framework

为了让 .NET 开发人员能够更轻松地构建代理，微软正在引入一些基础库，例如 Microsoft.Extensions.AI 和 Microsoft.Extensions.VectorData。这些库的设计旨在让您感觉与已经用于日志记录、配置和依赖项注入的其他 Microsoft.Extensions 包类似。

AI 扩展程序提供模块化组件，以可插拔的方式使用模型、工具和提示。与其硬编码特定的 LLM 供应商，不如注册模型提供商并通过配置进行切换，这在需要平衡不同环境的成本、延迟和功能时非常有用。

矢量数据扩展专注于将语义搜索和检索增强生成功能集成到您的应用程序中。它们抽象化了具体的向量数据库实现，并提供了用于存储、搜索和管理嵌入的通用接口，从而为你的代理的长期记忆提供支持。

在这些构建模块之上，Microsoft Agent Framework 旨在提供更高层次的抽象，专门针对代理和工作流场景量身定制。虽然细节仍在不断发展，但其目的是提供一种一致的方式来定义代理、工具、工作流和上下文，并与更广泛的 .NET 和 Azure 生态系统紧密集成。

AI Toolkit、Azure AI Foundry 和 Visual Studio Code 中的代理

许多开发者更喜欢直接在编辑器中探索和构建智能体原型，而这正是 Visual Studio Code 的 AI Toolkit 和 Azure AI Foundry 扩展发挥作用的地方。它们共同作用，让您无需离开编码环境即可浏览模型、部署模型、评估质量并将其连接到代理。

AI Toolkit 扩展程序提供了一个模型目录，您可以在其中查看云端托管和本地模型，包括通过 Ollama 等工具提供的模型。您可以快速启动托管在 GitHub 上的模型，并排比较不同模型的输出，快速查看哪个模型适合您的用例。

Azure AI Foundry 集成又增添了一层功能：您可以将模型直接部署到 Azure，生成用于调用模型的示例 C# 客户端代码，并直接在 VS Code 中调整配置和元数据。这简化了从实验到生产的路径，尤其适用于您的团队已经在 Azure 生态系统中工作的情况。

这些扩展程序还能帮助您进行评估，让您可以设置测试数据集、运行评估并在 Data Wrangler 等工具中查看结果。您可以定义针对您领域的自定义评估器，对多批模型输出运行这些评估器，并可视化您的代理在哪些方面表现良好或表现不佳。

对于代理构建，该工具支持创建带有系统提示的代理、自动生成系统消息以及连接到公开外部工具的模型上下文协议 (MCP) 服务器。您甚至可以构建密室逃脱式或特定领域的代理，这些代理会调用代表您自己服务的定制 MCP 服务器。

在 Azure AI Foundry 本身中，您将获得可视化代理设计器以及 YAML 同步功能。这意味着您可以配置代理、附加 Bing 搜索或代码解释器等工具、在 Playground 中测试交互，然后将配置导出或同步到源代码控制中，从而保持您的 C# 代码和代理定义一致。

C# AI 代理的测试、可观测性和成本控制

生产就绪的代理程序需要像其他任何关键任务服务一样严格的测试：全面的测试、良好的遥测数据和持续的成本管理。区别在于，LLM引入了随机输出和代币使用等新变量，您也必须密切关注这些变量。

在测试方面，你需要将经典的单元测试（用于测试你的工具）和集成式对话测试（用于模拟真实的用户流程）结合起来。单元测试验证每个工具在给定特定输入的情况下是否行为正确，而对话测试检查代理是否选择合理的工具，产生有效的论点并保持在策略边界内。

可观测性不应仅仅记录成功或失败；您还需要延迟分布、令牌消耗、运行步骤跟踪和工具调用统计信息。这些指标可以帮助您在更改模型、提示或工具实现时更容易地发现回归问题，并帮助您调整系统以提高性能和降低成本。

成本控制与您如何管理对话时长和工具调用频率密切相关。冗长、无限制的对话会造成令牌使用量激增，并减慢响应速度，因此，在任何严肃的 C# 部署中，摘要、上下文窗口和智能截断等策略都至关重要。

此外，最好跟踪特定执行路径或工作流程层面的成功率，而不仅仅是整个代理层面的成功率。这样，你就可以看到多代理系统中哪些路径是可靠的，哪些路径需要更好的提示、新的工具或额外的防护措施。

安全、合规和企业集成

当您的代理开始接触敏感数据或自动化关键业务操作时，安全性和合规性绝不能被忽视。LLM 的灵活性与企业的限制相结合，需要非常谨慎的安全策略。

首先，永远不要在 C# 代码中硬编码凭据或密钥。在云平台、环境变量或托管身份中使用标准密钥管理机制，并确保代理进程仅拥有其真正需要的权限。

其次，代表代理人发出的每一个外部调用都应该经过清理和验证层。这包括用户输入和模型生成的工具参数，因为两者都可能包含意外的、格式错误的或恶意的内容。

第三，您应该记录并审核每次工具调用，包括关键上下文信息，例如用户、调用代理、目标系统和结果。在受监管的行业中，这种审计追踪可能是强制性的；即使在这些环境之外，它对于事件响应和治理也具有不可估量的价值。

最后，使您的部署架构与企业模式保持一致，例如分离控制平面和推理平面。这意味着将编排、配置和监控与繁重的推理过程隔离开来，从而提高可扩展性、安全性和运营弹性。

部署、扩展和连接到分析

一旦您的 C# 代理在测试中运行良好，您就需要一种能够优雅扩展并与技术栈其他部分集成的部署策略。容器、编排器和托管式 AI 服务是你的得力助手。

一种常见的模式是将代理编排层打包到容器中，并在 Kubernetes 或其他编排器下运行，同时将 LLM 推理委托给 Azure OpenAI 等托管服务。这样，您可以根据需求波动独立地扩展控制平面和推理平面。

与代理进行长时间或高强度交互时，异步处理和队列通常会带来好处。与其在复杂的多步骤运行完成时阻塞 HTTP 请求，不如将工作项排队，让后台工作程序处理它们，并在结果准备就绪时通知客户端。

从商业角度来看，真正的价值往往体现在将代理的输出结果输入到分析和商业智能工具中。这可能意味着将结构化摘要、决策或指标推送到数据仓库，并通过 Power BI 或其他 BI 平台中的仪表板将其公开。

这个闭环——智能体生成洞察或行动、分析衡量影响、团队迭代提示和工具——将人工智能从一项新奇技术转变为一种可持续的运营能力。随着时间的推移，您可以逐步确定哪些代理商能带来最高的投资回报率，哪些工作流程应该进一步自动化，以及哪些环节必须保留人工监督。

将所有这些组件整合在一起，最终会形成一个以 C# 为中心的生态系统，其中助手、工具、工作流和云服务相互协作：助手 API 提供对话推理功能，您的 .NET 代码提供强大的工具和状态管理，Microsoft.Extensions 库提供清晰的抽象，而 Azure AI Foundry 和 AI Toolkit 则简化了实验和部署。通过对内存、可观测性、安全性和架构的精心关注，这些代理可以为您的组织带来真正可衡量的效率、决策质量和自动化方面的改进。