Приложения платформы агента самообслуживания

Самостоятельное размещение позволяет запускать агент или рабочий процесс Agent Framework в собственном ASP.NET Core приложении, контейнере, службе или среде выполнения. Приложение управляет маршрутизацией, удостоверением, авторизацией, политикой запросов, хранилищем, развертыванием и масштабированием. Добавьте интеграции протоколов на хост в зависимости от того, какие клиенты необходимо поддерживать.

Используйте этот параметр, если необходимо интегрировать конечную точку агента с существующей инфраструктурой приложений. Если вы хотите Microsoft Foundry запустить агент для вас, см. статью "Размещенные агенты Foundry". Если вам нужны Функции Azure триггеры или устойчивое выполнение, см. раздел "Устойчивое расширение".

Это важно

Пакеты среды размещения .NET имеют предварительную версию. Установите предварительные версии явным образом и просмотрите заметки о выпуске перед обновлением рабочего развертывания.

dotnet add package Microsoft.Agents.AI.Hosting --prerelease

Пакеты интеграции протоколов, такие как Microsoft.Agents.AI.Hosting.OpenAI и Microsoft.Agents.AI.Hosting.A2A.AspNetCore, уже содержат ссылку на Microsoft.Agents.AI.Hosting. Установите его напрямую, только если хост не использует пакет интеграции с протоколом.

Что предоставляют вспомогательные службы размещения

Пакет Microsoft.Agents.AI.Hosting интегрирует агенты и рабочие процессы с универсальным узлом .NET:

AddAIAgent регистрирует именованный AIAgent объект с внедрением зависимостей.
AddWorkflow регистрирует именованный рабочий процесс. Цепочка AddAsAIAgent для того, чтобы рабочий процесс был доступен для интеграции протокола через стандартный интерфейс агента.
IHostedAgentBuilder настраивает службы хостинга, связанные с этим агентом.
AgentSessionStore опционально загружает и сохраняет экземпляры AgentSession по идентификатору продолжения, заданному приложением или протоколом.

Пакет размещения не является HTTP-сервером или реестром протоколов. Приложение выбирает размещенные агенты и рабочие процессы, настраивает свои службы и добавляет необходимые конечные точки протокола.

Интеграция с ASP.NET Core

Пакет общего хостинга использует универсальный узел .NET и внедрение зависимостей. Для HTTP-сервера создайте приложение ASP.NET Core и добавьте пакеты для конкретных протоколов для конечных точек, которые вы хотите опубликовать. Эти пакеты получают именованные экземпляры AIAgent из контейнера внедрения зависимостей и добавляют сопоставления маршрутов для ASP.NET Core.

Например, пакет хостинга OpenAI может предоставлять доступ к настроенному агенту через конечную точку Responses:

dotnet add package Microsoft.Agents.AI.Hosting.OpenAI --prerelease

using Microsoft.Agents.AI.Hosting;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

WebApplication app = builder.Build();
app.MapOpenAIResponses(hostedAgent);
app.Run();

См. эндпоинты, совместимые с OpenAI, для получения полной информации по настройке.

Ваше приложение по-прежнему отвечает за конвейер промежуточного ПО, аутентификацию, авторизацию, проверку запросов, допустимые параметры модели и постоянное хранилище. Узел, не использующий HTTP, может использовать службы общего хостинга без добавления конечных точек протокола ASP.NET Core.

Добавление протоколов на сервер

Выберите интеграцию протокола, необходимую приложению:

Протокол	Integration
Конечные точки, совместимые с OpenAI	Завершения чата и HTTP-эндпоинты, совместимые с Responses
A2A	Межагентное обнаружение, обмен сообщениями и конечные точки для задач
AG-UI	Конечные точки потоковой передачи событий для приложений веб-агента

Сохранение хостируемых сеансов

AgentSessionStore Сохранение состояния является необязательной функцией для интеграций с хостингом, которые её используют. Без настроенного хранилища эти интеграции могут создать новый сеанс для каждого запроса, но не может восстановить состояние сеанса на сервере из более раннего запроса.

