点对点异常检测锻造代理

Name: 点对点异常检测锻造代理
Author: MSFT-Innovation-Hub-India

作者：MSFT-Innovation-Hub-India6 星标更新：2025-07-06

安装使用来源：spider==github.com

项目介绍

技术文档摘要

P2P 异常检测代理

一个使用 Azure AI Foundry Agent 服务进行从采购到付款（Procure-to-Pay）异常检测的应用。该工具分析采购发票图像以检测采购异常和合规问题。Azure AI Foundry 展示的关键能力包括：

Agent 服务仅通过自然语言指令执行多步骤业务流程。应用程序代码中几乎没有业务逻辑。
在多步骤业务流程期间调用各种自动化工具操作。它展示了最近宣布的与 MCP Server、Azure Logic Apps 的一键集成。此外，它还使用了 a) 使用 gpt-4o 模型的图像视觉推理，b) 一键向量搜索，c) 推理以应用业务规则并执行 P2P 异常检测。
Azure AI Foundry 中 Agent 服务的能力：
- 最重要的是，业务流程中的所有步骤都通过应用程序对 Agent 服务的单次调用完成。Agent 根据自然语言指令自主编排这些步骤。客户端应用程序本身在代码中没有业务逻辑。
- 处理应用程序状态：在不同工具调用之间确定从一个工具调用的输出中提取什么内容作为下一个输入。
- 编排整个业务流程，按顺序执行以实现业务目标。

解决方案架构

下图显示了解决方案的架构。客户端应用程序是一个基于 Python 的控制台应用程序，它调用运行在 Azure AI Foundry Agent 服务中的 P2P 异常检测代理。

alt text

解决方案组件

序号	实体	实体目的或描述
1	Foundry Agent	自主代理，实现端到端的 P2P 异常检测过程。它通过一次 API 调用编排业务流程中的所有步骤，处理不同工具调用之间的应用程序状态，并按顺序执行以实现业务目标。
2	视觉推理工具调用	使用 GPT-4o 的视觉能力分析输入的采购发票图像，提取采购发票抬头、发票行、供应商 ID 和合同 ID。这些提取的信息随后用于后续调用 Logic App 进行合同验证。
3	Azure Logic App 工具调用	由代理通过 HTTP 触发器调用，传入从发票中提取的供应商 ID 和合同 ID。通过在 Azure SQL 数据库上执行动态 SQL 查询返回匹配的合同数据，提供合同抬头和行项目详细信息以与发票进行比较。
4	向量搜索工具调用	检索适用于企业环境中 P2P 异常检测的业务规则。使用配置的向量存储搜索上传的业务规则文档（p2p-rules.txt），查找相关的合规性和验证标准。
5	推理	应用检索到的业务规则来评估采购发票与合同数据的一致性。确定是否存在异常或合规问题，并生成包含裁决、比较和建议的详细验证报告。
6	MCP Server 工具调用	目录并存储生成的报告在 Azure Blob 存储中。MCP Server 实现特定协议的实现以连接到 Blob 存储服务，执行创建容器、列出容器和上传 blob 等生命周期操作。代理使用 MCP Server 将 markdown 验证报告上传到指定的容器。

解决方案的一些关键方面是：

客户端应用程序只向 Azure AI Foundry 中的代理发出一次调用。其余步骤由 Agent 服务自主完成。下面的代码片段显示了客户端应用程序将用户提供的发票图像和用户指令传递给 Azure AI Foundry 中的代理。
注意代码中没有任何业务逻辑，也没有编写任何工具动作的代码。这些是由代理自主完成的。


def process_anomaly_detection(self, user_prompt: str, image_path: str, verbose: bool = True) -> str:
        """
        带有适当错误处理和重试逻辑的异常检测请求处理。
        
        参数：
            user_prompt: 用户的异常检测提示
            image_path: 发票图像路径
            
        返回：
            来自 AI 代理的响应
            
        异常：
            Exception: 各种处理错误
        """
        try:
            # 创建消息内容
            self._show_progress("正在创建消息内容...", verbose)
            content_blocks = self.create_message_content(user_prompt, image_path)
            
            # 为此对话创建一个新的线程
            self._show_progress("正在创建对话线程...", verbose)
            thread = self.client.threads.create()
            logger.info(f"创建线程，ID: {thread.id}")
            
            # 创建消息
            self._show_progress("正在发送消息给代理...", verbose)
            message = self.client.messages.create(
                thread_id=thread.id, 
                role="user", 
                content=content_blocks
            )
            
            # 使用适当的错误处理运行代理
            self._show_progress("正在使用 AI 代理处理（这可能需要一段时间）...", verbose)
            run = self.client.runs.create_and_process(
                thread_id=thread.id, 
                agent_id=self.agent.id
            )
            
            if run.status == "failed":
                error_msg = f"代理运行失败: {run.last_error}"
                logger.error(error_msg)
                raise Exception(error_msg)
            
            # 获取并处理消息
            self._show_progress("正在检索分析结果...", verbose)
            messages = self.client.messages.list(
                thread_id=thread.id, 
                order=ListSortOrder.ASCENDING
            )
            
            # 提取代理的响应
            agent_response = ""
            for message in messages:
                if message.role == "assistant" and message.text_messages:
                    agent_response = message.text_messages[-1].text.value
                    break
            
            if not agent_response:
                raise Exception("未收到代理的响应")
            
            self._show_progress("分析完成！", verbose)
            logger.info("成功处理异常检测请求")
            return agent_response
            
        except Exception as e:
            logger.error(f"处理异常检测时出错: {e}")
            raise

