Creare un agente di intelligenza artificiale e distribuirlo in Databricks Apps

Creare un agente di intelligenza artificiale e distribuirlo usando Databricks Apps. Databricks Apps offre il controllo completo sul codice dell'agente, sulla configurazione del server e sul flusso di lavoro di distribuzione. Questo approccio è ideale quando è necessario un comportamento del server personalizzato, il controllo delle versioni basato su Git o lo sviluppo di IDE locali.

Suggerimento

Se l'agente usa solo strumenti ospitati Azure Databricks e non richiede logica personalizzata tra le chiamate agli strumenti, è possibile usare l'API Supervisor (Beta) per consentire Azure Databricks gestire il ciclo dell'agente.

Anteprima dell'interfaccia utente della chat dell'agente

Ogni modello di agente di conversazione include un'interfaccia utente di chat predefinita (illustrata sopra) senza alcuna configurazione aggiuntiva. L'interfaccia utente della chat supporta le risposte in streaming, il rendering markdown, l'autenticazione di Databricks e la cronologia di chat persistente facoltativa.

Requisiti

Abilitare Le app di Databricks nell'area di lavoro. Vedere Configurare l'area di lavoro e l'ambiente di sviluppo di Databricks Apps.

Passaggio 1. Clonare il modello di app agente

Introduzione all'uso di un modello di agente predefinito dal repository dei modelli di app Databricks.

Questa esercitazione usa il modello agent-openai-agents-sdk, che include:

  • Un agente creato con OpenAI Agent SDK
  • Codice di avvio per un'applicazione agente con un'API REST di conversazione e un'interfaccia utente di chat interattiva
  • Codice per valutare l'agente usando MLflow

Scegliere uno dei percorsi seguenti per configurare il modello:

Interfaccia utente dell'area di lavoro

Installare il modello di app usando l'interfaccia utente dell'area di lavoro. In questo modo l'app viene installata e distribuita in una risorsa di calcolo nell'area di lavoro. È quindi possibile sincronizzare i file dell'applicazione nell'ambiente locale per un ulteriore sviluppo.

  1. Nell'area di lavoro di Databricks fare clic su + Nuova>app.

  2. Fare clic su Agenti>Agente personalizzato (OpenAI SDK).

  3. Creare un nuovo esperimento MLflow con il nome openai-agents-template e completare il resto della configurazione per installare il modello.

  4. Dopo aver creato l'app, fare clic sull'URL dell'app per aprire l'interfaccia utente della chat.

Dopo aver creato l'app, scaricare il codice sorgente nel computer locale per personalizzarlo:

  1. Copiare il primo comando in Sincronizzare i file

    Sincronizzare i file di Databricks Apps

  2. In un terminale locale eseguire il comando copiato.

Clonare da GitHub

Per iniziare da un ambiente locale, clonare il repository dei modelli di agente e aprire la agent-openai-agents-sdk directory:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Passaggio 2. Informazioni sull'applicazione agente

Il modello di agente illustra un'architettura pronta per la produzione con questi componenti chiave. Aprire le sezioni seguenti per altri dettagli su ogni componente:

Diagramma semplice dell'agente nell'app

Aprire le sezioni seguenti per altri dettagli su ogni componente:

Icona chat Interfaccia utente chat predefinita

Il modello di agente recupera automaticamente ed esegue il modello di app di chat come front-end. Questa interfaccia utente della chat viene inserita nella stessa distribuzione di App Databricks e viene servita insieme all'agente, quindi non è necessaria alcuna configurazione aggiuntiva.

È possibile personalizzare l'interfaccia utente della chat direttamente nel progetto. Per altri dettagli sulle funzionalità dell'app di chat, tra cui come abilitare la cronologia chat persistente e la raccolta di commenti e suggerimenti degli utenti, vedere Creare e condividere un'interfaccia utente di chat con Databricks Apps.

Icona chip. MLflow AgentServer

Un server FastAPI asincrono che gestisce le richieste degli agenti con traccia e osservabilità predefinite. AgentServer fornisce l'endpoint per l'esecuzione di query sull'agente /responses e gestisce automaticamente il routing delle richieste, la registrazione e la gestione degli errori.

Icona quadrata di Brackets. ResponsesAgent Interfaccia

Databricks consiglia MLflow ResponsesAgent per compilare gli agenti. ResponsesAgent consente di creare agenti con qualsiasi framework di terze parti, quindi integrarlo con le funzionalità di intelligenza artificiale di Databricks per funzionalità di registrazione, traccia, valutazione, distribuzione e monitoraggio affidabili.

