Ligações de agentes para Python no Funções do Azure

As associações de agentes para aplicações de funções em Python permitem adicionar comportamentos agentes a funções existentes. Quando a função é executada, a extensão constrói um Agent a partir de instruções Markdown e injeta-o no seu processador como um parâmetro com tipo. O seu código decide quando e como invocar o agente, juntamente com a lógica de aplicação determinística.

Importante

As associações de agentes para aplicações de funções em Python encontram-se atualmente em pré-visualização. Funcionalidades, nomes de pacotes e configuração podem mudar antes da disponibilidade geral.

Para comparar as ligações de agentes com outras funcionalidades relacionadas com IA, como as competências hospedadas no Funções do Azure e as ferramentas Model Context Protocol (MCP), consulte as opções de integração de IA para o Funções do Azure.

Uma associação de agente é uma associação de entrada pertencente à extensão que fornece um objeto Agent totalmente construído a uma função em Python. A extensão lê instruções do agente como texto bruto de um .agent.md ficheiro. O seu código de aplicação mantém a configuração específica de ferramentas para clientes e fornecedores, enquanto o projeto de aplicação de funções pode descobrir competências de agentes baseados em ficheiros e servidores MCP remotos.

A arquitetura de ligação de agentes suporta objetos agente de diferentes SDKs através de pacotes de extensão específicos de cada fornecedor. O Microsoft Agent Framework é o único SDK de agentes suportado na pré-visualização atual. Para o usar, instala o azurefunctions-agents-extensions-agent-framework pacote.

Quando usar associações de agentes

Use ligações de agentes quando uma Função do Azure necessita de raciocínio agente para parte de um fluxo de trabalho, mas a sua aplicação deve manter controlo sobre o seu gatilho, validação, ramificação, tratamento de erros e resposta. Cenários comuns incluem:

• Avalie um pedido HTTP. Valide uma encomenda com código determinístico, peça a um agente para avaliar o risco de cumprimento e use o resultado para construir a resposta HTTP.
• Enriquecer ou classificar eventos. Receba uma mensagem de fila, evento da Grade de Eventos ou outro payload de gatilho e use um agente para classificar, resumir ou enriquecer os dados antes que a sua função escreva o resultado.
• Adicione raciocínio a um fluxo de trabalho duradouro. Chame um agente a partir de um orquestrador do Durable Functions através da API context.call_agent() segura para reexecução e, em seguida, utilize o resultado em passos posteriores da orquestração.

As associações de agentes são uma boa opção quando o código determinístico da função deve continuar a atuar como coordenador. O agente executa uma tarefa de raciocínio delimitado e devolve o controlo ao processador ou à orquestração.

Porquê usar associações de agentes?

Muitos fluxos de trabalho de produção combinam passos que devem ser determinísticos com passos que beneficiam do raciocínio do modelo. As ligações de agentes oferecem os seguintes benefícios para estes fluxos de trabalho híbridos:

• Adicionar comportamento agente às funções existentes. Utilize o raciocínio do agente em funções acionadas por HTTP, temporizador, fila, Event Grid, Service Bus e outros acionadores.
• Controlar a invocação do agente no código de forma segura. Decidir quando invocar o agente, inspecionar a sua resposta e determinar a saída da função. A extensão encerra os recursos detidos pela invocação após sucesso, falha ou cancelamento.
• Reduzir o código de configuração do agente. Receba um Agent configurado como parâmetro tipado do processador, em vez de o construir e configurar as ligações para cada invocação.
• Separar as instruções da configuração em tempo de execução. Armazene instruções em linguagem natural num .agent.md ficheiro e configure clientes e ferramentas específicas do fornecedor explicitamente em Python.
• Utilize as capacidades partilhadas do agente. A extensão descobre competências de agentes baseados em ficheiros e servidores MCP baseados em HTTP a partir da raiz da aplicação e torna-os disponíveis para cada ligação de agentes.
• Chamar agentes a partir de orquestrações duradouras. A extensão executa trabalho de agente numa atividade oculta para que a repetição de orquestração permaneça determinística.
• Depure localmente com ferramentas conhecidas. Executa e depura a aplicação localmente como qualquer outra aplicação de funções em Python. Podes definir pontos de interrupção e percorrer tanto a lógica da função determinística como o código que invoca o agente.

