ai-agents-for-beginners

Raziskovanje Microsoft Agent Framework

Agent Framework

Uvod

Ta lekcija bo zajemala:

Cilji učenja

Po zaključku te lekcije boste znali:

Primeri kode

Primeri kode za Microsoft Agent Framework (MAF) so na voljo v tem repozitoriju v datotekah xx-python-agent-framework in xx-dotnet-agent-framework.

Razumevanje Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) je Microsoftov enoten okvir za gradnjo AI agentov. Nudil je prilagodljivost, da zadovolji široko paleto agentnih primerov uporabe, ki jih vidimo tako v proizvodnih kot raziskovalnih okoljih, vključno z:

Za zagotavljanje AI agentov v produkciji ima MAF tudi vključene funkcije za:

Microsoft Agent Framework je tudi osredotočen na interoperabilnost z:

Poglejmo, kako so te funkcije uporabljene pri nekaterih osnovnih pojmih Microsoft Agent Framework.

Ključni pojmi Microsoft Agent Framework

Agenti

Agent Framework

Ustvarjanje agentov

Ustvarjanje agenta poteka z določitvijo storitve sklepanja (LLM Provider), niza navodil, ki jih mora AI agent slediti, in dodeljenega imena:

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

Zgoraj se uporablja Azure OpenAI, vendar je mogoče agente ustvariti z uporabo različnih storitev, vključno z Microsoft Foundry Agent Service:

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

OpenAI Responses, ChatCompletion API-ji

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

ali MiniMax, ki ponuja OpenAI-kompatibilen API z velikimi kontekstnimi okni (do 204K tokenov):

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

ali oddaljene agente s protokolom A2A:

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

Zagon agentov

Agenti se zaženejo z metodama .run ali .run_stream za ne-stremirane oziroma stremirane odzive.

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)

Vsak zagon agenta lahko vsebuje tudi opcije za prilagajanje parametrov, kot so max_tokens, ki jih agent uporablja, tools (orodja), ki jih agent lahko poklič, in celo sam model, uporabljen za agenta.

To je uporabno v primerih, kjer so za zaključek uporabnikove naloge potrebni določeni modeli ali orodja.

Orodja

Orodja je mogoče definirati tako pri definiranju agenta:

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


# Ko neposredno ustvarjate ChatAgent

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

in tudi pri zagonu agenta:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Orodje na voljo samo za to izvajanje )

Niti agenta

Niti agenta se uporabljajo za obravnavo pogovorov z več hodi. Niti je mogoče ustvariti na dva načina:

Za ustvarjanje niti koda izgleda tako:

# Ustvari novo nit.
thread = agent.get_new_thread() # Zaženi agent z nitjo.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Nato lahko nit serializirate za poznejšo uporabo:

# Ustvari novo nit.
thread = agent.get_new_thread() 

# Zaženi agenta s to nitjo.

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

# Serializiraj nit za shranjevanje.

serialized_thread = await thread.serialize() 

# Deserializiraj stanje niti po nalaganju iz shrambe.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Middleware agenta

Agenti sodelujejo z orodji in LLM, da dokončajo uporabnikove naloge. V določenih scenarijih želimo izvajati ali spremljati vmesne interakcije. Middleware agenta to omogoča preko:

Funkcijski middleware

Ta middleware omogoča izvajanje dejanja med agentom in funkcijo/orodjem, ki ga agent kliče. Primer uporabe je, če želite zabeležiti klic funkcije.

V spodnji kodi next določa, ali je treba poklicati naslednji middleware ali dejansko funkcijo.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Pred-obdelava: Zabeleži pred izvajanjem funkcije
    print(f"[Function] Calling {context.function.name}")

    # Nadaljuj na naslednjo vmesno programsko opremo ali izvedbo funkcije
    await next(context)

    # Po-obdelava: Zabeleži po izvajanju funkcije
    print(f"[Function] {context.function.name} completed")

Chat middleware

Ta middleware omogoča izvajanje ali beleženje dejanja med agentom in zahtevki med LLM.

Vsebuje pomembne informacije, kot so messages, ki se pošiljajo AI storitvi.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Predobdelava: Zabeleži pred klicem AI
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Nadaljuj na naslednji vmesnik ali AI storitev
    await next(context)

    # Obdelava po: Zabeleži po odgovoru AI
    print("[Chat] AI response received")

Pomnilnik agenta

Kot je obravnavano v lekciji Agentic Memory, je pomnilnik pomemben element za omogočanje delovanja agenta v različnih kontekstih. MAF ponuja več različnih vrst pomnilnika:

Pomnilnik v teku (In-Memory Storage)

Pomnilnik shranjen v nitih med izvajanjem aplikacije.

# Ustvari novo nit.
thread = agent.get_new_thread() # Zaženi agenta z nitjo.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Vztrajna sporočila

Ta pomnilnik se uporablja za shranjevanje zgodovine pogovorov med različnimi sejami. Določen je z chat_message_store_factory:

from agent_framework import ChatMessageStore

# Ustvari prilagojeno skladišče sporočil
def create_message_store():
    return ChatMessageStore()

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

Dinamični pomnilnik

Ta pomnilnik se doda v kontekst pred zagonom agentov. Ti pomnilniki se lahko shranjujejo v zunanjih storitvah, kot je mem0:

from agent_framework.mem0 import Mem0Provider

# Uporaba Mem0 za napredne zmožnosti pomnilnika
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
)

Opazovanje agenta

