Usare Funzioni di Azure con il servizio agente Foundry (versione classica)

Funzioni di Azure è un servizio di calcolo serverless che è possibile usare per estendere gli agenti del servizio Foundry Agent con strumenti personalizzati creati usando il codice. Questo approccio è particolarmente utile quando è necessario che l'agente si integri con i sistemi all'interno dell'azienda.

Le funzioni offrono diversi piani di hosting. Il piano Flex Consumption è ideale per ospitare gli strumenti personalizzati perché offre:

• Hosting serverless scalabile fino a zero con prezzi basati sul consumo.
• Accesso basato sulle identità alle risorse in Azure, incluse le risorse all'interno delle reti virtuali.
• Connessioni dichiarative all'origine dati tramite associazioni di input/output.

Quando usare Funzioni di Azure vs invocazione di funzioni

Mentre chiamata di funzione consente di definire strumenti eseguiti in-process con il codice dell'agente, l'hosting di strumenti personalizzati in Funzioni di Azure offre capacità aziendali aggiuntive quando ne hai bisogno:

• Separazione delle problematiche: isolare la logica di business dal codice dell'agente, abilitare cicli di sviluppo, test e distribuzione indipendenti.
• Gestione centralizzata: creare strumenti riutilizzabili che più agenti, applicazioni o team possono usare in modo coerente.
• Isolamento della sicurezza: controllare l'accesso degli agenti agli strumenti separatamente dall'accesso degli strumenti alle risorse aziendali. Questo approccio consente di assegnare agli agenti solo le autorizzazioni specifiche necessarie per chiamare lo strumento senza dover fornire l'accesso diretto a database, API o reti sottostanti.
• Dipendenze esterne: sfruttare librerie non Microsoft, ambienti di runtime specifici o integrazioni di sistema legacy.
• Operazioni complesse: gestire flussi di lavoro e trasformazioni di dati con più passaggi o eseguire l'offload di operazioni a elevato utilizzo di calcolo.
• Elaborazione asincrona: eseguire operazioni a esecuzione prolungata con funzionalità di ripetizione dei tentativi e gestione resiliente dei messaggi.

Opzioni di integrazione

Il servizio agente Foundry offre due modi principali per consentire agli agenti di accedere agli strumenti ospitati Funzioni di Azure:

Per le funzioni di trigger HTTP, è anche possibile integrare descrivendo la funzione tramite una specifica OpenAPI e registrandola come strumento chiamabile usando lo strumento OpenAPI nella configurazione dell'agente. Questo approccio offre flessibilità per le funzioni esistenti basate su HTTP, ma richiede un'installazione aggiuntiva per definire la specifica dell'API.

Modelli supportati

Per usare tutte le funzionalità di chiamata di funzione, incluse le funzioni parallele, è necessario usare un modello rilasciato dopo il 6 novembre 2023.

Creare e distribuire un esempio di integrazione di uno strumento basato su coda

Nella resto di questo articolo viene illustrato come usare un esempio dell'interfaccia della riga di comando di Azure Developer (azd) che configura un progetto del servizio agenti di Foundry con Funzioni per supportare l'integrazione degli strumenti basata su coda per gli agenti.

Prerequisiti

• Funzioni di Azure Core Tools v4.x
• Un agente distribuito con la configurazione standard

  Nota

  La configurazione dell'agente di base non è supportata.

• Azurite
• Un account Azure con una sottoscrizione attiva. Creare gratuitamente un account.

Supporto per l'utilizzo

Inizializzare il modello di progetto

Questo progetto usa azd per semplificare la creazione di risorse Azure e la distribuzione del codice. Questa distribuzione segue le procedure consigliate correnti per le distribuzioni di funzioni sicure e scalabili. È possibile trovare il modello e il codice usati qui in GitHub.

1. Eseguire questo azd init comando in una finestra del terminale per inizializzare il progetto dal modello azd:

   azd init --template azure-functions-ai-services-agent-python
   

Quando richiesto, specificare un nome di ambiente, ad esempio ai-services-agent-python. In azdl'ambiente mantiene un contesto di distribuzione univoco per l'app ed è possibile definire più di uno. Il nome dell'ambiente viene usato anche nel nome del gruppo di risorse e di altre risorse create in Azure.

1. Eseguire questo comando per consentire l'esecuzione corretta degli script di installazione locale, che dipende dal sistema operativo locale:

   • Mac/Linux
   • Windows

   chmod +x ./infra/scripts/*.sh 
   

Erogazione delle risorse

Eseguire il comando azd provision per creare le risorse necessarie in Azure:

azd provision

Quando richiesto, specificare questi parametri di distribuzione obbligatori:

Il file di distribuzione main.bicep viene quindi letto da azd e usato per creare queste risorse in Azure:

• Piano Consumo Flessibile e app per le funzioni
• Piattaforma degli agenti in Foundry, inclusi:
  • Account dei servizi
  • Distribuzione del modello
  • Progetto
  • Agenti
  • Ricerca
  • Account Azure Cosmos DB (usato dalla ricerca)
• Archiviazione di Azure (richiesto dagli agenti di Funzioni e intelligenza artificiale) e Application Insights (scelta consigliata)
• Criteri di accesso e ruoli per gli account
• Connessioni da servizio a servizio che usano identità gestite (anziché stringhe di connessione archiviate)

È anche possibile usare queste risorse di Azure integrate nell'articolo Come usare Funzioni di Azure basate su coda con gli agenti di Microsoft Foundry.

Gli script di post-provisioning creano anche un file local.settings.json, che Functions richiede per funzionare in locale. Il file generato dovrebbe essere simile al seguente:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "STORAGE_CONNECTION__queueServiceUri": "https://<storageaccount>.queue.core.windows.net",
    "PROJECT_CONNECTION_STRING": "<project connection for AI Project>"
    }
}

Esegui la tua app in Visual Studio Code

1. Aprire la cartella in un nuovo terminale.
2. Eseguire il comando di codice code . per aprire il progetto in Visual Studio Code.
3. Nel riquadro comandi (F1) digitare Azurite: Start, che abilita il debug con l'archiviazione locale per il runtime di Funzioni.
4. Premere Esegui/Debug (F5) per l'esecuzione nel debugger. Selezionare Debug comunque se viene richiesto di non eseguire l'emulatore locale.
5. Invia gli endpoint POST prompt in successione usando lo strumento di test HTTP. Se è installata l'estensione RestClient, è possibile eseguire richieste direttamente dal file di progetto test.http.

Distribuire in Azure

Eseguire questo comando azd deploy per pubblicare il codice del progetto nell'app per le funzioni e le risorse correlate Azure di cui è stato appena effettuato il provisioning:

azd deploy

Al termine della pubblicazione, azd fornisce gli endpoint URL delle nuove funzioni, ma senza i valori della chiave di funzione necessari per accedere agli endpoint. È possibile usare il comando Funzioni di Azure Core Tools func azure functionapp list-functions con l'opzione --show-keys per ottenere le chiavi per gli endpoint della funzione. Per ulteriori informazioni, consulta Lavorare con le chiavi di accesso in Funzioni di Azure.

Ridistribuire il codice

Puoi anche eseguire il comando azd up quante volte è necessario per effettuare il provisioning delle risorse Azure e implementare gli aggiornamenti del codice alla funzione app.

Pulire le risorse

Al termine dell'uso delle funzioni applicative e delle risorse correlate, utilizzare questo comando per eliminare le funzioni applicative e le relative risorse da Azure ed evitare di sostenere ulteriori costi (--purge non esegue un'eliminazione temporanea della risorsa di intelligenza artificiale e ripristina la quota):

azd down --purge