ai-agents-for-beginners

Raziščemo Microsoft Agent Framework

Agent Framework

Uvod

Ta lekcija bo zajemala:

Cilji učenja

Po zaključku te lekcije boste znali:

Vzorce kode

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

Razumevanje Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) je Microsoftov enotni okvir za gradnjo AI agentov. Ponuja prilagodljivost za različne agentne primere uporabe, tako v produkcijskih kot raziskovalnih okoljih, vključno z:

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

Microsoft Agent Framework je tudi osredotočen na medsebojno delovanje z:

Poglejmo, kako so te funkcije uporabljene pri nekaterih glavnih konceptih Microsoft Agent Framework.

Ključni koncepti Microsoft Agent Framework

Agenti

Agent Framework

Ustvarjanje agentov

Ustvarjanje agenta poteka z definiranjem storitve sklepanja (LLM ponudnik), nabora navodil, ki jih AI agent sledi, in dodeljenega imena:

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

Zgornji primer uporablja Azure OpenAI, vendar lahko agente ustvarite z različnimi storitvami, vključno z Microsoft Foundry Agent Service:

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

OpenAI API-ji Responses, ChatCompletion

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 nudi združljiv API z OpenAI 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 z uporabo protokola A2A:

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

Zagon agentov

Agente zaženemo z metodama .run ali .run_stream za nestrimene ali strimene 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 vključuje tudi možnosti za prilagoditev parametrov, kot so max_tokens, orodja tools, ki jih lahko agent kliče, in celo model model, ki ga agent uporablja.

To je uporabno, kadar so za opravljanje uporabniške naloge potrebni določeni modeli ali orodja.

Orodja

Orodja lahko definiramo 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 ustvarjate ChatAgent neposredno

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

kot tudi pri zagonu agenta:


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

Nitke agentov

Nitke agentov se uporabljajo za večkratne pogovore (multi-turn). Nitke lahko ustvarimo bodisi z:

Kodo za ustvarjanje nitke je videti takole:

# 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)

Nato nitko lahko serializirate za shranjevanje in kasnejšo uporabo:

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

# Zaženi agenta z 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 agentov

Agenti sodelujejo z orodji in LLM-ji za opravljanje uporabniških nalog. V določenih primerih želimo izvajati ali slediti tej interakciji med agentom in orodjem. Middleware agentov to omogoča z:

Funkcijski middleware

Ta middleware omogoča izvajanje akcije med agentom in klicanjem funkcije/orodja. Primer uporabe je beleženje klica funkcije.

V spodnji kodi next določa, ali naj se kliče naslednji middleware ali dejanska funkcija.

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

    # Nadaljuj na naslednji vmesni programski opremi ali izvedbo funkcije
    await next(context)

    # Naknadna obdelava: Beleženje po izvajanju funkcije
    print(f"[Function] {context.function.name} completed")

Chat middleware

Ta middleware omogoča izvajanje ali beleženje akcije med agentom in zahtevami med LLM.

Vključuje 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 do naslednjega vmesnega sloja ali AI storitve
    await next(context)

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

Pomnilnik agentov

Kot je bilo zajeto v lekciji Agentic Memory, je pomnilnik ključni element za omogočanje delovanja agenta v različnih kontekstih. MAF ponuja več vrst pomnilnikov:

Shranjevanje v pomnilnik (In-Memory Storage)

To je pomnilnik, shranjen v nitkah 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)

Trajni sporočila (Persistent Messages)

Ta pomnilnik se uporablja za shranjevanje zgodovine pogovorov čez različne seje. Definiran je preko chat_message_store_factory:

from agent_framework import ChatMessageStore

# Ustvari prilagojeno shrambo 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 (Dynamic Memory)

Ta pomnilnik se doda kontekstu pred zagonom agentov. Te pomnilnike je mogoče shranjevati v zunanjih storitvah, kot je mem0:

from agent_framework.mem0 import Mem0Provider

# Uporaba Mem0 za napredne zmogljivosti 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 agentov

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

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 tokovi

