ai-agents-for-beginners

Изучение Microsoft Agent Framework

Agent Framework

Введение

В этом уроке будут рассмотрены:

Цели обучения

После завершения этого урока вы сможете:

Примеры кода

Примеры кода для Microsoft Agent Framework (MAF) находятся в этом репозитории в файлах xx-python-agent-framework и xx-dotnet-agent-framework.

Понимание Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) — это единая платформа Microsoft для создания AI-агентов. Она обеспечивает гибкость для решения широкого спектра агентных сценариев, встречающихся как в продуктивной среде, так и в исследовательских проектах, включая:

Для запуска AI-агентов в продакшене MAF также включает функции для:

Microsoft Agent Framework также ориентирован на обеспечение совместимости благодаря:

Рассмотрим, как эти функции применяются к основным концепциям Microsoft Agent Framework.

Ключевые концепции Microsoft Agent Framework

Агенты

Agent Framework

Создание агентов

Создание агента осуществляется путем определения сервиса вывода (поставщика LLM),
набора инструкций для AI-агента и присвоения ему имени:

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent( instructions="You are good at recommending trips to customers based on their preferences.", name="TripRecommender" )

Приведенный выше пример использует Azure OpenAI, но агенты могут создаваться с использованием различных сервисов, включая Microsoft Foundry Agent Service:

AzureAIAgentClient(async_credential=credential).create_agent( name="HelperAgent", instructions="You are a helpful assistant." ) as agent

OpenAI Responses, API ChatCompletion

agent = OpenAIResponsesClient().create_agent( name="WeatherBot", instructions="You are a helpful weather assistant.", )

agent = OpenAIChatClient().create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

или MiniMax, предоставляющий OpenAI-совместимый API с большим контекстным окном (до 204К токенов):

agent = OpenAIChatClient(base_url="https://api.minimax.io/v1", api_key=os.environ["MINIMAX_API_KEY"], model_id="MiniMax-M3").create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

или удаленных агентов с использованием протокола A2A:

agent = A2AAgent( name=agent_card.name, description=agent_card.description, agent_card=agent_card, url="https://your-a2a-agent-host" )

Запуск агентов

Агенты запускаются с помощью методов .run или .run_stream для не потоковых или потоковых ответов соответственно.

result = await agent.run("What are good places to visit in Amsterdam?")
print(result.text)

async for update in agent.run_stream("What are the good places to visit in Amsterdam?"):
    if update.text:
        print(update.text, end="", flush=True)

При запуске агента также можно задать параметры, например, max_tokens, используемые агентом, tools (инструменты), которые агент может вызывать, и даже сам model, применяемую для агента.

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

Инструменты

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

def get_attractions( location: Annotated[str, Field(description="The location to get the top tourist attractions for")], ) -> str: """Get the top tourist attractions for a given location.""" return f"The top attractions for {location} are." 


# При прямом создании ChatAgent

agent = ChatAgent( chat_client=OpenAIChatClient(), instructions="You are a helpful assistant", tools=[get_attractions]

так и при запуске агента:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Инструмент предоставлен только для этого запуска )

Потоки агента

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

Для создания потока код выглядит так:

# Создать новый поток.
thread = agent.get_new_thread() # Запустить агент с этим потоком.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

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

# Создать новый поток.
thread = agent.get_new_thread() 

# Запустить агента с потоком.

response = await agent.run("Hello, how are you?", thread=thread) 

# Сериализовать поток для хранения.

serialized_thread = await thread.serialize() 

# Десериализовать состояние потока после загрузки из хранилища.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Промежуточное ПО агента

Агенты взаимодействуют с инструментами и LLM для выполнения задач пользователя. В некоторых сценариях требуется выполнение действий или отслеживание между этими взаимодействиями. Промежуточное ПО агента позволяет это делать:

Функциональное промежуточное ПО

Это промежуточное ПО позволяет выполнять действие между агентом и вызываемой им функцией/инструментом. Пример использования — логирование вызова функции.

В приведенном коде next определяет, вызывать ли следующее промежуточное ПО или саму функцию.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Предварительная обработка: Лог перед выполнением функции
    print(f"[Function] Calling {context.function.name}")

    # Продолжить к следующему промежуточному ПО или выполнению функции
    await next(context)

    # Постобработка: Лог после выполнения функции
    print(f"[Function] {context.function.name} completed")

Промежуточное ПО чата

Это промежуточное ПО позволяет выполнять действия или вести логирование между агентом и запросами к LLM.

Содержит важную информацию, такую как messages, отправляемые AI-сервису.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Предобработка: журнал до вызова ИИ
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Продолжить к следующему промежуточному ПО или сервису ИИ
    await next(context)

    # Постобработка: журнал после ответа ИИ
    print("[Chat] AI response received")

Память агента

Как рассмотрено в уроке Agentic Memory, память — важный элемент, позволяющий агенту работать в различных контекстах. MAF предлагает несколько видов памяти:

Временное хранение в памяти

Это память, хранящаяся в потоках во время выполнения приложения.

# Создайте новый поток.
thread = agent.get_new_thread() # Запустите агент с потоком.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Постоянные сообщения

Эта память используется для хранения истории разговоров в разных сессиях. Определяется с помощью chat_message_store_factory:

from agent_framework import ChatMessageStore

# Создать пользовательское хранилище сообщений
def create_message_store():
    return ChatMessageStore()

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a Travel assistant.",
    chat_message_store_factory=create_message_store
)

Динамическая память

Эта память добавляется в контекст перед запуском агентов. Она может храниться во внешних сервисах, таких как mem0:

from agent_framework.mem0 import Mem0Provider