先决条件

Python 3.12+
配置好的 Azure AI Agents 服务
Azure 凭据（托管标识、服务主体或交互式）

在 Azure AI Foundry 中为代理创建项目

参考此处所述步骤，在 Azure AI Foundry 中创建一个项目。我们需要项目的连接字符串来完成以下步骤。接下来，部署在此应用程序中使用的 gpt-4o 模型，以便代理可以使用。

创建具有 MCP 工具集成的代理

在上面创建的项目中，使用以下脚本在 Azure AI Foundry 中创建代理。将此整块复制粘贴到您的 bash 终端中。我提供了代理的临时指令，一旦创建后我会更新它们。

注意：在此处配置之前，MCP Server 必须正在运行。在我的情况下，它托管在 Azure 容器应用中。托管在此 MCP Server 上的代码的 GitHub 仓库可在此处找到：这里

首先执行 az 登录，然后执行以下命令：

AZURE_AI_FOUNDRY_PROJECT_ENDPOINT="https://p2p-anomaly-detection-a-resource.services.ai.azure.com/api/projects/p2p-anomaly-detection-agent"
API_VERSION="2025-05-15-preview"
echo "获取访问令牌..."
AGENT_TOKEN=$(az account get-access-token --resource 'https://ai.azure.com' --query accessToken --output tsv)
echo "令牌已获取，正在创建代理..."
curl --request POST \
  --url "$AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=$API_VERSION" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "instructions": "您是一个客户服务聊天机器人。使用提供的工具和知识库来最好地回应客户查询。",
      "tools": [
          {
              "type": "mcp",
              "server_label": "azure_storage_operations_mcp",
              "server_url": "https://mcp-server-az-storage-svc.wonderfulsea-77230f8f.southindia.azurecontainerapps.io/sse",
              "require_approval": "never"
          }
      ],
      "name": "p2p-anomaly-detection-agent",
      "model": "gpt-4o"
  }'

截至撰写本文时，MCP 工具与 Azure AI Foundry 中的代理服务的集成需要通过 REST API 调用来完成。一旦配置好，它将在代理中如下所示。

alt text

注意：一旦创建，托管代理的项目的连接字符串/端点以及代理 ID 需要存储在应用程序的 .env 文件中。见下文。

az_agentic_ai_service_connection_string="https://p2p-anomaly-detection-a-resource.services.ai.azure.com/api/projects/p2p-anomaly-detection-agent"
az_assistant_id = "asst_EZdyBrR1TXOk8ynapJLUvMFY"
LOG_LEVEL=INFO

代理指令

导航到 Azure AI Foundry，选择上面创建的代理，并按照下述方式更新指令，以执行 P2P 异常检测。

这是一个从采购到付款的过程。您将被提供采购发票图像作为输入。

请注意必须严格遵守的执行顺序：
- 只有在执行步骤 1 后才能执行步骤 2
- 只有在完成步骤 1 和步骤 2 后才能执行步骤 3。
- 只有在成功执行步骤 1、步骤 2、步骤 3 和步骤 4 后才能执行步骤 5。
- 只有在执行步骤 5 后才能执行步骤 6

步骤 1：首先，您将从采购发票图像中提取合同 ID 和供应商 ID，以及发票中的所有行项。
步骤 2：然后，您将通过传递合同 ID 和供应商 ID 到函数工具来检索合同详情。
步骤 3：然后，您将使用文件搜索工具检索适用于从采购到付款过程中检测异常的业务规则。
步骤 4：然后，应用检索到的业务规则来匹配发票行项与系统中检索到的合同详情，并检测任何异常。
步骤 5：准备一份详细的“p2p 验证报告”以 markdown 格式，包含以下内容：
 - 裁决：采购发票是否符合合同？
 - 采购发票详情：发票抬头和发票行，以 Markdown 表格格式
 - 合同详情：合同抬头和合同行，以 Markdown 表格格式
 - P2P 业务规则：使用文件搜索工具检索到的规则
 - 裁决背后的理由：提供详细的推理，说明为什么认为发票与合同一致或不一致。使用 Markdown 表格格式比较发票中的每一项与合同，并指出您判断的基础。使用图标/图像来美化报告，使其易于商务用户理解。他们必须能够快速浏览并提交发票到系统。
步骤 6：您将使用可用的 MCP 工具上传在步骤 5 中创建的“p2p 验证报告”。
 - 选择一个名为“p2p-anomaly-detection-outcomes”的容器进行上传。如果不存在此名称的容器，请创建一个。
 - 报告名称必须以发票编号开头，后面加上连字符和 GUID。例如：Invoice001-001.md
 - 通过 MCP 工具上传到 Blob 存储帐户的报告文档名称必须安全。