Como funciona a associação de agente

AgentFunctionApp estende azure.functions.FunctionApp, pelo que tem as mesmas capacidades que FunctionApp. O markdown_agent decorador adiciona uma entrada de agente a uma função.

Para cada ligação de agentes, a extensão executa as seguintes operações:

1. Resolve o ficheiro solicitado .agent.md da raiz da aplicação de funções ou do seu agents/ diretório.
2. Carrega o ficheiro completo como instruções UTF-8 em bruto.
3. Combina as instruções com a fábrica de cliente configurada, as ferramentas do provedor explicitamente configuradas e as competências descobertas do agente e os servidores MCP.
4. Cria um novo Agent e abre recursos próprios da invocação.
5. Injeta o Agent no parâmetro do manipulador.
6. Fecha os recursos pertencentes à invocação quando a execução termina.

A extensão pode armazenar em cache a descoberta de fornecedores e definições de ligação compiladas. Não armazena em cache nem reutiliza recursos de invocações ativas entre invocações de funções.

Defina uma associação de agente

O exemplo seguinte utiliza o fornecedor atualmente suportado do Microsoft Agent Framework para adicionar um Agent a uma função ativada por HTTP. A função constrói a tarefa em código, invoca o agente e devolve a resposta do agente:

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)

O arg_name valor deve corresponder ao parâmetro do handler injetado. Para injetar vários agentes na mesma função, empilhe os decoradores markdown_agent e utilize um arg_name exclusivo e um parâmetro de handler para cada associação de agente. O agent_name valor identifica o ficheiro de instruções. Neste exemplo, order-fulfillment tem de corresponder exatamente a uma destas localizações:

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

Se ambos os ficheiros existirem, a definição é ambígua e o arranque da aplicação falha. Os nomes dos agentes não podem conter caminhos absolutos, separadores de caminho ou componentes de percurso. Não são permitidos ficheiros que se encontrem fora da raiz da aplicação.

Configure o cliente agente e as ferramentas

Configure um argumento client_factory zero ao construir AgentFunctionApp. A fábrica devolve um cliente novo apoiado pelo pacote do fornecedor. Também pode passar objetos da ferramenta Microsoft Agent Framework ou chamáveis em Python através do tools parâmetro ao nível da aplicação. Uma associação pode substituir a fábrica de clientes e as ferramentas da aplicação quando requer um comportamento diferente.

Por exemplo, a seguinte função desencadeada por HTTP utiliza uma ligação de agentes que disponibiliza lookup_inventory como ferramenta apenas para 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)

Tenha estas considerações em mente ao configurar o cliente agente e as ferramentas:

• A extensão do agente base é neutra em relação ao fornecedor. Um pacote de fornecedor integra um SDK de agente específico e define os tipos de cliente e agente suportados.
• O pacote de provedores Microsoft Agent Framework atualmente suportado não seleciona nem configura um fornecedor de modelos para a sua aplicação. A sua fábrica de cliente determina qual o cliente de chat e o modelo suportados pelo Microsoft Agent Framework que o agente utiliza.
• A extensão envia o ficheiro inteiro .agent.md ao fornecedor configurado como instruções para o agente. Não analisa definições de modelos, ferramentas, front matter YAML ou outras configurações de runtime a partir do ficheiro.

Competências de agentes partilhados e servidores MCP

A extensão descobre automaticamente capacidades de agentes partilhados a partir da raiz da aplicação:

Capacidade	Location	Comportamento
Competências de agente	skills/<skill-name>/SKILL.md ou Skills/<skill-name>/SKILL.md	O pacote do provedor carrega e valida a competência do agente baseada em ficheiro.
Servidores MCP remotos	mcp.json	A extensão configura os servidores HTTP ou HTTP passíveis de streaming suportados e as listas de permissões de ferramentas opcionais.
Ferramentas para fornecedores	Configuração de aplicação ou ligação	Objetos da ferramenta Microsoft Agent Framework ou chamáveis em Python são explicitamente fornecidos em vez de serem descobertos.

Tenha estas considerações em mente ao utilizar capacidades de agente partilhado:

