ai-agents-for-beginners

Microsoft Agent Frameworkin tutkiminen

Agent Framework

Johdanto

Tässä oppitunnissa käsitellään:

Oppimistavoitteet

Oppitunnin suorittamisen jälkeen osaat:

Koodiesimerkit

Microsoft Agent Frameworkin (MAF) koodiesimerkit löytyvät tästä arkistosta tiedostoista xx-python-agent-framework ja xx-dotnet-agent-framework.

Microsoft Agent Frameworkin ymmärtäminen

Framework Intro

Microsoft Agent Framework (MAF) on Microsoftin yhtenäinen kehys tekoälyagenttien rakentamiseen. Se tarjoaa joustavuutta käsitellä monenlaisia agenttikäyttötapauksia sekä tuotanto- että tutkimusympäristöissä, mukaan lukien:

Tuotantovalmiiden tekoälyagenttien toimittamiseksi MAF sisältää myös ominaisuuksia kuten:

Microsoft Agent Framework keskittyy myös yhteentoimivuuteen:

Katsotaan, miten näitä ominaisuuksia sovelletaan Microsoft Agent Frameworkin keskeisiin käsitteisiin.

Microsoft Agent Frameworkin keskeiset käsitteet

Agentit

Agent Framework

Agenttien luominen

Agentin luominen tapahtuu määrittelemällä päättelypalvelu (LLM-tarjoaja), joukko ohjeita, joita tekoälyagentin tulee noudattaa, ja nimi (name):

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

Yllä käytetään Azure OpenAI:ta, mutta agentteja voidaan luoda monilla eri palveluilla, kuten Microsoft Foundry Agent Service:

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

OpenAI:n Responses, ChatCompletion API:t

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

tai etäagentteja käyttäen A2A-protokollaa:

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

Agenttien ajaminen

Agenteja käytetään kutsumalla .run- tai .run_stream-metodeja, riippuen siitä, halutaanko ei-suoratoistavaa vai suoratoistavaa vastausta.

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)

Jokaisella agenttikutsulla voi myös olla parametreja, kuten agentin käyttämä max_tokens, agentin käyttämät tools eli työkalut, tai jopa agentissa käytettävä model.

Tämä on hyödyllistä, kun tehtävään vaaditaan tiettyjä malleja tai työkaluja.

Työkalut

Työkaluja voidaan määritellä sekä agenttia luotaessa:

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


# Kun luodaan ChatAgent suoraan

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

että agenttia ajettaessa:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Työkalu, joka on tarjottu vain tätä ajoa varten )

Agenttiketjut

Agenttiketjuja käytetään monikierroksisten keskustelujen käsittelyyn. Ketju voidaan luoda:

Ketjun luonti näyttää tältä:

# Luo uusi säie.
thread = agent.get_new_thread() # Käynnistä agentti säikeen kanssa.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Ketjun voi sen jälkeen sarjoittaa tallennettavaksi myöhempää käyttöä varten:

# Luo uusi säie.
thread = agent.get_new_thread() 

# Suorita agentti säikeellä.

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

# Sarjoita säie tallennusta varten.

serialized_thread = await thread.serialize() 

# Desarjoita säikeen tila latauksen jälkeen.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Agentin middleware

Agentit tekevät vuorovaikutusta työkalujen ja LLM:ien kanssa käyttäjien tehtävien suorittamiseksi. Joissain tilanteissa haluamme suorittaa tai seurata näiden välistä toimintaa. Agentin middleware mahdollistaa tämän seuraavasti:

Funktio-middleware

Tämä middleware suorittaa toiminnon agentin ja kutsuttavan funktion/työkalun välillä. Esimerkkinä voisi olla lokitus funktion kutsusta.

Alla olevassa koodissa next määrittää, kutsutaanko seuraavaa middlewarea vai varsinaista funktiota.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Esikäsittely: Kirjaa lokiin ennen funktion suoritusta
    print(f"[Function] Calling {context.function.name}")

    # Jatka seuraavaan middlewareen tai funktion suoritukseen
    await next(context)

    # Jälkikäsittely: Kirjaa lokiin funktion suorituksen jälkeen
    print(f"[Function] {context.function.name} completed")

Chatti-middleware

Tämän middleware mahdollistaa toiminnon suorittamisen tai lokituksen agentin ja LLM:lle lähetettyjen pyyntöjen välillä.

Sisältää tärkeää tietoa, kuten AI-palvelulle lähetettävät messages.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Esikäsittely: Kirjaa lokiin ennen AI-kutsua
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Jatka seuraavaan middlewareen tai AI-palveluun
    await next(context)

    # Jälkikäsittely: Kirjaa lokiin AI-vastauksen jälkeen
    print("[Chat] AI response received")

Agentin muisti

