快速入門：以託管代理身份部署您自己的程式碼

在 部署您的第一個託管代理 中，您已部署一個範例。 在這個快速入門中，你可以部署自己的 Python 或 .NET（C#）代理程式碼到 Foundry 代理服務。 你的程式碼可以使用任何代理框架——例如 Microsoft Agent Framework、LangGraph、GitHub Copilot SDK 或 OpenAI Agents SDK——或直接呼叫模型的純程式碼。

每個程式碼步驟都有你的語言和協議標籤。 每步驟都選擇相同的組合，例如 C#（回應）。

如果你使用像 GitHub Copilot 這樣的程式碼代理，Microsoft Foundry 技能可協助你將快速入門內容調整為適用於你自己的程式碼庫，並執行正確的azd部署步驟。

先決條件

在開始之前，您需要：

• Azure 訂用帳戶——免費建立一個。

• 如果你已有 Foundry 專案，則需要在專案範圍內使用 Foundry Project Manager。 如果您需要建立新的 Foundry 專案，則必須在資源群組範圍內具備 Owner 角色。 完整角色矩陣請參見 Hosted Agent permissions reference。

• Azure Developer CLI (azd) 1.27.1 或更新版本.

• azd microsoft.foundry 擴充功能：

  azd ext install microsoft.foundry
  

• 經過 azd 認證的會話：

  azd auth login
  

• 你現有的代理程式碼放在本地目錄中。

• 至於 Python 路徑，則是 Python 3.13 或更新版本。

• 至於 C# 路徑，則使用 .NET 10 SDK 或更新版本。

• （可選）要從 Visual Studio Code 範例開始，請安裝 Visual Studio Code 及 Microsoft Foundry for Visual Studio Code 工具包。

你的專案目錄至少應該包含以下內容，針對 Python：

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

或者，對於 C# 來說，是一個 .NET 網頁專案：

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

選擇你的框架

你在 第一步 新增的主機函式庫負責管理協定——HTTP 伺服器、健康檢查，以及請求和回應結構。 它不依賴特定代理框架，所以你的代理邏輯可以用你喜歡的任何套件，無論是 Python 還是 C#。

若要使用某個框架，請將其套件新增到託管程式庫旁，然後在處理常式中呼叫該框架。 下表列出常見選擇及每種 Python 範例。

Framework	要新增至 requirements.txt 的套件	範例
純 Python（直接呼叫模型）	azure-ai-projects	哈囉-世界
LangGraph	langgraph、langchain-azure-ai	langgraph-chat
GitHub Copilot SDK	github-copilot-sdk	GitHub-Copilot
OpenAI 智能代理 SDK	openai-agents	OpenAI-agents-SDK

每個樣本中的 requirements.txt 都會列出確切的套件版本。 完整自帶樣本集請參見 Python 範例資料夾。

對於 C#，請將 Framework 套件加入專案檔案中，並加在 hosting 套件旁，接著在 Program.cs 的處理常式中呼叫該 Framework。 完整 C# 範例，請參見 C# 自帶樣本資料夾。

注意

Microsoft Agent Framework 內建主機整合，使用自有套件。 若要部署 Microsoft Agent Framework 代理程式，請參閱部署您的第一個託管代理程式。

從 Visual Studio Code 的範例開始

若要從可直接使用的框架範本開始，而不是從自己的程式碼開始，請使用適用於 Visual Studio Code 的 Microsoft Foundry Toolkit 中的範例庫：

1. 在 Visual Studio Code 活動列中，選擇 Foundry 工具包圖示。
2. 在開發者工具> 代理開發工具中，選擇建立代理。
3. 在 「以程式碼創建並完全控制」中，選擇 使用範例。
4. 在「 從範例建立託管代理」中，使用篩選條件縮小畫廊範圍：
   • 至於 Framework，請選擇 Agent Framework、Bring Your Own、LangGraph 或 Copilot SDK。
   • 對於 協定類型，請選擇 回應 API 或 呼叫 API。
5. 選取一個範例，然後選擇 下一步。
6. 輸入代理名稱，選擇你的 Foundry 專案，然後選擇 建立。

工具組將樣本建構到一個新的工作區，並建立一鍵 F5 偵錯體驗。 若要安裝相依性、在本機測試，以及從 Visual Studio Code 部署，請依照 部署您的第一個託管代理程式 中的 Visual Studio Code 步驟。

選擇你的方案

每個程式碼步驟都有一個分頁，涵蓋各種語言和協定組合。 Responses 管理對話紀錄，且支援 OpenAI。 Invocations 讓你完全掌控請求與回應的結構。 每一步都選擇相同的語言和協定組合。

提示

不確定該用哪個協議？ 從 回應開始。

步驟 1：新增主機函式庫

把協議函式庫加入你的專案。 函式庫負責處理 HTTP 伺服器、健康檢查及協定合規，獨立於你使用的代理框架。 如果你使用框架，請將它的套件與主機函式庫一起加入——詳見 「選擇你的框架」。

Python（回應）

將通訊協定程式庫新增至您的 requirements.txt：

azure-ai-agentserver-responses>=1.0.0b7

Python（呼叫）

將協議函式庫加入您的 requirements.txt：

azure-ai-agentserver-invocations>=1.0.0b5

C#（回應）

