Implementazione di agenti AI con Databricks: una guida pratica completa

Informatec Digital » Risorse » Implementazione di agenti AI con Databricks: una guida pratica completa

Creare agenti AI in Databricks non è più un'esclusiva dei profili ultra-tecnici: grazie ad ambienti visivi come AI Playground , all'automazione con Agent Bricks e ai framework MLflow, ora è possibile passare dall'idea al prototipo e dal prototipo alla produzione senza perdersi nel processo. In questa guida, riassumiamo tutto ciò che serve per creare, valutare e implementare agenti che richiamano strumenti, interrogano dati e si integrano con la governance di Unity Catalog.

Oltre ad esplorare l'approccio no-code e lo sviluppo in Python, imparerai come impacchettare gli agenti con MLflow (ChatAgent e ResponsesAgent) , registrare le risorse nel catalogo, abilitare il monitoraggio in tempo reale e scalare utilizzando Model Serving. È inclusa anche un'app di esempio realizzata con React e FastAPI per integrare perfettamente il tuo agente in un'interfaccia web aziendale.

Opzioni per la creazione di agenti in Databricks

Se la velocità e la semplicità sono le tue priorità, Agent Bricks offre un flusso di lavoro automatizzato per la creazione di sistemi di agenti di alta qualità e conformi al dominio. Specifichi il tuo caso d'uso e colleghi i dati del tuo catalogo Unity ; la piattaforma genera varianti di agenti, le ottimizza tramite valutazione e ti consente di perfezionarle, il tutto con governance e sicurezza integrate.

Quando è necessario un controllo granulare e si desidera riutilizzare librerie già note, l'approccio basato sul codice combina il framework Mosaic AI Agent e MLflow . Con Python, è possibile definire la logica dell'agente, abilitare le chiamate agli strumenti, eseguire un tracciamento dettagliato e, infine, impacchettare e distribuire in produzione con l'ecosistema Databricks.

Se utilizzi già framework di terze parti, è disponibile il supporto nativo per LangGraph/ LangChain , LlamaIndex o implementazioni Python personalizzate. Grazie alle firme dei modelli e alle interfacce degli agenti di MLflow, puoi integrarli nelle funzionalità di valutazione e monitoraggio senza dover riscrivere il codice da zero.

Vuoi realizzare prototipi alla velocità della luce? Con AI Playground, scegli il modello e la macchina virtuale, aggiungi strumenti al LLM tramite un'interfaccia low-code e chatti per la convalida. Dopodiché, esporti l'agente in codice pronto per la produzione e prosegui con il ciclo di sviluppo standard.

Firme del modello e compatibilità con le funzionalità della piattaforma

Azure Databricks utilizza le firme del modello MLflow per descrivere lo schema di input e output degli agenti. Le funzionalità del prodotto, come AI Playground o la valutazione, richiedono che l'agente sia conforme a una delle firme supportate per garantire l'interoperabilità.

Se segui l'approccio consigliato durante la creazione dell'agente, MLflow deduce automaticamente la firma compatibile senza passaggi aggiuntivi. In caso contrario, verifica che la tua implementazione sia conforme a una delle firme presenti nello schema legacy per l'input e l'output dell'agente, per evitare sorprese durante l'integrazione con gli strumenti Databricks.

Tutorial rapido: Primo agente con Mosaic AI Agent Framework

L'obiettivo è quello di creare un agente che ragiona con un LLM ospitato presso Databricks ed essere in grado di eseguire strumenti, ad esempio la funzione integrata system.ai.python_exec dal catalogo Unity per eseguire il codice Python. Inoltre, abiliteremo il tracciamento con MLflow per l'ispezione delle tracce e la diagnostica.