ResponsesAgent esegue facilmente il wrapping degli agenti esistenti per la compatibilità di Databricks.

Per informazioni su come creare un ResponsesAgent, consultare gli esempi nella documentazione di MLflow - ResponsesAgent for Model Serving.

ResponsesAgent offre i vantaggi seguenti:

  • Funzionalità avanzate dell'agente

    • Supporto multi-agente
    • Output di streaming: trasmettere l'output in blocchi più piccoli.
    • cronologia completa dei messaggi relativi alla chiamata degli strumenti: restituzione di più messaggi, inclusi quelli intermedi relativi alla chiamata degli strumenti, per migliorare la qualità e la gestione delle conversazioni.
    • Supporto per la conferma dell'attivazione degli strumenti
    • Supporto per strumenti a esecuzione prolungata

  • Sviluppo, distribuzione e monitoraggio semplificati

    • Creare agenti usando qualsiasi framework: incapsulare qualsiasi agente esistente usando l'interfaccia ResponsesAgent per ottenere la compatibilità immediata con AI Playground, Agent Evaluation e Agent Monitoring.
    • Interfacce di creazione tipizzate: scrivere codice dell'agente usando classi Python tipizzate, sfruttando l'IDE e il completamento automatico del notebook.
    • Traccia automatica: MLflow aggrega automaticamente le risposte in streaming nelle tracce per facilitare la valutazione e la visualizzazione.
    • Compatibile con lo Responses schema OpenAI: vedere OpenAI: Risposte vs. CompletamentoChat.
Icona robot. OpenAI Agents SDK

Il modello usa OpenAI Agents SDK come framework agente per la gestione delle conversazioni e l'orchestrazione degli strumenti. È possibile creare agenti usando qualsiasi framework. La chiave è eseguire il wrapping del proprio agente con l'interfaccia MLflow ResponsesAgent.

Icona MCP. Server MCP (Model Context Protocol)

Il modello si connette ai server MCP di Databricks per concedere agli agenti l'accesso a strumenti e origini dati. Vedere Model Context Protocol (MCP) in Databricks.

Creare agenti usando assistenti per la scrittura del codice di intelligenza artificiale

Databricks consiglia di utilizzare assistenti di codifica basati su intelligenza artificiale come Claude, Cursor e Copilot per sviluppare agenti. Usare le competenze dell'agente fornite, in /.claude/skillse il AGENTS.md file per aiutare gli assistenti di intelligenza artificiale a comprendere la struttura del progetto, gli strumenti disponibili e le procedure consigliate. Gli agenti possono leggere automaticamente tali file per sviluppare e distribuire le app di Databricks.

Passaggio 3. Aggiungi strumenti all'agente

Offrire all'agente funzionalità come l'esecuzione di query sui database, la ricerca di documenti o la chiamata di API esterne connettendole ai server MCP. Il modello di agente include una connessione server MCP predefinita. Per aggiungere altri strumenti, configurare altri server MCP nel codice dell'agente e concedere le autorizzazioni necessarie in databricks.yml.

Vedere Strumenti dell'agente di intelligenza artificiale per i tipi di strumenti e gli esempi di codice supportati.

Definire le funzioni locali di Python

Per le operazioni che non richiedono origini dati o API esterne, definire gli strumenti direttamente nel codice dell'agente. Questi strumenti vengono eseguiti nello stesso processo dell'agente e sono utili per le trasformazioni, i calcoli o le operazioni di utilità dei dati.

OpenAI Agents SDK

Utilizzare il decoratore @function_tool dell'SDK di OpenAI Agents.

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

Usare il decoratore @tool di LangChain:

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

Gli strumenti delle funzioni locali non richiedono concessioni di risorse perché databricks.yml vengono eseguite all'interno del processo dell'agente.

Passaggio 4. Gestisci l'utilizzo di LLM dai tuoi agenti su Databricks Apps con Unity AI Gateway

Instradare le chiamate LLM dell'agente tramite il gateway di intelligenza artificiale (Beta) in modo che ogni richiesta sia governata dagli stessi controlli indipendentemente dal provider a cui risponde. Con il gateway nel percorso della richiesta, è possibile centralizzare le autorizzazioni, il costo degli attributi per app, i modelli di scambio e controllare o riprodurre il traffico senza modificare il codice dell'agente o ruotare le credenziali del provider.

