ai-agents-for-beginners

Meneroka Rangka Kerja Ejen Microsoft

Agent Framework

Pengenalan

Pelajaran ini akan meliputi:

Matlamat Pembelajaran

Selepas menamatkan pelajaran ini, anda akan mengetahui cara untuk:

Contoh Kod

Contoh kod untuk Microsoft Agent Framework (MAF) boleh didapati dalam repositori ini di bawah fail xx-python-agent-framework dan xx-dotnet-agent-framework.

Memahami Rangka Kerja Ejen Microsoft

Framework Intro

Microsoft Agent Framework (MAF) adalah rangka kerja sehenti Microsoft untuk membina ejen AI. Ia menawarkan fleksibiliti untuk menangani pelbagai kes penggunaan ejen yang dilihat dalam persekitaran produksi dan penyelidikan termasuk:

Untuk menyampaikan Ejen AI dalam Produksi, MAF juga mempunyai ciri untuk:

Rangka Kerja Ejen Microsoft juga memberi tumpuan kepada kebolehsambungan dengan:

Mari kita lihat bagaimana ciri-ciri ini digunakan dalam beberapa konsep teras Rangka Kerja Ejen Microsoft.

Konsep Utama Rangka Kerja Ejen Microsoft

Ejen

Agent Framework

Mencipta Ejen

Penciptaan ejen dilakukan dengan mentakrifkan perkhidmatan inferens (Penyedia LLM), satu set arahan untuk diikuti oleh Ejen AI, dan nama yang diberikan:

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

Kod di atas menggunakan Azure OpenAI tetapi ejen boleh dicipta menggunakan pelbagai perkhidmatan termasuk Microsoft Foundry Agent Service:

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

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

atau MiniMax, yang menyediakan API serasi OpenAI dengan tetingkap konteks besar (sehingga 204K token):

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

atau ejen jarak jauh menggunakan protokol A2A:

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

Menjalankan Ejen

Ejen dijalankan menggunakan kaedah .run atau .run_stream untuk respons bukan penstriman atau penstriman.

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)

Setiap larian ejen juga boleh mempunyai pilihan untuk mengubah parameter seperti max_tokens yang digunakan oleh ejen, tools yang boleh dipanggil oleh ejen, dan juga model yang digunakan bagi ejen tersebut.

Ini berguna dalam kes di mana model atau alat tertentu diperlukan untuk menyelesaikan tugasan pengguna.

Alat

Alat boleh ditakrifkan semasa mentakrifkan ejen:

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


# Apabila membuat ChatAgent secara langsung

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

dan juga semasa menjalankan ejen:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Alat disediakan untuk larian ini sahaja )

Thread Ejen

Thread Ejen digunakan untuk mengendalikan perbualan berbilang pusingan. Thread boleh dicipta dengan:

Kod untuk mencipta thread adalah seperti berikut:

# Cipta satu utas baru.
thread = agent.get_new_thread() # Jalankan ejen dengan utas itu.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Anda kemudian boleh menyusun serialize thread untuk disimpan bagi kegunaan kemudian:

# Cipta benang baru.
thread = agent.get_new_thread() 

# Jalankan ejen dengan benang tersebut.

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

# Siri benang untuk penyimpanan.

serialized_thread = await thread.serialize() 

# Nyah siri keadaan benang selepas memuat dari penyimpanan.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Middleware Ejen

Ejen berinteraksi dengan alat dan LLM untuk menyelesaikan tugasan pengguna. Dalam beberapa scenario, kita mahu menjalankan atau melacak interaksi antara itu. Middleware ejen membolehkan kita untuk melakukan ini melalui:

Middleware Fungsi

Middleware ini membolehkan tindakan dilakukan antara ejen dan fungsi/alat yang akan dipanggil. Contohnya adalah apabila anda mahu merekod log panggilan fungsi.

