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

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

使用 C# 工具构建 AI 代理不再是小众实验；它正迅速成为自动化实际工作流程、连接企业数据以及在应用程序中扩展智能助手的实用方法。 将现代大型语言模型 (LLM) 与可靠的 .NET 工程相结合，就可以从基本的聊天机器人发展成为功能强大的、使用工具的代理，这些代理可以读取文件、执行代码、调用 API 并在结构化的工作流程中协作。

本指南将引导您了解创建能够安全高效地使用工具和外部数据的 AI 代理所需的核心概念、架构模式、.NET 构建模块和具体的 C# 示例。 我们将把 OpenAI / Azure OpenAI 助手、微软的 .NET 代理生态系统、编排模式以及可观测性、安全性、生产部署等现实世界问题联系起来。

理解人工智能代理及其在 C# 中的重要性

人工智能代理的核心是旨在实现目标而非仅仅回答孤立问题的系统。 智能体会分析任务，将其分解为多个步骤，决定使用哪些工具，并在环境中采取行动以达成目标结果。在 C# 中，这通常意味着将智能体封装在一个服务中，该服务可以与用户交互、调用 API、访问数据库，并不断迭代直到获得满足目标的结果。

现代智能体的大部分力量来源于三种能力：推理、工具使用和情境感知。 推理通常由逻辑逻辑模型（LLM）或其他决策算法驱动，工具涵盖从代码执行到HTTP API和文件搜索等各种方式，而上下文则由聊天记录、企业数据、向量存储或知识图谱构成。当这三者结合在一起时，你的C#应用程序就不再仅仅是“输入提示/输出文本”，而是开始像一个半自主工作单元一样运行。

随着任务变得越来越复杂，代理通常会在工作流程中进行协调，而不是孤立地行动。 例如，企业网站的一项功能上线可能需要经历需求收集、设计、实现、测试和部署等流程。这些阶段中的每一个都可以由智能代理提供支持或部分自动化，这些代理可以协作、交接工作，并将结构化的结果反馈到下一个步骤，而不是仅仅与用户聊天。

工作流思维在 .NET 后端中尤为重要，因为代理必须接入现有的服务、日志记录、安全策略和部署管道。 不要将代理视为神奇的黑盒子，而是将其视为架构中的另一个组件：它接收输入、调用工具、产生输出，并由遥测、验证和业务逻辑进行封装。

.NET 中 AI 助手和代理的核心组件

当您使用 OpenAI 或 Azure OpenAI SDK 在 C# 中构建 AI 助手时，您将使用一组与代理概念完美对应的基本组件。 理解这些要素将有助于你设计出强大的代理程序，而不是临时编写的脚本。

助手是主要的 AI 客户端对象，它封装了模型配置、系统指令和工具定义。 它知道要调用哪个 LLM（例如，通过 Azure OpenAI 调用 gpt-4o），它应该如何运行，以及它被允许调用哪些工具，例如文件搜索功能或用于数据分析的代码解释器环境。

一个线程代表用户与助手之间的对话会话。 线程存储消息的按时间顺序排列的列表，跟踪上下文，并在对话过长超出模型上下文窗口时自动处理截断。实际上，您可以为每个用户或每个用例创建一个线程，以便代理能够随时间推移保持状态的一致性。

消息是指对话中由用户或助手编写的各个回合。 每条消息都可以包含纯文本、图像和其他文件。对于处理业务数据的代理来说，消息可能包含对已上传文档的引用、工具生成的图像或指向您存储中文件的引用。

运行是指助手在给定线程状态下的实际执行。 触发运行后，助手会读取线程消息，根据需要选择工具，调用模型，并将结果附加到新消息中。可以观察和轮询运行过程，直到其达到终止状态。这对于将代理集成到必须返回响应或触发下游操作的 .NET 服务中至关重要。

运行步骤是对代理在运行期间所执行操作的详细跟踪。 这包括每一次工具调用、每一条中间消息，以及代理从用户请求到最终输出的整个过程。检查运行步骤对于调试、审计以及理解代理做出某些决策的原因至关重要，尤其是在受监管或影响较大的环境中。

