Регистрация пользовательских агентов и управление ими

Microsoft Foundry Control Plane обеспечивает централизованное управление и наблюдаемость для агентов, работающих на разных платформах и инфраструктурах. Вы можете зарегистрировать пользовательские агенты, которые выполняются в Azure вычислительных службах или других облачных средах, чтобы получить представление о своих операциях и управлять их поведением.

В этой статье показано, как зарегистрировать пользовательского агента в системе управления Foundry Control Plane. Вы узнаете, как настроить агент для регистрации, настроить сбор данных и использовать возможности управления в Foundry Control Plane.

Необходимые условия

• Учетная запись Azure с активной подпиской. Если у вас нет, создайте учетную запись free Azure, которая включает бесплатную пробную подписку.

• Проект Foundry. Если у вас его нет, создайте проект.

• Шлюз ИИ, настроенный в ресурсе Foundry. Foundry использует Azure API Management для регистрации агентов в качестве API.

• Агент, который развертывается и предоставляется через доступную конечную точку. Конечная точка может быть общедоступной конечной точкой или конечной точкой, доступной из сети, в которой развертывается ресурс Foundry.

Добавление пользовательского агента

Вы можете зарегистрировать пользовательский агент в плоскости управления Foundry. Разработайте агент в выбранной технологии как для платформ, так и для решений инфраструктуры.

При регистрации пользовательского агента Foundry использует управление API для взаимодействия с агентом, чтобы управлять доступом и отслеживать действия.

На следующей схеме показана результирующая архитектура при регистрации пользовательского агента.

Проверьте вашего агента

Убедитесь, что агент соответствует требованиям для регистрации:

Подготовьте ваш проект Foundry

Прежде чем зарегистрировать пользовательский агент, добавленный в проект Foundry, убедитесь, что проект настроен правильно:

1. Войдите в Microsoft Foundry. Убедитесь, что переключатель New Foundry включен. Эти действия относятся к Foundry (new).

   

2. Убедитесь, что шлюз искусственного интеллекта настроен в проекте:

   1. На панели инструментов выберите "Работа".

   2. На левой панели выберите "Администратор".

   3. Откройте вкладку шлюза ИИ .

   4. На панели перечислены все шлюзы ИИ, настроенные и сопоставленные с ресурсом Foundry. Убедитесь, что ресурс Foundry, который вы хотите использовать, имеет связанный шлюз ИИ.

      

   5. Если ресурс Foundry, который вы хотите использовать, не настроен шлюз ИИ (он не указан), добавьте его с помощью параметра Add AI Gateway .

      Шлюз искусственного интеллекта можно настроить бесплатно, и он позволяет использовать мощные функции управления, такие как безопасность, диагностические данные и ограничения скорости для ваших агентов, инструментов и моделей. Дополнительные сведения см. в статье "Создание шлюза ИИ".

3. Убедитесь, что в проекте настроена возможность наблюдения. Панель управления Foundry использует ресурс Application Insights, который связан с вашим выбранным проектом, для отправки данных, помогающих вам диагностировать вашего агента.

   1. На панели инструментов выберите "Работа".

   2. На левой панели выберите "Администратор".

   3. В разделе "Все проекты" используйте поле поиска для поиска проекта.

   4. Выберите проект.

   5. Перейдите на вкладку "Подключенные ресурсы ".

   6. Убедитесь, что в категории AppInsights есть связанный ресурс.

      

   7. Если нет связанного ресурса, добавьте его, нажав кнопку "Добавить подключение>Application Insights".

Проект настроен для наблюдаемости и трассировки.

Регистрация агента (актива)

1. На панели инструментов выберите "Работа".

2. На панели "Обзор" выберите "Регистрация ресурса".

   

3. Откроется мастер регистрации. Сначала заполните сведения об агенте, который требуется зарегистрировать. Следующие свойства описывают агент при запуске на своей платформе:

   Свойство	Описание	Обязательно
   URL-адрес агента	Конечная точка (URL-адрес), в которой агент выполняет и получает запросы. Как правило, в зависимости от протокола указывается базовый URL-адрес, используемый клиентами. Например, если агент использует API завершения чата OpenAI, вы указываете https://<host>/v1/ , не /chat/completions так как клиенты обычно добавляют его.	Да
   Протокол	Протокол связи, поддерживаемый агентом. Обычно используйте ПРОТОКОЛ HTTP. Или если агент более конкретно поддерживает A2A, укажите этот вариант.	Да
   URL-адрес карточки агента A2A	Путь к спецификации формата JSON для карточки агента. Если он не указан, система использует значение по умолчанию /.well-known/agent-card.json.	Нет
   Идентификатор агента OpenTelemetry	Идентификатор агента, который ваш агент использует для выдачи трассировок в соответствии с семантическими соглашениями OpenTelemetry для генеративного ИИ. Трассировки указывают на это в атрибуте gen_ai.agent.id для диапазонов с именем операции create_agent. Если это значение не указано, система использует значение имени агента для поиска трассировок и журналов, сообщающих об этом новом агенте.	Нет
   URL-адрес портала администрирования	URL-адрес портала администрирования, где можно выполнять дальнейшие операции администрирования для этого агента. Foundry может хранить это значение для удобства. Foundry не имеет доступа к выполнению операций непосредственно на этом портале.	Нет