Это важно

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

Зарегистрируйте долговременную реализацию через внедрение зависимостей и передайте ее хостируемому агенту. Хранилище в памяти можно использовать условно во время разработки:

builder.Services.AddSingleton<AgentSessionStore, MyAgentSessionStore>();

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

if (builder.Environment.IsDevelopment())
{
    hostedAgent.WithInMemorySessionStore(withIsolation: false);
}
else
{
    hostedAgent.WithSessionStore((services, _) =>
        services.GetRequiredService<AgentSessionStore>());
}

В этом примере MyAgentSessionStore — это устойчивая реализация, предоставленная вашим приложением. Ветка разработки предполагает локальную среду с одним доверенным пользователем и является единственной веткой, в которой отключена изоляция. Рабочая ветвь сохраняет поведение изоляции по умолчанию; настройте поставщика ключей изоляции, как описано в разделе "Продолжение безопасного сеанса".

InMemoryAgentSessionStore теряет все сеансы при выходе процесса и не делится состоянием между экземплярами приложений. Реализуйте собственное AgentSessionStore с постоянным хранилищем, чтобы сохранять сеансы.

AgentSessionStore реализует асинхронные операции сохранения, получения и удаления. Он получает владеющий AIAgent и непрозрачный идентификатор продолжения, выбранный интеграцией размещения или маршрутом, принадлежащим приложению, и должен возвращать независимый экземпляр AgentSession при каждой операции get. Рассматривайте идентификатор продолжения как непрозрачный ключ в пользовательских хранилищах; способ интерпретации этого идентификатора зависит от конкретного протокола.

Устойчивая реализация имеет следующую структуру. Замените каждую заглушку операциями, соответствующими выбранной системе хранения:

public sealed class MyAgentSessionStore : AgentSessionStore
{
    public override ValueTask SaveSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        AgentSession session,
        CancellationToken cancellationToken = default)
    {
        // Persist the session using your storage system.
        throw new NotImplementedException();
    }

    public override ValueTask<AgentSession> GetSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Restore an independent session, or create one when no state exists.
        throw new NotImplementedException();
    }

    public override ValueTask DeleteSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Delete the stored session if it exists.
        throw new NotImplementedException();
    }
}

Ключевые записи по agent.Id и непрозрачному sessionStoreId. GetSessionAsync должен возвращать независимый экземпляр сессии при каждом вызове; при сохранении сериализованного состояния используйте API сериализации сессий агента-владельца. Сохраненные сеансы могут содержать конфиденциальные данные, поэтому защищайте их с помощью соответствующих механизмов управления доступом и шифрования.

AgentSessionStore сохраняет полный AgentSession, выбранный размещённым запросом, а не только сообщения беседы. В зависимости от стека агента сеанс может содержать идентификатор беседы, управляемый службой, историю чата, управляемую фреймворком, состояние памяти или поставщика контекста, сообщения в очереди, ожидающие утверждения, и другие данные состояния, которые должны сохраняться между запусками.

Поставщики истории определяют, где хранятся сообщения диалога. Если история хранится в состоянии сеанса, то при сохранении сеанса эта история также сохраняется. Внешний поставщик истории хранит сообщения отдельно; сеанс может сохранять ссылку или связанное с поставщиком состояние.

Продолжение безопасного сеанса

Идентификатор продолжения сеанса идентифицирует сеанс, который нужно возобновить; однако сам по себе он не доказывает, что инициатору принадлежит этот сеанс. Ограничивайте сохранённые сеансы рамками аутентифицированного пользователя, тенанта или иной границы авторизации, прежде чем принимать идентификаторы, предоставленные клиентом. IsolationKeyScopedAgentSessionStore получает ключ изоляции из AgentIsolationKeyProvider, объединяет его с идентификатором продолжения протокола и передает полученный идентификатор с областью действия в нижележащее хранилище. В результате один и тот же идентификатор продолжения при двух разных ключах изоляции соответствует двум разным сохранённым сеансам, и вызывающая сторона может извлекать только сеансы, сохранённые с тем же ключом изоляции.

