ai-agents-for-beginners

探索 Microsoft Agent Framework

Agent Framework

介紹

本課程將涵蓋：

學習目標

完成本課程後，您將會知道如何：

程式碼範例

Microsoft Agent Framework (MAF) 的程式碼範例可在本資源庫 xx-python-agent-framework 與 xx-dotnet-agent-framework 檔案內找到。

了解 Microsoft Agent Framework

Framework Intro

Microsoft Agent Framework (MAF) 是微軟統一的 AI 代理建構框架。它提供彈性以解決在生產與研究環境中各種代理任務用例，包括：

為在生產環境交付 AI 代理，MAF 亦包含以下功能：

Microsoft Agent Framework 亦著重互操作性，透過：

現在讓我們看看這些功能如何應用於 Microsoft Agent Framework 的核心概念。

Microsoft Agent Framework 核心概念

代理 (Agents)

Agent Framework

創建代理

代理創建透過定義推理服務（LLM 提供者）、 一套供 AI 代理遵循的指示，以及指派一個 name 來完成：

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

上述範例使用的是 Azure OpenAI，但代理可使用多種服務來創建，包括 Microsoft Foundry Agent Service：

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

OpenAI 的 Responses 與 ChatCompletion API

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

或 MiniMax，其提供兼容 OpenAI 的 API 及大上下文窗口（最高 204K 代幣）：

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

亦可使用 A2A 通訊協議的遠端代理：

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

運行代理

代理可使用 .run 或 .run_stream 方法運行，分別支援非串流和串流回應。

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)

每次運行代理時亦可傳入選項，客製化例如代理所用的 max_tokens、代理可調用的 tools 及代理本身所用的 model。

這在需要特定模型或工具來完成使用者任務時非常有用。

工具

工具可在定義代理時設定：

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


# 當直接創建一個 ChatAgent 時

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

亦可在運行代理時設定：


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # 此工具僅供此運行使用 )

代理執行緒

代理執行緒用於處理多輪對話。執行緒可以：

創建執行緒的程式碼如下：

# 創建一個新執行緒。
thread = agent.get_new_thread() # 使用該執行緒運行代理。
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

之後可將執行緒序列化以便儲存以供稍後使用：

# 建立一個新執行緒。
thread = agent.get_new_thread() 

# 使用該執行緒運行代理。

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

# 將執行緒序列化以便儲存。

serialized_thread = await thread.serialize() 

# 從儲存中載入後反序列化執行緒狀態。

resumed_thread = await agent.deserialize_thread(serialized_thread)

代理中介軟體

代理在完成使用者任務時，會與工具和 LLM 互動。有時我們希望在這些互動過程中執行或追蹤某些操作。代理中介軟體讓我們可以透過以下方式做到這點：

功能中介軟體

此中介軟體允許我們在代理與其調用的功能／工具間執行操作。例如可以在功能呼叫時做記錄。

下列程式碼中 next 表示是否呼叫下一個中介軟體或實際功能。

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # 預處理：函數執行前記錄日誌
    print(f"[Function] Calling {context.function.name}")

    # 繼續到下一個中介軟件或函數執行
    await next(context)

    # 後處理：函數執行後記錄日誌
    print(f"[Function] {context.function.name} completed")

聊天中介軟體

此中介軟體允許我們在代理與 LLM 之間的請求過程中執行或記錄操作。

其中包含了重要資訊，如傳送至 AI 服務的 messages 等。

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # 預處理：在呼叫 AI 之前記錄日誌
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # 繼續下一個中介軟件或 AI 服務
    await next(context)

    # 後處理：在 AI 回應後記錄日誌
    print("[Chat] AI response received")

代理記憶體

如在「Agentic Memory」課程中所述，記憶是讓代理能在不同上下文中運作的重要元素。MAF 提供數種記憶型態：

記憶體內部存儲

這是應用執行期間執行緒內部的記憶。

# 建立一個新執行緒。
thread = agent.get_new_thread() # 使用該執行緒執行代理。
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

持久訊息

用於跨不同會話存儲對話歷史。透過 chat_message_store_factory 定義：

from agent_framework import ChatMessageStore

# 創建自訂消息存儲
def create_message_store():
    return ChatMessageStore()

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

動態記憶

這些記憶會在代理運行之前加入到上下文中。這些記憶可以存儲在像 mem0 這樣的外部服務中：

from agent_framework.mem0 import Mem0Provider

