AI导哈

AI代理工具集成服务

FoundryAgent-MCP是一个展示如何驱动Azure AI Foundry代理的Python示例，支持调用MCP工具、文件搜索工具和连接其他代理，适用于需要多工具协作和增强响应的场景。

  • by pdas-codespace
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 pdas-codespace/FoundryAgent-MCP

使用说明

FoundryAgent-MCP 翻译为中文是：“Foundry代理-MCP（或：Foundry代理-多控制平面/管理控制平面，具体翻译取决于MCP在此上下文中的具体含义）”。不过，由于“MCP”可能是一个特定于某个领域或公司的缩写，没有上下文很难给出最准确的翻译，所以这里提供了两种可能的解释。在实际应用中，应根据具体上下文来确定最合适的翻译

概述

FoundryAgent-MCP 是一个 Python 示例，展示了如何驱动一个 Azure AI Foundry 代理，该代理能够调用：

  1. 模型上下文协议（MCP）工具（例如，一个暴露天气信息的MCP服务器） get_alerts， get_forecast）。
  2. 当您提供现有的向量存储ID时，Foundry的“文件”（向量存储）搜索工具可用于检索增强型响应。
  3. 通过AI Foundry的“连接代理”工作流编排功能，使用另一个代理作为工具

它还向Azure Monitor / Application Insights流式传输操作遥测数据。该项目会配置一个AI项目客户端，创建一个与您的模型部署绑定的代理，绑定MCP（机器学习编排器）和（可选）文件搜索功能，并协调执行整个流程，包括调用连接代理、调用MCP工具以及步骤级别的跟踪。

主要特点

  • Azure AI Foundry 代理编排 由……提供支持/驱动 azure-ai-projects 并且 azure-ai-agents。
  • MCP工具集成 用于天气数据查询（get_alerts， get_forecast）。
  • 铸造文件搜索（向量存储）集成 通过提供现有的向量存储ID来 FILES_VECTOR_STORE_IDS （无需重建商店）。
  • 连接代理协调代理可以在单次运行中选择MCP工具和文件搜索（需通过工具审批关卡），从而实现多工具推理。
  • 步骤级追踪与推理捕捉 当……的时候 ENABLE_STEP_TRACE=true （显示增量运行步骤和建议的工具调用）。
  • Application Insights 监控 通过Azure Monitor OpenTelemetry导出器，实现结构化日志记录和跨度追踪。
  • 环境驱动的配置 使用一个 .env 文件和 python-dotenv。

先决条件

  • Python 3.10 或更高版本（已测试过 3.12 版本）。
  • 一个可访问Azure AI项目和模型部署的Azure订阅。
  • 如果您需要遥测数据，请使用一个 Application Insights（Azure Monitor）资源。
  • 访问一个与MCP兼容的天气服务（示例中需要提供服务器URL和标签）。

项目结构

WeatherAgent.py     # Main entry point that sets up and runs the agent
requirements.txt    # Python dependencies
.env                # Environment variable template (do not commit real secrets)
```text

## Configuration

1. Copy `.env` and fill in the required values:
   - `PROJECT_ENDPOINT`: Azure AI project endpoint URL.
   - `MODEL_DEPLOYMENT_NAME`: Name of your model deployment (e.g. `gpt-4o`).
   - `MCP_SERVER_URL`: Base URL of the Weather MCP server.
   - `MCP_SERVER_LABEL`: Friendly label for the MCP server (used in the tool definition).
   - `APPLICATIONINSIGHTS_CONNECTION_STRING`: *(optional)* Connection string for your Application Insights instance.
   - `FILES_VECTOR_STORE_IDS`: *(optional)* Comma-separated list of existing vector store IDs to enable the File Search tool (e.g. `vs_weather_docs,vs_adventure_gear`). If omitted, File Search is not attached.
   - `AGENT_INSTRUCTIONS`: *(optional)* Override system instructions for the agent (multi-line supported). If not set, defaults provided in code.
   - `USER_ADVENTURE_PROMPT` / `USER_WEATHER_PROMPT`: *(optional)* Override initial user message.
   - `ENABLE_STEP_TRACE`: *(optional, default `true`)* Emit live run step tracing (reasoning + pending tool calls) to console + telemetry.
   - `AGENT_ID`: *(optional)* If set, reuses an existing agent instead of creating a new one. Clear/unset this if you add new tools (e.g. File Search) and need them attached during agent creation.
   - `CONNECTED_AGENT_ID`: *(optional)* If set, uses an existing agent to create a connected workflow

2. Ensure you are authenticated for Azure (e.g. `az login`, managed identity, or service principal creds).

## Install dependencies

```powershell
python -m pip install -r requirements.txt
```text

> If you are using a virtual environment, activate it first (e.g. `.\.venv\Scripts\Activate.ps1`).

## Run the agent

```powershell
python WeatherAgent.py