Для приложений ASP.NET Core, использующих аутентификацию на основе утверждений, установите предварительную версию пакета Microsoft.Agents.AI.Hosting.AspNetCore, зарегистрируйте поставщик изоляции на основе утверждений и оставьте изоляцию включённой в хранилище сеансов:

dotnet add package Microsoft.Agents.AI.Hosting.AspNetCore --prerelease

builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();

По умолчанию UseClaimsBasedAgentIsolation использует утверждение ClaimTypes.NameIdentifier. Настройте другое утверждение, только если оно стабильно и уникально для каждого вызывающего абонента, обслуживаемого магазином. Поставщик изоляции не проходит проверку подлинности запросов; настройте ASP.NET Core аутентификацию и авторизацию отдельно. При строгой изоляции, используемой по умолчанию, не удаётся получить доступ к сеансу, если текущий принципал не содержит настроенного утверждения.

Для хоста, отличного от HTTP, или другой модели арендатора зарегистрируйте пользовательский AgentIsolationKeyProvider. Перегрузки WithInMemorySessionStore() и WithSessionStore(...) по умолчанию оборачивают настроенное хранилище в IsolationKeyScopedAgentSessionStore.

Дальнейшие действия

Добавление конечной точки, совместимой с OpenAI

Вернитесь глубже:

Замечание

Вспомогательные средства протокола для самостоятельного хостинга в настоящее время недоступны для Go.

Самостоятельное размещение позволяет запускать агент Agent Framework или рабочий процесс в собственном веб-приложении, контейнере, службе или среде выполнения. Приложение управляет маршрутизацией, удостоверением, авторизацией, политикой запросов, хранилищем, развертыванием и масштабированием. Добавьте на этот сервер одну или несколько интеграций протоколов в зависимости от того, каких клиентов необходимо поддерживать.

Разработка этих пакетов обеспечивает максимальную гибкость для разработчика. Это означает, что если вы хотите создать хост, который предоставляет агента через Responses API, и использовать параметры для других целей (то есть сопоставить temperature с top_p), вы можете это сделать. Если вы не хотите хранить сеансы, вы можете этого не делать; если вы хотите разрешить вызывающей стороне полностью управлять запуском агента, вы можете сделать и это. Мы не будем стоять у вас на пути: мы предоставляем вспомогательные инструменты для типичных сценариев, а за всё остальное оставляем отвечать вам, чтобы вы могли создать именно тот узел, который вам нужен.

Это важно

agent-framework-hosting, agent-framework-hosting-responses, , agent-framework-hosting-telegramagent-framework-a2aagent-framework-hosting-a2aи agent-framework-hosting-mcp являются предварительной версией пакетов Python. Установите предварительные версии явным образом и просмотрите заметки о выпуске перед обновлением рабочего развертывания.

pip install --pre agent-framework-hosting

Что предоставляют вспомогательные службы размещения

Обобщённый пакет размещения предоставляет общее состояние выполнения для сервера, принадлежащего приложению:

AgentState связывает целевой объект агента с объектом SessionStore и создает сеансы, когда приложение выбирает новый ключ.
SessionStore сохраняет, извлекает и удаляет сеансы по идентификатору, выбранному приложением. Его хранилище по умолчанию является локальным процессом и не имеет политики вытеснения.
WorkflowState определяет цель рабочего процесса. Приложение отвечает за хранилище контрольных точек и за любое сопоставление идентификатора продолжения клиента с контрольной точкой.

AgentState не является сервером или реестром протоколов. Приложение выбирает ключ авторизованного сеанса, определяет целевой объект и сохраняет состояние после завершения выполнения. Он может использовать одну и ту же целевую и общую инфраструктуру приложений для одной или нескольких конечных точек протокола.

Настройка хранилища сеансов

SessionStore— это небольшой асинхронный класс хранилища с getsetметодами , а также delete методами. Реализация по умолчанию сохраняет сеансы в памяти процесса. Создайте его подкласс и переопределите эти методы, чтобы хранить объекты AgentSession в Redis, базе данных, хранилище BLOB-объектов или другом хранилище, принадлежащем приложению, а затем передайте экземпляр в AgentState(session_store=...).

