注册和管理自定义代理

Microsoft Foundry 控制平面为跨不同平台和基础结构运行的代理提供集中管理和可观测性。 可以注册在Azure计算服务或其他云环境中运行的自定义代理，以便了解其操作并控制其行为。

本文介绍如何在 Foundry 控制平面中注册自定义代理。 了解如何配置智能体进行注册、设置数据集合和使用 Foundry 控制平面的管理功能。

先决条件

• 具有活动订阅的Azure帐户。 如果没有订阅，请创建一个 free Azure 帐户，其中包括免费试用订阅。

• 铸造项目。 如果没有项目， 请创建一个项目。

• 在 Foundry 资源中配置的 AI 网关。 Foundry 使用 Azure API 管理 将代理注册为 API。

• 一款通过可访问的终结点部署并公开使用的智能体。 终结点可以是公共终结点，也可以是可从部署 Foundry 资源的网络访问的终结点。

添加自定义代理

可以在 Foundry 控制平面中注册自定义代理。 选择您偏好的技术来开发适合平台和基础设施解决方案的代理。

注册自定义代理时，Foundry 使用 API 管理作为代理服务器来代理与您的代理的通信，以便能够控制访问并监控活动。

下图显示了注册自定义代理时生成的体系结构。

验证代理

验证代理是否满足注册要求：

准备您的铸造项目

在注册已添加到 Foundry 项目的自定义代理之前，请确保正确配置项目：

1. 登录到 Microsoft Foundry。 确保 “新建 Foundry ”开关处于打开状态。 这些步骤适用于 Foundry（新版）。

   

2. 确保在项目中配置 AI 网关：

   1. 在工具栏上，选择“ 操作”。

   2. 在左窗格中，选择“ 管理员”。

   3. 打开 “AI 网关 ”选项卡。

   4. 该窗格列出配置并映射到 Foundry 资源的所有 AI 网关。 检查要使用的 Foundry 资源是否具有关联的 AI 网关。

      

   5. 如果要使用的 Foundry 资源未配置 AI 网关（未列出），请使用 “添加 AI 网关 ”选项添加一个。

      AI 网关可以免费设置和解锁强大的治理功能，例如代理、工具和模型的安全、诊断数据和速率限制。 有关详细信息，请参阅 创建 AI 网关。

3. 确保已在项目中配置可观测性。 Foundry 控制平面利用与所选项目关联的 Application Insights 资源来发送数据，帮助诊断智能体。

   1. 在工具栏上，选择“ 操作”。

   2. 在左窗格中，选择“ 管理员”。

   3. 在 “所有项目”下，使用搜索框查找项目。

   4. 选择项目。

   5. 选择“ 已连接资源 ”选项卡。

   6. 确保 AppInsights 类别中有一个关联的资源。

      

   7. 如果没有关联的资源，请选择“ 添加连接>Application Insights”添加一个资源。

您的项目已配置为支持可观测性和追踪。

注册代理（资产）

1. 在工具栏上，选择“ 操作”。

2. 在“ 概述 ”窗格中，选择“ 注册资产”。

   

3. 此时会显示注册向导。 首先，完成要注册的代理的详细信息。 以下属性描述代理在其平台上运行时：

   财产	描述	必填
   代理 URL	代理运行并接收请求的终结点（URL）。 一般情况下，根据协议，您需指明客户端使用的基础 URL。 例如，如果智能体使用 OpenAI 聊天补全 API，则表示使用 https://<host>/v1/ 而不是使用 /chat/completions，因为客户端通常会添加它。	是的
   协议	代理支持的通信协议。 通常使用 HTTP。 或者，如果您的代理更具体地支持 A2A，则请注明这一点。	是的
   A2A 代理卡 URL	智能体卡的 JSON 规范的路径。 如果未指定，系统将使用默认值 /.well-known/agent-card.json。	是，协议为 A2A 时
   OpenTelemetry 代理 ID	智能体根据生成式 AI 的 OpenTelemetry 语义规范发出跟踪所使用的智能体 ID。 对于操作名为 create_agent 的跨度，跟踪在 gen_ai.agent.id 属性中指示它。 如果未指定此值，系统会使用 代理名称 值查找此新代理报告的跟踪和日志。	不
   管理门户 URL	管理门户的 URL，您可以在此为此代理执行进一步的管理操作。 Foundry 可以为方便起见存储此值。 Foundry 无权直接对此门户执行操作。	不

4. 配置希望代理在 Foundry 控制平面中显示的方式：

   财产	描述	必填
   Project	注册代理的项目。 Foundry 使用包含项目的资源中配置的 AI 网关来为代理配置入站终结点。 您只能选择那些在其资源中启用了 AI 网关的项目。 如果未看到任何 AI 网关， 请在 Foundry 资源中配置 AI 网关。 我们还建议在所选项目中配置 Application Insights。 Foundry 使用项目的 Application Insights 资源来收集跟踪和日志。	是的
   代理名称	你希望智能体在 Foundry 中显示的名称。 如果未为 OpenTelemetry 代理 ID 指定其他值，系统还可以使用此名称在 Application Insights 中查找相关的跟踪和日志。	是的
   描述	关于此代理的清晰描述。	不

5. 保存更改。

6. Foundry 添加了新代理。 要查看代理列表，请选择左侧窗格中的资产。

7. 若要仅显示自定义代理，请使用 源 筛选器并选择“ 自定义”。

   

将客户端连接到代理