除了这些基本功能之外，还可以配置助手并行使用多个工具，以更有效地完成任务。 常见的例子包括：用于执行分析或可视化代码片段的代码解释器；将模型决策映射到您自己的 C# 方法的函数调用；以及允许代理在您的私有文档或销售数据中查找答案的向量存储文件搜索。

设计 C# AI 代理的架构

从架构角度来看，将你的 AI 堆栈视为两层是明智的：一层是模型提供程序之上的聊天客户端抽象层，另一层是管理上下文和工具的代理。 聊天层隐藏了您正在使用的模型（OpenAI、Azure OpenAI 或其他提供商），而代理层包含特定于业务的技能，例如检索、编写或与外部系统集成。

一个切实可行的方法是将代理构建为专门的组件，而不是单一的整体式超级代理。 您可以设置一个代理专注于搜索和事实核查，另一个代理专门负责撰写或重写内容，第三个代理负责调用外部 API 或数据库。每个代理都更容易测试、部署和安全维护，而且您可以独立分配资源限制或令牌预算。

状态和内存管理必须被视为一种不断增长的资源，而不是事后才考虑的事情。 对话和工作流日志会迅速累积，因此您需要一些策略，例如定期汇总旧消息、为每个用户或场景创建单独的线程，以及优先处理语义重要内容的策略。在 .NET 环境中，这通常意味着将内存上下文与持久存储相结合，以实现可审计性和可恢复性。

工具的出现，使得客服人员不再仅仅是功能强大的聊天机器人，而是开始创造切实的商业价值。 通过将原生 C# 函数作为工具公开，您可以允许模型请求诸如“查询此数据库”、“生成图表”或“调用此外部 REST API”之类的操作。每个工具都应包含清晰的元数据和参数模式文档，以便 LLM 可以决定何时以及如何调用它。

稳健的工具执行需要严格的安全措施，因为工具中的任何故障都可能破坏用户体验，甚至如果不加以检查，还会损坏系统。 在实践中，您需要为工具强制执行超时、严格的输入验证、防御性异常处理和速率限制。这样，代理程序就能分析故障，安全地重试，或者优雅地降级，同时确保您的基础架构始终受到保护。

对于复杂的业务任务，多代理编排通常比让单个代理承担所有职责更有效。 您可以创建“研究”代理来收集信息，创建“分析”代理来综合分析或进行计算，以及创建“撰写”代理来生成所需格式的最终​​输出。这些代理通过结构化消息和共享工作区进行通信，从而提高专业化程度，并增强审计或审查的可追溯性。

使用 C# 构建一个极简助手

为了了解这些想法在实际代码中是如何体现的，请考虑一个最基本的 .NET 控制台应用程序，该应用程序创建一个 AI 助手，能够搜索销售数据集并生成可视化效果。 使用 OpenAI 或 Azure OpenAI SDK，您可以设置客户端、上传文件、配置工具并运行对话线程。

首先，你需要创建你的代理将依赖的 OpenAI 客户端。 一个客户端与核心模型和助手 API 通信，另一个可选的 Azure 专用客户端则使用 Azure Identity 进行身份验证，指向您的 Azure OpenAI 终结点。由此，您可以派生出一个 AssistantClient 用于管理助手，以及一个 FileClient 用于上传和检索文件。

接下来，您需要在内存中准备样本数据，并将其作为文件上传，以便助手可以通过文件搜索使用该文件。 例如，您可以构建一个描述不同产品 ID 月度销售额的 JSON 有效负载，将其转换为数据流，并以“用途”设置为“助手”的方式发送到 OpenAI 文件端点。返回的文件标识符随后会成为您的向量存储配置的一部分。

数据准备就绪后，您可以配置助手选项以启用文件搜索和代码解释器。 您为助手取一个易于理解的名称，编写清晰的指令，例如“当用户请求图表时，您可以分析销售数据并生成可视化图表”，并附加文件搜索和代码执行的工具定义。此外，您还设置了工具资源，用于创建一个包含已上传销售文件的新矢量存储库，以便助手可以执行检索增强型生成操作。