步骤 7：等待步骤 6 完成，然后返回上传到 Blob 存储的 Markdown 文档的内容。

alt text

按照上述步骤创建代理后，剩余的工具配置可以直接在 Azure AI Foundry 中进行。当然，您可以使用 SDK 通过代码执行这些步骤，但为了这篇文章的简单起见，我选择了这种方式。

创建并配置向量存储

将p2p-rules.txt作为知识源上传到代理，以创建向量存储。此文件包含适用于从采购到付款过程中检测异常的业务规则。创建后，应如图所示出现：

alt text

配置 Azure Logic App 作为代理的工具动作

在此处配置之前，必须先创建 Logic App。创建一个可以通过 REST API 调用触发的 Azure Logic App。Logic App 应实现 HTTP 请求触发器，并将最后一个动作设置为 HTTP 响应。

在本文涵盖的用例中，Logic App 用于根据从采购发票图像中提取的合同 ID 和供应商 ID 从 Azure SQL 数据库中检索合同抬头和合同行信息。

创建 Logic App

注意：Logic App 中的所有动作必须配置为同步运行。 有关更多详细信息，请参阅此处的文档。

为了运行此示例，创建一个类似于以下描述的 Logic App。Logic App 接收 ContractID 和 SupplierID。它使用这些参数在 Azure SQL 数据库上即时运行 T-SQL 查询，并返回合同抬头和行信息。

HTTP 触发器中使用的有效负载模式如下：

{
    "properties": {
        "ContractID": {
            "type": "string"
        },
        "SupplierID": {
            "type": "string"
        }
    },
    "type": "object"
}

以下是 Logic App 流程的截图：

logicapp

Logic App 动作应禁用异步模式。见下图：

alt text

将 Logic App 配置为代理的工具动作

使用 Azure AI Foundry 门户将 Logic App 配置为 P2P 代理的工具动作。见下图：

alt text

设置

安装依赖项
```
pip install -r requirements.txt
```

配置环境

cp .env.template .env
# 编辑 .env 文件以包含您的 Azure 配置

设置 Azure 认证
- 对于本地开发：使用 az login 进行交互式认证
- 对于生产环境：配置托管标识或服务主体

使用方法

交互模式

运行主脚本并遵循提示：

python p2pagent.py

脚本会要求：

发票图像的路径
分析提示（或使用默认值）

运行的示例输出：

(.venv) PS C:\Users\sansri\agentic-ai-service-samples\p2p-anomaly-detection-agent> python p2pagent.py
2025-07-04 09:04:22,149 - __main__ - INFO - 成功初始化 Azure AI Agents 客户端
2025-07-04 09:04:22,149 - INFO - 成功初始化 Azure AI Agents 客户端

=== P2P 异常检测代理 ===
此工具分析发票图像以检测采购异常。

请输入您的发票图像路径：data_files/Invoice-002.png

请输入您的分析提示（或按 Enter 使用默认值）：
能否根据您提供的指令执行从采购到付款的异常检测，并给我一个详细的响应，说明附带的采购发票图像是否与合同一致？

正在处理图像：C:\Users\sansri\agentic-ai-service-samples\p2p-anomaly-detection-agent\data_files\Invoice-002.png
正在使用 Azure AI 代理分析...
🔄 正在创建消息内容...
2025-07-04 09:04:46,774 - __main__ - INFO - 成功将图像转换为 base64：C:\Users\sansri\agentic-ai-service-samples\p2p-anomaly-detection-agent\data_files\Invoice-002.png
2025-07-04 09:04:46,774 - INFO - 成功将图像转换为 base64：C:\Users\sansri\agentic-ai-service-samples\p2p-anomaly-detection-agent\data_files\Invoice-002.png
2025-07-04 09:04:46,777 - __main__ - INFO - 成功创建消息内容块
2025-07-04 09:04:46,777 - INFO - 成功创建消息内容块
🔄 正在创建对话线程...
2025-07-04 09:04:47,231 - __main__ - INFO - 创建线程，ID: thread_Lz8ViyvcnDMG9i9TGkgE7jq6
2025-07-04 09:04:47,231 - INFO - 创建线程，ID: thread_Lz8ViyvcnDMG9i9TGkgE7jq6
🔄 正在发送消息给代理...
🔄 正在使用 AI 代理处理（这可能需要一段时间）...
🔄 正在检索分析结果...
🔄 分析完成！
2025-07-04 09:05:55,543 - __main__ - INFO - 成功处理异常检测请求
2025-07-04 09:05:55,543 - INFO - 成功处理异常检测请求

==================================================
异常检测结果
==================================================
### P2P 验证报告

#### **裁决：**
采购发票**不符合**合同。

---

#### **采购发票详情**

| **属性**        | **值**                                                                    |
|------------------|------------------------------------------------------------------------------|
| **发票编号**    | INV001002                                                                   |
| **合同参考**     | CON000002                                                                   |
| **供应商 ID**    | SUP0008                                                                     |
| **总发票金额**   | 113130.16 USD                                                              |
| **发票日期**     | 2023-06-