Binding di agenti per Python in Funzioni di Azure

I legami agenti per le app di funzioni Python permettono di aggiungere comportamenti agentici alle funzioni esistenti. Quando la funzione viene eseguita, l'estensione costruisce un Agent a partire da istruzioni Markdown e lo inietta nel tuo handler come parametro tipizzato. Il tuo codice decide quando e come invocare l'agente insieme alla logica applicativa deterministica.

Importante

Le associazioni degli agenti per le app per funzioni Python sono attualmente in versione di anteprima. Funzionalità, nomi di pacchetti e configurazioni possono cambiare prima della disponibilità generale.

Per confrontare i bindings degli agenti con altre funzionalità legate all'IA, come le competenze ospitate da Funzioni di Azure e gli strumenti Model Context Protocol (MCP), consulta le opzioni di integrazione AI per Funzioni di Azure.

Un agent binding è un input binding di proprietà dell'estensione che fornisce un oggetto completamente costruito Agent a una funzione Python. L'estensione legge le istruzioni dell'agente come testo grezzo da un .agent.md file. Il codice dell'applicazione mantiene la configurazione degli strumenti specifici per client e provider, mentre il progetto di app per le funzioni può individuare le competenze degli agenti basati su file e server MCP remoti.

L'architettura di associazione degli agenti supporta gli oggetti agent di SDK diversi tramite pacchetti di estensione specifici del provider. Microsoft Agent Framework è l'unico agente SDK supportato nell'anteprima attuale. Per usarlo, installa il azurefunctions-agents-extensions-agent-framework pacchetto.

Quando utilizzare i legami agenti

Usa le leghe di agente quando una funzione Azure necessita di ragionamento agentico per parte di un workflow, ma la tua applicazione deve mantenere il controllo sul suo trigger, validazione, ramificazione, gestione degli errori e risposta. Gli scenari comuni includono:

• Valuta una richiesta HTTP. Valida un ordine con codice deterministico, chiedi a un agente di valutare il rischio di esecuzione e usa il risultato per costruire la risposta HTTP.
• Arricchisci o classifica gli eventi. Ricevi un messaggio di coda, un evento Event Grid o un altro payload trigger e usa un agente per classificare, riassumere o arricchire i dati prima che la tua funzione scriva il risultato.
• Aggiungi ragionamento a un flusso di lavoro duraturo. Chiama un agente da un orchestratore Durable Functions tramite l'API replay-safecontext.call_agent(), poi usa il risultato nei passaggi successivi di orchestrazione.

I legami agenti sono adatti quando il codice deterministico della funzione dovrebbe rimanere il coordinatore. L'agente esegue un compito di ragionamento limitato e restituisce il controllo al gestore o all'orchestrazione.

Perché usare i legami agenti?

Molti flussi di lavoro di produzione combinano passaggi che devono essere deterministici con passaggi che traggono beneficio dal ragionamento del modello. Le associazioni degli agenti offrono i seguenti vantaggi per questi flussi di lavoro ibridi:

• Aggiungi il comportamento agentico alle funzioni esistenti. Usare il ragionamento degli agenti da funzioni HTTP-, timer-, coda-, Griglia di eventi-, Bus di servizio- e altre funzioni attivate.
• Controlla in modo sicuro l'invocazione dell'agente nel codice. Decidi quando invocare l'agente, ispeziona la sua risposta e determina l'output della funzione. L'estensione chiude le risorse associate alla chiamata dopo il completamento, un errore o l'annullamento.
• Riduci il codice di configurazione dell'agente. Ricevi un parametro configurato Agent come handler tipizzato invece di costruirlo e cablarlo per ogni invocazione.
• Separare le istruzioni dalla configurazione in tempo reale. Memorizza istruzioni in linguaggio naturale in un .agent.md file e configura client e strumenti specifici per provider esplicitamente in Python.
• Usa le funzionalità condivise dell'agente. L'estensione rileva le skill degli agenti basate su file e i server MCP basati su HTTP nella directory radice dell'applicazione e le rende disponibili per ogni associazione di agente.
• Chiamare gli agenti da orchestrazioni durevoli. L'estensione esegue il lavoro dell'agente in un'attività nascosta in modo che la riproduzione dell'orchestrazione rimanga deterministica.
• Debug localmente con strumenti familiari. Esegui e fai il debug dell'app localmente come qualsiasi altra app di funzioni Python. Puoi impostare breakpoint e passare attraverso la logica delle funzioni deterministiche e il codice che invoca l'agente.