Kuten Agentic Memory -oppitunnissa käsiteltiin, muisti on tärkeä osa agentin kykyä toimia eri konteksteissa. MAF tarjoaa useita muistityyppejä:

Muisti sovelluksen ajon aikana

Muisti, joka tallennetaan ketjuihin sovelluksen käynnin aikana.

# Luo uusi säie.
thread = agent.get_new_thread() # Suorita agentti säikeellä.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Pysyvät viestit

Tätä muistia käytetään, kun halutaan tallentaa keskusteluhistoria eri istuntojen välillä. Määritellään käyttäen chat_message_store_factory:

from agent_framework import ChatMessageStore

# Luo mukautettu viestivarasto
def create_message_store():
    return ChatMessageStore()

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

Dynaaminen muisti

Tämä muisti lisätään kontekstiin ennen agenttien ajoa. Näitä muisteja voidaan tallentaa ulkoisiin palveluihin, kuten mem0:

from agent_framework.mem0 import Mem0Provider

# Käytetään Mem0:n kehittyneitä muistitoimintoja
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
)

Agentin havainnointi

Havainnointi on tärkeää luotettavien ja ylläpidettävien agenttijärjestelmien rakentamisessa. MAF integroituu OpenTelemetryyn tarjoamaan jäljitystä ja mittareita parempaa havainnointia varten.

from agent_framework.observability import get_tracer, get_meter

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

Työnkulut

MAF tarjoaa työnkulkuja, jotka ovat ennalta määriteltyjä vaiheita tehtävän suorittamiseksi ja sisältävät tekoälyagentteja osina näitä vaiheita.

Työnkulut koostuvat erilaisista komponenteista, jotka mahdollistavat paremman ohjauksen. Työnkulut mahdollistavat myös moniagenttiorkestroinnin ja tarkistuspisteet, joilla tallennetaan työnkulun tilat.

Työnkulun ydinkomponentit ovat:

Suorittajat

Suorittajat vastaanottavat syöteviestejä, suorittavat niille määritellyt tehtävät ja tuottavat tulosviestin. Tämä vie työnkulkua eteenpäin kohti suuremman tehtävän valmistumista. Suorittaja voi olla tekoälyagentti tai mukautettu logiikka.

Kaarteet

Kaarteilla määritellään viestien kulku työnkulussa. Ne voivat olla:

Suorat kaarteet – Yksinkertaiset yhdistykset suorittajien välillä yksi-yhteen:

from agent_framework import WorkflowBuilder

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

Ehdolliset kaarteet – Aktivoituvat tietyn ehdon täyttyessä. Esimerkiksi, hotellihuoneiden ollessa loppu, suorittaja voi ehdottaa muita vaihtoehtoja.

Valintaehdot (switch-case) -kaarteet – Reitittävät viestit eri suorittajille määriteltyjen ehtojen perusteella. Esim. jos matkustajalla on prioriteettioikeus, hänen tehtävänsä käsitellään toisessa työnkulussa.

Monikohdekarkaisu (fan-out) -kaarteet – Lähettävät yhden viestin monille kohteille.

Monilähtökarkaisu (fan-in) -kaarteet – Keräävät useita viestejä eri suorittajilta ja lähettävät yhden viestin yhdelle kohteelle.

Tapahtumat

Työnkulkujen havainnollisuuden parantamiseksi MAF tarjoaa sisäänrakennettuja tapahtumia suoritusprosessiin, kuten:

Edistyneet MAF-mallit

Yllä olevat osiot käsittelevät Microsoft Agent Frameworkin keskeisiä käsitteitä. Kun rakennat monimutkaisempia agenteja, tässä muutamia edistyneitä malleja harkittavaksi:

Koodiesimerkit

Microsoft Agent Frameworkin koodiesimerkit löytyvät tästä arkistosta tiedostoista xx-python-agent-framework ja xx-dotnet-agent-framework.

Lisäkysymyksiä Microsoft Agent Frameworkista?

Liity Microsoft Foundry Discordiin tapaamaan muita oppijoita, osallistumaan toimistoaikoihin ja saamaan vastauksia tekoälyagentteihin liittyviin kysymyksiisi.

Vastuuvapauslauseke: Tämä asiakirja on käännetty käyttäen tekoälypohjaista käännöspalvelua Co-op Translator. Pyrimme tarkkuuteen, mutta huomioithan, että automaattiset käännökset saattavat sisältää virheitä tai epätarkkuuksia. Alkuperäinen asiakirja sen alkuperäiskielellä on virallinen lähde. Tärkeissä asioissa suositellaan ammattimaisen ihmiskääntäjän käyttöä. Emme ole vastuussa tästä käännöksestä aiheutuvista väärinymmärryksistä tai tulkinnoista.

This site is open source. Improve this page.