Microsoft Agent Framework: ИИ-агенты и workflows на Python и .NET

Microsoft Agent Framework, сокращённо MAF, предоставляет SDK для агентов и процессов из нескольких шагов. Основной репозиторий содержит Python и .NET. Агент получает модель, инструкции и инструменты; workflow задаёт порядок работы нескольких исполнителей.

Проект продолжает подходы AutoGen и Semantic Kernel. Он подходит для приложения, в котором нужно связать разговор с пользователем, функции бизнес-системы и управляемые этапы обработки. Готовый пользовательский интерфейс и правила доступа вы строите вокруг SDK.

Azure не обязателен для каждого сценария: поддерживаются разные провайдеры. В примерах ниже используется Microsoft Foundry, чтобы показать согласованную настройку клиента и модели. Go SDK находится в отдельном репозитории и не входит в описанный здесь Python/.NET-пакет.

Начните с одного агента и узкого набора функций. Workflow добавляйте, когда появился обязательный порядок действий, ожидание внешнего ответа или несколько независимых исполнителей. Это помогает оставить простой путь простым и не скрывать бизнес-правила в длинных инструкциях модели.

Client связывает агент с конкретным сервисом модели. Agent задаёт инструкции и доступные инструменты. AgentSession хранит состояние разговора между вызовами. Workflow соединяет агентов и обычные обработчики в общий процесс.

Для управления процессом есть графовый API с исполнителями и связями, а также функциональный Python API: функция с декоратором @workflow использует обычные if, циклы и asyncio.gather. Общие правила лучше выражать в коде, а свободную интерпретацию текста поручать модели внутри шага.

Python SDK требует Python 3.10 или новее. Метапакет agent-framework устанавливает основной набор компонентов и интеграций. Если нужна только работа с Foundry, можно установить agent-framework-foundry и azure-identity. Экспериментальные модули agent-framework-lab подключаются отдельно.

uv init maf-demo
cd maf-demo
uv add agent-framework-foundry azure-identity python-dotenv

В .NET базовый пакет называется Microsoft.Agents.AI; для Foundry нужны соответствующая интеграция и клиент Azure. Не переносите названия Python-классов буквально в C#: у SDK похожие задачи, но разные API и пакеты. Для приложения фиксируйте выбранные версии зависимостей.

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

Создайте проект Microsoft Foundry, разверните доступную модель и получите endpoint проекта. Установите Azure CLI и выполните az login под учётной записью с правами на проект. В FOUNDRY_MODEL указывайте имя развёртывания, а не произвольное название модели.

FOUNDRY_PROJECT_ENDPOINT=https://<ресурс>.services.ai.azure.com/api/projects/<проект>
FOUNDRY_MODEL=<имя-развёртывания>

import asyncio
import os
from dotenv import load_dotenv
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

load_dotenv()

async def main():
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        name="SupportHelper",
        instructions="Отвечай по-русски. Не придумывай условия обслуживания.",
    )
    result = await agent.run("Какие сведения уточнить, если приложение не запускается?")
    print(result)

asyncio.run(main())

az login
uv run python main.py

Agent Framework не загружает .env автоматически: это делает load_dotenv() в примере. Ошибка авторизации обычно требует проверить права на проект, активную учётную запись и endpoint. В рабочем сервисе выбирайте подходящую серверную идентификацию вместо входа разработчика через Azure CLI.

Для чтения данных подключите типизированную функцию. Декоратор @tool задаёт описание, а SDK строит схему аргументов. Модель выбирает, когда вызвать инструмент; сама функция выполняет действие и возвращает результат.

from agent_framework import tool

@tool(name="read_ticket", description="Читает статус тестовой заявки по номеру.")
def read_ticket(ticket_id: str) -> str:
    tickets = {"DEMO-1": "Ожидает уточнения", "DEMO-2": "Передана специалисту"}
    return tickets.get(ticket_id, "Заявка не найдена")

# В Agent из быстрого старта добавьте tools=[read_ticket].

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

AgentSession связывает последовательные обращения к агенту. Создайте сессию и передавайте её в run(). Это позволяет задать исходные сведения в первом сообщении, а затем попросить уточнение без повторной передачи всей истории вручную.

session = agent.create_session()
await agent.run("Приложение не открывается после обновления.", session=session)
follow_up = await agent.run("Составь один вопрос для уточнения проблемы.", session=session)
print(follow_up)