Requisiti di base dell'area di lavoro: abilitare le funzionalità dell'agente e avere accesso al Model ServingNell'ambiente di runtime, installare pacchetti come mlflow, databricks-openai e l'agente imballatore (databricks-agent o databricks-agents(a seconda della guida che segui e della versione) e riavvia Python per caricare le dipendenze.

Definire la connessione al servizio modello utilizzando il client OpenAI che espone WorkspaceClient, attivo mlflow.openai.autolog() per la strumentazione automatica e registra gli strumenti disponibili. Tra questi, system.ai.python_exec Funziona come interprete Python stateless e consente all'LLM di risolvere calcoli o manipolare dati durante il dialogo.

Con una funzione come run_agent(), invii il prompt dell'utente all'endpoint della chat (Ad esempio, un modello come «databricks-claude-3-7-sonnet«e gestire possibili chiamate agli strumenti restituendo i messaggi dell'assistente e le risposte degli strumenti in un elenco coerente.

Per eseguire il test, esegui una query che richieda del codice (ad esempio, il calcolo del centesimo numero di Fibonacci ) e analizza sia l'output della procedura guidata sia le tracce di MLflow registrate nel notebook o nell'esperimento associato. Questo ti permetterà di perfezionare l'orchestrazione prima di creare il pacchetto.

Confezionato con MLflow e distribuito in Model Serving

Un modo consigliato per preparare l'agente per la produzione è implementare l'interfaccia Agente di chat MLflowHai bisogno di un metodo predict() che accetta messaggi, chiama la logica dell'agente e restituisce un Risposta dell'agente di chat con l'elenco dei messaggi (inclusi i messaggi intermedi associati agli strumenti, se applicabile).

Per facilitare la servitù, consolidare tutto il codice in un singolo file Python (ad esempio, utilizzando %%writefile quickstart_agent.py (se stai lavorando su un portatile). Nella parte finale, chiama mlflow.models.set_model() passando l'istanza della tua classe (ad esempio, QuickstartAgent) per stabilire il punto di ingresso inferenza.

Registra l'agente in Catalogo Unity con mlflow.pyfunc.log_model, compreso mezzi di cui avrai bisogno in produzione: l'endpoint del modello LLM (ad esempio, DatabricksServingEndpoint) e le funzioni di catalogo che l'agente invocherà (ad esempio, DatabricksFunction con system.ai.python_execPertanto, Databricks può Configurare l'autenticazione per queste risorse durante la distribuzione.

Infine, utilizzare l'API dell'agente per da distribuire il modello a un endpoint del servizio: from databricks import agents y agents.deploy(model_name, model_version)Quando l'endpoint si avvia, sarai in grado di Chat da AI Playgroundcondividilo con le parti interessate e inizia a raccogliere feedback.

Se desideri continuare a migliorare, Databricks offre guide per misurare la qualità degli agenti , creare agenti con recupero di informazioni (RAG) su dati non strutturati e gestire conversazioni a più turni, oltre ad alternative con LangGraph, Python puro o OpenAI.

ResponsesAgent: l'interfaccia moderna per gli agenti di produzione

Sebbene Agente di chat Funziona bene, MLflow lo consiglia oggi RisposteAgente Per agenti seri. Questa interfaccia è compatibile con lo schema Responses da OpenAI e consente l'integrazione di agenti da qualsiasi quadro con le funzionalità di Databricks (registrazione, tracciamento, valutazione, distribuzione e osservabilità) senza attriti.

Vantaggi principali: supporto nativo per sistemi multi-agente, modalità di uscita Streaming, cronologia completa dei messaggi e delle chiamate degli strumenti, conferma delle chiamate degli strumenti e strumenti di lunga durata. Inoltre, offre interfacce tipizzate In Python, inferenza automatica della firma, tracciamento automatico di predict y predict_stream e tabelle di inferenza migliorate tramite Gateway AI.

Requisiti di installazione per questo approccio: databricks-agents 1.2.0+, mlflow 3.1.3+ y Pitone 3.10+ (utilizzando Serverless o Databricks Runtime 13.3 LTS+). Databricks consiglia anche i seguenti pacchetti: Ponte AI per integrazioni comuni.

Integrazioni utili: databricks-openai (OpenAI), databricks-langchain (LangChain/LangGraph), databricks-dspy (DSPy) e databricks-ai-bridge (Agenti in puro Python). Con questi pezzi puoi costruire qualsiasi cosa, da semplici agenti a condotte complesse con recupero e chiamata utensile.

Se hai già un agente integrato, avvolgilo in una classe che eredita da mlflow.pyfunc.ResponsesAgent. Implement predict per convertire gli input e gli output in Schema ResponsesAgentPer lo streaming, affidati a predict_stream, emettendo delta e un evento finale response.output_item.done Per favore aggiungi la risposta completa.

Per quanto riguarda gli errori di streaming, Mosaic AI propaga l'errore insieme all'ultimo token all'interno databricks_output.errorIl tuo cliente dovrebbe catturarlo e visualizzarlo correttamente, migliorando l' esperienza di depurazione.

Sistemi di recupero, input personalizzati e tracciabilità

Molti agenti usano recuperatori per RAG su indici vettoriali. Se i tuoi intervalli di recupero espongono uno schema diverso, puoi mapparlo con mlflow.models.set_retriever_schemadichiarando primary_key, text_column, doc_uri e altre colonne. Pertanto, AI Playground mostrerà Link alle fonti recuperato e la valutazione verrà applicata indicatori di pertinenza automaticamente.

Nei casi in cui il tuo agente richieda informazioni aggiuntive (ad esempio, tipo_cliente o session_id), usi custom_inputs e restituisce i metadati in custom_outputs che non dovrebbe contaminare la cronologia della chat. Sia AI Playground che l'app di revisione ti consentono di inserire input personalizzati dall'interfaccia utente.

Distribuzione con deploy(), requisiti e azioni automatizzate

Per pubblicare il tuo agente su Mosaic AI Model Serving, usa la funzione deploy() dell'API Python. In MLflow 3, installa mlflow >= 3.1.3 y databricks-agents >= 1.1.0 (se si esegue la distribuzione al di fuori dei notebook). In MLflow 2.x, i minimi cambiano (ad esempio, mlflow >= 2.13.1 y databricks-agents >= 0.12.0Assicurarsi Registra l'agente nel catalogo Unity prima della distribuzione.

Chiama a deploy() creare un endpoint scalabile con bilanciamento automatico, configurare il autenticazione sicura per le risorse Databricks (indici vettoriali, funzioni di catalogo) —verificando i permessi del proprietario— e attiva il domanda di revisione per la collaborazione con le parti interessate.

Consente inoltre il monitoraggio in tempo reale in MLflow (con tracce nell'esperimento attivo e nelle tabelle di inferenza). In MLflow 3 è possibile configurare il monitoraggio della produzione con valutazione automatica della qualità; le richieste REST e i commenti vengono registrati nelle tabelle di inferenza (utilizzando API di feedback moderne).

Per personalizzare, passare gli argomenti a deploy() come scale_to_zero_enabled=Trueriducendo i costi dopo i tempi di inattività a scapito di una maggiore latenza alla prima richiesta. Inoltre, hai utilità per elencare, ottenere ed eliminare distribuzioni tramite l'API dell'agente.

Buone pratiche per modelli di stato, configurazione ed esecuzione

Il modello di servizio è distribuito: evitare cache locali e presuppone che risposte diverse possano gestire svolte diverse in una conversazione. Ricostruisce lo stato dal dizionario di ResponsesAgentRequest in ciascuno predict e progettare lo stato affinché sia thread-safe.

Inizializza lo stato all'interno predict e non nel costruttore dell'agente, poiché una singola replica potrebbe gestire conversazioni da utenti diversi. Ciò impedisce perdite di informazioni e conflitti di concorrenza in ambienti ad alta produttività.

Parametrizzare il comportamento dell'agente con ModelConfig (dizionario o YAML). Definisci, ad esempio, model_serving_endpointParametri LLM e modelli di prompt; caricare tale configurazione nello sviluppo e promuoverla in produzione senza toccare il codice.

Evitate di introdurre cicli di eventi o frame asincroni sul server dell'agente: Databricks gestisce la concorrenza internamente . Utilizzate codice sincrono o callback; in caso contrario, potreste riscontrare errori come "Questo ciclo di eventi è già in esecuzione" e un comportamento anomalo.

Agent Bricks: automazione "senza codice" per accelerare il valore

Agent Bricks, lanciato nel 2025, offre un flusso di lavoro intuitivo per la creazione di agenti che non richiede alcuna programmazione . È sufficiente inserire l'attività in linguaggio naturale, collegare i dati e la piattaforma seleziona i modelli, genera dati sintetici , valuta e perfeziona il processo fino a fornire un agente pronto per la produzione con governance di Unity Catalog.

Tra i suoi vantaggi figurano l'automazione end-to-end , la scalabilità in Databricks (con endpoint che possono azzerarsi dopo 3 giorni di inattività), l'analisi dell'utilizzo e dei costi su Lakehouse e tipologie di agenti predefinite (estrazione di informazioni, LLM personalizzato , assistente alla conoscenza e supervisore multi-agente per orchestrazioni complesse).

Tra le limitazioni si annovera il fatto che il codice generato non è attualmente scaricabile , il che limita le possibilità di personalizzazione approfondita, e che il catalogo di modelli è pensato per organizzazioni già integrate con Lakehouse e Unity Catalog. Alcuni utenti ritengono inoltre che le metriche di costo manchino di granularità .

Esempi di agenti multi-agente e agenti con stato

Nella documentazione ufficiale, troverete notebook con OpenAI (chat semplice e chiamate a strumenti, sia per modelli ospitati su Databricks che su OpenAI), LangGraph (invocazione di strumenti) e DSPy (chiamate di strumenti in un singolo turno). Questi rappresentano un'ottima base per estendere le funzionalità con strumenti personalizzati e valutazioni di qualità.

Per coordinare più specialisti, è possibile configurare sistemi cooperativi utilizzando strumenti come Genie. Inoltre, se siete interessati alla memorizzazione delle conversazioni, è disponibile il supporto per agenti con stato che consentono di creare checkpoint e mantenere la persistenza dei thread di chat.

Nella documentazione ufficiale, troverete notebook con OpenAI (chat semplice e chiamate a strumenti, sia per modelli ospitati su Databricks che su OpenAI), LangGraph (invocazione di strumenti) e DSPy (chiamate di strumenti in un singolo turno). Questi rappresentano un'ottima base per estendere le funzionalità con strumenti personalizzati e valutazioni di qualità.

App su Databricks: interfaccia utente con React e backend in FastAPI

Le app Databricks offrono una piattaforma solida per la creazione di interfacce ricche di funzionalità senza la necessità di configurare infrastrutture esterne. Si integrano nativamente con Databricks SQL, Unity Catalog , Model Serving e Jobs, ed ereditano i controlli di sicurezza e conformità della piattaforma.

Un modello molto pratico consiste nel creare un frontend con React (che supporti lo streaming, il rendering dei messaggi e l'interfaccia utente Markdown) e un backend con FastAPI che funga da ponte verso l'endpoint dell'agente. Il backend instrada la richiesta dell'utente al servizio del modello e restituisce la risposta strutturata al client.

In FastAPI, l'ordine di assemblaggio delle sotto-applicazioni è importante: app.mount("/api", api_app) dirige i percorsi API (ad esempio, /api/chat) Y app.mount("/", ui_app) Fornisce i file statici dalla build di React nella directory principale. Questo schema mantiene chiarezza dei percorsi e separa l'interfaccia utente dagli endpoint.

Configurare le variabili di ambiente (ad esempio, SERVING_ENDPOINT_NAME o l'FQN del modello dell'agente in Unity Catalog) dalla definizione dell'app in Databricks. Compila il frontend (npm run build), sincronizza i file, dichiara le dipendenze (requirements.txt) e inizia con Gunicorn + Uvicorn lavoratori per ASGI.

Caso reale: chatbot per le operazioni di produzione

Negli scenari di gestione delle operazioni di produzione (MOM), un chatbot di Databricks può assistere i responsabili di produzione nell'analisi dei colli di bottiglia , nel monitoraggio delle scorte e nella generazione di report. Le funzioni sono esposte come strumenti nel catalogo Unity (tramite SQL o Python) e l'agente le richiama in base al contesto.

Esempi: una funzione identify_bottleneck_station Esegue query in Databricks SQL per rilevare la fase che causa il maggior numero di ritardi; un altro, check_inventory_levelsRestituisce lo stock in tempo reale. L'agente può anche inviare e-mail, produrre report ed eseguire analisi del sentiment, il tutto orchestrato tramite chiamate di strumenti.

L'implementazione dell'endpoint Model Serving funge da backend standard . L'app React utilizza questo endpoint, visualizzando risposte in tempo reale con un'esperienza utente ottimizzata e supportando lo streaming di token quando abilitato nel tuo ResponsesAgent.

Migrazione da ChatCompletions e compatibilità

Se il tuo agente legacy utilizza l'API ChatCompletions di OpenAI , puoi migrare a ResponsesAgent con un container che traduce i messaggi in entrata/uscita e, facoltativamente, mappa le variazioni di streaming a ResponsesAgentStreamEvent . Questo modernizza la telemetria e l'osservabilità senza riscrivere la logica principale.

Per elencare e gestire le distribuzioni, l'API dell'agente consente di visualizzare le distribuzioni esistenti, recuperare una distribuzione specifica (per nome e versione) e rimuovere gli endpoint non più necessari. Ricorda di gestire le credenziali delle risorse esterne utilizzando variabili d'ambiente e segreti.

Databricks offre un percorso completo: dall'ideazione con AI Playground o l'automazione con Agent Bricks, passando per lo sviluppo del codice (Mosaic AI, MLflow, LangGraph, DSPy), fino al packaging, alla registrazione nel catalogo Unity , al deployment con deploy() e al monitoraggio in produzione. Grazie a best practice come firme di modelli corrette , stato sicuro in ambienti distribuiti e configurazione parametrizzata, è possibile fornire agenti affidabili e controllati, pronti per l'integrazione in applicazioni web sulla piattaforma.

Articolo correlato:

Claude 4: Anthropic reinventa l'intelligenza artificiale con modelli avanzati per la programmazione e agenti autonomi