Come funziona un'associazione di agente

AgentFunctionApp estende azure.functions.FunctionApp, quindi ha le stesse capacità di FunctionApp. Il markdown_agent decoratore aggiunge un input di agente a una funzione.

Per ogni lego agente, l'estensione esegue le seguenti operazioni:

1. Individua il file richiesto .agent.md nella radice dell'app per le funzioni o nella relativa cartella agents/.
2. Carica il file completo come istruzioni grezze UTF-8.
3. Combina le istruzioni con la factory client configurata, gli strumenti del provider configurati esplicitamente, le competenze dell'agente individuate e i server MCP individuati.
4. Crea una nuova istanza di Agent e apre le risorse associate all'invocazione.
5. Inietta il Agent nel parametro del gestore.
6. Chiude le risorse associate all'invocazione al termine dell'esecuzione.

L'estensione può mettere in cache la scoperta del provider e compilare le definizioni di binding. Non memorizza né riutilizza risorse di invocazione live tra le invocazioni di funzione.

Definire un'associazione di agente

Il seguente esempio utilizza il provider Microsoft Agent Framework attualmente supportato per aggiungere un Agent a una funzione attivata da HTTP. La funzione costruisce il compito in codice, invoca l'agente e restituisce la risposta dell'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)

Il arg_name valore deve corrispondere al parametro del handler iniettato. Per inserire più agenti nella stessa funzione, impilare i decoratori markdown_agent e usare un arg_name univoco e un parametro di gestione univoco per ogni associazione di agente. Il agent_name valore identifica il file di istruzioni. In questo esempio, order-fulfillment deve corrispondere esattamente a una di queste posizioni:

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

Se entrambi i file esistono, la definizione è ambigua e l'avvio dell'app fallisce. I nomi degli agenti non possono contenere percorsi assoluti, separatori di percorso o componenti di attraversamento. I file che si risolvono fuori dalla radice dell'applicazione non sono ammessi.

Configura il client agente e gli strumenti

Configura un client_factory senza argomenti quando costruisci AgentFunctionApp. La fabbrica restituisce un nuovo cliente supportato dal pacchetto fornitore. Puoi anche passare oggetti dello strumento Microsoft Agent Framework o chiamabili Python attraverso il tools parametro a livello di app. Un binding può sostituire il client factory e gli strumenti a livello di app se richiede un comportamento diverso.

Ad esempio, la seguente funzione attivata da HTTP utilizza un agente binding che rende lookup_inventory disponibile come strumento solo a 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)

Tieni a mente queste considerazioni quando configuri il client agente e gli strumenti:

• L'estensione di base dell'agente è indipendente dal provider. Un pacchetto provider integra uno specifico SDK di agente e definisce i tipi di client e agente supportati.
• Il pacchetto provider Microsoft Agent Framework attualmente supportato non seleziona né configura un provider di modelli per la tua applicazione. La factory del client determina quale client di chat e quale modello supportati da Microsoft Agent Framework usa l'agente.
• L'estensione passa l'intero file .agent.md al fornitore configurato come istruzioni per l'agente. Non interpreta le impostazioni del modello, gli strumenti, il front matter YAML o altre configurazioni di runtime dal file.

Competenze di agente condiviso e server MCP

L'estensione scopre automaticamente le capacità degli agenti condivisi dalla radice dell'applicazione:

Capability	Location	Behavior
Competenze dell'agente	skills/<skill-name>/SKILL.md oppure Skills/<skill-name>/SKILL.md	Il pacchetto del provider carica e convalida l'abilità dell'agente basata su file.
Server MCP remoti	mcp.json	L'estensione configura server HTTP supportati o server HTTP trasmissibili in streaming ed elenchi opzionali di strumenti consentiti.
Strumenti per i fornitori	Configurazione dell'applicazione o del binding	Gli oggetti dello strumento Microsoft Agent Framework o i chiamabili Python sono esplicitamente forniti invece che scoperti.

Tieni a mente queste considerazioni quando utilizzi le funzionalità di agente condiviso:

