FoundryAgent-MCP 翻译为中文是：“Foundry代理-MCP（或：Foundry代理-多控制平面/管理控制平面，具体翻译取决于MCP在此上下文中的具体含义）”。不过，由于“MCP”可能是一个特定于某个领域或公司的缩写，没有上下文很难给出最准确的翻译，所以这里提供了两种可能的解释。在实际应用中，应根据具体上下文来确定最合适的翻译
概述
FoundryAgent-MCP 是一个 Python 示例，展示了如何驱动一个 Azure AI Foundry 代理，该代理能够调用：
- 模型上下文协议（MCP）工具（例如，一个暴露天气信息的MCP服务器）
get_alerts，get_forecast）。 - 当您提供现有的向量存储ID时，Foundry的“文件”（向量存储）搜索工具可用于检索增强型响应。
- 通过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
- Copy
.envand 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
- Ensure you are authenticated for Azure (e.g.
az login, managed identity, or service principal creds).
Install dependencies
python -m pip install -r requirements.txtIf 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该脚本将：
- （如果提供了Application Insights连接字符串）则初始化遥测。
- 创建一个绑定到指定模型部署的代理。
- 附加MCP工具定义，并可选地附加文件搜索工具定义（如果
FILES_VECTOR_STORE_IDS（当前）并创建代理。 - 发布已配置的用户消息并创建运行。
- 轮询运行状态；当模型提议工具调用时，运行进入
requires_action并且脚本会自动批准符合条件的MCP/File Search调用。 - 将流运行状态、实时步骤追踪（如已启用）、工具审批以及对话数据输出到控制台（并在启用时输出到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）标志，用于在冒险模式和天气指令配置文件之间切换。
- 将缓存运行步骤或响应保存到磁盘以供离线分析。