ai-agents-for-beginners

Microsoft Agent Framework tyrinėjimas

Agent Framework

Įvadas

Šioje pamokoje aptarsime:

Mokymosi Tikslai

Baigę šią pamoką žinosite, kaip:

Kodo Pavyzdžiai

Kodo pavyzdžius Microsoft Agent Framework (MAF) rasite šiame saugykloje failese xx-python-agent-framework ir xx-dotnet-agent-framework.

Microsoft Agent Framework supratimas

Framework Intro

Microsoft Agent Framework (MAF) yra „Microsoft“ vieningas dirbtinio intelekto agentų kūrimo karkasas. Jis siūlo lankstumą spręsti plačią agentinių naudojimo atvejų įvairovę, kuri pasitaiko tiek gamybos, tiek mokslinių tyrimų aplinkose:

Siekiant pristatyti AI agentus gamybai, MAF taip pat apima funkcijas:

Microsoft Agent Framework taip pat orientuotas į tarpusavio veikimą:

Pažiūrėkime, kaip šios funkcijos taikomos pagrindinėms Microsoft Agent Framework koncepcijoms.

Microsoft Agent Framework pagrindinės koncepcijos

Agentai

Agent Framework

Agentų kūrimas

Agentų kūrimas vykdomas apibrėžiant išvedimo paslaugą (LLM tiekėją), instrukcijų rinkinį AI agentui vykdyti ir priskiriamą pavadinimą:

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

Aukščiau naudojamas Azure OpenAI, bet agentai gali būti kuriami naudojant įvairias paslaugas, tarp jų ir 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.", )

arba MiniMax, kuris siūlo OpenAI suderinamą API su dideliais konteksto langais (iki 204K žetonų):

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

arba nuotolinius agentus, naudojant A2A protokolą:

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

Agentų paleidimas

Agentai paleidžiami naudojant .run arba .run_stream metodus, skirta ne srautinėms arba srautinėms atsakų versijoms.

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)

Kiekvienam agentui paleidžiant taip pat galima nurodyti parinktis, tokias kaip agento naudojamų max_tokens, agento galimų iškviesti tools ir net paties naudojamo model.

Tai naudinga atvejais, kai tam tikri modeliai ar įrankiai yra būtini vartotojo užduočiai atlikti.

Įrankiai

Įrankiai gali būti apibrėžiami tiek aprašant agentą:

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


# Kai kuriamas ChatAgent tiesiogiai

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

tiek paleidžiant agentą:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Įrankis suteiktas tik šiam vykdymui )

Agentų gijos

Agentų gijos naudojamos daugiafunkcinių pokalbių valdymui. Gijos gali būti sukuriamos:

Gijos kūrimas atrodo taip:

# Sukurkite naują giją.
thread = agent.get_new_thread() # Paleiskite agentą su šia gija.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Giją galima serializuoti ir išsaugoti ateičiai:

# Sukurkite naują giją.
thread = agent.get_new_thread() 

# Vykdykite agentą su gija.

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

# Seralizuokite giją saugojimui.

serialized_thread = await thread.serialize() 

# Deserializuokite gijos būseną po įkėlimo iš saugyklos.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Agentų tarpinė programinė įranga

Agentai sąveikauja su įrankiais ir LLM, kad atliktų vartotojo užduotis. Tam tikrais atvejais reikia vykdyti arba stebėti šias sąveikas. Agentų tarpinė programinė įranga leidžia tai padaryti per:

Funkcinę tarpinę programinę įrangą

Ši tarpinė programinė įranga leidžia vykdyti veiksmą tarp agento ir funkcijos/įrankio, kurį agentas kvies. Pavyzdys yra tokiu atveju, kai norima atlikti žurnalo įrašymą apie funkcijos kvietimą.

Žemiau pateiktame kode next nurodo, ar turi būti iškviečiama kita tarpinė programinė įranga, ar pati funkcija.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Išankstinis apdorojimas: žurnalas prieš funkcijos vykdymą
    print(f"[Function] Calling {context.function.name}")

    # Tęsti iki kito tarpinio programos sluoksnio arba funkcijos vykdymo
    await next(context)

    # Po apdorojimo: žurnalas po funkcijos vykdymo
    print(f"[Function] {context.function.name} completed")

