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, ChatCompletion API-та

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)

Агентски middleware

Агентите взаимодействат с инструменти и LLM за изпълнение на потребителските задачи. В определени сценарии искаме да изпълним или проследим действия между тези взаимодействия. Агентският middleware ни позволява да правим това чрез:

Функционален middleware

Този middleware ни позволява да изпълним действие между агента и функция/инструмент, който той ще извика. Пример за използване е когато искаме да правим логване при извикване на функция.

В кода по-долу next определя дали ще бъде извикан следващият middleware или реалната функция.

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}")

    # Продължете към следващия middleware или изпълнение на функцията
    await next(context)

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

Chat middleware

Този middleware ни позволява да изпълним или логнем действие между агента и заявките между LLM.

Тук се съдържа важна информация като messages, които се изпращат към AI услугата.

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

    # Продължава към следващия посредник или AI услуга
    await next(context)

    # Последваща обработка: Запис след отговор на AI
    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 е framework-interoperable - не сте ограничени до агенти, написани с 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)

Отказ от отговорност: Този документ е преведен с помощта на AI преводачески услуга Co-op Translator. Въпреки че се стремим към точност, моля имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод.

This site is open source. Improve this page.