如果你添加 FILES_VECTOR_STORE_IDS 稍后（或之前）已固定（或置顶）了一个 AGENT_ID，清晰 AGENT_ID 因此，代理被重新创建，并绑定了文件搜索工具：

Remove-Item Env:AGENT_ID -ErrorAction SilentlyContinue
$env:FILES_VECTOR_STORE_IDS = "vs_weather_docs,vs_adventure_gear"
python WeatherAgent.py

该脚本将：

  1. （如果提供了Application Insights连接字符串）则初始化遥测。
  2. 创建一个绑定到指定模型部署的代理。
  3. 附加MCP工具定义，并可选地附加文件搜索工具定义（如果 FILES_VECTOR_STORE_IDS （当前）并创建代理。
  4. 发布已配置的用户消息并创建运行。
  5. 轮询运行状态；当模型提议工具调用时，运行进入 requires_action 并且脚本会自动批准符合条件的MCP/File Search调用。
  6. 将流运行状态、实时步骤追踪（如已启用）、工具审批以及对话数据输出到控制台（并在启用时输出到Application Insights）。

代理编排流程

User Prompt -> Agent (system instructions) -> Model reasoning -> (Propose tool calls?) -> requires_action
      -> Tool approvals (script) -> submit approvals -> model executes tools (MCP / File Search)
      -> Additional reasoning -> final answer -> run completion

步进追踪打印出的线条如下所示：

[STEP TRACE] id=step_abc status=in_progress type=message_creation
   tool_calls (1 pending):
      - id=call_xyz type=file_search

这些也会作为OpenTelemetry跨度事件发出，以便进行深入诊断。

使用 Application Insights 进行监控

  • 日志以结构化属性发出（weather_agent 日志记录器（logger）。
  • 一个名为（某名）的跨度 weather_agent.run 捕获整体执行情况；在 Application Insights > 事务中进行检查。
  • 每个SDK调用都被封装在一个子跨度（例如。 runs.create， run_steps.list）。
  • 实时运行步骤（启用时）以名为的跨度事件形式出现 run_step 具有以下属性： step.id， step.status， tool.call.count，以及任何启发式方法 step.reasoning 文本已捕获。
  • 工具选择决策通过事件记录 tool_selection 和 tool_selection_error。
  • 通过扩展助手来添加自定义指标或追踪信息 log_info 函数或使用 tracer 例子

通用遥测属性

属性 含义
weather.agent_id 创建/重用的代理ID
weather.run.status 最终运行状态
weather.user_prompt 截断的初始用户提示（前500个字符）
step.reasoning 捕获的推理片段（启发式）
tool.call.count 该步骤中提议的工具调用次数

故障排除

  • 缺少导入项跑 python -m pip install -r requirements.txt 拉取所有依赖项。
  • 认证错误确认 az login 或者服务主体环境变量已设置。
  • 遥测数据未显示请再次检查Application Insights的连接字符串，并验证出站网络访问。
  • 文件搜索工具未使用确保 FILES_VECTOR_STORE_IDS 在创建代理之前进行设置，并且 AGENT_ID 未设置，因此会创建一个新的代理。请确认向量存储ID是有效的。
  • 未提出任何工具调用这个模型可能认为它可以直接回答——请加强指令，要求“在回答产品或目录相关问题之前，先使用文件搜索”。进行调整 AGENT_INSTRUCTIONS 因此，相应地。
  • 现有代理缺少新工具移除 AGENT_ID 或者删除该代理，以便使用更新的工具定义重新创建它。

下一步

  • 将示例MCP URL替换为您自己的工具服务器。
  • 将用户提示参数化以接受动态输入。
  • 将代理打包为 Azure 函数、容器应用或 Web 作业以实现自动化。
  • 通过自定义指标或仪表板扩展监控功能。
  • 为长时间运行添加重试/退避或指数级轮询策略。
  • 集成一个命令行界面（CLI）标志，用于在冒险模式和天气指令配置文件之间切换。
  • 将缓存运行步骤或响应保存到磁盘以供离线分析。

相关 MCP