建立一個 .NET 網頁專案並新增協定套件：

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

C#（召喚）

建立一個 .NET 網頁專案並新增協定套件：

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

步驟 2：新增主機包裝

使用託管包裝器建立或更新代理程式的進入點。 以下範例展示了最小模式。 用你現有的代理邏輯取代標記區塊。

Python（回應）

建立或更新 main.py：

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

Python（叫用）

建立或更新 main.py：

import json
from starlette.requests import Request
from starlette.responses import JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


if __name__ == "__main__":
    app.run()

C#（回應）

替換 Program.cs：

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

C#（呼叫）

替換 Program.cs：

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

注意

這些範例呼應使用者輸入，以展示主機包裝。 用你自己的代理邏輯取代標記區塊——模型呼叫、RAG，或像 LangGraph 或 GitHub Copilot SDK 這類框架。 完整範例請參見 Python 範例與 C# 範例。

步驟 3：初始化專案

從你的代理來源目錄執行 azd ai agent init 。 Azure 開發者 CLI 會從專案檔案中偵測你的語言：

Python（回應）

azd ai agent init --protocol responses --deploy-mode code

Python（呼叫）

azd ai agent init --protocol invocations --deploy-mode code

C#（回應）

azd ai agent init --protocol responses --deploy-mode code

C#（呼叫）

azd ai agent init --protocol invocations --deploy-mode code

互動流程會提示您輸入以下內容：

• 代理人名稱：自訂名稱或接受預設名稱。
• Foundry Project：選擇使用現有 Foundry project 或建立新的 Foundry project。
• 訂閱：選取您的 Azure 訂閱。
• 地點：選擇 Azure 區域。

完成後，你會看到： AI 代理定義成功加入你的 azd 專案！

步驟 4：配置 Azure 資源

azd provision

這會產生所需的 Azure 資源，例如 Application Insights。

步驟五：在本地測試代理人

azd ai agent run

這個指令會建立虛擬環境（Python）或還原並建置專案（C#）、安裝相依，然後啟動你的代理程式。 它也會在瀏覽器開啟客服檢查器，讓你能與客服人員聊天。

你也可以在獨立終端機從 CLI 呼叫：

azd ai agent invoke --local "Hello from my hosted agent"

步驟 6：部署至 Foundry 代理服務

azd deploy

指令結束後，輸出會顯示指向代理遊樂場和代理端點的連結：

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

步驟 7：呼叫已部署的代理

azd ai agent invoke "Hello from my hosted agent"

你應該會在幾秒內看到回覆。

清理資源

警告

如果目前 azd 環境建立了 Foundry 專案， azd down 則會永久刪除該專案的資源群組及所有相關資料。 如果你在初始化時選擇了現有專案，則保留 azd down 該專案、其資源群組、託管代理程式及其他快速啟動資源。 從現有專案中刪除不再需要的資源。

azd down

Troubleshooting

Issue	Solution
ModuleNotFoundError: azure.ai.agentserver	確認協定程式庫位於 requirements.txt 中，然後重新安裝：pip install -r requirements.txt。
C#： The type or namespace name 'AgentServer' could not be found	確認協定套件有被參考（dotnet add package Azure.AI.AgentServer.Responses --prerelease 或 Azure.AI.AgentServer.Invocations），且專案是否使用網頁 SDK（dotnet new web）。
C#：Cannot resolve scoped service ... Handler from root provider 在 dotnet run	預設 dotnet new web 啟動設定檔會設定 ASPNETCORE_ENVIRONMENT=Development，以啟用嚴格範圍驗證。 使用 azd ai agent run 進行測試（它會以託管模式執行），或在 dotnet run 之前先設定 ASPNETCORE_ENVIRONMENT=Production。
FOUNDRY_PROJECT_ENDPOINT not set	使用 azd ai agent run （自動設定）而不是直接執行應用程式。 或者把它加到你的 .env 檔案裡。
Connection refused 在本機執行時	確保沒有其他程序使用 8088 埠。
AuthorizationFailed 部署期間	你需要在專案範圍內使用 Foundry Project Manager。
Agent 卡在 provisioning	執行 azd ai agent show 以檢查狀態。 首次部署可能需要 2 到 3 分鐘，因為系統正在安裝相依套件。
azd ai agent init 失敗	執行 azd version 以確認版本為 1.27.1 或更新版本。 執行 azd ext show azure.ai.agents 以驗證 1.0.0-beta.4 或更新版本。 使用 azd ext upgrade azure.ai.agents 升級。

完整權限與角色指派矩陣，請參見 Hosted agent permissions 參考。

你學到了什麼

在這篇快速啟動指南中，您將：

• 在你現有的代理程式碼中新增了一個主機函式庫。
• 從你的來源目錄初始化了一個 azd 專案。
• 已在本機使用 azd ai agent run 和 azd ai agent invoke --local 測試。
• 已使用 azd deploy 部署至 Foundry Agent Service。

下一步

管理託管代理生命週期

• 建立工具箱並搭配代管代理程式使用，將多種工具整合至單一受管理的端點後方。

相關內容

• 什麼是託管代理？
• 從原始碼部署託管代理
• 從容器部署託管代理
• 代理開發生命週期
• Python 託管代理範例
• 自帶框架範例（LangGraph、GitHub Copilot SDK 等）
• C# 託管代理範例