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

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

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

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

• Учетная запись 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. На панели перечислены все шлюзы ИИ, настроенные и сопоставленные с ресурсом Foundry. Убедитесь, что ресурс Foundry, который вы хотите использовать, имеет связанный шлюз ИИ.

      

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

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

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

   1. На панели инструментов нажмите кнопку "Управление".

   2. На левой панели выберите Сведения о проекте.

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

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

      

   5. Если нет связанного ресурса, добавьте его, нажав кнопку "Добавить подключение>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.	Да, если протокол — A2A
   Идентификатор агента 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 блокируется. Агенты в заблокированном состоянии работают в связанной инфраструктуре, но не могут принимать входящие запросы. Foundry блокирует любую попытку интерфейса с агентом.

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

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

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

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

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

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

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

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

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

2. На левой панели выберите Активы.

3. Выберите радиокнопку рядом с агентом, чтобы открыть область сведений. Не выбирайте имя агента, так как эта ссылка выходит из панели Активы.

4. В разделе "Трассировка" показана одна запись для каждого вызова 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?
• Мониторинг состояния и производительности агентов во флоте