ai-agents-for-beginners

Utforske Microsoft Agent Framework

Agent Framework

Introduksjon

Denne leksjonen vil dekke:

Læringsmål

Etter å ha fullført denne leksjonen, vil du vite hvordan du:

Eksempelkode

Eksempelkode for Microsoft Agent Framework (MAF) finnes i dette arkivet under filene xx-python-agent-framework og xx-dotnet-agent-framework.

Forstå Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) er Microsofts enhetlige rammeverk for å bygge AI-agenter. Det tilbyr fleksibilitet til å håndtere den store variasjonen av agentiske brukstilfeller som sees både i produksjon og forskningsmiljøer inkludert:

For å levere AI-agenter i produksjon, inneholder MAF også funksjoner for:

Microsoft Agent Framework fokuserer også på å være interoperabel ved å:

La oss se på hvordan disse funksjonene anvendes på noen av kjernebegrepene i Microsoft Agent Framework.

Nøkkelbegreper i Microsoft Agent Framework

Agenter

Agent Framework

Opprette agenter

Opprettelse av agent skjer ved å definere inferensetjenesten (LLM-leverandør), et sett instruksjoner for AI-agenten å følge, og et tildelt navn:

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

Ovenfor brukes Azure OpenAI men agenter kan opprettes ved bruk av flere tjenester inkludert Microsoft Foundry Agent Service:

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

OpenAI Responses, ChatCompletion APIer

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

eller MiniMax, som tilbyr en OpenAI-kompatibel API med store kontekstvinduer (opp til 204K tokens):

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

eller eksterne agenter ved bruk av A2A-protokollen:

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

Kjøre agenter

Agenter kjøres ved hjelp av .run eller .run_stream metoder for henholdsvis ikke-strømmende eller strømmende svar.

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)

Hver agentkjøring kan også ha alternativer for å tilpasse parametere som max_tokens som brukes av agenten, tools som agent kan kalle, og til og med model som selv brukes av agenten.

Dette er nyttig i tilfeller hvor spesifikke modeller eller verktøy kreves for å utføre brukerens oppgave.

Verktøy

Verktøy kan defineres både ved opprettelse av agenten:

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


# Når du oppretter en ChatAgent direkte

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

og også ved kjøring av agenten:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Verktøy gitt kun for denne kjøringen )

Agenttråder

Agenttråder brukes til å håndtere flertrinns samtaler. Tråder kan opprettes ved enten:

For å opprette en tråd, ser koden slik ut:

# Opprett en ny tråd.
thread = agent.get_new_thread() # Kjør agenten med tråden.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Du kan deretter serialisere tråden for lagring til senere bruk:

# Opprett en ny tråd.
thread = agent.get_new_thread() 

# Kjør agenten med tråden.

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

# Serialiser tråden for lagring.

serialized_thread = await thread.serialize() 

# Deserialiser trådens tilstand etter lasting fra lagring.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Agent Mellomvare

Agenter interagerer med verktøy og LLM-er for å fullføre brukerens oppgaver. I visse scenarier ønsker vi å utføre eller spore handlinger mellom disse interaksjonene. Agent mellomvare gjør dette mulig gjennom:

Funksjonsmellomvare

Denne mellomvaren lar oss utføre en handling mellom agenten og en funksjon/verktøy som den vil kalle. Et eksempel på bruk er hvis du ønsker å logge funksjonskallet.

I koden under definerer next om neste mellomvare eller den faktiske funksjonen skal kalles.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Forbehandling: Logg før funksjonsutførelse
    print(f"[Function] Calling {context.function.name}")

    # Fortsett til neste mellomvare eller funksjonsutførelse
    await next(context)

    # Etterbehandling: Logg etter funksjonsutførelse
    print(f"[Function] {context.function.name} completed")

Chat-mellomvare

Denne mellomvaren lar oss utføre eller logge en handling mellom agenten og forespørslene mellom LLM.

Dette inneholder viktig informasjon som messages som sendes til AI-tjenesten.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Forbehandling: Logg før AI-kall
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Fortsett til neste mellomvare eller AI-tjeneste
    await next(context)

    # Etterbehandling: Logg etter AI-svar
    print("[Chat] AI response received")

Agentminne

Som dekket i Agentic Memory-leksjonen, er minne et viktig element for at agenten skal kunne operere over forskjellige kontekster. MAF tilbyr flere forskjellige typer minne:

In-memory storage

Dette er minnet lagret i tråder under applikasjonens kjøretid.

# Opprett en ny tråd.
thread = agent.get_new_thread() # Kjør agenten med tråden.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Vedvarende meldinger

Dette minnet brukes til lagring av samtalehistorikk over flere økter. Det defineres ved bruk av chat_message_store_factory:

from agent_framework import ChatMessageStore

# Opprett et egendefinert meldingslager
def create_message_store():
    return ChatMessageStore()

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

Dynamisk minne

Dette minnet legges til konteksten før agenter kjøres. Disse minnene kan lagres i eksterne tjenester som mem0:

from agent_framework.mem0 import Mem0Provider

# Bruker Mem0 for avanserte minnefunksjoner
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
)

Agentobservabilitet

Observabilitet er viktig for å bygge pålitelige og vedlikeholdbare agentiske systemer. MAF integreres med OpenTelemetry for å tilby sporing og måleinstrumenter for bedre observabilitet.

