快速入门：将你自己的代码部署为托管代理

在 “部署第一个托管代理”中，你部署了一个示例。 在本快速入门中，你将自己的Python代理代码部署到 Foundry 代理服务。 代码可以使用任何代理框架（如 Microsoft Agent Framework、LangGraph、GitHub Copilot SDK 或 OpenAI 代理 SDK）或直接调用模型的普通Python。

先决条件

在开始之前，需要：

• Azure subscription--免费创建一个订阅。

• 如果您有现有 Foundry 项目，您在项目范围需要 Foundry Project Manager。 如果需要创建新的 Foundry 项目，则需要在资源组范围内具有 Owner 角色权限。 有关完整角色矩阵，请参阅 托管代理权限参考。

• Azure Developer CLI （AZD） 1.25.3 或更高版本。

• azd microsoft.foundry 扩展：

  azd ext install microsoft.foundry
  

• 本地目录中的现有智能体代码。

• Python 3.13 或更高版本。

• （可选）若要从 Visual Studio Code 中的示例开始，请安装 Visual Studio Code 和 Microsoft Foundry Toolkit for Visual Studio Code。

项目目录应至少包含：

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

选择框架

在 步骤 1 中添加的托管库处理协议 - HTTP 服务器、运行状况检查和请求和响应架构。 它不依赖于特定的代理框架，因此代理逻辑可以使用你喜欢的任何Python包。

若要使用框架，请将其包添加到 requirements.txt 宿主库旁边，然后从处理程序中 main.py调用框架。 下表列出了每个选项的常见选项和示例。

Framework	要添加到 requirements.txt 的包	Sample
纯Python（直接调用模型）	azure-ai-projects	hello-world
LangGraph	langgraph、langchain-azure-ai	langgraph-chat
GitHub Copilot SDK	github-copilot-sdk	github-copilot
OpenAI 代理 SDK	openai-agents	openai-agents-sdk

每个示例列出了确切的 requirements.txt 包版本。 请参阅 samples 文件夹，了解完整的自带示例集。

注意

Microsoft Agent Framework 具有一个内置托管集成，该集成使用自己的包。 若要部署 Microsoft Agent Framework 代理，请参阅部署第一个托管代理。

从 Visual Studio Code 中的示例开始

若要从工作框架模板而不是你自己的代码开始，请使用 Microsoft Foundry Toolkit for Visual Studio Code中的示例库：

1. 在Visual Studio Code活动栏中，选择 Foundry Toolkit 图标。
2. 在 “开发人员工具>代理开发工具”下，选择“ 创建代理”。
3. 在“使用完全控制在代码中创建”下，选择“使用示例”。
4. 在 “从示例创建托管代理”上，使用筛选器缩小库范围：
   • 对于 Framework，请选择 代理框架、Bring Your Own、LangGraph 或 Copilot SDK。
   • 对于 协议类型，请选择 “响应 API ”或 “调用 API”。
5. 选择示例，然后选择“ 下一步”。
6. 输入代理名称，选择 Foundry 项目，然后选择“ 创建”。

该工具包将示例搭建到新工作区中，并设置一键 F5 调试体验。 若要从Visual Studio Code安装依赖项、在本地测试并部署，请按照部署第一个托管代理中的Visual Studio Code步骤操作。

选择协议

选择与代理交互模式匹配的选项卡。 响应 管理对话历史记录，并且与 OpenAI 兼容。 调用 使你可以完全控制请求和响应架构。

Tip

不确定要使用哪个协议？ 从 响应开始。

步骤 1：添加托管库

将协议库添加到 requirements.txt 中。 该库处理 HTTP 服务器、运行状况检查和协议符合性，与使用的代理框架无关。 如果使用框架，请将其包添加到同一文件 - 请参阅 “选择框架”。

反应

azure-ai-agentserver-responses>=1.0.0b7

调用

azure-ai-agentserver-invocations>=1.0.0b5

步骤 2：添加宿主包装器

使用宿主包装器创建或更新 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()

调用

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()

注意

这些示例会原样返回用户输入，以演示托管包装器。 将标记块替换为自己的代理逻辑 - 模型调用、RAG 或框架（如 LangGraph 或 GitHub Copilot SDK）。 有关完整示例，请参阅Python示例和 C# 示例。

步骤 3：初始化项目

从代理源目录运行 azd ai agent init ：

反应

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

调用

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

交互式流会提示输入以下内容：

• 代理名称：自定义名称或接受默认值。
• Foundry Project：选择“使用现有 Foundry 项目”或“创建新的 Foundry 项目”。
• 订阅：选择 Azure 订阅。
• 位置：选择Azure区域。

完成后，可以看到： 已成功添加到 azd 项目的 AI 代理定义！

步骤 4：预配Azure资源

azd provision

这会创建所需的Azure资源，例如 Application Insights。

步骤 5：在本地测试代理

azd ai agent run

此命令创建虚拟环境、安装依赖项并启动代理。 它还会在浏览器中打开代理检查器，以便你可以与代理聊天。

也可以在单独的终端中从 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 down 永久删除资源组中的每个资源，包括 Foundry 项目和托管代理。 如果资源组包含其他资源，也会删除这些资源。

azd down

Troubleshooting

Issue	解决方案
ModuleNotFoundError: azure.ai.agentserver	验证协议库是否位于 requirements.txt 中，然后重新安装：pip install -r requirements.txt
FOUNDRY_PROJECT_ENDPOINT not set	使用 azd ai agent run （自动设置）而不是 python main.py。 或将其添加到您的 .env 文件中。
Connection refused 在本地运行中	确保没有其他进程使用端口 8088。
AuthorizationFailed 部署过程中	您需要在项目范围内使用Foundry Project Manager。
智能体卡在 provisioning 中	运行 azd ai agent show 以检查状态。 首次部署可能需要 2 到 3 分钟，因为系统需要安装依赖项。
azd ai agent init 失败	运行 azd version 以验证 1.25.3 或更高版本。 更新扩展： azd ext upgrade microsoft.foundry.

有关完全权限和角色分配矩阵，请参阅 托管代理权限参考。

你学到的内容

在本快速入门中，请执行以下操作：

• 向现有代理代码添加了一个托管库。
• 已从你的源目录初始化一个 azd 项目。
• 已在本地使用 azd ai agent run 和 azd ai agent invoke --local 进行测试。
• 使用 azd deploy 部署到 Foundry 智能体服务。

后续步骤

管理托管代理生命周期

• 生成工具箱并将其与托管代理一起使用 ，以合并一个托管终结点后面的工具。

相关内容

• 什么是托管代理？
• 从源代码部署托管代理
• 从容器部署托管代理
• 代理开发生命周期
• Python托管代理示例
• 自带框架示例（LangGraph、GitHub Copilot SDK 等）
• C# 托管代理示例