Important

Questa funzionalità è in versione beta. Gli amministratori dell'area di lavoro possono controllare l'accesso a questa funzionalità dalla pagina Anteprime . Vedere Gestire le anteprime di Azure Databricks.

  1. Abilitare gateway di intelligenza artificiale nell'area di lavoro. AI Gateway è attivabile volontariamente durante la versione Beta. Un amministratore dell'account deve attivarlo dalla pagina Anteprime della console dell'account prima di poter creare o eseguire query sugli endpoint del gateway. Vedere Gestire le anteprime di Azure Databricks.

  2. Indirizza il tuo agente all'endpoint del Gateway di Intelligenza Artificiale. Nel codice dell'agente, passare il nome dell'endpoint del gateway AI come argomento model e impostare use_ai_gateway=True nel client LLM di Azure Databricks. Il client instrada il traffico attraverso il gateway e gestisce automaticamente l'autenticazione.

    OpenAI

    from agents import Agent, set_default_openai_api, set_default_openai_client
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
set_default_openai_api("chat_completions")

agent = Agent(
    name="Agent",
    instructions="You are a helpful assistant.",
    model="<ai-gateway-endpoint>",
)

    LangGraph

    from databricks_langchain import ChatDatabricks

llm = ChatDatabricks(
    model="<ai-gateway-endpoint>",
    use_ai_gateway=True,
)

    Per altre superfici API (API OpenAI Responses, API Anthropic Messages, Google Gemini) ed esempi REST, vedere Query Unity AI Gateway endpoint.

Argomenti avanzati sull'autoring

Risposte in streaming

Risposte in streaming

Lo streaming consente agli agenti di inviare risposte in blocchi in tempo reale invece di attendere la risposta completa. Per implementare lo streaming con ResponsesAgent, generare una serie di eventi delta seguiti da un evento di completamento finale:

  1. Generare eventi differenziali: inviare più output_text.delta eventi con lo stesso item_id per trasmettere blocchi di testo in tempo reale.
  2. Concludere con l'evento finale: inviare un ultimo evento response.output_item.done con lo stesso item_id degli eventi delta, contenente il testo dell'output finale completo.

Ogni evento delta trasmette un blocco di testo al client. L'evento completato finale contiene il testo di risposta completo e segnala a Databricks di eseguire le operazioni seguenti:

  • Traccia l'output dell'agente con il tracciamento di MLflow
  • Aggregare le risposte in streaming nelle tabelle di inferenza del gateway di intelligenza artificiale
  • Visualizzare l'output completo nell'interfaccia utente di AI Playground

Propagazione degli errori di streaming

Mosaic AI propaga gli errori riscontrati durante lo streaming sotto l'ultimo token databricks_output.error. Spetta al client chiamante gestire e individuare correttamente questo errore.

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}
Input e output personalizzati

Input e output personalizzati

Alcuni scenari potrebbero richiedere input aggiuntivi da parte dell'agente, come client_type e session_id, o output come collegamenti alle fonti di recupero, che non dovrebbero essere inclusi nella cronologia delle chat destinate a interazioni future.

Per questi scenari, MLflow ResponsesAgent supporta in modo nativo i campi custom_inputs e custom_outputs. È possibile accedere agli input personalizzati tramite request.custom_inputs gli esempi di framework precedenti.

L'app Valutazione agente non supporta il rendering delle tracce per gli agenti con campi di input aggiuntivi.

Fornire custom_inputs in AI Playground ed esaminare l'app

Se l'agente accetta input aggiuntivi usando il custom_inputs campo , è possibile fornire manualmente questi input sia in AI Playground che nell'app di revisione.

  1. Selezionare l'icona a forma di ingranaggio in AI Playground o nell'app di revisione agente.

  2. Abilitare custom_inputs.

  3. Fornire un oggetto JSON che corrisponda allo schema di input definito dell'agente.

    Fornisci input personalizzati nell'AI Playground.

Passaggio 5. Esegui l'app Agente localmente

Configurare l'ambiente locale:

  1. Installare uv (gestione pacchetti Python), nvm (Gestione versioni node) e l'interfaccia della riga di comando di Databricks:

  2. Cambiare directory verso la cartella agent-openai-agents-sdk.

  3. Eseguire gli script di avvio rapido forniti per installare le dipendenze, configurare l'ambiente e avviare l'app.

    uv run quickstart
