Foundry Agent 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)

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

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

Install dependencies

python -m pip install -r requirements.txt

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

Run the agent

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 例子

通用遥测属性

故障排除

• 缺少导入项跑 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）标志，用于在冒险模式和天气指令配置文件之间切换。
• 将缓存运行步骤或响应保存到磁盘以供离线分析。