ai-agents-for-beginners

Microsoft Agent Frameworki uurimine

Agent Framework

Sissejuhatus

See õppetund käsitleb:

Õpieesmärgid

Selle õppetunni lõpuks oskad:

Koodinäited

Microsoft Agent Frameworki (MAF) koodinäiteid leiate sellest varamuhoidlast failide xx-python-agent-framework ja xx-dotnet-agent-framework alt.

Microsoft Agent Frameworki mõistmine

Framework Intro

Microsoft Agent Framework (MAF) on Microsofti ühtne raamistik tehisintellekti agentide loomiseks. See pakub paindlikkust käsitleda laias valikus agentuurseid kasutusjuhtumeid nii tootmises kui uurimistöödes, sealhulgas:

AI agentide tootmiseks sisaldab MAF lisafunktsioone nagu:

Microsoft Agent Framework paneb rõhku ka omavahelise koostalitlusvõime saavutamisele:

Vaatame, kuidas neid funktsioone rakendatakse Microsoft Agent Frameworki põhikontseptsioonide puhul.

Microsoft Agent Frameworki võtmekontseptsioonid

Agendid

Agent Framework

Agentide loomine

Agendi loomine toimub, määrates järeldusteenuse (LLM pakkuja), juhised, mida AI agent peab järgima, ja määrates name:

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

Ülaltoodud näites kasutatakse Azure OpenAI-d, kuid agente saab luua erinevate teenuste abil, sh Microsoft Foundry Agent Service:

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

OpenAI Responses, ChatCompletion API-d

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

või MiniMax, mis pakub OpenAI-kompatibelset API-d suure kontekstiga aknaga (kuni 204K tokenit):

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

või kaugagendid, kasutades A2A protokolli:

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

Agentide käivitamine

Agente käivitatakse .run või .run_stream meetoditega, kas mitte-voogedastuseks või voogedastuseks vastamiseks.

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)

Iga agendi jooksul võivad olla ka valikud parameetrite kohandamiseks, nagu agendi kasutatavad max_tokens, tools, mida agent saab kutsuda, ja isegi kasutatav model.

See on kasulik juhtudel, kus ülesande täitmiseks on vaja kindlaid mudeleid või tööriistu.

Tööriistad

Tööriistad saab määratleda nii agendi määratlemisel:

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


# Kui luuakse ChatAgent otse

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

kui ka agendi käivitamisel:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Tööriist, mis on mõeldud ainult selleks jooksuks )

Agendi lõimed

Agendi lõimesid kasutatakse mitmevooruliste vestluste käsitlemiseks. Lõimed saab luua kas:

Lõime loomise kood näeb välja nii:

# Loo uus lõim.
thread = agent.get_new_thread() # Käivita agent lõimega.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Lõime saab seejärel serialiseerida hilisemaks kasutamiseks:

# Loo uus lõim.
thread = agent.get_new_thread() 

# Käivita agent koos lõimiga.

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

# Serialiseeri lõim salvestamiseks.

serialized_thread = await thread.serialize() 

# Deserialiseeri lõime olek pärast laadimist salvestusest.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Agendi vahendustarkvara

Agendid suhtlevad tööriistade ja LLM-idega, et täita kasutaja ülesandeid. Mõnel juhul soovime nende vahelist suhtlust jälgida või täiendavalt käivitada. Agendi vahendustarkvara võimaldab seda järgmiste abil:

Funktsioonide vahendustarkvara

See vahendustarkvara võimaldab meil käivitada toimingu agendi ja tema poolt kutsutava funktsiooni/tööriista vahel. Näide: logimine funktsiooni kutsel.

Koodis allpool määrab next, kas kutsutakse järgmine vahendustarkvara või tegelik funktsioon.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Eeltöötlus: Logi enne funktsiooni täitmist
    print(f"[Function] Calling {context.function.name}")

    # Jätka järgmise vahendustarkvara või funktsiooni täitmisega
    await next(context)

    # Järel-töötlus: Logi pärast funktsiooni täitmist
    print(f"[Function] {context.function.name} completed")

Vestluse vahendustarkvara

See vahendustarkvara võimaldab jälgida või täita toiminguid agendi ja LLM-i vaheliste päringute vahel.

See sisaldab olulist informatsiooni, nt AI teenusele saadetavad messages.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Eeltöötlemine: Logi enne tehisintellekti kutsumist
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Jätka järgmise vahendustaseme või tehisintellekti teenuse poole
    await next(context)

    # Järelprotsessimine: Logi pärast tehisintellekti vastust
    print("[Chat] AI response received")

Agendi mälu

Nagu õppetunnis Agentic Memory käsitleti, on mälu oluline element, mis võimaldab agentidel töötada erinevates kontekstides. MAF pakub mitut erinevat mälutüüpi:

Rakenduse mälu

See mälu on salvestatud lõimede ajal rakenduse jooksu ajal.

# Loo uus lõim.
thread = agent.get_new_thread() # Käivita agent lõimega.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Püsivad sõnumid

Seda mälu kasutatakse vestlusajaloo salvestamiseks erinevate sessioonide vahel. See määratletakse chat_message_store_factory abil:

from agent_framework import ChatMessageStore

# Loo kohandatud sõnumite hoidla
def create_message_store():
    return ChatMessageStore()

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

Dünaamiline mälu

See mälu lisatakse konteksti enne agentide käivitumist. Seda mälu saab hoida välisteenustes nagu mem0:

from agent_framework.mem0 import Mem0Provider

# Kasutades Mem0 arenenud mälu funktsionaalsuse jaoks
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
)

Agendi jälgitavus

