Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Il runtime per gli agenti serverless delle funzioni di Azure è un modello di programmazione markdown-first per creare agenti di IA come app delle funzioni di Azure. Invece di combinare hosting, trigger, client di modello, strumenti, archiviazione delle sessioni, identità e osservabilità, definisci gli agenti nei file .agent.md e li distribuisci come app di funzione.
Il runtime è progettato per agenti che reagiscono agli eventi, invocano strumenti e vengono eseguiti su un'infrastruttura serverless. Gli agenti possono iniziare da richieste HTTP, pianificazioni, code, messaggi, modifiche del database e altri eventi; usare server MCP remoti, server MCP ospitati negli spazi dei nomi dei connettori, competenze riutilizzabili ed esecuzione in modalità sandbox; ed eseguire con le stesse funzionalità di distribuzione, identità, monitoraggio e scalabilità usate da altre app Funzioni di Azure. Per la logica specifica dell'app, è possibile scrivere strumenti personalizzati nella stessa app per le funzioni.
Note
Il runtime per gli agenti serverless è in anteprima. Le funzionalità, i nomi di configurazione e i connettori supportati possono cambiare prima della disponibilità generale.
Perché creare agenti in Funzioni di Azure?
Gli agenti di produzione necessitano di più di una richiesta e di un modello. Hanno bisogno di modi affidabili per avviare il lavoro, chiamare sistemi esterni, rendere persistente la cronologia delle conversazioni, eseguire codice non attendibile in modo sicuro, eseguire l'autenticazione senza segreti, generare dati di telemetria e ridimensionare su richiesta.
Funzioni di Azure fornisce già un modello di calcolo basato su eventi per tali problematiche operative. Il runtime degli agenti serverless applica tale modello agli agenti:
- Gli agenti sono l'unità di lavoro. Un
.agent.mdfile definisce il trigger e le istruzioni per un agente. - Gli eventi attivano gli agenti. I trigger di funzione consentono agli agenti di essere eseguiti in base a una pianificazione, reagire a code ed eventi o esporre endpoint HTTP.
- Le funzionalità vengono configurate per prime, con codice quando necessario. Gli agenti possono usare server MCP remoti, server MCP ospitati nei namespace dei connettori, skill ed esecuzione di codice in modalità sandbox tramite configurazione. Usare strumenti personalizzati per la logica specifica dell'app.
- L'hosting è serverless. Flex Consumption supporta il ridimensionamento fino a zero, la fatturazione al secondo, l'identità gestita, l'integrazione con la rete virtuale e Application Insights.
- L'impianto idraulico operativo è costruito. Il runtime gestisce l'individuazione dell'agente, la registrazione dei trigger, l'assembly degli strumenti, la cronologia delle sessioni e gli endpoint predefiniti facoltativi.
Anatomia del progetto
Un'app serverless per agenti è un'app Funzioni di Azure in Python con file specifici per gli agenti insieme ai normali file di progetto di Functions.
| File o cartella | Obbligatorio | Purpose |
|---|---|---|
function_app.py |
Sì | Importa create_function_app() e restituisce l'app Funzioni di Azure configurata. |
*.agent.md |
Sì | Definisce gli agenti. Il front matter YAML configura l'agente e il corpo Markdown costituisce le istruzioni. |
agents.config.yaml |
No | Definisce le impostazioni predefinite del runtime a livello di app, ad esempio le impostazioni del modello, del timeout e della sandbox. |
mcp.json |
Quando si usano i server MCP o gli strumenti del connettore | Definisce i server MCP HTTP remoti che gli agenti possono usare come strumenti, inclusi gli strumenti del connettore per attività come l'invio di posta elettronica o l'uso di Teams. |
tools/ |
No | Contiene strumenti di Python personalizzati per le funzionalità non coperte da server MCP, connessioni, competenze o esecuzione in modalità sandbox. |
skills/ |
No | Contiene asset SKILL.md di prompt riutilizzabili che gli agenti possono caricare secondo necessità. |
host.json |
Sì | Configura l'host di Funzioni di Azure. |
requirements.txt |
Sì | Comprende il pacchetto di runtime degli agenti serverless e tutte le dipendenze Python specifiche dell'applicazione. |
infra/ |
No | Contiene file di infrastruttura come codice usati da strumenti di distribuzione quali azd. |
Un progetto minimo ha function_app.py, host.json, requirements.txte almeno un .agent.md file. Aggiungi agents.config.yaml quando l'app necessita di impostazioni predefinite per il runtime a livello di app.
File dell'agente
Un file agente utilizza un'intestazione YAML seguita da istruzioni in markdown. Questo esempio definisce un agente attivato dal timer:
---
name: Daily Tech News Email
description: Fetches top tech news and emails a summary daily.
trigger:
type: timer_trigger
args:
schedule: "0 0 15 * * *"
---
You are a news assistant. When triggered, do the following:
1. Gather today's top technology news from reputable sources.
1. Summarize the stories in a concise HTML email body.
1. Email the summary to $TO_EMAIL with the subject "Daily Tech News Summary".
La parte introduttiva specifica come viene invocato l'agente. Il corpo markdown è il blocco di istruzioni che il runtime passa al modello durante l'esecuzione. La sostituzione delle variabili di ambiente consente alle istruzioni e ai valori di configurazione di fare riferimento alle impostazioni dell'app, $TO_EMAILad esempio .
Ogni .agent.md file definisce un agente. Il nome file viene usato per derivare il nome della funzione Azure e il segmento di route per gli endpoint predefiniti. Il campo name è un nome visualizzato utilizzato nei log, nelle etichette e nella documentazione.
Usare questi campi front-matter per configurare un agente:
| Campo | Obbligatorio | Description |
|---|---|---|
name |
Sì | Mostra il nome dell'agente. |
description |
Sì | Breve descrizione delle operazioni che l'agente esegue e quando deve essere usato. |
trigger |
Sì, a meno che builtin_endpoints non sia attivato |
Definisce la modalità di chiamata dell'agente. È consentito un solo trigger per ogni file dell'agente. |
model |
No | Sovrascrive il modello predefinito configurato in agents.config.yaml o nelle impostazioni dell'app. |
timeout |
No | Esegue l'override del timeout di esecuzione predefinito, espresso in secondi. |
builtin_endpoints |
No | Abilita gli endpoint di debug e composizione predefiniti. Usare true per abilitare tutti gli endpoint predefiniti o configurare debug_chat_uisingolarmente , chat_apie mcp . |
logger |
No | Determina se la registrazione in fase di esecuzione è abilitata per l'agente. Di default è true. |
mcp |
No | Controlla l'accesso ai server MCP individuati da mcp.json. Usare false per disabilitare i server MCP per questo agente o per exclude rimuovere server specifici. |
skills |
No | Controlla l'accesso alle competenze individuate. Usare false per disabilitare le competenze per questo agente o per exclude rimuovere competenze specifiche. |
tools |
No | Controlla l'accesso agli strumenti di Python personalizzati individuati. Usare false per disabilitare gli strumenti personalizzati per questo agente o per exclude rimuovere strumenti specifici. |
system_tools |
No | Consente a un agente di rifiutare esplicitamente gli strumenti di sistema configurati, ad esempio l'esecuzione in modalità sandbox. |
input_schema |
No | Schema JSON usato per convalidare i corpi delle richieste HTTP per gli agenti attivati tramite HTTP. |
response_schema |
No | Schema JSON usato per convalidare le risposte strutturate restituite dagli agenti attivati da HTTP. |
response_example |
No | Forma di risposta di esempio usata per guidare risposte strutturate da agenti attivati tramite HTTP. |
metadata |
No | Metadati personalizzati per la propria organizzazione o strumenti. |
substitute_variables |
No | Controlla se la sostituzione delle variabili di ambiente viene applicata alla materia iniziale e alle istruzioni. Di default è true. |
Impostazioni predefinite del runtime in agents.config.yaml
Usare agents.config.yaml per le impostazioni predefinite di runtime a livello di app che ogni agente può ereditare. Il runtime può caricare un'app senza questo file. Aggiungerlo quando sono necessarie impostazioni condivise, ad esempio una distribuzione del modello, un timeout o un endpoint di esecuzione sandbox.
Questo file è un input a livello di app. Il runtime individua anche i server MCP da mcp.json, competenze di skills/ e strumenti di Python personalizzati da tools/. Queste funzionalità sono abilitate per impostazione predefinita negli agenti. Il front matter dell'agente può eseguire l'override delle impostazioni predefinite di runtime o filtrare i server, le competenze e gli strumenti MCP ereditati.
system_tools:
dynamic_sessions_code_interpreter:
endpoint: $ACA_SESSION_POOL_ENDPOINT
model: $FOUNDRY_MODEL
timeout: 900
I singoli agenti possono eseguire l'override delle impostazioni di runtime supportate nel proprio front-matter.
Usare questi campi di primo livello in agents.config.yaml:
| Campo | Obbligatorio | Description |
|---|---|---|
model |
No | Modello predefinito o distribuzione del modello usati dagli agenti che non impostano model nel proprio front matter. |
timeout |
No | Timeout di esecuzione predefinito, espresso in secondi. Il valore predefinito del runtime è 900 secondi. |
system_tools.dynamic_sessions_code_interpreter.endpoint |
Quando si usa l'esecuzione in modalità sandbox | Endpoint di gestione per il pool di sessioni dinamiche App contenitore di Azure usato dagli strumenti sandbox. |
system_tools.dynamic_sessions_code_interpreter.client_id |
No | ID client dell'identità gestita utilizzata per chiamare il pool di sessioni. |
tools.exclude |
No | Elenco di esclusione globale per gli strumenti di Python personalizzati individuati dalla cartella tools/. |
Il runtime risolve prima i valori nel front matter dell'agente, poi agents.config.yaml, quindi le impostazioni dell'app e i valori predefiniti del runtime. I valori stringa in agents.config.yaml possono fare riferimento alle impostazioni dell'app, ad esempio $AZURE_OPENAI_DEPLOYMENT o $ACA_SESSION_POOL_ENDPOINT.
Mantenere le impostazioni predefinite per il modello, il timeout e lo strumento di sistema in agents.config.yaml. Mantieni le definizioni dei server MCP remoti, inclusi gli endpoint dei server MCP dei namespace dei connettori, in mcp.json.
Sostituzione di variabili
Il runtime può sostituire le impostazioni dell'app e le variabili di ambiente in valori stringa nel front matter dell'agente, nei corpi di istruzione dell'agente, agents.config.yamle mcp.json. Usare $SETTING_NAME o %SETTING_NAME%. I nomi delle variabili devono iniziare con una lettera o un carattere di sottolineatura e possono contenere lettere, numeri e caratteri di sottolineatura.
model: $FOUNDRY_MODEL
system_tools:
dynamic_sessions_code_interpreter:
endpoint: %ACA_SESSION_POOL_ENDPOINT%
Email the summary to $TO_EMAIL.
{
"servers": {
"office365": {
"type": "http",
"url": "$O365_MCP_SERVER_URL"
}
}
}
La sostituzione si applica ai valori stringa, incluse le stringhe annidate in oggetti o elenchi. Non si applica alle chiavi degli oggetti. I blocchi di codice delimitati nei corpi delle istruzioni dell'agente non vengono sostituiti, quindi gli esempi possono includere testo letterale $VALUE o %VALUE%.
Usare $$SETTING_NAME o %%SETTING_NAME%% quando è necessario un segnaposto letterale nel contenuto sostituito. Le variabili di ambiente mancanti vengono lasciate invariate, i valori vuoti vengono risolti in stringhe vuote e la sostituzione è un singolo passaggio. La ${SETTING_NAME} sintassi non è supportata.
Per disabilitare la sostituzione per la parte introduttiva e le istruzioni di un agente, specificare substitute_variables: false nel file dell'agente. Questa impostazione non disabilita la sostituzione in agents.config.yaml o mcp.json.
Modalità di avvio di un'app da parte del runtime
Quando l'host Funzioni di Azure importa l'app, create_function_app() compila un FunctionApp configurato dai file di progetto:
- Risolvere la radice dell'app.
- Carica
agents.config.yaml. - Carica ogni file
.agent.md. - Scopri i server MCP, le competenze e gli strumenti personalizzati.
- Comporre le impostazioni predefinite a livello di app e la configurazione per agente.
- Verificare la configurazione risolta dell'agente.
- Definire le capacità finali dello strumento e delle competenze per ogni agente.
- Registra i trigger di Funzioni di Azure e gli endpoint predefiniti opzionali.
Dopo l'avvio, l'host Funzioni di Azure indicizza i trigger registrati esattamente come avviene per altre app per le funzioni. Quando viene attivato un trigger, il runtime compila l'agente con le istruzioni, l'impostazione del modello, gli strumenti, le competenze e la cronologia delle sessioni, quindi la esegue tramite Microsoft Agent Framework.
Attivare gli agenti tramite eventi
Gli agenti serverless sono utili quando l'evento che avvia l'elaborazione è importante quanto la chiamata al modello. Il runtime supporta un trigger per ogni file dell'agente.
Una definizione di trigger ha un type oggetto e un args oggetto .
type Identifica l'associazione di trigger e args contiene le impostazioni specifiche del trigger che configurano l'evento che avvia l'agente.
trigger:
type: timer_trigger
args:
schedule: "0 0 15 * * *"
I tipi di trigger comuni includono http_trigger, timer_triggerqueue_trigger, blob_trigger, , event_grid_triggere service_bus_trigger. Per i trigger integrati di Funzioni di Azure, usa la documentazione sui trigger e sui binding di Python v2 e il riferimento del binding per il trigger per individuare le impostazioni da includere in args. Ad esempio, un trigger timer usa un'impostazione schedule , un trigger della coda usa impostazioni come queue_name e connectione e un trigger BLOB usa impostazioni come path e connection. Il runtime fornisce il punto di ingresso della funzione generato, quindi il file dell'agente necessita solo delle impostazioni del trigger che identificano l'origine evento.
I modelli di trigger comuni includono:
| Pattern | Esempio |
|---|---|
| Agente HTTP | Ricevere una richiesta, chiamare gli strumenti e restituire una risposta strutturata. |
| Agente pianificato | Eseguire un flusso di lavoro giornaliero per report, riepilogo, pulizia o riconciliazione. |
| Agente di coda o agente di messaggistica | Elaborare gli elementi di lavoro che richiedono il ragionamento del modello o le chiamate agli strumenti. |
| Agente di eventi di archiviazione o database | Reagire a file, record o eventi modificati. |
| Agente attivato da un connettore | Reagire agli eventi provenienti da servizi connessi, ad esempio messaggi di Teams, Outlook posta o eventi di calendario se supportati dal connettore. |
Poiché ogni agente è registrato come funzione Azure, l'app può usare funzioni che ospitano funzionalità come regole di scalabilità, identità gestita, rete e monitoraggio.
Assegnare agli agenti strumenti
Gli agenti diventano utili quando possono agire. Iniziare con le funzionalità configurate: server MCP remoti, server MCP ospitati in spazi dei nomi dei connettori, competenze ed esecuzione in modalità sandbox. Usare strumenti di Python personalizzati per funzionalità specifiche dell'app che non soddisfano tali opzioni.
Server MCP remoti
Quando un'app usa server MCP remoti, aggiungere mcp.json alla radice del progetto dell'app per le funzioni. Il runtime individua in questo file i server HTTP remoti o i server MCP HTTP con streaming e rende i loro strumenti disponibili agli agenti, in base agli eventuali filtri configurati per ciascun agente.
Usa questi campi in ogni elemento servers:
| Campo | Obbligatorio | Description |
|---|---|---|
type |
Sì | Usare http o streamable-http. I server MCP locali stdio non sono supportati dal runtime. |
url |
Sì | Endpoint del server MCP remoto. La sostituzione delle variabili di ambiente è supportata. |
headers |
No | Intestazioni statiche per un server MCP remoto generico. Non archiviare segreti statici in mcp.json. |
auth.scope |
Quando si usa l'autenticazione Microsoft Entra | Ambito del token di Microsoft Entra usato per autenticare le chiamate al server MCP. |
auth.client_id |
No | ID client dell'identità gestita da usare per l'autenticazione con questo server MCP. Omettere questo campo per usare l'identità gestita assegnata dal sistema dell'app per le funzioni in Azure. |
Usare i server MCP remoti quando gli agenti devono chiamare gli strumenti ospitati da un altro servizio o comporre agenti e strumenti oltre i limiti delle app.
Connettori di Azure
I connettori consentono agli agenti di lavorare con servizi esterni senza codice client DELL'API personalizzato. Ad esempio, un connettore Microsoft 365 Outlook può inviare messaggi di posta elettronica, un connettore di Teams può lavorare con i messaggi e altri connettori possono chiamare azioni nei sistemi come Salesforce, SAP o SQL. Un namespace del connettore ospita le connessioni, i trigger e i server MCP che rendono tali integrazioni disponibili nella tua app.
Per usare le funzionalità del connettore in un'app per agenti serverless, crea prima un Connector Namespace, crea una connessione al servizio e autorizza la connessione. Scegliere quindi il modo in cui l'agente usa la connessione:
- Il connettore attiva gli agenti quando si verifica qualcosa in un servizio connesso, ad esempio un nuovo messaggio di posta elettronica, un messaggio di Teams o un evento del calendario. Per usarne uno, crea un trigger nel namespace del connettore che utilizza la connessione autorizzata, quindi configura l'agente con il nome del trigger e gli argomenti definiti nella definizione di quel trigger del connettore.
-
Gli strumenti MCP del connettore consentono agli agenti di chiamare azioni del servizio, ad esempio l'invio di messaggi di posta elettronica o l'aggiornamento di un record. Per usarli, crea un server MCP nel namespace Connector che utilizza la connessione autorizzata, quindi aggiungi l'endpoint del server MCP a
mcp.json.
Per gli strumenti MCP del connettore, una voce del server MCP in mcp.json archivia le impostazioni di autenticazione dell'endpoint e dell'identità gestita. Usa l'ambito di Azure API Hub quando l'agente utilizza un server MCP gestito da un namespace del connettore. Non archiviare i segreti degli utenti in mcp.json.
{
"servers": {
"office365-outlook": {
"type": "http",
"url": "$O365_MCP_SERVER_URL",
"auth": {
"scope": "https://apihub.azure.com/.default",
"client_id": "$O365_MCP_CLIENT_ID"
}
}
}
}
L'impostazione auth.client_id seleziona l'identità gestita autenticata con il server MCP. Impostarlo sull'ID client di un'identità gestita assegnata dall'utente. Ometterlo per usare l'identità gestita assegnata dal sistema dell'app per le funzioni in Azure. L'identità selezionata o l'identità dello sviluppatore locale quando si esegue in locale, deve essere autorizzata a chiamare il server MCP.
Competenze
Le skill sono risorse di prompt riutilizzabili memorizzate in skills/. Consentono di mantenere le istruzioni dell'agente di base di piccole dimensioni, rendendo disponibili istruzioni specifiche del dominio quando necessario. Il runtime usa il formato Competenze dell'agente.
Il runtime analizza skills/ nella radice del progetto dell'app per le funzioni e individua ricorsivamente le cartelle che contengono SKILL.md:
skills/
incident-response/
SKILL.md
triage-checklist.md
escalation-policy.md
Il SKILL.md file contiene la materia iniziale YAML seguita dalle istruzioni markdown:
---
name: incident-response
description: Triage production incidents, summarize impact, and recommend next steps. Use when the task mentions incidents, outages, alerts, or severity levels.
---
Follow the incident response checklist in [triage-checklist.md](triage-checklist.md).
Usa queste regole per la creazione di skill:
- Ogni cartella skill deve contenere un file
SKILL.md. - I
namecampi edescriptionsono obbligatori. - I nomi delle competenze devono usare lettere minuscole, numeri e trattini singoli. Non usare spazi, caratteri di sottolineatura, lettere maiuscole, trattini iniziali, trattini finali o trattini ripetuti.
- I nomi delle competenze devono essere univoci nell'app.
- La descrizione deve spiegare sia cosa fa la competenza sia quando l'agente deve usarla. Il runtime carica prima i nomi e le descrizioni delle competenze in modo che l'agente possa decidere quando caricare la competenza completa.
- Le skill possono includere più file markdown nella stessa cartella dello skill. Fare riferimento ai file markdown di supporto da
SKILL.mdutilizzando collegamenti relativi. - Sono supportati solo i file Markdown come contenuto delle competenze nel runtime degli agenti serverless. Se una competenza richiede un comportamento eseguibile, impacchetta quel codice come strumento Python personalizzato e fai riferimento allo strumento per nome nelle istruzioni della competenza.
Gli agenti ereditano tutte le competenze individuate per impostazione predefinita. Disabilitare o escludere le competenze in un file dell'agente quando un agente specifico non deve usarle:
skills: false
skills:
exclude:
- incident-response
Esecuzione in modalità sandbox
Per l'esecuzione del codice o l'automazione del browser, il runtime può usare App contenitore di Azure sessioni dinamiche. Le sessioni dinamiche forniscono ambienti isolati dai pool di sessioni. Il runtime usa sessioni di interprete del codice per fornire uno execute_python strumento agli agenti.
Configurare l'esecuzione in modalità sandbox in agents.config.yaml:
system_tools:
dynamic_sessions_code_interpreter:
endpoint: $ACA_SESSION_POOL_ENDPOINT
Usa questi requisiti della sandbox:
- Il pool di sessioni deve essere un pool di sessioni dell'interprete del codice Python, ad esempio un pool creato con
--container-type PythonLTS. - Il
endpointvalore è l'endpoint di gestione del pool di sessioni. - In Azure l'identità gestita usata dall'app per le funzioni deve avere le assegnazioni di ruolo necessarie per eseguire il codice nel pool di sessioni. Le sessioni dell'interprete di codice di App contenitore di Azure richiedono i ruoli
Azure ContainerApps Session ExecutoreContributornel pool di sessioni. - Durante l'esecuzione in locale, l'identità dello sviluppatore deve avere lo stesso accesso necessario al pool di sessioni.
- Per usare un'identità gestita assegnata dall'utente per l'esecuzione in modalità sandbox, impostare
system_tools.dynamic_sessions_code_interpreter.client_idsull'ID client dell'identità con le assegnazioni di ruolo necessarie. Se questa impostazione non è impostata, il runtime usaAZURE_CLIENT_ID, quindi la catena di credenziali predefinita.
Lo strumento sandbox esegue Python in una sessione isolata. Le variabili, le importazioni e i file possono essere mantenuti tra le chiamate degli strumenti nella stessa sessione dell'agente. Quando non è disponibile alcun ID sessione agente, il runtime usa una nuova sessione sandbox in modo che le esecuzioni non correlate non condividono lo stato.
Gli agenti ereditano l'esecuzione in modalità sandbox quando è configurata a livello globale. Disabilitarla per un agente specifico quando l'agente non deve eseguire il codice:
system_tools:
dynamic_sessions_code_interpreter: false
Strumenti di Python personalizzati
Usa strumenti Python personalizzati per funzionalità specifiche per l'app che non si adattano ai server MCP, ai server MCP ospitati nei namespace dei connettori, alle skill o all'esecuzione in sandbox. Gli strumenti personalizzati consentono di usare pacchetti Funzioni di Azure e Python dalla stessa app per le funzioni.
Aggiungere i file degli strumenti alla tools/ cartella nella radice del progetto dell'app per le funzioni:
tools/
submit_ticket.py
lookup_customer.py
Il runtime individua i .py file nei tools/ cui nomi di file non iniziano con _. Nell'anteprima corrente il runtime registra il primo strumento supportato da ogni file. Usare uno strumento per ogni file per mantenere prevedibile l'individuazione.
Puoi definire un tool decorando una funzione con @tool del pacchetto runtime:
from azure_functions_agents import tool
@tool(name="submit_ticket", description="Create a support ticket with a title and summary.")
async def submit_ticket(title: str, summary: str) -> str:
return f"Created ticket for {title}: {summary}"
Per descrizioni e convalida dei parametri più avanzati, usare un modello Pydantic come schema dello strumento:
from pydantic import BaseModel, Field
from azure_functions_agents import tool
class LookupCustomerParams(BaseModel):
customer_id: str = Field(description="Customer identifier from the CRM system.")
@tool(schema=LookupCustomerParams, description="Look up customer details by customer ID.")
async def lookup_customer(params: LookupCustomerParams) -> str:
return f"Customer details for {params.customer_id}"
È anche possibile definire una funzione di Python normale senza decorator. Il runtime esegue il wrapping della prima funzione normale che trova nel file, usa il nome della funzione come nome dello strumento e usa la docstring come descrizione dello strumento.
def summarize_order(order_id: str) -> str:
"""Summarize an order by order ID."""
return f"Summary for order {order_id}"
I nomi degli strumenti, le descrizioni, gli hint di tipo e le descrizioni dei campi Pydantic consentono al modello di decidere quando e come chiamare lo strumento. Aggiungi a requirements.txt eventuali dipendenze dei pacchetti utilizzate dagli strumenti personalizzati, come faresti per altro codice Python in un'app di Funzioni di Azure.
Gli agenti ereditano per impostazione predefinita gli strumenti personalizzati rilevati. Disabilitare o escludere strumenti personalizzati in un file dell'agente quando un agente specifico non deve usarli:
tools: false
tools:
exclude:
- submit_ticket
Configurare i provider di modelli
Il runtime usa Microsoft Agent Framework per chiamare i provider di modelli. Il supporto dell'anteprima include Azure OpenAI, Azure AI Foundry e OpenAI.
La selezione del provider si basa sulle impostazioni dell'app. È possibile aggiungere il provider con AZURE_FUNCTIONS_AGENTS_PROVIDERo consentire al runtime di dedurre il provider da impostazioni come AZURE_OPENAI_ENDPOINT, FOUNDRY_PROJECT_ENDPOINTo OPENAI_API_KEY.
La selezione del modello usa questa precedenza generale:
- Il modello richiesto dall'agente o dalla chiamata di runtime.
- Impostazioni specifiche del provider, ad esempio
AZURE_OPENAI_DEPLOYMENToFOUNDRY_MODEL. -
AZURE_FUNCTIONS_AGENTS_MODEL. - Provider predefinito.
Per le app di produzione, preferire l'identità gestita, se supportata. Quando un'app deve usare un'identità gestita assegnata dall'utente, impostare AZURE_CLIENT_ID in modo che i provider di modelli e l'esecuzione in modalità sandbox usino tale identità.
Configurare le identità gestite
Il runtime usa un'identità gestita per le risorse di Azure che supportano l'autenticazione di Microsoft Entra. Usa AZURE_CLIENT_ID come selettore di identità predefinito dell'app. I server MCP ospitati negli spazi dei nomi dei connettori e nella cronologia delle sessioni supportate da BLOB possono usare impostazioni di identità più specifiche.
Per i provider di modelli e l'esecuzione in modalità sandbox, impostare AZURE_CLIENT_ID quando si vuole che il runtime usi un'identità gestita assegnata dall'utente. Se AZURE_CLIENT_ID non è impostato, il runtime usa il comportamento standard delle credenziali Azure SDK, che può includere l'identità gestita assegnata dal sistema quando ne è disponibile una.
Usare queste impostazioni per selezionare le identità gestite:
| Funzionalità di runtime | Impostazione dell'identità | Alternativa |
|---|---|---|
| Azure fornitore di modelli OpenAI | AZURE_CLIENT_ID |
Comportamento predefinito delle credenziali |
| Fornitore di modelli di Azure AI Foundry | AZURE_CLIENT_ID |
Comportamento predefinito delle credenziali |
| Sandbox di sessioni dinamiche delle app contenitore di Azure | system_tools.dynamic_sessions_code_interpreter.client_id |
AZURE_CLIENT_ID, quindi comportamento predefinito delle credenziali |
| Server MCP ospitati negli spazi dei nomi dei connettori | Il valore auth.client_id nella voce del server in mcp.json |
AZURE_CLIENT_ID, quindi comportamento predefinito delle credenziali |
| Cronologia delle sessioni supportate da BLOB |
AzureWebJobsStorage__clientId quando si usa lo storage basato sull'identità |
AZURE_CLIENT_ID, quindi comportamento predefinito delle credenziali |
Per Azure OpenAI, queste impostazioni di identità si applicano solo quando AZURE_OPENAI_API_KEY non è impostato. Se è configurata una chiave API, il provider di modelli usa la chiave anziché l'identità gestita.
La cronologia delle sessioni usa la stessa configurazione dell'identità di archiviazione dell'host Funzioni di Azure. Usare AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri e AzureWebJobsStorage__clientId per configurare l'archiviazione basata sull'identità per la cronologia supportata da BLOB. Il runtime non usa un'impostazione di identità specifica dell'agente separata per la cronologia delle sessioni.
Sessioni e stato
Le interazioni tra agenti a più turni richiedono la cronologia delle sessioni. In Azure il runtime archivia la cronologia delle sessioni in gestione rete virtuale di Azure usando l'account AzureWebJobsStorage dell'app per le funzioni. Questa progettazione evita un database di sessione separato per molte app e funziona con la configurazione di archiviazione basata su stringa di connessione o identità.
Per lo sviluppo locale, in assenza di una configurazione di Archiviazione di Azure, il runtime può ripiegare su una cronologia delle sessioni basata su file nella directory di configurazione locale degli agenti.
L'esecuzione in modalità sandbox è anche compatibile con la sessione. Quando il runtime crea strumenti sandbox senza un ID sessione esplicito, usa una sessione isolata per la chiamata invece di condividere lo stato tra esecuzioni dell'agente non correlate.
Endpoint predefiniti
Il runtime può esporre endpoint di debug e composizione predefiniti senza codice dell'applicazione aggiuntivo. Usare l'interfaccia utente della chat e le API di chat per lo sviluppo, il test e la diagnostica, non come interfaccia principale dell'applicazione di produzione.
| Surface | Itinerario | chiave Azure |
|---|---|---|
| Interfaccia utente chat |
/agents/<AGENT_NAME>/ quando builtin_endpoints.debug_chat_ui: true |
Richiede una chiave di funzione quando è ospitata in Azure. |
| HTTP chat API |
POST /agents/<AGENT_NAME>/chat quando builtin_endpoints.chat_api: true |
Tasto funzione. |
| Streaming chat API |
POST /agents/<AGENT_NAME>/chatstream quando builtin_endpoints.chat_api: true |
Tasto funzione. |
| Endpoint MCP | /runtime/webhooks/mcp |
mcp_extension tasto di sistema. |
Qualsiasi file dell'agente può essere abilitato tramite le impostazioni builtin_endpoints nel front matter. Il <AGENT_NAME> segmento di route deriva dal nome del .agent.md file, non dal campo visualizzato name . Ad esempio, main.agent.md usa /agents/main/.
Se ospitato in Azure, l'interfaccia utente della chat richiede una chiave di funzione prima di inviare messaggi. È anche possibile usare questa chiave per chiamare direttamente le API di chat HTTP:
az functionapp keys list \
--resource-group <RESOURCE_GROUP> \
--name <FUNCTION_APP_NAME> \
--query "functionKeys.default" \
--output tsv
Passa la chiave nell'intestazione x-functions-key o nel parametro della stringa di query code. Per connettere un client MCP, ottenere invece la chiave di sistema dell'estensione MCP:
az functionapp keys list \
--resource-group <RESOURCE_GROUP> \
--name <FUNCTION_APP_NAME> \
--query "systemKeys.mcp_extension" \
--output tsv
L'endpoint MCP richiede questa chiave di sistema a meno che l'app non configuri l'accesso anonimo.
Quando usare il runtime degli agenti serverless
Usa il runtime per agenti serverless quando il tuo agente è basato su eventi, fa ampio uso di strumenti o è operativamente simile ai carichi di lavoro di Funzioni di Azure.
Le funzionalità più adatte includono:
- Agenti in background pianificati che riepilogano, monitorano, riconciliano o segnalano.
- Assistenti basati su eventi che reagiscono a messaggi, messaggi di posta elettronica, avvisi, messaggi in coda o modifiche ai dati.
- Agenti tra sistemi che usano connettori per coordinare il lavoro tra applicazioni SaaS e aziendali.
- Interfacce conversazionali che espongono lo stesso agente tramite HTTP, interfaccia di chat o MCP.
- Agenti che devono scalare fino a zero e usare l'identità gestita, il monitoraggio, gli slot di distribuzione e altre funzionalità di hosting di Azure.
Se è sufficiente esporre funzioni deterministiche come strumenti per un altro client di intelligenza artificiale, l'estensione MCP Funzioni di Azure potrebbe essere un punto di partenza migliore. Per altre informazioni, vedere Usare strumenti e modelli di intelligenza artificiale in Funzioni di Azure.
Get started
Iniziare con la guida introduttiva per distribuire un'app di agenti serverless con un agente chat, un agente di riepilogo del blog attivato da timer, una distribuzione del modello, l'esecuzione in modalità sandbox e gli strumenti MCP da uno spazio dei nomi di connessione: