Azure Functions 中适用于 Python 的代理绑定

Python函数应用的代理绑定允许你为现有函数添加代理行为。 当函数运行时，扩展会根据 Markdown 指令构建一个 Agent，并将其作为带类型的参数注入到你的处理程序中。 你的代码决定何时以及如何调用该代理，同时配合你的确定性应用逻辑。

Important

Python函数应用的代理绑定目前处于预览阶段。 功能、包名和配置在正式发布前可能会发生变化。

要比较代理绑定与其他 AI 相关功能，如 Azure Functions 托管技能和模型上下文协议（MCP）工具，请参见 Azure Functions 的 AI 集成选项。

代理绑定是一种由扩展拥有的输入绑定，它为 Python 函数提供了一个完整构Agent造的对象。 扩展程序从 .agent.md 文件中将代理指令作为原始文本读取。 您的应用代码保留了客户端和提供者专用的工具配置，而函数应用项目则可以发现基于文件的代理技能和远程MCP服务器。

代理绑定架构通过提供方专用扩展包，支持来自不同 SDK 的代理对象。 Microsoft Agent Framework 是当前预览版中唯一支持的代理 SDK。 要使用它，请安装 azurefunctions-agents-extensions-agent-framework 软件包。

何时使用药剂结合剂

当 Azure 函数需要针对部分工作流程进行代理推理，但应用程序必须保留对其触发、验证、分支、错误处理和响应的控制时，可以使用代理绑定。 常见方案包括：

• 评估HTTP请求。 用确定性代码验证订单，要求代理评估履约风险，并利用结果构建HTTP响应。
• 丰富或分类事件。 接收队列消息、事件网格事件或其他触发负载，并使用代理对数据进行分类、总结或丰富，然后再写入结果。
• 为持久的工作流程添加推理。 通过重放安全的 context.call_agent() API 调用 Durable Functions 编排器中的代理，然后在后续的编排步骤中使用结果。

当函数的确定性代码应保持协调者时，代理绑定是合适的选择。 代理执行有界推理任务，并将控制权返回处理器或编排。

为什么要使用药剂结合剂？

许多生产工作流程将必须确定的步骤与受益于模型推理的步骤结合起来。 代理绑定为这些混合工作流程带来了以下好处：

• 在现有功能中添加代理行为。 在由 HTTP、计时器、队列、事件网格、服务总线 和其他方式触发的函数中使用代理推理。
• 在代码中安全地控制代理调用。 决定何时调用代理，检查其响应，并确定函数输出。 扩展会在调用成功、失败或被取消后关闭由调用持有的资源。
• 减少代理设置代码。 接收一个已配置的 Agent 作为类型化处理程序参数，而不是在每次调用时都构造并装配它。
• 指令与运行时配置分开。 将自然语言指令存储在.agent.md文件中，并在 Python 中显式配置客户端和特定提供者的工具。
• 使用共享代理能力。 该扩展从应用根节点发现基于文件的代理技能和基于HTTP的MCP服务器，并向每个代理绑定者开放。
• 从持久业务流程调用智能体。 该扩展在隐藏的活动中运行代理任务，以确保编排重放保持确定性。
• 用熟悉的工具本地调试。 像其他 Python 函数应用一样，在本地运行和调试应用。 你可以设置断点，并逐步处理确定性函数逻辑和调用代理的代码。

药物结合的工作原理

AgentFunctionApp 扩展 azure.functions.FunctionApp，因此它具有与 FunctionApp相同的能力。 markdown_agent装饰器会向函数添加代理输入。

对于每个代理绑定，扩展执行以下操作：

1. 从函数应用根目录或其 .agent.md 目录中解析所请求的 agents/ 文件。
2. 以原始 UTF-8 指令加载完整文件。
3. 将这些指令与已配置的客户端工厂、显式配置的提供程序工具以及已发现的代理技能和 MCP 服务器结合起来。
4. 创建一个新的 Agent，并打开由该调用拥有的资源。
5. 将 Agent 注入到处理程序参数中。
6. 执行结束时关闭调用拥有的资源。

该扩展可以缓存提供者发现和编译绑定定义。 它不会缓存或重用跨函数调用的实时调用资源。

定义代理绑定

以下示例使用当前受支持的 Microsoft Agent Framework 提供程序，向一个 HTTP 触发的函数添加 Agent。 该函数在代码中构造任务，调用代理，并返回代理响应：

import azure.functions as func
from agent_framework import Agent
from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.function_name(name="ProcessOrder")
@app.route(route="orders/{orderId}", methods=["POST"])
@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    task = (
        "Validate the order and return fulfillment guidance for "
        f"{req.route_params['orderId']}."
    )
    response = await order_agent.run(task)
    return func.HttpResponse(response.text)

该 arg_name 值必须与注入的处理程序参数匹配。 要将多个代理注入同一函数，可以叠加 markdown_agent 装饰器，并为每个代理绑定使用唯一的 arg_name 和处理参数。 该 agent_name 值用于标识指令文件。 在此示例中，order-fulfillment 必须准确解析为以下位置中的一个：

<app_root>/order-fulfillment.agent.md
<app_root>/agents/order-fulfillment.agent.md

如果两个文件都存在，定义就不明确，应用启动失败。 代理名称不能包含绝对路径、路径分隔符或遍历组件。 不允许解析到应用程序根目录之外的文件。

配置代理客户端和工具