• Cada vinculação de agente na aplicação de funções recebe todas as competências de agente descobertas e todos os servidores MCP.
• As competências de agentes baseadas em ficheiros são capacidades que um agente pode carregar. Não são competências alojadas pelo Funções do Azure, que usam um modelo de execução separado.
• A versão de pré-visualização atual da extensão do agente não suporta a seleção de um subconjunto de capacidades para uma aplicação ou associação individual.
• As competências do agente e as ferramentas MCP podem realizar operações privilegiadas. Coloque apenas capacidades que todos os agentes na aplicação possam usar, e use aplicações de funções separadas quando os agentes exigem limites de capacidades diferentes.

A configuração do MCP pode referenciar variáveis de ambiente para URLs, cabeçalhos, escopos de autenticação e IDs de clientes. As referências são resolvidas para cada invocação, antes de a extensão se ligar ao servidor. Não guarde segredos diretamente num ficheiro controlado mcp.json por código-fonte.

Servidores MCP de processo local e de entrada/saída padrão (stdio) não são suportados. O suporte ao MCP é uma dependência opcional e as importações normais de pacotes continuam seguras quando não estão instalados.

Use ligações de agentes com Durable Functions

As ligações de agentes suportam fluxos de trabalho híbridos e de longa duração através de uma integração opcional com Durable Functions. Um orquestrador de geradores síncronos chama context.call_agent() e devolve a tarefa resultante:

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() programa uma atividade oculta que resolve a definição do agente e executa todas as operações de modelo, sistema de ficheiros, credenciais, ferramentas e rede. O orquestrador apenas cria um pedido de esquema v1 determinístico, serializável em JSON. Como resultado, a repetição de orquestração não repete as operações não determinísticas dos agentes.

Chamadas de agente duráveis utilizam o fornecedor e capacidades partilhadas configuradas por AgentFunctionApp. As entradas e saídas devem ser serializáveis em JSON.

O suporte Durable Functions é opcional. As aplicações que não o usam não precisam de instalar ou importar o Durable Functions. Para usar orchestration_trigger e context.call_agent(), instale o pacote de fornecedores suportado com o seu extra de dependência duradoura.

Ficheiros de projeto

Uma aplicação habilitada por agente é uma aplicação padrão de funções em Python v2 com dependências de extensão de agente e um ou mais ficheiros de instruções:

Ficheiro ou pasta	Purpose
function_app.py	Define AgentFunctionApp, acionadores padrão do Functions, associações de agentes, fábricas de clientes e ferramentas do fornecedor explicitamente configuradas.
host.json	Configura o host do Funções do Azure.
requirements.txt	Inclui um pacote de fornecedor de agente suportado e qualquer pacote de cliente específico de SDK. Para a pré-visualização atual, utilize azurefunctions-agents-extensions-agent-framework. Extras opcionais permitem o suporte a Durable Functions e MCP.
*.agent.md ou agents/*.agent.md	Contém instruções UTF-8 brutas para um agente. Cada nome referenciado deve corresponder a exatamente um ficheiro.
skills/ ou Skills/	(Opcional) Contém competências de agente baseadas em ficheiros partilhadas por todas as ligações de agente.
mcp.json	(Opcional) Define servidores MCP remotos baseados em HTTP partilhados por todas as ligações de agentes.

Para a estrutura padrão Python do projeto, consulte o guia para desenvolvedores Funções do Azure Python.

Validação e diagnóstico

A extensão valida as definições dos agentes antes ou durante a compilação da associação, para que os problemas de configuração sejam assinalados com erros que indicam como corrigi-los. Validação abrange:

• Ficheiros em falta ou ambíguos .agent.md .
• Assinaturas de handler inválidas, incluindo um parâmetro injetado em falta ou incompatível.
• Opções ou capacidades de fornecedores não suportadas.
• Diretórios de habilidades inválidos e configuração MCP mal formada.
• Transportes MCP não suportados e valores de ambiente em falta.
• Payloads Duráveis inválidos ou valores que não são serializáveis em JSON.

Quando disponível, a extensão preserva o nome da Função Azure, o ID de invocação e o ID da instância Durable na fronteira do fornecedor para suportar correlação e diagnóstico.

Artigos relacionados

• Opções de integração de IA para Funções do Azure
• Use um agente do Microsoft Agent Framework numa função Python
• Use um vínculo de agente do Microsoft Agent Framework numa orquestração Durable
• Visão geral do Microsoft Agent Framework