Opazovanje je pomembno za gradnjo zanesljivih in vzdržljivih agentnih sistemov. MAF se povezuje z OpenTelemetry za zagotavljanje sledenja in meritev za boljšo opaznost.

from agent_framework.observability import get_tracer, get_meter

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

Delovni procesi

MAF ponuja delovne procese, ki so preddefinirani koraki za dokončanje naloge in vključujejo AI agente kot komponente v teh korakih.

Delovni procesi so sestavljeni iz različnih komponent, ki omogočajo boljši nadzor toka. Delovni procesi omogočajo tudi večagentno orkestracijo in točkovanje zaustavitve za shranjevanje stanj delovnega procesa.

Osnovne komponente delovnega procesa so:

Izvajalci

Izvajalci prejemajo vhodna sporočila, izvajajo dodeljene naloge in potom proizvedejo izhodno sporočilo. Tako delovni proces napreduje proti zaključku večje naloge. Izvajalci so lahko AI agenti ali lastna logika.

Povezave

Povezave se uporabljajo za definiranje toka sporočil v delovnem procesu. Lahko so:

Neposredne povezave - Enostavne povezave eden-na-eden med izvajalci:

from agent_framework import WorkflowBuilder

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

Povezave s pogoji - Aktivirane po izpolnitvi določenega pogoja. Na primer, ko sob ni na voljo, izvajalec lahko predlaga druge možnosti.

Preklopne povezave - Usmerjajo sporočila različnim izvajalcem glede na določene pogoje. Na primer, če ima potnik prednostni dostop, bodo njegove naloge obravnavane preko drugega delovnega procesa.

Razširitvene povezave - Pošljejo eno sporočilo več ciljem.

Združevalne povezave - Zberejo več sporočil iz različnih izvajalcev in pošljejo enemu cilju.

Dogodki

Za boljšo opaznost delovnih procesov MAF ponuja vgrajene dogodke izvajanja, vključno z:

Napredni MAF vzorci

Prejšnji odseki obravnavajo ključne pojme Microsoft Agent Framework. Ko gradite bolj zapletene agente, upoštevajte naslednje napredne vzorce:

Gostovanje LangChain / LangGraph agentov na Microsoft Foundry

Microsoft Agent Framework je okvirno interoperabilen — niste omejeni na agente napisane z MAF. Če že imate agenta zgrajenega z LangChain ali LangGraph, ga lahko poganjate kot Microsoft Foundry gostovanega agenta, tako da Foundry upravlja izvajanje, seje, skaliranje, identiteto in protokolne končne točke, medtem ko vaša logika agentov ostane v LangGraph.

To se izvaja z langchain_azure_ai.agents.hosting paketom, ki razgrne sestavljen LangGraph graf prek enakih protokolov, kot jih uporabljajo Foundry gostovani agenti.

1. Namestite hosting dodatek:

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

Dodatek hosting namesti Foundry protokolne knjižnice: azure-ai-agentserver-responses (OpenAI-kompatibilna /responses končna točka) in azure-ai-agentserver-invocations (splošna /invocations končna točka).

2. Izberite gostovalni protokol:

Protokol Gostiteljska razred Končna točka Uporaba
Responses ResponsesHostServer /responses Želite klepet, pretakanje, zgodovino odzivov in nitke pogovorov kompatibilne z OpenAI — priporočeno privzeto za pogovorne agente.
Invocations InvocationsHostServer /invocations Potrebujete lastno JSON obliko, webhook-stil končno točko ali ne-pogovorno obdelavo.

Ker je Responses API glavna API za razvoj agentov v Foundry, začnite z ResponsesHostServer za večino agentov.

3. Konfigurirajte okoljske spremenljivke (az login najprej, da se DefaultAzureCredential lahko avtorizira):

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

Ko agent kasneje teče kot gostovani agent v Foundry, platforma samodejno vbrizga FOUNDRY_PROJECT_ENDPOINT.

4. Izpostavite LangGraph agenta prek protokola 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-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 tukaj cilja na OpenAI-kompatibilno (Odgovori) končno točko projekta 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()

Zaženite ga lokalno z python main.py, nato pošljite zahtevek Responses na http://localhost:8088/responses.

Ključna vedenja:

Delujoča različica tega primera je na voljo v code-samples/14-langchain-hosted-agent.py. Za celoten vodnik (protokol Invocations, prilagojene sheme zahtevkov in odpravljanje težav) si oglejte Host LangGraph agents as Foundry hosted agents.

Primeri kode

Primeri kode za Microsoft Agent Framework so na voljo v tem repozitoriju v datotekah xx-python-agent-framework in xx-dotnet-agent-framework.

Imate več vprašanj o Microsoft Agent Framework?

Pridružite se Microsoft Foundry Discord, da se povežete z drugimi učenci, obiskujete uradne ure in dobite odgovore na vprašanja o AI agentih.

Prejšnja lekcija

Pomnilnik za AI agente

Naslednja lekcija

Gradnja agentov za uporabo računalnika (CUA)

Omejitev odgovornosti: Ta dokument je bil preveden z uporabo AI prevajalske storitve Co-op Translator. Čeprav si prizadevamo za natančnost, vas prosimo, da upoštevate, da avtomatizirani prevodi lahko vsebujejo napake ali netočnosti. Izvirni dokument v njegovem izvirnem jeziku je treba obravnavati kot avtoritativni vir. Za kritične informacije je priporočljiv strokovni človeški prevod. Ne odgovarjamo za morebitna nesporazume ali napačne interpretacije, ki izhajajo iz uporabe tega prevoda.

This site is open source. Improve this page.