uv run start-app

In un browser passare a http://localhost:8000 per aprire l'interfaccia utente della chat predefinita e iniziare a chattare con l'agente.

Passaggio 6. Configurare l'autenticazione

L'agente deve eseguire l'autenticazione per accedere alle risorse di Azure Databricks. Databricks Apps offre due metodi di autenticazione: autorizzazione dell'app (principale del servizio) e autorizzazione utente (per conto dell'utente). È possibile configurarne uno tramite l'interfaccia utente dell'area di lavoro o in modo dichiarativo in databricks.yml con Declarative Automation Bundles. I modelli di agente vengono forniti con un databricks.yml, così quel percorso è impostato come predefinito all'avvio da un modello.

Per informazioni di riferimento complete, inclusi tutti i tipi di risorse supportati, i valori delle autorizzazioni e una procedura dettagliata end-to-end databricks.yml , vedere Autenticazione per gli agenti di intelligenza artificiale.

Autorizzazione dell'app (impostazione predefinita)

L'autorizzazione dell'app usa un'entità servizio che Azure Databricks crea automaticamente per l'app. Tutti gli utenti condividono le stesse autorizzazioni.

Dichiarare ogni risorsa utilizzata dall'agente sotto resources.apps.<app>.resources in databricks.yml. Distribuire il bundle per concedere all'entità del servizio le autorizzazioni dichiarate.

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Per l'elenco completo dei tipi di risorse, vedere Autorizzazione dell'app.

Autorizzazione utente

L'autorizzazione utente consente all'agente di agire con le singole autorizzazioni di ogni utente. Usare questa opzione quando è necessario il controllo di accesso per utente o audit trail.

Aggiungi questo codice all'agente:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Important

Inizializza get_user_workspace_client() all'interno di @invoke o @stream funzioni, non durante l'avvio dell'app. Le credenziali utente esistono solo quando si gestisce una richiesta.

Configurare quali API di Azure Databricks l'agente può chiamare per conto dell'utente aggiungendo scope sotto user_api_scopes nell'applicazione in databricks.yml:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Per l'elenco degli ambiti disponibili e istruzioni di configurazione complete, vedere Autorizzazione utente.

Passaggio 7. Valutare l'agente

Il modello include il codice di valutazione dell'agente. Per altre informazioni, vedere agent_server/evaluate_agent.py. Valutare la pertinenza e la sicurezza delle risposte dell'agente eseguendo quanto segue in un terminale:

uv run agent-evaluate

Passaggio 8. Distribuire l'agente su app Databricks

Dopo aver configurato l'autenticazione, distribuire l'agente in Azure Databricks. I modelli di agente usano Databricks Asset Bundles (DAB) per la distribuzione. Il databricks.yml file nel modello definisce le autorizzazioni di configurazione e risorse dell'app. Assicurati di avere il Databricks CLI installato e configurato.

Nota

Se l'app è stata creata tramite l'interfaccia utente dell'area di lavoro nel passaggio 1, eseguire databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve prima di eseguire la distribuzione per associare l'app esistente al bundle. In caso contrario, databricks bundle deploy genera l'errore "Esiste già un'app con lo stesso nome".

  1. Convalidare la configurazione del bundle per rilevare gli errori prima della distribuzione:

    databricks bundle validate

  2. Distribuire il pacchetto. Questo carica il codice e configura le risorse (esperimento MLflow, gestione degli endpoint e così via) definite in databricks.yml:

    databricks bundle deploy

  3. Avviare o riavviare l'app:

    databricks bundle run agent_openai_agents_sdk

    Nota

    bundle deploy carica solo i file e configura le risorse. bundle run è necessario per avviare o riavviare l'app con il nuovo codice.

Per gli aggiornamenti futuri, eseguire databricks bundle deploy e poi eseguire databricks bundle run agent_openai_agents_sdk per ridistribuire.

Passaggio 9. Interrogare l'agente distribuito

L'esempio seguente usa una richiesta rapida curl con un token OAuth. I token di accesso personale (PAT) non sono supportati per le app Databricks.

Per l'elenco completo dei metodi di query, tra cui l'API REST e il client OpenAI di Databricks, vedere Query un agente distribuito in Azure Databricks.

Generare un token OAuth usando l'interfaccia della riga di comando di Databricks:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Usa il token per eseguire una query sull'agente.

curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Limitazioni

Passaggi successivi

  • Last updated on