Способ хранения истории зависит от провайдера и выбранного API: она может находиться в вашем процессе или на стороне сервиса. При работе нескольких пользователей храните соответствие сессии владельцу в приложении. Внешний service_session_id сам по себе не служит границей авторизации.

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

from agent_framework.orchestrations import SequentialBuilder

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["FOUNDRY_MODEL"],
    credential=AzureCliCredential(),
)
writer = client.as_agent(
    name="writer", instructions="Напиши короткий черновик ответа по-русски.",
)
reviewer = client.as_agent(
    name="reviewer", instructions="Исправь неподтверждённые обещания и верни готовый ответ.",
)
workflow = SequentialBuilder(participants=[writer, reviewer]).build()
events = await workflow.run("Клиент сообщает, что приложение не запускается.")
for output in events.get_outputs():
    for message in output.messages:
        print(message.text)

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

Human-in-the-loop позволяет остановить workflow, отправить запрос наружу и продолжить после ответа. Согласование вызова инструмента и свободный вопрос оператору требуют разных сценариев. Для произвольного запроса используют механизмы request/response; интерфейс приложения должен показать вопрос и передать ответ.

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

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

В экосистеме есть интеграции с Microsoft Foundry, Azure OpenAI, OpenAI, Anthropic и локальными моделями через Ollama, а также другие провайдеры. Проверяйте поддержку для нужного языка SDK и конкретного клиента: общая таблица возможностей не означает, что любой сервис работает одинаково.

Hosted tools выполняются у провайдера: это может быть поиск по файлам или интерпретатор кода. Function tools исполняются вашим приложением. У разных клиентов набор hosted tools различается; переход с одного API на другой может потребовать заменить способ поиска или обработки файлов.

Локальный SDK не делает облачную модель локальной. Если документы нельзя отправлять внешнему сервису, отдельно настройте модель, поиск, журналирование и хранилище. Доступность tool calling у локальной модели также нужно учитывать.

MCP подключает инструменты сервера к агенту. SDK поддерживает локальные и сетевые соединения; различайте инструменты, вызываемые вашим процессом, и hosted MCP, вызываемый провайдером. Параметры соединения и время жизни клиента нужно настроить в приложении.

A2A, Agent-to-Agent, помогает выставить агент как сервис для других агентов. Это отдельный способ взаимодействия: MCP обычно предоставляет действия и данные, A2A представляет удалённого исполнителя задачи. Размещение сервиса требует собственного контроля доступа и конфигурации.

Для сложного PDF полезно подготовить текст и таблицы до передачи агенту. Docling в связанных материалах решает этот этап. Дальше функцию поиска или получения фрагментов можно подключить как инструмент, а workflow использовать для извлечения и проверки нужных полей.

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

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

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

Agent Framework рекомендован Microsoft как продолжение AutoGen и Semantic Kernel. Для AutoGen опубликовано сопоставление клиентов, агентов, инструментов и процессов. Переход меняет API: AssistantAgent и model_client заменяются соответствующими объектами Agent Framework, а командные сценарии требуют переноса в workflows.

Начните с одного агента, затем перенесите функцию-инструмент и управление сессией. После этого сравните поведение команды: какой контекст видит следующий исполнитель, где запрашивается человек и как сохраняется прогресс. Механическая замена импортов не проверяет эти различия.

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

Python-код можно запускать в собственном процессе, а агентный сервис разместить на своей инфраструктуре. Для Foundry настраиваются endpoint, развёртывание модели и серверная идентификация. Возможности конкретного размещения зависят от выбранных интеграций; установкой SDK инфраструктура не создаётся.

Код распространяется по MIT. Разрешены изменения и коммерческое использование с сохранением уведомления об авторских правах и лицензии; гарантий качества нет. У Azure, провайдеров моделей и подключённых инструментов собственные условия и расходы.

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

Если команда работает на .NET и использует Foundry, у Agent Framework есть понятный путь подключения. Для Python-проекта попробуйте один процесс во всех трёх вариантах: данные заявки, подготовка ответа, остановка для человека. Выбор станет яснее по коду и восстановлению работы. Подробные альтернативы открываются из таблицы ниже.

• Microsoft Agent Framework на GitHub
• Microsoft Agent Framework: сайт и документация