ai-agents-for-beginners

A Microsoft Agent Framework felfedezése

Agent Framework

Bevezetés

Ez a lecke a következőket tárgyalja:

Tanulási célok

A lecke elvégzése után tudni fogod, hogyan:

Kódminták

A Microsoft Agent Framework (MAF) kódmintái megtalálhatók ebben a tárolóban az xx-python-agent-framework és az xx-dotnet-agent-framework fájlok alatt.

A Microsoft Agent Framework megértése

Framework Intro

Microsoft Agent Framework (MAF) a Microsoft egységes keretrendszere AI ügynökök építéséhez. Rugalmasságot kínál a különféle ügynöki felhasználási esetek kezelésére, amelyek mind a termelési, mind a kutatási környezetekben előfordulnak, többek között:

Az AI ügynökök termelési bevezetéséhez a MAF a következő funkciókat is tartalmazza:

A Microsoft Agent Framework interoperabilitásra is törekszik az alábbi módokon:

Nézzük meg, hogyan alkalmazzák ezeket a funkciókat a Microsoft Agent Framework néhány alapvető koncepciójánál.

A Microsoft Agent Framework kulcsfogalmai

Ügynökök

Agent Framework

Ügynökök létrehozása

Az ügynök létrehozása úgy történik, hogy definiáljuk az inferencia szolgáltatást (LLM szolgáltató), egy sor utasítást, amelyet az AI ügynök követ, és egy hozzárendelt name-et:

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

A fenti példa Azure OpenAI használatával készült, de az ügynökök különféle szolgáltatásokkal is létrehozhatók, beleértve a Microsoft Foundry Agent Service-t:

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

OpenAI Responses, ChatCompletion API-k

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.", )

vagy távoli ügynökök az A2A protokollt használva:

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

Ügynökök futtatása

Az ügynökök a nem-sugárzó vagy sugárzó válaszokhoz a .run vagy .run_stream metódusokkal futtathatók.

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)

Minden ügynök futtatáshoz opciók is megadhatók a paraméterek testreszabásához, mint például az ügynök által használt max_tokens, azok a tools, amelyeket az ügynök hívhat, és maga a model, amely az ügynök számára használatos.

Ez hasznos olyan esetekben, amikor egy felhasználói feladat elvégzéséhez bizonyos modellekre vagy eszközökre van szükség.

Eszközök

Eszközök definiálhatók mind az ügynök definiálásakor:

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." 


# Amikor közvetlenül hozunk létre egy ChatAgentet

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

mind az ügynök futtatásakor is:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Ez az eszköz csak erre a futtatásra van biztosítva )

Ügynök szálak

Az ügynök szálakat többszörös fordulós beszélgetések kezelésére használják. A szálak létrehozhatók az alábbi módok valamelyikével:

A szál létrehozásához a kód így néz ki:

# Hozzon létre egy új szálat.
thread = agent.get_new_thread() # Futtassa az ügynököt a szállal.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

A szálat ezután sorosíthatod (serialize) későbbi felhasználás céljából:

# Hozzon létre egy új szálat.
thread = agent.get_new_thread() 

# Futtassa az ügynököt a szállal.

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

# Szerializálja a szálat tároláshoz.

serialized_thread = await thread.serialize() 

# Deszerializálja a szál állapotát a tárolóból való betöltés után.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Ügynök köztes szoftver (Middleware)

Az ügynökök eszközökkel és LLM-ekkel lépnek kölcsönhatásba a felhasználói feladatok elvégzése érdekében. Bizonyos forgatókönyvekben közbe szeretnénk lépni vagy nyomon követni ezeket a kölcsönhatásokat. Az ügynök middleware lehetővé teszi számunkra ezt a következők révén:

Funkció middleware

Ez a middleware lehetővé teszi egy művelet végrehajtását az ügynök és egy általa hívott függvény/eszköz között. Ennek tipikus példája, amikor a függvényhívást szeretnéd naplózni.

A lenti kódban a next határozza meg, hogy a következő middleware-t vagy a tényleges függvényt kell-e meghívni.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Előfeldolgozás: Naplózás a függvény végrehajtása előtt
    print(f"[Function] Calling {context.function.name}")

    # Tovább a következő middleware-hez vagy a függvény végrehajtásához
    await next(context)

    # Utófeldolgozás: Naplózás a függvény végrehajtása után
    print(f"[Function] {context.function.name} completed")

Chat middleware

Ez a middleware lehetővé teszi egy művelet végrehajtását vagy naplózását az ügynök és az LLM közötti kérések között.

Ez olyan fontos információkat tartalmaz, mint azok a messages, amelyeket az AI szolgáltatásnak küldenek.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Előfeldolgozás: Naplózás az MI hívása előtt
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Tovább a következő köztes réteghez vagy MI-szolgáltatáshoz
    await next(context)

    # Utófeldolgozás: Naplózás az MI válasza után
    print("[Chat] AI response received")