# 使用 Mem0 以獲取進階記憶功能
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
)

代理可觀察性

可觀察性對於構建可靠且可維護的代理系統非常重要。MAF 集成了 OpenTelemetry，提供追蹤和計量器以增強可觀察性。

from agent_framework.observability import get_tracer, get_meter

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

工作流

MAF 提供了預定義步驟的工作流，用於完成任務，且在這些步驟中包含 AI 代理作為組件。

工作流由不同的組件組成，允許更好的控制流程。工作流還支援多代理協調和檢查點，以保存工作流狀態。

工作流的核心組件是：

執行器

執行器接收輸入訊息，執行其指定的任務，然後生成輸出訊息。這推動工作流程向完成更大的任務前進。執行器可以是 AI 代理或自定義邏輯。

邊緣

邊緣用於定義工作流中訊息的流動。這些可以是：

直接邊緣 - 執行器之間的簡單一對一連接：

from agent_framework import WorkflowBuilder

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

條件邊緣 - 在某些條件滿足後啟動。例如，當飯店房間無法預訂時，執行器可以建議其他選項。

切換-案例邊緣 - 根據定義的條件將訊息路由到不同的執行器。例如，若旅客擁有優先權，則其任務將透過另一個工作流程處理。

多重發送邊緣 - 將一條訊息發送給多個目標。

多重接收邊緣 - 收集來自不同執行器的多條訊息並發送給一個目標。

事件

為了提供對工作流更好的可觀察性，MAF 提供了內置的執行事件，包括：

進階 MAF 模式

上面章節涵蓋了 Microsoft Agent Framework 的關鍵概念。在您建構更複雜的代理時，這裡有一些值得考慮的進階模式：

在 Microsoft Foundry 上承載 LangChain / LangGraph 代理

Microsoft Agent Framework 是框架互操作的 — 您並不受限於只能使用 MAF 寫的代理。若您已經有使用LangChain或LangGraph建構的代理，可以將其作為Microsoft Foundry 托管代理運行，讓 Foundry 管理執行環境、會話、擴展、自身識別及協定端點，而您的代理邏輯仍保留於 LangGraph。

這是透過 langchain_azure_ai.agents.hosting 套件完成的，該套件透過 Foundry 托管代理使用的協定，暴露編譯後的 LangGraph 圖表。

1. 安裝 hosting 額外功能：

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

hosting 額外功能會安裝 Foundry 協定庫：azure-ai-agentserver-responses（兼容 OpenAI 的 /responses 端點）和 azure-ai-agentserver-invocations（通用 /invocations 端點）。

2. 選擇承載協定：

協定 主機類別 端點 使用情況
Responses ResponsesHostServer /responses 需要 OpenAI 兼容的聊天、串流、回應歷史與對話串連 — 推薦的對話型代理預設。
Invocations InvocationsHostServer /invocations 需要自定義 JSON 格式、Webhook 式端點或非對話性處理。

因為 Responses API 是 Foundry 對代理型開發的主要 API，大多數代理建議先用 ResponsesHostServer。

3. 配置環境變數（先執行 az login，使 DefaultAzureCredential 可認證）：

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

當代理後續作為托管代理運行於 Foundry 時，平台會自動注入 FOUNDRY_PROJECT_ENDPOINT。

4. 透過 Responses 協定公開 LangGraph 代理：

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 這裡針對 Foundry 項目的 OpenAI 相容（Responses）端點。
    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()

本機運行指令為 python main.py，然後可向 http://localhost:8088/responses 發送 Responses 請求。

主要行為：

此範例可執行版本位於 code-samples/14-langchain-hosted-agent.py。如需完整教程（Invocations 協定、自訂請求結構與故障排除），請參閱 Host LangGraph agents as Foundry hosted agents。

程式碼範例

Microsoft Agent Framework 的程式碼範例可在此儲存庫的 xx-python-agent-framework 和 xx-dotnet-agent-framework 檔案中找到。

對 Microsoft Agent Framework 有更多問題？

加入 Microsoft Foundry Discord ，與其他學習者交流，參加諮詢時間並獲得 AI 代理相關問題的解答。

上一課

代理記憶

下一課

建立電腦使用代理 (CUA)

免責聲明： 本文件由 AI 翻譯服務 Co-op Translator 翻譯而成。雖然我們致力於確保準確性，但請注意，機器自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議進行專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或誤釋承擔責任。

This site is open source. Improve this page.