Pokalbių tarpinė programinė įranga

Ši tarpinė programinė įranga leidžia vykdyti ar registruoti veiksmus tarp agento ir LLM užklausų.

Joje yra svarbi informacija, pavyzdžiui, messages, siunčiami AI paslaugai.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Išankstinis apdorojimas: Žurnalas prieš kviečiant DI
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Tęsti kitam tarpinio sluoksnio arba DI paslaugai
    await next(context)

    # Po apdorojimo: Žurnalas po DI atsakymo
    print("[Chat] AI response received")

Agentų atmintis

Kaip aptarta pamokoje Agentinė atmintis, atmintis yra svarbus elementas leidžiantis agentui dirbti įvairiuose kontekstuose. MAF siūlo kelis atminties tipus:

Atmintis atmintyje

Tai atmintis saugoma gijų metu programos veikimo metu.

# Sukurti naują giją.
thread = agent.get_new_thread() # Vykdyti agentą su gija.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Išliekantys pranešimai

Ši atmintis naudojama saugoti pokalbio istoriją skirtingų sesijų metu. Ji aprašoma naudojant chat_message_store_factory:

from agent_framework import ChatMessageStore

# Sukurkite pasirinktinių pranešimų saugyklą
def create_message_store():
    return ChatMessageStore()

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

Dinaminė atmintis

Ši atmintis pridedama prie konteksto prieš paleidžiant agentus. Ši atmintis gali būti saugoma išorinėse paslaugose, pavyzdžiui, mem0:

from agent_framework.mem0 import Mem0Provider

# Naudojant Mem0 pažangioms atminties galimybėms
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
)

Agentų stebėjimas

Stebėjimas yra svarbus kuriant patikimas ir prižiūrimas agentines sistemas. MAF integruojasi su OpenTelemetry, kad suteiktų sekimą ir matuoklius geresniam stebėjimui.

from agent_framework.observability import get_tracer, get_meter

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

Darbo eigos

MAF siūlo darbo eigas – iš anksto apibrėžtus žingsnius užduočiai atlikti, įtraukiant AI agentus kaip žingsnių komponentus.

Darbo eigos susideda iš įvairių komponentų, leidžiančių geriau valdyti srautus. Darbo eigos taip pat leidžia daugiaagentinę orkestraciją ir punkto patikrinimą, kad būtų išsaugotos darbo eigos būsenos.

Pagrindiniai darbo eigos komponentai yra:

Vykdytojai

Vykdytojai gauna įėjimo pranešimus, atlieka priskirtas užduotis ir sukuria išėjimo pranešimą. Tai juda darbo eigą link didesnės užduoties užbaigimo. Vykdytojai gali būti dirbtinio intelekto agentai arba pasirinktinė logika.

Sąsajos (Edges)

Sąsajos naudojamos apibrėžti pranešimų srautą darbo eigoje. Jos gali būti:

Tiesioginės sąsajos – Paprasti vienas prie vieno jungimai tarp vykdytojų:

from agent_framework import WorkflowBuilder

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

Sąlyginės sąsajos – Aktyvuojamos, kai pateikiama tam tikra sąlyga. Pavyzdžiui, kai viešbučių kambariai yra neprieinami, vykdytojas gali pasiūlyti kitas galimybes.

Perjungimo sąsajos (Switch-case) – Maršrutuoti pranešimus skirtingiems vykdytojams pagal apibrėžtas sąlygas. Pavyzdžiui, jei keliautojas turi prioritetinę prieigą, jo užduotys bus tvarkomos per kitą darbo eigą.

Išsklaidymo sąsajos – Siųsti vieną pranešimą keliems gavėjams.

Suvartojimo sąsajos – Surinkti kelis pranešimus iš skirtingų vykdytojų ir nusiųsti vienam gavėjui.

Įvykiai

Siekiant geresnio stebėjimo darbo eigose, MAF siūlo integruotus vykdymo įvykius, tokius kaip:

