Vinculações de agentes para Python no Azure Functions

Vinculações de agentes para aplicativos 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 em Markdown e o injeta no seu manipulador como um parâmetro tipado. Seu código decide quando e como invocar o agente junto com sua lógica de aplicação determinística.

Importante

As vinculações de agente para aplicativos de função do Python estão em versão prévia. Recursos, nomes de pacotes e configurações podem mudar antes da disponibilidade geral.

Para comparar as vinculações de agentes com outros recursos relacionados à IA, como habilidades hospedadas no Azure Functions e ferramentas Model Context Protocol (MCP), veja opções de integração de IA para Azure Functions.

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 Python. A extensão lê instruções do agente como texto bruto de um .agent.md arquivo. O código do seu aplicativo mantém a configuração específica de ferramentas para clientes e provedores, enquanto o projeto de aplicação de funções pode descobrir habilidades de agentes baseados em arquivos e servidores MCP remotos.

A arquitetura de vinculação de agentes suporta objetos de agente de diferentes SDKs por meio de pacotes de extensão específicos de cada provedor. O Microsoft Agent Framework é o único agente SDK suportado na prévia atual. Para usá-lo, instale o azurefunctions-agents-extensions-agent-framework pacote.

Quando usar vinculações de agentes

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

• Avalie uma requisição HTTP. Valide um pedido 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 sua função escreva o resultado.
• Adicione raciocínio a um fluxo de trabalho duradouro. Chame um agente em um orquestrador do Durable Functions por meio da API context.call_agent(), segura para replay, e depois use o resultado em etapas posteriores da orquestração.

Vinculações de agentes são adequadas quando o código determinístico da função deve permanecer como coordenador. O agente executa uma tarefa de raciocínio delimitado e retorna o controle ao manipulador ou à orquestração.

Por que usar vinculações de agentes?

Muitos fluxos de trabalho de produção combinam etapas que devem ser determinísticas com etapas que se beneficiam do raciocínio do modelo. As vinculações de agentes oferecem os seguintes benefícios para esses fluxos de trabalho híbridos:

• Adicione comportamento agente às funções existentes. Use raciocínio de agente de HTTP-, timer-, queue-, Event Grid-, Barramento de Serviço- e outras funções disparadas.
• Controle a invocação do agente com segurança no código. Decida quando invocar o agente, inspecione sua resposta e determine a saída da função. A extensão fecha os recursos pertencentes à invocação após sucesso, fracasso ou cancelamento.
• Reduza o código de configuração do agente. Receba um Agent configurado como parâmetro de um manipulador tipado, em vez de construí-lo e conectá-lo a cada invocação.
• Separe as instruções da configuração em tempo de execução. Armazene instruções em linguagem natural em um .agent.md arquivo e configure clientes e ferramentas específicas de cada fornecedor explicitamente em Python.
• Use as capacidades de agentes compartilhados. A extensão descobre habilidades de agentes baseados em arquivos e servidores MCP baseados em HTTP a partir da raiz da aplicação e os disponibiliza para cada vinculação de agentes.
• Chame agentes de orquestrações duradouras. A extensão executa o trabalho do agente em uma atividade oculta para que a reprodução da orquestração permaneça determinística.
• Depure localmente com ferramentas familiares. Execute e depure o app localmente como qualquer outro app de funções em Python. Você pode definir pontos de interrupção e percorrer tanto a lógica da função determinística quanto o código que invoca o agente.

Como funciona uma vinculação de agente

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

Para cada vinculação de agente, a extensão realiza as seguintes operações:

1. Localiza o arquivo solicitado .agent.md na raiz do aplicativo de funções ou em seu diretório agents/.
2. Carrega o arquivo completo como instruções UTF-8 brutas.
3. Combina as instruções com a fábrica de clientes já configurada, as ferramentas de provedor configuradas explicitamente, as habilidades do agente descobertas e os servidores MCP descobertos.
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 provedores e definições de binding compiladas. Ele não armazena em cache nem reutiliza recursos de invocação ao vivo entre as invocações de funções.

Defina uma ligação de agente

O exemplo a seguir utiliza o provedor atualmente suportado do Microsoft Agent Framework para adicionar um Agent a uma função acionada por HTTP. A função constrói a tarefa em código, invoca o agente e retorna 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 decoradores markdown_agent e use um arg_name exclusivo e um parâmetro de manipulador para cada associação de agente. O agent_name valor identifica o arquivo de instruções. Neste exemplo, order-fulfillment deve corresponder exatamente a um destes locais:

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

Se ambos os arquivos existirem, a definição é ambígua e a inicialização do app falha. Nomes de agentes não podem conter caminhos absolutos, separadores de caminho ou componentes de percurso. Arquivos que ficam localizados fora da raiz da aplicação não são permitidos.

Configure o cliente agente e as ferramentas

Configure um argumento client_factory zero ao construir AgentFunctionApp. O alocador retorna um cliente novo compatível com o pacote do provedor. Você também pode passar objetos da ferramenta Microsoft Agent Framework ou chamadas em Python pelo tools parâmetro no nível do app. Uma associação poderá substituir o alocador cliente no nível do aplicativo e as ferramentas quando exigir um comportamento diferente.