Jälgitavus on oluline usaldusväärsete ja hooldatavate agentuursete süsteemide ehitamisel. MAF integreerub OpenTelemetry-ga, pakkudes jälgimist ja mõõdikuid parema nähtavuse saavutamiseks.

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 midagi
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Töövood

MAF pakub töövoogusid, mis on eelmääratletud sammud ülesande täitmiseks ja mis sisaldavad AI agente nendes sammudes komponendina.

Töövood koosnevad erinevatest komponentidest, mis võimaldavad paremat juhtimisvoogu. Töövood võimaldavad ka mitmeagendi orkestreerimist ja vaheetappide salvestamist töövoo olekute säilitamiseks.

Töövoo põhikomponendid on:

Täiturid

Täiturid võtavad vastu sisendsõnumeid, teevad oma määratud ülesanded ja toodavad väljundisõnumi. See viib töövoogu suurema ülesande täitmise poole. Täiturid võivad olla kas AI agent või kohandatud loogika.

Käärid

Käärid määratlevad sõnumite voogu töövoos. Need võivad olla:

Otsesed käärid - lihtsad ühe-kaheni ühendused täiturite vahel:

from agent_framework import WorkflowBuilder

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

Tingimuslikud käärid - aktiveeruvad, kui teatud tingimus on täidetud. Näiteks, kui hotellitube pole saadaval, võib täitur soovitada teisi võimalusi.

Lüliti-käsu (switch-case) käärid - marsruutivad sõnumeid erinevatele täituritele vastavalt määratud tingimustele. Näiteks kui reisiklient on prioriteediga ligipääsuga, käsitletakse nende ülesanded teise töövoo kaudu.

Fan-out käärid - saadavad ühe sõnumi mitmele sihtmärgile.

Fan-in käärid - koguvad mitu sõnumit erinevatelt täituritelt ja saadavad üheks sihtmärgiks.

Sündmused

Paremaks jälgitavuseks töövoogudes pakub MAF sisseehitatud täitmissündmusi, sealhulgas:

Täiustatud MAF mustrid

Ülaltoodud sektsioonid käsitlevad Microsoft Agent Frameworki põhikontseptsioone. Kui loote keerukamaid agente, kaaluge järgmisi täiustatud mustreid:

LangChain / LangGraph agentide majutamine Microsoft Foundrys

Microsoft Agent Framework on raamistikuülene — te ei ole piiratud ainult MAF-i kirjutatud agentidega. Kui teil on juba agent loodud LangChain või LangGraph abil, saate selle käitada kui Microsoft Foundry majutatud agenti, kus Foundry haldab käitamist, sessioone, skaleerimist, identiteeti ja protokolli lõpp-punkte, samal ajal kui teie agendi loogika jääb LangGraph-i.

Seda tehakse langchain_azure_ai.agents.hosting paketiga, mis ekspordib kompileeritud LangGraph graafi samade protokollide kaudu, mida Foundry majutatud agentide kasutab.

1. Installi majutamise lisand:

pip install -U "langchain-azure-ai[hosting]>=1.2.4" azure-identity

hosting lisand installib Foundry protokolliteegid: azure-ai-agentserver-responses (OpenAI-kompatibelne /responses lõpp-punkt) ja azure-ai-agentserver-invocations (üldine /invocations lõpp-punkt).

2. Valige majutamisprotokoll:

Protokoll Host klass Lõpp-punkt Kasutamise olukord
Responses ResponsesHostServer /responses Soovite OpenAI-kompatibelset vestlust, voogedastust, vastuste ajalugu ja vestluse lõimimist — soovitatud vaikeseade vestlusagentidele.
Invocations InvocationsHostServer /invocations Vajate kohandatud JSON-kujulist lõpp-punkti, webhook-laadset lõpp-punkti või mittevestluslikku töötlemist.

Kuna Responses API on Foundry agentide arenduse põhiliides, alustage enamiku agentide puhul ResponsesHostServer kasutamisest.

3. Konfigureerige keskkonnamuutujad (az login esmalt, et DefaultAzureCredential saaks autentida):

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_NAME="gpt-5-mini"

Kui agent hiljem käivitatakse Foundry majutatud agendina, süstib platvorm automaatselt FOUNDRY_PROJECT_ENDPOINT.

4. Eksponeerige LangGraph agent Responses protokolli kaudu:

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 sihib siin Foundry projekti OpenAI-ühilduvat (Responses) lõpp-punkti.
    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()

Käivitage see lokaalselt käsuga python main.py, seejärel saatke responses-päring aadressile http://localhost:8088/responses.

Peamised käitumised:

Selle näite töökorras versioon asub failis code-samples/14-langchain-hosted-agent.py. Täieliku juhendi (Invocations protokoll, kohandatud päringute skeemid ja tõrkeotsing) leiate siit: Host LangGraph agents as Foundry hosted agents.

Koodinäited

Microsoft Agent Frameworki koodinäiteid leiate sellest varamuhoidlast failide xx-python-agent-framework ja xx-dotnet-agent-framework alt.

Kas teil on Microsoft Agent Frameworki kohta rohkem küsimusi?

Liituge Microsoft Foundry Discordiga, et kohtuda teiste õppijatega, osaleda kontoritundides ja saada vastused oma AI agentide küsimustele.

Eelmine õppetund

AI agentide mälu

Järgmine õppetund

Arvuti kasutamise agentide loomine (CUA)

Lahtiütlus: See dokument on tõlgitud kasutades AI tõlketeenust Co-op Translator. Kuigi me püüdleme täpsuse poole, palun pange tähele, et automatiseeritud tõlgetes võib esineda vigu või ebatäpsusi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlkega seotud eksimustest või valesti mõistmistest.

This site is open source. Improve this page.