ai-agents-for-beginners

Istraživanje Microsoft Agent Frameworka

Agent Framework

Uvod

Ova lekcija obuhvatit će:

Ciljevi učenja

Nakon završetka ove lekcije ćete znati kako:

Primjeri koda

Primjeri koda za Microsoft Agent Framework (MAF) mogu se pronaći u ovom spremištu pod datotekama xx-python-agent-framework i xx-dotnet-agent-framework.

Razumijevanje Microsoft Agent Frameworka

Framework Intro

Microsoft Agent Framework (MAF) je jedinstveni okvir tvrtke Microsoft za izgradnju AI agenata. Nudi fleksibilnost za rješavanje širokog spektra agentičnih slučajeva upotrebe viđenih u produkcijskim i istraživačkim okruženjima, uključujući:

Za isporuku AI agenata u produkciji, MAF također uključuje značajke za:

Microsoft Agent Framework se također fokusira na interoperabilnost kroz:

Pogledajmo kako se ove značajke primjenjuju na neke od ključnih pojmova Microsoft Agent Frameworka.

Ključni pojmovi Microsoft Agent Frameworka

Agenti

Agent Framework

Kreiranje agenata

Kreiranje agenta se ostvaruje definiranjem usluge zaključivanja (LLM Provider), skupa uputa koje AI agent treba slijediti, i dodijeljenog imena:

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

Gore navedeni primjer koristi Azure OpenAI, ali agenti se mogu kreirati koristeći razne usluge uključujući Microsoft Foundry Agent Service:

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

OpenAI Responses, ChatCompletion API-je

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

ili MiniMax, koji pruža OpenAI-kompatibilan API s velikim kontekstnim okvirima (do 204 tisuće tokena):

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

ili udaljene agente koristeći A2A protokol:

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

Pokretanje agenata

Agenti se pokreću koristeći metode .run ili .run_stream za odgovore bez streaminga ili sa streamingom.

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)

Svako pokretanje agenta također može imati opcije za prilagodbu parametara kao što su max_tokens koje agent koristi, tools koje agent može pozvati, i čak sam model koji agent koristi.

Ovo je korisno u slučajevima kada su potrebni specifični modeli ili alati za dovršetak zadatka korisnika.

Alati

Alati se mogu definirati i prilikom definiranja 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." 


# Prilikom izravnog stvaranja ChatAgenta

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

i također prilikom pokretanja agenta:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Alat dostavljen samo za ovaj izvođenje )

Threadovi agenata

Threadovi agenata se koriste za vođenje višekratnih razgovora s više okretaja. Threadovi se mogu kreirati na dva načina:

Kod za kreiranje threada izgleda ovako:

# Kreirajte novu nit.
thread = agent.get_new_thread() # Pokrenite agenta s niti.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Thread se zatim može serijalizirati za pohranu i kasniju upotrebu:

# Kreirajte novu dretvu.
thread = agent.get_new_thread() 

# Pokrenite agenta s dretvom.

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

# Serijalizirajte dretvu za pohranu.

serialized_thread = await thread.serialize() 

# Deserijalizirajte stanje dretve nakon učitavanja iz pohrane.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Middleware agenata

Agenti komuniciraju s alatima i LLM-ovima za dovršavanje zadataka korisnika. U određenim scenarijima želimo izvršiti ili pratiti interakcije između njih. Middleware agenata omogućuje ovo kroz:

Middleware funkcija

Ovaj middleware nam dopušta izvršavanje akcije između agenta i funkcije/alata koji će agent pozvati. Primjer kada se ovo koristi je za vođenje zapisa (log) o pozivu funkcije.

U sljedećem kodu next definira treba li se pozvati sljedeći middleware ili stvarna funkcija.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Pretprocesiranje: Zabilježi prije izvršavanja funkcije
    print(f"[Function] Calling {context.function.name}")

    # Nastavi na sljedeći middleware ili izvršavanje funkcije
    await next(context)

    # Postprocesiranje: Zabilježi nakon izvršavanja funkcije
    print(f"[Function] {context.function.name} completed")

Middleware razgovora

Ovaj middleware omogućuje izvršavanje ili bilježenje akcije između agenta i zahtjeva između LLM-a.

Ovo sadrži važne informacije poput poruka koje se šalju AI servisu.

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

    # Nastavi na sljedeći middleware ili AI servis
    await next(context)

    # Obrada nakon: Zabilježi nakon AI odgovora
    print("[Chat] AI response received")

Memorija agenata

Kao što je obrađeno u lekciji Agentic Memory, memorija je važan element za omogućavanje rada agenta u različitim kontekstima. MAF nudi nekoliko različitih vrsta memorije:

Memorija u radnom prostoru

Ovo je memorija pohranjena u threadovima tijekom izvođenja aplikacije.

# Kreirajte novu dretvu.
thread = agent.get_new_thread() # Pokrenite agenta s dretvom.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Postojane poruke

Ova memorija se koristi za pohranu povijesti razgovora kroz različite sesije. Definira se korištenjem chat_message_store_factory:

from agent_framework import ChatMessageStore

# Stvori prilagođenu pohranu poruka
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čka memorija

Ova memorija se dodaje u kontekst prije pokretanja agenata. Ova memorija može biti pohranjena u vanjskim uslugama poput mem0:

from agent_framework.mem0 import Mem0Provider

# Korištenje Mem0 za napredne memorijske mogućnosti
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
)

Promatranje agenata

