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-агентом та призначеного name:

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 API Responses, 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 з великими контекстними вікнами (до 204K токенів):

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 — направляють повідомлення до різних виконавців на основі визначених умов. Наприклад, якщо у клієнта пріоритетний доступ, його завдання будуть оброблятись іншим робочим процесом.

Розподільчі ребра — надсилають одне повідомлення кільком адресатам.

Об’єднувальні ребра — збирають кілька повідомлень від різних виконавців і надсилають одному адресату.

Події

Для кращої спостережуваності робочих процесів 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-стиль або не розмовна обробка.

Оскільки Responses API є основним 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 тут націлено на сумісний з OpenAI (Responses) кінцевий пункт проекту Foundry.
    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.