Dalam kod di bawah next menentukan sama ada middleware seterusnya atau fungsi sebenar dipanggil.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Pralaksanaan: Log sebelum pelaksanaan fungsi
    print(f"[Function] Calling {context.function.name}")

    # Teruskan ke middleware seterusnya atau pelaksanaan fungsi
    await next(context)

    # Pasca-pemprosesan: Log selepas pelaksanaan fungsi
    print(f"[Function] {context.function.name} completed")

Middleware Perbualan

Middleware ini membolehkan tindakan atau pencatatan dilakukan antara ejen dan permintaan antara LLM.

Ini mengandungi maklumat penting seperti messige yang dihantar ke perkhidmatan AI.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Pra-pemprosesan: Log sebelum panggilan AI
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Terus ke middleware atau perkhidmatan AI seterusnya
    await next(context)

    # Pasca-pemprosesan: Log selepas maklum balas AI
    print("[Chat] AI response received")

Memori Ejen

Seperti yang dibincangkan dalam pelajaran Memori Agenik, memori adalah elemen penting untuk membolehkan ejen beroperasi atas konteks yang berbeza. MAF menawarkan beberapa jenis memori yang berbeza:

Penyimpanan Dalam Memori

Ini adalah memori yang disimpan dalam thread semasa runtime aplikasi.

# Buat benang baru.
thread = agent.get_new_thread() # Jalankan ejen dengan benang tersebut.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Mesej Kekal

Memori ini digunakan apabila menyimpan sejarah perbualan merentasi sesi yang berbeza. Ia ditakrifkan menggunakan chat_message_store_factory:

from agent_framework import ChatMessageStore

# Cipta stor mesej tersuai
def create_message_store():
    return ChatMessageStore()

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

Memori Dinamik

Memori ini ditambah ke dalam konteks sebelum ejen dijalankan. Memori ini boleh disimpan dalam perkhidmatan luar seperti mem0:

from agent_framework.mem0 import Mem0Provider

# Menggunakan Mem0 untuk keupayaan memori lanjutan
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
)

Kebolehpantauan Ejen (Observability)

Kebolehpantauan adalah penting untuk membina sistem ejen yang boleh dipercayai dan mudah diselenggara. MAF mengintegrasi dengan OpenTelemetry untuk menyediakan penjejakan dan pengukuran bagi kebolehpantauan yang lebih baik.

from agent_framework.observability import get_tracer, get_meter

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

Aliran Kerja

MAF menawarkan aliran kerja yang merupakan langkah yang telah ditetapkan untuk melengkapkan tugasan dan termasuk ejen AI sebagai komponen dalam langkah tersebut.

Aliran kerja terdiri daripada pelbagai komponen yang membolehkan aliran kawalan yang lebih baik. Aliran kerja juga membolehkan pengaturan banyak ejen dan penandaan cekmatan untuk menyimpan keadaan aliran kerja.

Komponen teras aliran kerja adalah:

Pelaksana

Pelaksana menerima mesej input, melaksanakan tugasan yang diberikan, dan menghasilkan mesej output. Ini menggerakkan aliran kerja maju ke arah menyelesaikan tugasan yang lebih besar. Pelaksana boleh sama ada ejen AI atau logik khusus.

Tepi

Tepi digunakan untuk mentakrifkan aliran mesej dalam aliran kerja. Ini boleh terdiri daripada:

Tepi Langsung - Sambungan satu-ke-satu mudah antara pelaksana:

from agent_framework import WorkflowBuilder

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

Tepi Bersyarat - Diaktifkan selepas syarat tertentu dipenuhi. Contohnya, apabila bilik hotel tidak tersedia, pelaksana boleh mencadangkan pilihan lain.

Tepi Suis - Mengarahkan mesej ke pelaksana yang berbeza berdasarkan syarat ditetapkan. Contoh, jika pelanggan perjalanan mempunyai akses keutamaan, tugasan mereka akan diurus melalui aliran kerja yang lain.

Tepi Fan-out - Hantar satu mesej ke pelbagai sasaran.