Por exemplo, a seguinte função ativada por HTTP usa uma ligação de agente 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 essas considerações em mente ao configurar o cliente agente e as ferramentas:

• A extensão do agente base é neutra em relação ao provedor. Um pacote de provedor integra um SDK de agente específico e define os tipos de cliente e agente suportados.
• O pacote de provedores do Microsoft Agent Framework atualmente suportado não seleciona nem configura um provedor de modelo para sua aplicação. O alocador cliente determina qual cliente de chat do Microsoft Agent Framework e modelo o agente usa.
• A extensão envia o arquivo inteiro .agent.md ao provedor configurado na forma de instruções para o agente. Ele não analisa configurações de modelo, ferramentas, front matter YAML ou outras configurações de runtime a partir do arquivo.

Habilidades de agentes compartilhados e servidores MCP

A extensão descobre automaticamente as capacidades do agente compartilhado a partir da raiz da aplicação:

Capacidade	Localidade	Behavior
Habilidades do agente	skills/<skill-name>/SKILL.md ou Skills/<skill-name>/SKILL.md	O pacote provedor carrega e valida a habilidade do agente baseado em arquivos.
Servidores MCP remotos	mcp.json	A extensão configura servidores HTTP compatíveis ou com transmissão via HTTP e listas opcionais de ferramentas permitidas.
Ferramentas de provedores	Configuração de aplicação ou ligação	Objetos de ferramenta do Microsoft Agent Framework ou callables Python são fornecidos explicitamente em vez de serem descobertos.

Tenha essas considerações em mente ao usar capacidades de agente compartilhado:

• Cada associação de agente no aplicativo de funções recebe todas as habilidades de agente descobertas e os servidores MCP.
• Habilidades de agentes baseados em arquivos são capacidades que um agente pode carregar. Elas não são habilidades hospedadas no Azure Functions, que usam um modelo de execução separado.
• A prévia atual da extensão do agente não suporta selecionar um subconjunto de capacidades para um aplicativo ou vinculação individual.
• As habilidades do agente e as ferramentas MCP podem realizar operações privilegiadas. Coloque apenas capacidades que todo agente no app possa usar, e use aplicativos de funções separados quando os agentes exigirem 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 que a extensão se conecte ao servidor. Não armazene segredos diretamente em um arquivo controlado mcp.json por código-fonte.

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

Usar associações de agente com o Durable Functions

As vinculações de agentes dão suporte a fluxos de trabalho híbridos e de longa duração por meio de uma integração opcional ao Durable Functions. Um orquestrador de gerador síncrono chama context.call_agent() e produz 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() agenda uma atividade oculta que resolve a definição do agente e executa todas as operações de modelo, sistema de arquivos, credenciais, ferramentas e rede. O orquestrador cria apenas uma requisição de schema-v1 determinística, serializável em JSON. Como resultado, a reprodução de orquestração não repete operações de agente não determinísticos.

Chamadas duráveis de agente utilizam o provedor e os recursos compartilhados configurados por AgentFunctionApp. Entradas e saídas devem ser serializáveis em JSON.

O suporte ao Durable Functions é opcional. Aplicações que não usam esse recurso não precisam instalar nem importar o Durable Functions. Para usar orchestration_trigger e context.call_agent(), instale o pacote de provedor suportado com seu extra de dependência Durável.

arquivos do projeto

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

Arquivo ou pasta	Purpose
function_app.py	Define AgentFunctionApp, gatilhos do Functions padrão, associações de agente, alocadores cliente e ferramentas de provedor configuradas explicitamente.
host.json	Configura o host do Azure Functions.
requirements.txt	Inclui um pacote do provedor de agente compatível e qualquer pacote cliente específico do SDK. Para a prévia atual, use azurefunctions-agents-extensions-agent-framework. Extras opcionais permitem suporte ao Durable Functions e MCP.
*.agent.md ou agents/*.agent.md	Contém instruções brutas em UTF-8 para um agente. Cada nome referenciado deve corresponder a um único arquivo.
skills/ ou Skills/	(Opcional) Contém habilidades de agente baseadas em arquivos compartilhadas por todas as vinculações de agentes.
mcp.json	(Opcional) Define servidores MCP remotos baseados em HTTP compartilhados por todas as vinculações de agentes.

Para a estrutura padrão Python do projeto, veja o guia do desenvolvedor Azure Functions Python.

Validação e diagnóstico

A extensão valida as definições de agentes antes ou durante a compilação da associação, para que problemas de configuração gerem erros acionáveis. Validação abrange:

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

Quando disponível, a extensão preserva o nome da Azure Function, o ID de invocação e o ID de instância do Durable no limite do provedor para dar suporte à correlação e ao diagnóstico.

Artigos relacionados

• Opções de integração de IA para Azure Functions
• Use um agente do Microsoft Agent Framework em uma função Python
• Usar uma associação de agente do Microsoft Agent Framework em uma orquestração do Durable
• Visão geral do Microsoft Agent Framework