Promatranje je važno za izgradnju pouzdanih i održivih agentičnih sustava. MAF se integrira s OpenTelemetry za pružanje praćenja i mjerenja za bolje promatranje.

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # učini nešto
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Radni tokovi

MAF nudi radne tokove koji su unaprijed definirani koraci za dovršetak zadatka i uključuju AI agente kao komponente u tim koracima.

Radni tokovi se sastoje od različitih komponenti koje omogućuju bolju kontrolu protoka. Radni tokovi također omogućuju orkestraciju više agenata i checkpointing za spremanje stanja radnog toka.

Osnovne komponente radnog toka su:

Izvršitelji

Izvršitelji primaju ulazne poruke, izvršavaju svoje zadatke i zatim proizvode izlaznu poruku. Ovo pomiče radni tok prema dovršetku većeg zadatka. Izvršitelji mogu biti AI agenti ili prilagođena logika.

Veze

Veze se koriste za definiranje protoka poruka u radnom toku. Mogu biti:

Izravne veze - Jednostavne veze jedan na jedan između izvršitelja:

from agent_framework import WorkflowBuilder

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

Uvjetne veze - Aktiviraju se nakon što je zadovoljen određeni uvjet. Na primjer, ako sobe u hotelu nisu dostupne, izvršitelj može predložiti druge opcije.

Switch-case veze - Usmjeravaju poruke različitim izvršiteljima na temelju definiranih uvjeta. Na primjer, ako putnički korisnik ima prioritetni pristup, njegovi će zadaci biti obrađeni kroz drugi radni tok.

Fan-out veze - Šalju jednu poruku na više odredišta.

Fan-in veze - Prikupljaju više poruka od različitih izvršitelja i šalju na jedno odredište.

Događaji

Za pružanje bolje promatranosti radnih tokova, MAF nudi ugrađene događaje za izvršavanje uključujući:

Napredni MAF obrasci

Gornji odjeljci obuhvaćaju ključne pojmove Microsoft Agent Frameworka. Kako gradite složenije agente, evo nekoliko naprednih obrazaca za razmatranje:

Hostanje LangChain / LangGraph agenata na Microsoft Foundry

Microsoft Agent Framework je interoperabilan s drugim frameworkovima — niste ograničeni samo na agente napisane s MAF-om. Ako već imate agenta izrađenog s LangChain ili LangGraph, možete ga pokrenuti kao Foundry hostanog agenta tako da Foundry upravlja runtime-om, sesijama, skaliranjem, identitetom i krajnjim točkama protokola, dok vaša logika agenta ostaje u LangGraphu.

To se ostvaruje s paketom langchain_azure_ai.agents.hosting koji izlaže kompajlirani LangGraph graf preko iste protokole koje koriste Foundry hostani agenti.

1. Instalirajte hosting dodatak:

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

Dodatak hosting instalira Foundry protokol biblioteke: azure-ai-agentserver-responses (OpenAI-kompatibilnu /responses krajnju točku) i azure-ai-agentserver-invocations (generičku /invocations krajnju točku).

2. Odaberite hosting protokol:

Protokol Host klasa Krajnja točka Koristi kada
Responses ResponsesHostServer /responses Želite OpenAI-kompatibilan chat, streaming, povijest odgovora i threading razgovora — preporučeni zadani izbor za konverzacijske agente.
Invocations InvocationsHostServer /invocations Potrebna vam je prilagođena JSON struktura, webhook-stil krajnje točke ili ne-konverzacijsko procesiranje.

Budući da je Responses API primarni API za razvoj agenata u Foundryju, počnite s ResponsesHostServer za većinu agenata.

3. Konfigurirajte varijable okoline (az login prvo kako bi se DefaultAzureCredential mogao autentificirati):

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

Kada agent kasnije radi kao hostani agent u Foundryju, platforma automatski ubrizga FOUNDRY_PROJECT_ENDPOINT.

4. Izložite 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 ovdje cilja OpenAI-kompatibilnu (Odgovori) točku 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()

Pokrenite lokalno s python main.py, zatim pošaljite Responses zahtjev na http://localhost:8088/responses.

Ključna ponašanja:

Verzija ovog primjera koja se može pokrenuti živi u code-samples/14-langchain-hosted-agent.py. Za cjeloviti vodič (Invocations protokol, prilagođene sheme zahtjeva i rješavanje problema), pogledajte Host LangGraph agents as Foundry hosted agents.

Primjeri koda

Primjeri koda za Microsoft Agent Framework mogu se pronaći u ovom spremištu pod datotekama xx-python-agent-framework i xx-dotnet-agent-framework.

Imate dodatnih pitanja o Microsoft Agent Frameworku?

Pridružite se Microsoft Foundry Discord da biste upoznali druge učenike, sudjelovali na konzultacijama i dobili odgovore na pitanja o AI agentima.

Prethodna lekcija

Memorija za AI agente

Sljedeća lekcija

Izgradnja agenata za upotrebu računala (CUA)

Napomena: Ovaj dokument je preveden korištenjem AI prevoditeljskog servisa Co-op Translator. Iako težimo točnosti, imajte na umu da automatski prijevodi mogu sadržavati greške ili netočnosti. Izvorni dokument na izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporuča se profesionalni ljudski prijevod. Nismo odgovorni za bilo kakva nesporazumevanja ili pogrešne interpretacije koje proizlaze iz korištenja ovog prijevoda.

This site is open source. Improve this page.