Ügynök memória

Ahogy az Agentic Memory leckében tárgyaltuk, a memória fontos eleme annak, hogy az ügynök különböző kontextusokban működhessen. A MAF többféle memóriatípust kínál:

Memória a memóriában (In-Memory Storage)

Ez az alkalmazás futása során a szálakban tárolt memória.

# Hozzon létre egy új szálat.
thread = agent.get_new_thread() # Futtassa az ügynököt a szálon.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Perzisztens üzenetek (Persistent Messages)

Ezt a memóriát a beszélgetési előzmények különböző munkamenetek közötti tárolására használják. A chat_message_store_factory segítségével definiálható:

from agent_framework import ChatMessageStore

# Hozzon létre egy egyéni üzenettárolót
def create_message_store():
    return ChatMessageStore()

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

Dinamikus memória

Ez a memória az ügynökök futtatása előtt kerül hozzáadásra a kontextushoz. Ezek a memóriák külső szolgáltatásokban is tárolhatók, például mem0-ban:

from agent_framework.mem0 import Mem0Provider

# Mem0 használata fejlett memóriafunkciókhoz
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
)

Ügynök megfigyelhetőség

A megfigyelhetőség fontos a megbízható és karbantartható ügynöki rendszerek építéséhez. A MAF integrálja az OpenTelemetry-t, hogy jobb nyomkövetést és mérőszámokat biztosítson.

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # csinálj valamit
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Munkafolyamatok

A MAF munkafolyamatokat kínál, amelyek előre definiált lépések egy feladat végrehajtásához, és ezekben a lépésekben AI ügynökök is szerepelhetnek.

A munkafolyamatok különböző összetevőkből állnak, amelyek jobb vezérlési folyamatot tesznek lehetővé. A munkafolyamatok emellett lehetővé teszik a többügynökös orchestrationt és a pontmentést (checkpointing) a munkafolyamat állapotainak mentéséhez.

Egy munkafolyamat magját az alábbi összetevők képezik:

Végrehajtók (Executors)

A végrehajtók bemeneti üzeneteket kapnak, elvégzik a nekik kiosztott feladatokat, majd kimeneti üzenetet állítanak elő. Ez előreviszi a munkafolyamatot a nagyobb feladat teljesítése felé. A végrehajtók lehetnek AI ügynökök vagy egyedi logikák.

Élek (Edges)

Az élek határozzák meg az üzenetek áramlását egy munkafolyamatban. Ezek lehetnek:

Direkt élek - Egyszerű egy-az-egy kapcsolatok a végrehajtók között:

from agent_framework import WorkflowBuilder

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

Feltételes élek - Akkor aktiválódnak, amikor egy meghatározott feltétel teljesül. Például, ha a szállodai szobák nem elérhetők, egy végrehajtó más lehetőségeket javasolhat.

Switch-case élek - Az üzeneteket különböző végrehajtókhoz irányítják meghatározott feltételek alapján. Például ha egy utazó ügyfélnek prioritási hozzáférése van, akkor a feladatait egy másik munkafolyamaton keresztül kezelik.

Fan-out élek - Egy üzenetet több célhoz küldenek.

Fan-in élek - Több üzenetet gyűjtenek össze különböző végrehajtóktól és egyetlen célhoz továbbítanak.

Események

A munkafolyamatok jobb megfigyelhetőségének biztosításához a MAF beépített eseményeket kínál a végrehajtás számára, többek között:

Fejlett MAF minták

A fenti részek lefedik a Microsoft Agent Framework kulcsfogalmait. Ahogy egyre összetettebb ügynököket építesz, érdemes megfontolni az alábbi fejlett mintákat:

Kódminták

A Microsoft Agent Framework kódmintái megtalálhatók ebben a tárolóban az xx-python-agent-framework és az xx-dotnet-agent-framework fájlok alatt.

Van további kérdésed a Microsoft Agent Framework-kel kapcsolatban?

Csatlakozz a Microsoft Foundry Discord-hoz, hogy találkozhass más tanulókkal, részt vehess office hour-okon és választ kapj az AI ügynökökkel kapcsolatos kérdéseidre.

Felelősségkizárás: Ezt a dokumentumot az AI fordítószolgáltatás, a Co-op Translator használatával fordították. Bár törekszünk a pontosságra, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum anyanyelvű változatát tekintse hivatalos forrásnak. Fontos információk esetén professzionális, emberi fordítást javaslunk. Nem vállalunk felelősséget az e fordítás használatából eredő félreértésekért vagy helytelen értelmezésekért.

This site is open source. Improve this page.