在 Foundry 中注册代理时，会获得可供客户端使用的新 URL。 由于 Foundry 充当与代理通信的代理，因此它可以控制访问和监视活动。

若要分发新 URL，以便客户端可以调用代理：

1. 在代理列表中，选择自定义代理名称旁边的单选按钮以打开信息窗格。 请不要选择代理人名称，因为该链接会将您带离资产窗格。

2. 在信息窗格的 “代理 URL”下，选择“ 复制 ”选项。

   

3. 使用新 URL 调用代理，而不是原始终结点。

在此示例中，部署 LangGraph 代理。 客户使用 LangGraph SDK 来使用它。 客户端使用 新的代理 URL 值。 此代码创建一个线程，发送询问天气的消息，并将响应流式传输回来。

import asyncio
from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/")

async def stream_run():
    thread = await client.threads.create()
    input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}

    async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
        print(chunk)

asyncio.run(stream_run())

预期输出：代理处理消息，并以区块形式流式传输响应。 每个区块都包含代理执行过程中产生的部分结果。 这些结果可能包括对天气函数的工具调用以及有关洛杉矶天气的最终响应。

阻止和取消阻止代理

对于自定义代理，Foundry 无权访问运行代理的底层基础结构，因此启动和停止操作不可用。 但是，Foundry 可以阻止对代理的传入请求，从而使客户端无法使用它。 此功能允许管理员禁用代理（如果其行为不当）。

若要阻止向代理发出的传入请求，请执行以下操作：

1. 在工具栏上，选择“ 操作”。

2. 在左窗格中，选择“ 资产”。

3. 选择要阻止的智能体旁边的单选按钮。 此时会显示信息窗格。 不要选择代理名称，因为该链接会将您从资产窗格导航出去。

4. 选择 “更新状态”，然后选择“ 阻止”。

   

5. 确认操作。

阻止代理后，Foundry 中代理的状态值为阻止。 处于 阻止 状态的代理在其关联的基础结构中运行，但无法接收传入的请求。 Foundry 阻止任何尝试与代理进行交互。

取消阻止代理：

1. 选择 “更新状态”，然后选择“ 取消阻止”。

2. 确认操作。

为代理启用诊断数据

Foundry 使用 OpenTelemetry 开放标准来了解代理正在执行的操作。 如果项目配置了 Application Insights，则 Foundry 默认将请求记录到 Application Insights 中。 Foundry 还使用此数据来计算：

• 运行
• 错误率
• 使用情况（如果可用）

为了获得最佳保真度级别，Foundry 希望自定义代理符合 OpenTelemetry 标准中生成 AI 解决方案的语义约定。

查看发送到 Foundry 的跟踪和日志

1. 在工具栏上，选择“ 操作”。

2. 在左窗格中，选择“ 资产”。

3. 选择智能体旁边的单选按钮以打开信息窗格。 不要选择代理的名称，因为该链接会将您从 资产 窗格中跳转出去。

4. “跟踪”部分显示每个发往代理终结点的 HTTP 调用对应的一个条目。

   若要查看详细信息，请选择一个条目。

   

   提示

   在此示例中，可以看到客户端如何使用新代理的终结点与代理通信。 该示例展示了一个使用 LangChain 的 Agent Protocol 提供服务的代理。 客户端使用路由 /runs/stream。

在此示例中，跟踪不包括 HTTP 帖子之外的任何详细信息。 智能体的代码不包含任何进一步的检测。 在下一部分中，你将了解如何检测代码并获取工具调用和大型语言模型（LLM）调用等详细信息。

检测自定义代码代理

如果使用自定义代码构建代理程序，请为您的解决方案添加监控，使其根据 OpenTelemetry 标准生成跟踪信息并将其发送到 Application Insights。 检测使 Foundry 可以详细了解代理正在执行的操作。

使用项目的检测密钥将跟踪发送到项目的 Application Insights 资源。 若要获取与项目关联的检测密钥，请按照 Connect Application Insights to your Foundry project 中的说明进行操作。

在此示例中，您将配置使用 LangGraph 开发的代理，以按照 OpenTelemetry 标准格式输出跟踪数据。 跟踪器捕获所有代理操作，包括工具调用和模型交互。 然后，跟踪程序将操作发送到 Application Insights 进行监视。

此代码使用 langchain-azure-ai 包。 有关使用 OpenTelemetry 检测特定解决方案的指南，具体取决于解决方案使用的编程语言和框架，请参阅 语言 API 和 SDK。

pip install -U langchain-azure-ai[opentelemetry]

然后，配置您的代理：

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = "InstrumentationKey=12345678-..."

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

预期输出：代理正常运行，同时自动向 Application Insights 发出 OpenTelemetry 跟踪。 跟踪包括操作名称、持续时间、模型调用、工具调用和令牌用法。 可以在 Foundry 门户的 “跟踪 ”部分查看这些跟踪。

检测平台解决方案

如果代理在支持 OpenTelemetry 但不支持 Application Insights 的平台解决方案上运行，请部署 OpenTelemetry 收集器并将软件配置为将 OTLP 数据发送到收集器（标准 OpenTelemetry 配置）。

使用 Azure Monitor 导出程序配置收集器，通过使用您的连接字符串将数据转发到 Application Insights。 有关如何实现它的详细信息，请参阅 Configure Azure Monitor OpenTelemetry。

排查跟踪问题

如果未看到痕迹，请检查下列事项：

相关内容

• 什么是Microsoft Foundry控制平面？
• 监控整个设备群中的代理健康状态和性能
• 优化模型成本和性能