配置好助手后，您可以创建助手实例，并通过初始用户问题启动对话线程。 提示信息可能会询问某个特定产品在二月份的销售情况，并要求提供其随时间变化的趋势图。您需要调用一个操作，该操作既创建线程又启动运行，然后按定时循环轮询运行状态，直到运行结束，这表明代理已完成推理和工具调用。

运行完成后，从线程中检索所有消息，并遍历这些消息以显示结果并处理生成的文件。 对于每条消息，您需要打印其角色（用户或助手）以及所有文本内容，包括引用输入或输出文件的注释。如果助手生成了图像文件（例如，代码解释器创建的图表），您需要通过文件客户端获取其元数据和字节，将其保存为 PNG 格式到磁盘，并将文件名记录到控制台。

这个最简单的场景说明了使用工具的代理的完整生命周期：它读取问题，搜索向量化数据集，运行代码来构建可视化，并将文本和图像返回给用户。 从这里开始，您可以使用您喜欢的 .NET 技术栈将相同的模式集成到 Web API、桌面应用程序或后台服务中。

.NET 构建模块：Microsoft.Extensions.AI、矢量数据和代理框架

除了原始的 SDK 调用之外，微软还在投资一套分层的 .NET 库，使 AI 代理更具可组合性和可测试性。 两个核心软件包是 Microsoft.Extensions.AI 和 Microsoft.Extensions.VectorData，它们共同构成了更高级别的 Microsoft Agent Framework 的基础。

Microsoft.Extensions.AI 专注于将模型访问、工具和 AI 相关管道抽象到与其他 .NET 扩展一致的接口背后。 使用此软件包，您可以在不更改应用程序其余部分的情况下切换模型提供程序，通过依赖注入注入 AI 服务，并以熟悉的方式将日志记录、缓存或安全过滤器等行为链接在一起。

Microsoft.Extensions.VectorData 提供用于以一致、与提供程序无关的方式处理矢量存储和检索的基本功能。 它允许您定义如何索引文档、存储嵌入以及查询它们以进行相似性搜索，这对于您的代理必须根据内部文档、策略或交易日志而不是凭空想象来回答问题至关重要。

在这些基础之上，是 Microsoft Agent Framework，它为创建代理、定义其工作流程和协调多代理系统提供了结构化的模式。 虽然细节还在不断演变，但其理念是将代理和工作流视为 .NET 中的一等公民：您可以定义目标、插入工具、连接上下文提供程序，并让框架处理常见的问题，例如编排模式和状态进展。

这些构建模块自然地融入了标准的 .NET 开发模型中，其中配置、依赖注入、日志记录和中间件模式已经很熟悉了。 与其专门为 AI 发明一套全新的技术栈，不如在现有服务中添加 AI 功能，同时仍然遵守公司治理、DevOps 实践和代码质量标准。

面向人工智能代理的工作流编排模式

现实世界中的智能体很少像单次线性调用模型那样运行；它们参与到精心设计的流程中，这些流程定义了任务如何从开始到结束。 不同的编排模式满足不同的业务需求，了解这些模式有助于设计更可预测的系统。

顺序工作流程是最直接的，其中代理依次处理任务并将输出传递给下游。 这可以很简单，比如先有一个提取代理从文档中提取数据并构建结构，然后是一个验证代理，最后是一个报告代理。每个阶段都会等待前一个阶段完成后再运行。

并发工作流允许多个代理或子任务在依赖关系允许的情况下并行运行。 例如，一个代理可能分析销售业绩，而另一个代理则汇总客户反馈，两者都基于同一数据集。完成后，一个综合代理会将他们的发现合并成一份报告。这种模式可以显著降低复杂流程的整体延迟。

交接工作流程根据条件或结果在代理人之间转移责任。 初始分诊代理会对请求进行分类；如果检测到计费问题，则会将相关信息转发给财务专员，而技术问题则会转交给技术支持代理。交接流程可以在 C# 编排代码中显式实现，也可以通过监督代理隐式实现，由监督代理决定下一步由谁处理。

群聊工作流程将多个客服人员置于同一个对话环境中，让他们实时交换信息。 在这种架构下，代理可以进行辩论、互相评价答案或交叉核对数据，然后再向用户呈现最终回复。编排层控制发言轮次，并确保对话保持有序且可观察。

