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, които агентът може да извиква, и дори самият модел, използван от агента.

Това е полезно в случаи, когато са необходими специфични модели или инструменти за изпълнение на задача на потребителя.

Инструменти

Инструментите могат да се дефинират както при създаване на агента:

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."""
    # Предварителна обработка: Запис преди извикване на AI
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Продължете към следващия middleware или 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, можете да го стартирате като hosted агент в 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-4.1"

Когато агентът по-късно работи като хостван агент в 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-4.1")
    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.