# Использование Mem0 для расширенных возможностей памяти
memory_provider = Mem0Provider(
    api_key="your-mem0-api-key",
    user_id="user_123",
    application_id="my_app"
)

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant with memory.",
    context_providers=memory_provider
)

Наблюдаемость агента

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

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # сделать что-то
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Рабочие процессы

MAF предлагает рабочие процессы — предопределенные шаги для выполнения задачи с включением AI-агентов в качестве компонентов на этих шагах.

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

Основные компоненты рабочего процесса:

Исполнители

Исполнители получают входящие сообщения, выполняют назначенные задачи и генерируют выходное сообщение. Благодаря этому рабочий процесс продвигается к завершению большой задачи. Исполнители могут быть AI-агентами или настраиваемой логикой.

Рёбра

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

Прямые рёбра — простые однонаправленные связи между исполнителями:

from agent_framework import WorkflowBuilder

builder = WorkflowBuilder()
builder.add_edge(source_executor, target_executor)
builder.set_start_executor(source_executor)
workflow = builder.build()

Условные рёбра — активируются при выполнении определенного условия. Например, когда гостиничные номера недоступны, исполнитель может предложить другие варианты.

Рёбра switch-case — направляют сообщения к разным исполнителям в зависимости от заданных условий. Например, если у туриста есть приоритетный доступ, их задачи обрабатываются другим рабочим процессом.

Рёбра fan-out — отправляют одно сообщение нескольким получателям.

Рёбра fan-in — собирают несколько сообщений от разных исполнителей и направляют их одному получателю.

События

Для улучшения наблюдаемости рабочих процессов MAF предоставляет встроенные события выполнения, включая:

Продвинутые шаблоны MAF

В приведенных разделах описаны ключевые концепции Microsoft Agent Framework. При построении более сложных агентов рассмотрите следующие продвинутые шаблоны:

Размещение агентов LangChain / LangGraph на Microsoft Foundry

Microsoft Agent Framework является фреймворк-интероперабельным — вы не ограничены агентами, написанными только с помощью MAF. Если у вас уже есть агент, созданный с использованием LangChain или LangGraph, вы можете запускать его как размещенный в Microsoft Foundry агент, чтобы Foundry управлял средой выполнения, сессиями, масштабированием, идентификацией и конечными точками протокола, а логика агента оставалась в LangGraph.

Это реализуется с помощью пакета langchain_azure_ai.agents.hosting, который предоставляет скомпилированный граф LangGraph через те же протоколы, что и агенты, размещенные в Foundry.

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

pip install -U "langchain-azure-ai[hosting]>=1.2.4" azure-identity

Вспомогательная установка (hosting) включает библиотеки протокола Foundry: azure-ai-agentserver-responses (совместимый с OpenAI эндпоинт /responses) и azure-ai-agentserver-invocations (универсальный эндпоинт /invocations).

2. Выберите протокол размещения:

Протокол Класс хоста Конечная точка Использование
Responses ResponsesHostServer /responses Используйте для совместимого с OpenAI чата, потоковой передачи, истории ответов и ведения диалогов — рекомендованный вариант для разговорных агентов.
Invocations InvocationsHostServer /invocations Используйте для пользовательского JSON-формата, webhook-подобного эндпоинта или неперсонального процесса.

Поскольку API Responses является основным API для разработки агентов в Foundry, начните с ResponsesHostServer для большинства агентов.

3. Настройте переменные окружения (сначала выполните az login, чтобы DefaultAzureCredential мог аутентифицироваться):

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_NAME="gpt-5-mini"

При запуске агента как размещенного агента в Foundry платформа автоматически добавит FOUNDRY_PROJECT_ENDPOINT.

4. Опубликуйте агента LangGraph через протокол Responses:

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_azure_ai.agents.hosting import ResponsesHostServer

_AZURE_AI_SCOPE = "https://ai.azure.com/.default"


def build_chat_model() -> ChatOpenAI:
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
    deployment = os.environ.get("FOUNDRY_MODEL_NAME", "gpt-5-mini")
    credential = DefaultAzureCredential()
    project = AIProjectClient(endpoint=project_endpoint, credential=credential)
    openai_client = project.get_openai_client()
    token_provider = get_bearer_token_provider(credential, _AZURE_AI_SCOPE)

    # ChatOpenAI здесь нацелен на конечную точку Foundry проекта, совместимую с OpenAI (Responses).
    return ChatOpenAI(
        model=deployment,
        base_url=str(openai_client.base_url),
        api_key=token_provider,
    )


def main() -> None:
    graph = create_agent(build_chat_model(), tools=[])
    port = int(os.environ.get("PORT", "8088"))
    ResponsesHostServer(graph).run(port=port)


if __name__ == "__main__":
    main()

Запустите локально с помощью python main.py, затем отправьте запрос на Responses к http://localhost:8088/responses.

Ключевые особенности:

Рабочая версия этого примера доступна в code-samples/14-langchain-hosted-agent.py. Для полного руководства (протокол Invocations, пользовательские схемы запросов и устранение неполадок) смотрите Host LangGraph agents as Foundry hosted agents.

Примеры кода

Примеры кода для Microsoft Agent Framework находятся в этом репозитории в файлах xx-python-agent-framework и xx-dotnet-agent-framework.

Есть вопросы по Microsoft Agent Framework?

Присоединяйтесь к Microsoft Foundry Discord, чтобы встретиться с другими учащимися, посетить часы работы офиса и получить ответы на вопросы об AI-агентах.

Предыдущий урок

Память для AI-агентов

Следующий урок

Создание агентов для работы с компьютером (CUA)

Отказ от ответственности: Этот документ был переведен с использованием сервиса машинного перевода Co-op Translator. Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода.

This site is open source. Improve this page.