Creare un agente personalizzato usando l'API Supervisor (Beta)

Important

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

È possibile compilare un agente app di Azure Databricks che usa l'API Supervisor (Beta) per l'orchestrazione anziché gestire il ciclo dell'agente nel proprio codice. Il risultato è lo stesso della creazione di un agente personalizzato: un'app distribuita con un'interfaccia utente di chat, un /invocations endpoint e l'autenticazione. La differenza è che Azure Databricks esegue il ciclo dell'agente per te. Il agent.py effettua una singola chiamata API e Azure Databricks gestisce la selezione, l'esecuzione e la sintesi della risposta degli strumenti.

L'API Supervisor funziona con uno dei modelli di base supportati. Modificare il model campo per cambiare provider senza toccare le definizioni degli strumenti o la logica del gestore.

Quando usare l'API Supervisor

L'API Supervisor funziona bene quando l'agente usa solo strumenti ospitati Azure Databricks e non richiede logica personalizzata tra le chiamate degli strumenti. Usare invece un ciclo dell'agente personalizzato se l'agente richiede uno dei seguenti elementi:

  • Strumenti di funzione lato client (l'API supervisore non può combinare strumenti ospitati e sul lato client in una richiesta)
  • Endpoint dell'agente diversi da endpoint di Agent Brick Knowledge Assistant
  • Retriever personalizzati, input/output personalizzati o controllo dello streaming dettagliato
  • Logica di Python personalizzata tra le chiamate degli strumenti, ad esempio la gestione condizionale del ramo o dello stato
  • Controllare i parametri di inferenza, ad esempio temperature

Per informazioni di riferimento sull'API completa e parametri supportati, vedere API supervisore (beta).

Requisiti

Creare un agente personalizzato usando l'API Supervisor

Il punto di partenza consigliato consiste nel creare una nuova app dal modello di app Databricks più recente. I modelli più recenti includono una competenza predefinita use-supervisor-api per gli assistenti di codifica per intelligenza artificiale, nonché una add-tools competenza per l'aggiunta di strumenti ospitati.

Per creare una nuova app da un modello, vedere Creare un agente di intelligenza artificiale e distribuirlo in Databricks Apps.

Dopo aver configurato l'app dal modello più recente, aprire il progetto nell'assistente per la codifica di intelligenza artificiale ed eseguire:

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

L'abilità aggiorna il tuo agent_server/agent.py affinché DatabricksOpenAI().responses.create() utilizzi strumenti ospitati, sostituendo il ciclo manuale dell'agente. Aggiunge anche la databricks-openai dipendenza e annota le limitazioni beta.

Il risultato è la stessa app distribuita, con un'interfaccia chat, l'autenticazione e un /invocations endpoint, ma con codice dell'agente più semplice. Per il flusso di lavoro di distribuzione completo (distribuzione in App, aggiungere strumenti, valutare), vedere Creare un agente di intelligenza artificiale e distribuirlo in Databricks Apps.

Strumenti e parametri supportati

Per l'elenco completo dei tipi di strumenti supportati, dei parametri di richiesta e degli esempi di codice, vedere API supervisore (beta).

Per ogni strumento aggiunto, concedere anche l'autorizzazione di risorsa corrispondente in databricks.yml. Per esempio, vedere la add-tools abilità in .claude/skills/ .

Autorizzazione per gli strumenti ospitati

Quando l'API supervisore esegue il ciclo dell'agente, esegue gli strumenti ospitati usando l'identità dell'app o l'identità dell'utente richiedente. Scegliere in base al fatto che tutti gli utenti dell'app debbano condividere lo stesso accesso agli strumenti o che ogni utente debba accedere solo alle autorizzazioni consentite.

  • Autorizzazione dell'app (impostazione predefinita): gli strumenti vengono eseguiti tramite l'entità servizio dell'app. Concedi all'entità servizio le autorizzazioni per ogni strumento utilizzato dall'agente. Vedere Autorizzazione dell'app.
  • Autorizzazione utente: gli strumenti vengono eseguiti come utente che ha inviato la richiesta, quindi le autorizzazioni del catalogo Unity, i filtri di riga e le maschere di colonna si applicano per utente. Vedere la sezione seguente.

Esegui gli strumenti come utente richiedente

Important

L'autorizzazione utente è in anteprima pubblica. L'amministratore dell'area di lavoro deve abilitarlo prima di poter aggiungere ambiti all'app. Vedere Aggiungere ambiti a un'app.

Per eseguire gli strumenti ospitati per conto dell'utente richiedente, inoltrare il token dell'utente al DatabricksOpenAI client e aggiungere gli ambiti di autorizzazione utente necessari agli strumenti.

  1. Aggiungere gli ambiti di autorizzazione utente necessari per l'app. ai-gateway è obbligatorio per qualsiasi accesso all'API Supervisor. Aggiungere l'ambito specifico di ciascuno strumento per ogni tipo di strumento che l'agente utilizza:

    Tipo di strumento Ambito obbligatorio
    Tutti gli strumenti ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    Il app tipo di strumento non è supportato con l'autorizzazione utente. Per chiamare un endpoint dell'app come strumento, utilizzare invece l'autorizzazione dell'app. Per informazioni su come aggiungere ambiti tramite l'interfaccia utente dell'area di lavoro o i bundle di automazione dichiarativa, vedere Autorizzazione utente.

  2. Nel gestore agent.py , passa un client dell'area di lavoro utente a DatabricksOpenAI. Si tratta dell'unico cablaggio specifico del supervisore: invece di chiamare una risorsa direttamente con il client utente, è possibile passarla al client che esegue il ciclo dell'agente.

    from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

    get_user_workspace_client() legge il token utente inoltrato dagli header della richiesta, che vengono popolati solo al momento della query. Chiamalo all'interno dei gestori invoke e stream, mai in __init__ o all'avvio dell'app. Se manca il token inoltrato, il client risultante non viene autenticato come utente richiedente. Per verificare che l'agente venga eseguito come chiamante anziché come entità servizio dell'applicazione, vedere Autorizzazione utente.

  3. Concedere a ogni utente che esegue l'agente l'autorizzazione necessaria per ogni strumento, ad esempio CAN_RUN in uno spazio Genie o CAN_QUERY in un endpoint di Knowledge Assistant.

Risorse aggiuntive

  • Last updated on