Pažangūs MAF modeliai

Aukščiau aptarti pagrindiniai Microsoft Agent Framework konceptai. Kuriant sudėtingesnius agentus, verta apsvarstyti šiuos pažangius modelius:

LangChain / LangGraph agentų talpinimas Microsoft Foundry

Microsoft Agent Framework yra framework-interoperabilus — jums nėra ribojimų naudoti tik MAF rašytus agentus. Jei jau turite agentą parašytą su LangChain arba LangGraph, galite paleisti jį kaip Microsoft Foundry talpinamą agentą, kad Foundry valdyti vykdymą, sesijas, mastelį, tapatybę ir protokolo galinius taškus, o jūsų agento logika liktų LangGraph.

Tai daroma naudojant langchain_azure_ai.agents.hosting paketą, kuris pateikia kompiliuotą LangGraph schemą per tuos pačius protokolus, kuriuos naudoja Foundry talpinami agentai.

1. Įdiekite hosting papildinį:

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

Hosting papildinys įdiegia Foundry protokolo bibliotekas: azure-ai-agentserver-responses (OpenAI suderinamas /responses galinis taškas) ir azure-ai-agentserver-invocations (bendras /invocations galinis taškas).

2. Pasirinkite hosting protokolą:

Protokolas Host klasė Galinis taškas Naudokite kai
Responses ResponsesHostServer /responses Norite OpenAI suderinamo pokalbių, srautų, atsakymų istorijos ir pokalbio gijų – rekomenduojama daugumai pokalbių agentų.
Invocations InvocationsHostServer /invocations Reikia pritaikytos JSON struktūros, webhook stiliaus galinio taško arba nesikalbinių procesų.

Kadangi Responses API yra pagrindinė agentų raidos API Foundry, daugumai agentų pradėkite nuo ResponsesHostServer.

3. Sukonfigūruokite aplinkos kintamuosius (az login, kad DefaultAzureCredential galėtų autentifikuotis):

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

Kai agentas vėliau paleidžiamas Foundry kaip talpinamas agentas, platforma automatiškai įterpia FOUNDRY_PROJECT_ENDPOINT.

4. Pateikite LangGraph agentą per Responses protokolą:

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)

    # Čia ChatOpenAI taikosi į Foundry projekto OpenAI suderinamą (Atsakymai) galinį tašką.
    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()

Vykdykite lokaliai su python main.py, tada nusiųskite Responses užklausą adresu http://localhost:8088/responses.

Pagrindiniai elgesiai:

Šio pavyzdžio veikianti versija yra code-samples/14-langchain-hosted-agent.py. Pilnai instrukcijai (Invocations protokolas, įprastinės schema, trikčių šalinimas) žr. Host LangGraph agents as Foundry hosted agents.

Kodo Pavyzdžiai

Kodo pavyzdžius Microsoft Agent Framework rasite šiame saugykloje failese xx-python-agent-framework ir xx-dotnet-agent-framework.

Turite daugiau klausimų apie Microsoft Agent Framework?

Prisijunkite prie Microsoft Foundry Discord, kad susitiktumėte su kitais besimokančiais, dalyvautumėte konsultacijose ir gautumėte atsakymus į savo AI agentų klausimus.

Ankstesnė pamoka

Atmintis dirbtinio intelekto agentams

Tolimesnė pamoka

Kompiuterio naudojimo agentų kūrimas (CUA)

Atsakomybės apribojimas: Šis dokumentas buvo išverstas naudojant dirbtinio intelekto vertimo paslaugą Co-op Translator. Nors siekiame tikslumo, prašome atkreipti dėmesį, kad automatiniai vertimai gali turėti klaidų ar netikslumų. Originalus dokumentas jo gimtąja kalba laikomas autoritetingu šaltiniu. Svarbiai informacijai rekomenduojama naudoti profesionalų žmogiškąjį vertimą. Mes neatsakome už jokius nesusipratimus ar neteisingą interpretaciją, kilusią naudojantis šiuo vertimu.

This site is open source. Improve this page.