构造 AgentFunctionApp时配置一个零参数client_factory。 该工厂返回一个由提供程序包提供支持的全新客户端。 你也可以在应用级别通过 tools 参数传递 Microsoft Agent Framework 工具对象或 Python 可调用对象。 绑定可以在需要不同行为时覆盖应用级客户端工厂和工具。

例如，以下由 HTTP 触发的函数使用了一个代理绑定，使 lookup_inventory 仅作为工具提供给 order_agent：

def lookup_inventory(product_id: str) -> str:
    """Return the available inventory for a product."""
    return f"Inventory is available for {product_id}."


@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
    tools=[lookup_inventory],
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    response = await order_agent.run(req.get_body().decode())
    return func.HttpResponse(response.text)

在配置代理客户和工具时，请牢记以下几点：

• 基础代理扩展是提供者中立的。 提供者包集成了特定的代理 SDK，并定义了支持的客户端和代理类型。
• 目前支持的 Microsoft Agent Framework 提供工具包不会为您的应用选择或配置模型提供者。 你的客户端工厂决定了支持的 Microsoft Agent Framework 聊天客户端和代理使用的模型。
• 扩展将整个 .agent.md 文件作为代理指令传递给配置的提供者。 它不会解析模型设置、工具、YAML前置信息或其他运行时配置。

共享代理技能与MCP服务器

该扩展会自动从应用根节点发现共享代理能力：

能力	位置	Behavior
代理技能	skills/<skill-name>/SKILL.md 或 Skills/<skill-name>/SKILL.md	提供者包负责加载并验证基于文件的代理技能。
远程 MCP 服务器	mcp.json	该扩展用于配置受支持的 HTTP 服务器或可流式传输的 HTTP 服务器，以及可选的工具允许列表。
提供商工具	应用程序或绑定配置	Microsoft Agent Framework工具对象或Python可调用对象是显式提供的，而非被发现。

使用共享代理功能时请牢记以下几点：

• 函数应用中的每个代理绑定都会获得所有已发现的代理技能和 MCP 服务器。
• 基于文件的代理技能是代理可加载的功能。 它们不是 Azure Functions 托管的技能，后者使用独立的执行模型。
• 当前代理扩展的预览版不支持为某个应用或单个绑定选择部分能力。
• 代理技能和MCP工具可以执行特权操作。 只设置应用中每个代理都允许使用的能力，当代理需要不同能力边界时，使用不同的功能应用。

MCP 配置可以引用环境变量，包括 URL、头部、认证范围和客户端 ID。 在扩展连接到服务器之前，为每个调用解析引用。 不要直接把密钥存储在源代码控制 mcp.json 的文件里。

不支持本地进程和标准输入输出（stdio）MCP服务器。 MCP 支持是可选的依赖，正常的包导入在未安装时依然安全。

在 Durable Functions 中使用代理绑定

代理绑定通过可选的 Durable Functions 集成支持混合、长期运行的工作流程。 同步生成器编排器调用 context.call_agent() 并产出所得任务：

from typing import Any

from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.orchestration_trigger(context_name="context")
def order_orchestrator(context: Any):
    assessment = yield context.call_agent(
        "order-fulfillment",
        {"order": context.get_input()},
    )
    return assessment

call_agent() 调度隐藏活动，解析代理定义并执行所有模型、文件系统、凭据、工具和网络操作。 编排器只创建确定性、可 JSON 序列化的 schema-v1 请求。 因此，编排重放不会重复非确定性代理操作。

持久代理通话使用由 AgentFunctionApp配置的提供者和共享能力。 输入和输出必须是可序列化的 JSON 的。

对 Durable Functions 的支持是可选的。 不使用它的应用程序不需要安装或导入 Durable Functions。 使用 orchestration_trigger 和 context.call_agent()，安装支持的提供者包及其持久依赖附加功能。

项目文件

代理启用的应用程序是一个标准的 Python v2 函数应用，具有代理扩展依赖关系和一个或多个指令文件：

文件或文件夹	Purpose
function_app.py	定义 AgentFunctionApp，标准函数触发器、代理绑定、客户端工厂以及显式配置的提供者工具。
host.json	配置Azure Functions主机。
requirements.txt	包含支持的代理提供者包和任何针对SDK的客户端包。 当前预览请使用 azurefunctions-agents-extensions-agent-framework。 可选扩展提供对 Durable Functions 和 MCP 的支持。
*.agent.md 或 agents/*.agent.md	包含供代理使用的原始 UTF-8 指令。 每个被引用的名称必须精确解析到一个文件。
skills/ 或 Skills/	（可选）包含所有代理绑定共享的基于文件的代理技能。
mcp.json	（可选）定义所有代理绑定共享的基于HTTP的远程MCP服务器。

关于标准Python项目结构，请参见Azure Functions Python开发者指南。

验证与诊断

该扩展在绑定编译前或期间验证代理定义，从而避免配置问题失败并产生可操作的错误。 验证涵盖：

• 缺少或模糊 .agent.md 的文件。
• 处理程序签名无效，包括缺失或不匹配的注入参数。
• 不支持的提供者选项或能力。
• 技能目录无效，MCP配置也变形。
• 不支持的MCP传输和缺失的环境值。
• 无效的持久负载或无法序列化的JSON值。

在可用的情况下，该扩展会在提供者边界保留 Azure 函数名称、调用 ID 和持久实例 ID，以支持关联和诊断。

相关文章

• Azure Functions 的 AI 集成选项
• 在 Python 函数中使用 Microsoft Agent Framework代理
• 在 Durable 编排中使用 Microsoft Agent Framework 的代理绑定
• Microsoft Agent Framework 概述