Tepi Fan-in - Kumpul beberapa mesej dari pelaksana yang berbeza dan hantar ke satu sasaran.

Peristiwa

Untuk menyediakan kebolehpantauan yang lebih baik ke dalam aliran kerja, MAF menawarkan peristiwa terbina dalam untuk pelaksanaan termasuk:

Corak MAF Lanjutan

Bahagian di atas merangkumi konsep utama Rangka Kerja Ejen Microsoft. Semasa anda membina ejen yang lebih kompleks, ini adalah beberapa corak lanjutan yang boleh dipertimbangkan:

Mengehos Ejen LangChain / LangGraph pada Microsoft Foundry

Rangka Kerja Ejen Microsoft adalah kerangka-interoperable — anda tidak terhad kepada ejen yang ditulis dengan MAF. Jika anda sudah mempunyai ejen yang dibina dengan LangChain atau LangGraph, anda boleh menjalankannya sebagai ejen dihoskan Microsoft Foundry supaya Foundry mengurus runtime, sesi, penskalaan, identiti, dan titik akhir protokol untuk anda, sementara logik ejen anda kekal dalam LangGraph.

Ini dilakukan dengan pakej langchain_azure_ai.agents.hosting, yang mendedahkan graf LangGraph yang telah disusun di atas protokol yang sama digunakan oleh ejen yang dihoskan Foundry.

1. Pasang tambahan hosting:

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

Tambahan hosting memasang perpustakaan protokol Foundry: azure-ai-agentserver-responses (titik akhir /responses yang serasi dengan OpenAI) dan azure-ai-agentserver-invocations (titik akhir /invocations generik).

2. Pilih protokol hosting:

Protokol Kelas Host Titik Akhir Gunakan apabila
Responses ResponsesHostServer /responses Anda mahukan chat, penstriman, sejarah respons, dan penyusunan perbualan yang serasi dengan OpenAI — lalai yang disyorkan untuk ejen perbualan.
Invocations InvocationsHostServer /invocations Anda memerlukan bentuk JSON tersuai, titik akhir gaya webhook, atau pemprosesan bukan perbualan.

Oleh kerana API Responses adalah API utama untuk pembangunan gaya ejen di Foundry, mulakan dengan ResponsesHostServer untuk kebanyakan ejen.

3. Konfigurasikan pemboleh ubah persekitaran (az login dahulu supaya DefaultAzureCredential boleh mengesahkan):

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

Apabila ejen dijalankan kemudian sebagai ejen dihoskan dalam Foundry, platform secara automatik menyuntik FOUNDRY_PROJECT_ENDPOINT.

4. Dedahkan ejen LangGraph di atas protokol 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 di sini mensasarkan titik akhir OpenAI-compatible (Responses) projek 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()

Jalankan secara setempat dengan python main.py, kemudian hantar permintaan Responses ke http://localhost:8088/responses.

Tingkah laku utama:

Versi boleh dijalankan contoh ini boleh didapati dalam code-samples/14-langchain-hosted-agent.py. Untuk panduan penuh (protokol Invocations, skema permintaan tersuai, dan penyelesaian masalah), lihat Host LangGraph agents as Foundry hosted agents.

Contoh Kod

Contoh kod untuk Rangka Kerja Ejen Microsoft boleh didapati dalam repositori ini di bawah fail xx-python-agent-framework dan xx-dotnet-agent-framework.

Ada Soalan Lagi Mengenai Rangka Kerja Ejen Microsoft?

Sertai Microsoft Foundry Discord untuk bertemu dengan pembelajar lain, hadiri waktu pejabat dan dapatkan jawapan untuk soalan Ejen AI anda.

Pelajaran Sebelumnya

Memori untuk Ejen AI

Pelajaran Seterusnya

Membangunkan Ejen Penggunaan Komputer (CUA)

Penafian: Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI Co-op Translator. Walaupun kami berusaha untuk ketepatan, sila ambil maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan oleh manusia profesional adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini.

This site is open source. Improve this page.