4. Настройте способ отображения агента в плоскости управления Foundry:

   Свойство	Описание	Обязательно
   Project	Проект, в котором регистрируется агент. Для настройки входящей конечной точки у агента Foundry использует шлюз ИИ, настроенный в ресурсе, содержащем проект. Вы можете выбрать только проекты с включенным шлюзом искусственного интеллекта в своих ресурсах. Если шлюзы ИИ не отображаются, настройте шлюз ИИ в ресурсе Foundry. Мы также рекомендуем настроить Application Insights в выбранном проекте. Foundry использует ресурс Application Insights проекта для приёма трассировок и журналов.	Да
   Имя агента	Имя агента, как вы хотите, чтобы оно отображалось в Foundry. Система также может использовать это имя для поиска соответствующих трассировок и журналов в Application Insights, если не указать другое значение для идентификатора агента OpenTelemetry.	Да
   Описание	Четкое описание этого агента.	Нет

5. Сохраните изменения.

6. Foundry добавляет нового агента. Чтобы проверить список агентов, выберите Активы на левой панели.

7. Чтобы отобразить только пользовательские агенты, используйте фильтр источника и выберите "Настраиваемый".

   

Подключение клиентов к агенту

При регистрации агента в Foundry вы получите новый URL-адрес для клиентов. Так как Foundry выступает в качестве прокси-сервера для обмена данными с агентом, он может управлять доступом и отслеживать действия.

Чтобы новые клиенты могли обращаться к агенту, распространите новый URL-адрес:

1. Выберите пользовательский агент.

2. В области сведений в разделе URL-адрес агента выберите параметр "Копировать ".

   

3. Используйте новый URL-адрес для вызова агента вместо исходной конечной точки.

В этом примере вы развернете агент LangGraph. Клиенты используют пакет SDK LangGraph для его использования. Клиент использует новое значение 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 блокируется. Агенты в состоянии Blocked работают в своей связанной инфраструктуре, но не могут принимать входящие запросы. Foundry блокирует любую попытку интерфейса с агентом.

Чтобы разблокировать агента, выполните следующие шаги.

1. Выберите "Обновить состояние" и выберите " Разблокировать".

2. Подтвердите операцию.

Включите диагностические данные для агента

Foundry использует открытый стандарт OpenTelemetry, чтобы понять, что делают агенты. Если в проекте настроено Application Insights, Foundry регистрирует запросы в Application Insights по умолчанию. Foundry также использует эти данные для вычисления:

• Запуски
• Частота ошибок
• Использование (если доступно)

Чтобы получить лучший уровень точности, Foundry ожидает, что пользовательские агенты будут соответствовать семантическим соглашениям для генеративных ИИ-решений в стандарте OpenTelemetry.

Просмотр трассировок и журналов, отправленных в Foundry

1. На панели инструментов выберите "Работа".

2. На левой панели выберите Ресурсы.

3. Выберите агент.

4. В разделе Traces показана одна запись для каждого HTTP-вызова, направленного к конечной точке агента.

   Чтобы просмотреть сведения, выберите запись.

   

   Совет

   В этом примере вы узнаете, как клиенты используют конечную точку нового агента для взаимодействия с агентом. В примере показан агент, использующий Протокол агента из LangChain. Клиенты используют маршрут /runs/stream.

В этом примере трассировка не содержит никаких сведений за пределами записи HTTP. Код агента не включает дополнительный инструментарий. В следующем разделе вы узнаете, как инструментировать код и получать сведения, такие как вызовы инструментов и вызовы большой языковой модели (LLM).

Инструменты для создания агентов пользовательского кода

Если вы создаете агент с помощью пользовательского кода, настройте решение для генерации трассировок в соответствии со стандартом OpenTelemetry и отправьте их в Application Insights. Инструментирование предоставляет Foundry доступ к подробным сведениям о том, что делает ваш агент.

Отправьте данные трассировки в ресурс Application Insights вашего проекта, используя его ключ инструментирования. Чтобы получить ключ инструментирования, связанный с вашим проектом, следуйте инструкциям в разделе Как подключить Application Insights к проекту Foundry.

В этом примере вы настроите агент, разработанный с помощью 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] })

Ожидаемые выходные данные: агент работает нормально, автоматически передавая трассировки OpenTelemetry в Application Insights. Трассировки включают имена операций, длительность, вызовы модели, вызовы инструментов и использование маркеров. Эти трассировки можно просмотреть на портале Foundry в разделе Трассировки.

Решения для платформ инструментов

Если агент работает на платформе, поддерживающей OpenTelemetry, но не поддерживает Application Insights, разверните сборщик OpenTelemetry и настройте программное обеспечение для отправки данных OTLP сборщику (стандартная конфигурация OpenTelemetry).

Настройте сборщик данных с помощью экспортера Azure Monitor, чтобы осуществлять пересылку данных в Application Insights, используя ваш "строка подключения". Дополнительные сведения о реализации см. в разделе Configure Azure Monitor OpenTelemetry.

Устранение неполадок трассировок

Если трассировки не отображаются, проверьте следующие элементы:

Связанное содержимое

• Что такое Microsoft Foundry Control Plane?
• Мониторинг работоспособности и производительности агентов в вашей сети
• Оптимизация затрат и производительности модели