from agent_framework.observability import get_tracer, get_meter

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

Arbeidsflyter

MAF tilbyr arbeidsflyter som er forhåndsdefinerte trinn for å fullføre en oppgave og inkluderer AI-agenter som komponenter i disse trinnene.

Arbeidsflyter består av ulike komponenter som tillater bedre kontrollflyt. Arbeidsflyter muliggjør også multi-agent orkestrering og checkpointing for å lagre arbeidsflyttilstander.

Kjernen i en arbeidsflyt er:

Utførere

Utførere mottar innkommende meldinger, utfører tildelte oppgaver, og produserer deretter en utgående melding. Dette driver arbeidsflyten fremover mot å fullføre den større oppgaven. Utførere kan være enten AI-agent eller egendefinert logikk.

Kantrer

Kantrer brukes for å definere flyten av meldinger i en arbeidsflyt. Disse kan være:

Direkte kantrer - Enkle en-til-en forbindelser mellom utførere:

from agent_framework import WorkflowBuilder

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

Betingede kantrer - Aktiveres når en viss betingelse er oppfylt. For eksempel, når hotellrom er utilgjengelige, kan en utfører foreslå andre alternativer.

Switch-case kantrer - Ruter meldinger til forskjellige utførere basert på definerte betingelser. For eksempel hvis en reisekunde har prioritetsadgang og deres oppgaver vil håndteres via en annen arbeidsflyt.

Fan-ut kantrer - Sender en melding til flere mål.

Fan-inn kantrer - Samler flere meldinger fra ulike utførere og sender til ett mål.

Hendelser

For bedre observabilitet i arbeidsflyter tilbyr MAF innebygde hendelser for utførelse inkludert:

Avanserte MAF-mønstre

Seksjonene over dekker nøkkelbegrepene i Microsoft Agent Framework. Når du bygger mer komplekse agenter, her er noen avanserte mønstre å vurdere:

Hosting LangChain / LangGraph-agenter på Microsoft Foundry

Microsoft Agent Framework er rammeverks-interoperabelt — du er ikke begrenset til agenter skrevet med MAF. Hvis du allerede har en agent bygget med LangChain eller LangGraph, kan du kjøre den som en Microsoft Foundry-hostet agent slik at Foundry håndterer kjøretid, økter, skalering, identitet og protokollendepunkter for deg, mens agentlogikken din forblir i LangGraph.

Dette gjøres med langchain_azure_ai.agents.hosting-pakken, som eksponerer en kompilert LangGraph-graf over de samme protokollene som Foundry-hostede agenter bruker.

1. Installer hosting-ekstraen:

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

hosting ekstraen installerer Foundry protokollbibliotekene: azure-ai-agentserver-responses (det OpenAI-kompatible /responses endepunktet) og azure-ai-agentserver-invocations (det generiske /invocations endepunktet).

2. Velg en hostingprotokoll:

Protokoll Host-klasse Endepunkt Bruk når
Responses ResponsesHostServer /responses Du ønsker OpenAI-kompatibel chat, strømming, svarhistorikk og samtaletråding — anbefalt standard for samtaleagenter.
Invocations InvocationsHostServer /invocations Du trenger et egendefinert JSON-format, et webhook-lignende endepunkt, eller ikke-samtaleprosessering.

Siden Responses API er hoved-APIen for agentstilutvikling i Foundry, start med ResponsesHostServer for de fleste agenter.

3. Konfigurer miljøvariabler (az login først slik at DefaultAzureCredential kan autentisere):

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

Når agenten senere kjører som en hostet agent i Foundry, injiserer plattformen automatisk FOUNDRY_PROJECT_ENDPOINT.

4. Eksponer en LangGraph-agent over Responses-protokollen:

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 her retter seg mot Foundry-prosjektets OpenAI-kompatible (Responses) endepunkt.
    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()

Kjør den lokalt med python main.py, og send deretter en Responses-forespørsel til http://localhost:8088/responses.

Nøkkeladferder:

En kjørbar versjon av dette eksempelet finnes i code-samples/14-langchain-hosted-agent.py. For full gjennomgang (Invocations-protokoll, egendefinerte forespørselskjemaer og feilsøking), se Host LangGraph agents as Foundry hosted agents.

Eksempelkode

Eksempelkode for Microsoft Agent Framework finnes i dette arkivet under filene xx-python-agent-framework og xx-dotnet-agent-framework.

Har du flere spørsmål om Microsoft Agent Framework?

Bli med i Microsoft Foundry Discord for å møte andre elever, delta på kontortimer og få svar på dine spørsmål om AI-agenter.

Forrige leksjon

Memory for AI Agents

Neste leksjon

Bygge datamaskinbruk-agenter (CUA)

Ansvarsfraskrivelse: Dette dokumentet er oversatt ved hjelp av AI-oversettelsestjenesten Co-op Translator. Selv om vi streber etter nøyaktighet, vær oppmerksom på at automatiske oversettelser kan inneholde feil eller unøyaktigheter. Det opprinnelige dokumentet på originalspråket skal betraktes som den autoritative kilden. For kritisk informasjon anbefales profesjonell menneskelig oversettelse. Vi er ikke ansvarlige for eventuelle misforståelser eller feiltolkninger som oppstår ved bruk av denne oversettelsen.

This site is open source. Improve this page.