磁性工作流引入了一个主要的“控制器”代理，该代理协调其下属的一组专门代理。 主代理分析目标，决定需要哪些下属代理参与，汇总它们的输出，并管理重试或错误处理。这种结构在企业系统中尤为有用，因为它既能提供单一入口点，又能利用后台的专用代理。

工具、函数调用以及与 C# 代码的集成

扩展代理的最有效方法之一是通过以强类型 C# 函数形式实现的工具，LLM 可以在运行时请求这些工具。 与其赋予模型自由形式的控制权，不如公开一个具有结构化输入和输出的安全操作目录，代理可以在需要时调用这些操作。

函数调用通过描述每个工具的用途、参数和预期响应格式来工作，以便模型可以决定何时使用某个工具。 例如，您可以定义一个名为 GetCustomerById 的工具，它需要一个 customerId 参数，并返回基于记录的结果。模型的作用是选择何时调用该工具以及使用哪些参数。

在 .NET 方面，每个工具都必须配备相应的防护措施，使其能够投入生产使用。 这包括捕获异常而不是让异常向上冒泡给用户，强制执行超时或取消令牌，验证用户提供的参数，以及限制任何副作用。当工具写入数据库、触发外部工作流或调用第三方服务时，这一点尤为重要。

在处理分析或数据处理的代理中，可以使用代码解释器工具来执行沙盒代码，以进行转换和可视化。 代理程序可以生成 Python 或 C# 代码片段来计算聚合数据或创建图表，并在安全环境中运行这些代码，然后将结果以图像或数据表的形式返回。您的 C# 宿主应用程序控制着沙箱，以防止不受信任的代码逃逸或访问敏感资源。

文件搜索工具通过为代理提供对文档和知识库的结构化访问权限，来补充函数调用。 上传的文件会被索引到向量存储库中，以便智能体能够检索语义相关的段落，并基于可验证的来源给出答案。在 C# 中，你需要管理文件的上传、索引和生命周期，而智能体则专注于请求正确的文本块。

测试、可观测性和成本管理

在没有进行严格测试和可观测性的情况下将人工智能代理投入生产，会迅速导致不可预测的行为和成本飙升。 因为代理可以调用​​工具、循环执行工作流程并生成长时间的对话，所以你需要低级测试策略和端到端测试策略。

单元测试侧重于工具和编排代码，而不是模型本身。 您可以模拟 LLM 响应、模拟工具调用，并验证您的 C# 逻辑是否能正确处理成功、部分失败和完全失败的情况。您还可以在这里测试输入验证、超时和重试策略，将工具视为任何其他关键服务依赖项。

情景测试或对话测试通过具有代表性的提示和预期来检验整个工作流程。 例如，您可以录制一系列用户消息，并验证代理是否选择了正确的工具、遵守了业务规则，以及输出结果是否在可接受的范围内。这些测试有助于在升级模型、工具或提示策略时发现回归问题。

可观测性应包括延迟、令牌使用情况、工具使用情况以及每条路径的成功率等指标。 您想了解每次代理运行需要多长时间、消耗了多少令牌、哪些工具调用最频繁以及错误集中在哪里。标准的 .NET 日志框架和跟踪工具可以很好地集成到这些功能中，使 AI 专用遥测数据能够与现有应用程序指标并列显示。

会话长度和内存策略直接影响成本和性能。 过长的线程会导致更多的令牌计数和更慢的响应速度，因此实现智能截断和摘要至关重要。代理可以定期将较早的上下文摘要成更短的形式，或者将详细的历史记录存储在外部存储器中，每次运行仅加载相关的部分。

从财务角度来看，监控每个租户、每个功能或每个工作流程的代币使用情况并强制执行预算或配额通常是有益的。 这一点在基于 .NET 构建的多租户 SaaS 产品中尤为重要，因为如果放任不管，单个配置错误的代理可能会产生意想不到的账单。

安全、合规和企业准备情况