MAF nudi delovne tokove, ki so prednastavljeni koraki za dokončanje naloge in vključujejo AI agente kot komponente teh korakov.

Delovni tokovi so sestavljeni iz različnih komponent, ki omogočajo boljši nadzor nad tokom. Prav tako omogočajo več-agentno orkestracijo in checkpointing za shranjevanje stanja delovnega toka.

Osnovne komponente delovnega toka so:

Izvajalci (Executors)

Izvajalci prejmejo vhodna sporočila, opravijo dodeljene naloge in proizvedejo izhodno sporočilo. To premakne delovni tok naprej k dokončanju večje naloge. Izvajalci so lahko AI agenti ali prilagojena logika.

Povezave (Edges)

Povezave določajo tok sporočil v delovnem toku. Lahko so:

Neposredne povezave - Enostavne povezave ena na ena 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()

Pogojne povezave - Aktivirajo se, ko je izpolnjen določen pogoj. Na primer, ko hotelske sobe niso na voljo, lahko izvajalec predlaga druge možnosti.

Povezave s preklopi - Usmerjajo sporočila do različnih izvajalcev glede na določene pogoje. Na primer, če ima potovalni kupec prednostni dostop in bodo njegove naloge obdelane v drugem delovnem toku.

Razvejitev (Fan-out Edges) - Pošlje eno sporočilo več naslovnikom.

Združitev (Fan-in Edges) - Zbere več sporočil od različnih izvajalcev in jih pošlje enemu naslovniku.

Dogodki

Za boljše opazovanje delovnih tokov MAF ponuja vgrajene dogodke za izvajanje, vključno z:

Napredni MAF vzorci

Zgornji oddelki pokrivajo ključne koncepte Microsoft Agent Framework. Ko gradite bolj zapletene agente, upoštevajte naslednje napredne vzorce:

Gostovanje LangChain / LangGraph agentov na Microsoft Foundry

Microsoft Agent Framework je sistem medsebojne združljivosti z ogrodji — niste omejeni samo na agente, napisane z MAF. Če že imate agenta, zgrajenega z LangChain ali LangGraph, ga lahko zaženete kot Najbolj gostovan agent Microsoft Foundry, tako da Foundry upravlja čas izvajanja, seje, prilagajanje, identiteto in protokolne končne točke, medtem ko logika vašega agenta ostane v LangGraph.

To se izvaja z langchain_azure_ai.agents.hosting paketom, ki omogoča sestavljeni LangGraph graf preko istih protokolov, ki jih uporabljajo Foundry gostovani agenti.

1. Namestite dodatni paket za gostovanje:

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

Paket hosting namesti Foundry protokolne knjižnice: azure-ai-agentserver-responses (združljiv /responses endpoint kot OpenAI) in azure-ai-agentserver-invocations (splošni /invocations endpoint).

2. Izberite protokol gostovanja:

Protokol Razred gostitelja Končna točka Uporaba
Responses ResponsesHostServer /responses Želite združljiv klepet OpenAI, streaming, zgodovino odzivov in povezanost pogovorov — priporočen privzeti način za pogovorne agente.
Invocations InvocationsHostServer /invocations Potrebujete prilagojeno JSON obliko, webhook slog končne točke ali ne-pogovorno obdelavo.

Ker je Responses API primarni API za razvoj agentnega sloga v Foundry, začnite s ResponsesHostServer za večino agentov.

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

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

Ko agent pozneje teče kot gostovani agent v Foundry, platforma samodejno vstavi FOUNDRY_PROJECT_ENDPOINT.

4. Izpostavite LangGraph agenta preko Responses protokola:

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)

    # 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 lokalno z python main.py, nato pošljite zahtevo Responses na http://localhost:8088/responses.

Ključna vedenja:

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

Vzorce kode

Vzorce kode za Microsoft Agent Framework lahko najdete v tem repozitoriju pod datotekami xx-python-agent-framework in xx-dotnet-agent-framework.

Imate več vprašanj o Microsoft Agent Framework?

Pridružite se Microsoft Foundry Discord, da spoznate druge učence, se udeležite uradnih ur in dobite odgovore na vaša 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.