• Ogni associazione di agente nell'app per le funzioni riceve tutte le competenze degli agenti individuate e i server MCP individuati.
• Le funzionalità basate su file sono capacità che un agente può caricare. Non sono competenze ospitate da Funzioni di Azure, che utilizzano un modello di esecuzione separato.
• L'anteprima attuale dell'estensione per l'agente non supporta la selezione di un sottoinsieme di funzionalità per un'app o un singolo binding.
• Le competenze dell'agente e gli strumenti MCP possono eseguire operazioni privilegiate. Inserisci solo le funzionalità che ogni agente nell'app può usare, e usa app di funzione separate quando gli agenti richiedono limiti di capacità differenti.

La configurazione MCP può fare riferimento a variabili di ambiente per URL, header, scope di autenticazione e ID client. I riferimenti vengono risolti per ogni invocazione, prima che l'estensione si connetta al server. Non archiviare segreti direttamente in un file mcp.json sotto controllo del codice sorgente.

I server MCP a processo locale e quelli standard input/output (stdio) non sono supportati. Il supporto MCP è una dipendenza opzionale e le normali importazioni di pacchetti rimangono sicure quando non è installato.

Usare le associazioni di agenti con funzioni permanenti

I binding degli agenti supportano flussi di lavoro ibridi e di lunga durata tramite un'integrazione opzionale con Durable Functions. Un generatore sincrono d'orchestra chiama context.call_agent() e produce il compito risultante:

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() Programma un'attività nascosta che risolve la definizione dell'agente ed esegue tutte le operazioni di modello, file system, credenziali, strumenti e rete. L'orchestrator crea solo una richiesta schema-v1 deterministica, serializzabile in formato JSON. Di conseguenza, la riproduzione dell'orchestrazione non ripete le operazioni di agente non deterministiche.

Le chiamate di agente duratura utilizzano il provider e le capacità condivise configurate da AgentFunctionApp. Ingressi e uscite devono essere serializzabili in JSON.

Il supporto Durable Functions è opzionale. Le applicazioni che non lo usano non devono installare o importare Durable Functions. Per utilizzare orchestration_trigger e context.call_agent(), installare il pacchetto provider supportato con la dipendenza durevole aggiuntiva.

File del progetto

Un'applicazione abilitata da agente è un'app standard di funzione Python v2 con dipendenze di estensione di agente e uno o più file di istruzioni:

File o cartella	Purpose
function_app.py	Definisce AgentFunctionApp, trigger standard delle funzioni, legami agenti, fabbriche client e strumenti provider esplicitamente configurati.
host.json	Configura l'host di Funzioni di Azure.
requirements.txt	Include un pacchetto provider di agente supportato e qualsiasi pacchetto client specifico per SDK. Per l'anteprima attuale, usa azurefunctions-agents-extensions-agent-framework. I componenti aggiuntivi opzionali consentono il supporto per Durable Functions e MCP.
*.agent.md oppure agents/*.agent.md	Contiene istruzioni grezze UTF-8 per un agente. Ogni nome a cui si fa riferimento deve risolversi in un solo file.
skills/ oppure Skills/	(Opzionale) Contiene competenze dell'agente basate su file condivise da tutte le associazioni di agenti.
mcp.json	(Opzionale) Definisce server MCP remoti basati su HTTP condivisi da tutti i binding agente.

Per la struttura standard Python del progetto, consulta la guida per sviluppatori Funzioni di Azure Python.

Validazione e diagnostica

L'estensione valida le definizioni degli agenti prima o durante la compilazione dei binding, quindi i problemi di configurazione falliscono con errori azionabili. La validazione comprende:

• File mancanti o ambigui .agent.md .
• Signature dell’handler non valide, incluso un parametro iniettato mancante o non corrispondente.
• Opzioni o funzionalità del fornitore non supportate.
• Directory di competenze non valide e configurazione MCP malformata.
• Trasporti MCP non supportati e valori ambientali mancanti.
• Payload Durable non validi o valori non serializzabili in JSON.

Ove disponibile, l'estensione conserva il nome della funzione Azure, l'ID dell'invocazione e l'ID dell'istanza Durable a livello del limite del provider per supportare la correlazione e la diagnostica.

Articoli correlati

• Opzioni di integrazione AI per Funzioni di Azure
• Usa un agente Microsoft Agent Framework in una funzione Python
• Usa un binding di agente di Microsoft Agent Framework in un'orchestrazione Durable
• Panoramica di Microsoft Agent Framework