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 з великими контекстними вікнами (до 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 тут орієнтується на сумісну з 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.