当代理程序处理敏感的企业数据或在生产系统中执行实际操作时，安全性和合规性必须从一开始就融入到设计中。 智能代理不仅仅是聊天伙伴；它还是您基础设施的潜在控制界面。

数据访问应遵循与 .NET 服务其他部分相同的原则。 基于角色的访问控制、最小权限原则和租户隔离需要扩展到代理程序可以访问的任何工具或数据源。如果用户没有直接查看数据集的权限，代理程序也不应能够代表用户显示该数据集。

为了审计目的，应该记录每次工具调用，包括参数、调用者身份和结果。 这些日志能在出现问题时提供溯源线索，并在您需要证明谁在何时何地以及出于何种原因访问了哪些数据时，帮助您满足监管合规要求。您组织中的集中式日志管道可以将 AI 工具跟踪数据作为另一个数据流整合进来。

密钥和凭证绝不能硬编码到代理或提示中。 相反，它们存储在安全的配置存储、环境变量或托管身份系统中，您的 C# 代码会在运行时获取它们。代理本身应该只能看到不透明的句柄，而不能看到原始的连接字符串或 API 密钥。

任何与第三方服务的出站通信都应经过清理层，以清除敏感数据并执行策略。 代理有时会尝试发送超出实际需要的上下文信息，因此您的集成代码可以在数据离开您的环境之前对其进行过滤、屏蔽或聚合。这有助于防止意外数据泄露，并确保您遵守隐私承诺。

对于受监管行业的组织而言，明确记录代理人的行为、批准的工具和界限也很有价值。 像对待人类角色一样对待智能体：明确定义它们可以做什么、绝对不能做什么，以及如何处理例外情况。随着时间的推移，这将大大简化风险评估和治理工作。

部署、扩展和与开发者工具集成

从概念验证到用 C# 实现生产级 AI 代理，需要仔细考虑部署拓扑和扩展策略。 您希望代理程序在高负载下具有弹性，易于更新，并且与您的平台架构的其他部分兼容。

一个有用的模式是将控制平面与推理平面分开。 控制平面用于配置代理、模型、工具和工作流，而推理平面则由处理实时请求并调用模型的无状态服务组成。这种分离使您可以根据流量灵活地独立扩展推理实例。

基于容器的编排（例如 Kubernetes）天然适合代理工作负载，这些工作负载可能会出现峰值或涉及长时间运行的操作。 您可以将 C# 代理服务运行在容器中，并根据指标自动扩展，实现 分布式搜索中的负载均衡并使用作业队列将多步骤工作流或大型文档处理等长时间操作与同步用户交互解耦。

对于涉及多次工具调用或大量计算的代理任务，队列和后台工作线程尤其方便。 您的 API 可以接收请求，将描述目标的任务加入队列，并让工作进程处理该工作流程，同时在共享存储中更新状态和结果。用户随后可以轮询或订阅更新，而无需等待单个耗时的 HTTP 调用。

在企业环境中，通常会将代理输出导入 BI 仪表板和分析平台。 例如，可以将结果导出到 Power BI 或类似工具，从而实现自动化分析与决策之间的闭环。您的 C# 服务充当 AI 层和传统报表堆栈之间的桥梁。

面向开发者的工具，例如 Azure AI Foundry 和 Visual Studio Code 的 AI 相关扩展，可以简化模型和代理的生命周期。 在 VS Code 中，您可以浏览模型目录，部署 GitHub 托管或本地模型（例如通过 Ollama），并排比较多个模型的输出，并运行评估以了解性能差异。

这些工具还可以更轻松地以可视化的方式创建和改进代理，然后将配置同步到存储库中的 YAML 或代码。 您可以添加 Bing 搜索或代码解释器等工具，将它们连接到代理设计中，为 Azure 集成生成 C# 代码片段，并更快地迭代提示和代理行为，而无需不断重建整个应用程序。

综合来看，强大的 .NET 库、云 AI 平台和现代工具的组合，形成了一个强大的生态系统，用于构建、运行和发展由 C# 工具驱动的 AI 代理。 通过将代理建模为目标导向系统，使其融入工作流程，使其具备可观察性，并强制执行严格的安全边界，您可以创建真正增强组织能力的助手，而不是充当不透明的黑盒子。