SessionStore и поставщики истории сохраняют отдельные части разговора агента. Хранилище сеансов сохраняет один объект сеанса для каждого идентификатора сеанса, включая метаданные сеанса и состояние провайдера. HistoryProvider Выделенное хранилище сохраняет беседу отдельно, как правило, как одну запись для каждого сообщения. Такое разделение рекомендуется для постоянных хостов, поскольку добавлять отдельные сообщения обычно эффективнее, чем перезаписывать растущий объект сеанса после каждого шага. Поставщик журнала определяется для каждого агента, передав требуемый класс поставщика журнала параметру context_providers .

Замечание

Поставщик истории по умолчанию: InMemoryHistoryProvider — это исключение: он хранит весь разговор в AgentSession.state. При использовании этого поставщика SessionStore сохраняет разговор в объекте сеанса. Для долгих диалогов или постоянного хранения в рабочей среде используйте отдельный поставщик истории, чтобы хранилище сеансов отвечало только за облегчённое состояние сеанса.

Используйте собственный фреймворк или клиентскую библиотеку

Пакеты размещения не привязаны к веб-платформе или клиентской библиотеке. В примерах используются FastAPI и aiogram, потому что они позволяют привести краткие рабочие примеры, а не потому, что вспомогательные функции требуют их.

Для конечных точек HTTP используйте API маршрутизации и запроса и ответа платформы приложений, такие как FastAPI, Starlette, Django, Flask, Функции Azure или другая платформа.
Для клиентов протокола, таких как Telegram, используйте любую клиентную библиотеку, которая может предоставить обновление протокола и выполнить операции, созданные вспомогательным поставщиком.

Приложение выбирает свою платформу и клиентную библиотеку; Пакеты Agent Framework преобразуют только данные протокола и управляют необязательным состоянием выполнения. Они не регистрируют маршруты, не аутентифицируют вызывающих, не авторизуют доступ к состоянию, не выбирают допустимые параметры модели и не предоставляют постоянное хранилище.

Добавление протоколов на сервер

Выберите одну или несколько интеграции протокола:

Протокол	Упаковка и интеграция
Ответы OpenAI	`agent-framework-hosting-responses`
Телеграмма	`agent-framework-hosting-telegram`
A2A	`agent-framework-a2a` или `agent-framework-hosting-a2a`
MCP	`agent-framework-hosting-mcp`

Каждая страница протокола описывает ее настройку. Однако они предназначены для создания одного узла с поддержкой одного или нескольких протоколов и вызываемого целевого объекта; агент или рабочий процесс. Поскольку мы не ограничиваем вас одним веб-фреймворком, вы можете выбрать тот, который вам нужен, и без труда настроить хост с этими протоколами.

Продолжение безопасного сеанса

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

Проверьте подлинность вызывающей стороны.
Авторизуйте вызывающий объект для доступа к указанному состоянию.
Разделяйте сохраняемое состояние по прошедшему аутентификацию арендатору, пользователю или рабочей области.
Сохраняйте состояние сеанса и контрольной точки только после завершения запуска или потока.

Этот шаблон самостоятельного размещения позволяет приложению реализовать только необходимые конечные точки протокола и политики; Он не пытается реализовать полную поверхность API каждого поддерживаемого протокола.

Дальнейшие действия

Добавление протокола Ответов OpenAI

Вернитесь глубже:

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-08-31

Приложения платформы агента самообслуживания

Что предоставляют вспомогательные службы размещения

Интеграция с ASP.NET Core

Добавление протоколов на сервер

Сохранение хостируемых сеансов

Продолжение безопасного сеанса

Дальнейшие действия

Что предоставляют вспомогательные службы размещения

Настройка хранилища сеансов

Используйте собственный фреймворк или клиентскую библиотеку

Добавление протоколов на сервер

Продолжение безопасного сеанса

Дальнейшие действия

Обратная связь

Дополнительные ресурсы