CLI di Agent Bricks

Importante

Questa funzionalità è in versione beta. Non è richiesta alcuna impostazione dello spazio di lavoro per attivarlo. Installa la CLI di Agent Bricks per iniziare.

L'Agent Bricks CLI (databricks-agentbricks) è uno strumento a riga di comando di Azure Databricks per gli sviluppatori che creano e distribuiscono agenti personalizzati in codice.

La CLI di Agent Bricks è un approccio incentrato sul codice per creare agenti personalizzati dal terminale. La CLI Agent Bricks supporta un progetto utilizzando un framework integrato basato sulle best practice di Databrick. Può quindi eseguire il progetto localmente per i test e distribuirlo sull'runtime dell'agente Azure Databricks. La CLI ti permette di passare da una directory vuota a un agente distribuito senza dover collegare runtime, strumenti, memoria e risorse gestite manualmente. Per altri modi per creare agenti personalizzati, incluso il flusso di lavoro basato su app, consulta Eseguire agenti su Databricks Apps usando il server agent legacy.

Prerequisiti

• La CLI Databricks, installata e disponibile sul tuo percorso.

• Python 3.10 o superiore, con pip.

• Installa la CLI di Agent Bricks:

  pip install databricks-agentbricks
  

Il ciclo di vita della CLI di Agent Bricks

La CLI di Agent Bricks genera una directory locale di codice di agente distribuibile a partire da un modello di framework, con il runtime, i test e un'interfaccia utente di chat opzionale già configurati. Scrivi la logica applicativa (modello, strumenti e prompt), e la CLI gestisce l'esecuzione locale e la distribuisce sull'infrastruttura di Azure Databricks.

agent.toml è la fonte dichiarativa di riferimento per tutte le risorse gestite da Azure Databricks da cui dipende il tuo agente: associazioni agli strumenti (sandbox dei dati, servizi gestiti Model Context Protocol (MCP), funzioni di Unity Catalog) e risorse di memoria, sessione e tracciamento. agentbricks deploy lo legge per effettuare il provisioning e collegare e configurare tutto, quindi è il file, non il codice di configurazione scritto a mano, a eseguire il deployment.

I tre comandi che portano un agente da una directory vuota alla produzione:

• agentbricks init crea la struttura del progetto a partire da un modello incluso, popolando facoltativamente il file .env con un profilo Databricks in modo che il progetto possa essere eseguito subito.
• agentbricks devEsegue l'agente localmente contro il modello di Azure Databricks così puoi testarlo prima di distribuire.
• agentbricks deployfornisce le risorse dichiarate in agent.toml e distribuisce l'agente all'runtime dell'agente Azure Databricks.

Note

Puoi anche aggiungere strumenti e associare memoria e archivi sessione in qualsiasi momento, non solo all'init. Usa agentbricks tools add, agentbricks memory bind, e agentbricks sessions bind per aggiornare la configurazione del tuo agente tra uno qualsiasi di questi passaggi.

Funzionalità della CLI di Agent Bricks

Capability	Description
Accesso al modello	La CLI Agent Bricks fornisce automaticamente l'accesso al modello affinché il tuo agente possa chiamare un modello servito da Azure Databricks senza gestire credenziali o endpoint. Vedere API del modello di Databricks Foundation.
Memoria gestita	Memorie a lungo termine che un agente può scrivere e interrogare, suddivise in base all'attore e supportate da archivi gestiti. Usa la memoria per mantenere fatti e preferenze tra le sessioni. Vedere Memoria dell'agente gestito.
Sessioni gestibili	Le trascrizioni delle conversazioni sono conservate in archivi gestiti delle sessioni e suddivise per attore, con supporto per duplicare le sessioni in copie indipendenti. Vedi Sessioni per agenti gestiti.
Tools	Capacità gestite da Azure Databricks dichiarate inagent.toml: un sandbox Unity Catalog ridotto, un servizio MCP gestito da Azure Databricks, o una funzione Unity Catalog. Gli strumenti Python personalizzati sono scritti direttamente nel codice del progetto. Vedi MCPs.
Tracciamento	Tracciamento MLflow attivato per impostazione predefinita, che invia le tracce di ogni esecuzione a un esperimento MLflow dedicato per ciascun progetto per il debug e il monitoraggio. Consulta Panoramica del tracciamento.
Distribuzione	Distribuisce un agente nel runtime dell’agente di Azure Databricks, concede all’entità servizio dell’agente l’accesso agli archivi associati e gestisce il ciclo di vita della distribuzione.

Crea un nuovo agente

Passo 1: Autentica con OAuth e salva un profilo

La CLI Agent Bricks utilizza l'autenticazione della CLI Databricks. Autenticati nel tuo spazio di lavoro con OAuth (da utente a macchina) e salva le credenziali come profilo con nome.

Per avviare il flusso OAuth, esegui il seguente, sostituendo l'host con l'URL del tuo workspace. Il comando apre un browser per completare l'accesso, poi scrive il profilo su ~/.databrickscfg:

databricks auth login --host https://<your-workspace-url> --profile <profile>

Per impostare quel profilo come predefinito della CLI in modo che i comandi successivi possano ometterlo --profile, esegui quanto segue:

agentbricks login --profile <profile>

agentbricks login Valida le credenziali del profilo. Se mancano o vengono rifiutati, la CLI esegue nuovamente databricks auth login e ritenta.

Passo 2: Crea la struttura del progetto dell'agente

Crea un nuovo progetto per un agente e passa --framework per scegliere il modello. Questo esempio utilizza il template LangGraph, che include un'app di chat per browser:

agentbricks init --framework langgraph my-agent
cd my-agent

La CLI include un modello integrato per ciascun framework e --framework seleziona quale usare per generare il progetto: langgraph per LangGraph o openai per l’SDK OpenAI Agents. La CLI scrive le risorse gestite del progetto e le associazioni degli strumenti in agent.toml e la provenienza del modello in .agentbricks/project.toml. Per generare il backend solo API senza l'app di chat, aggiungi --disable-chat-app.

Passo 3: Collega gli archivi gestiti di sessione e memoria

Associa i managed store così il tuo agente può conservare la cronologia delle conversazioni e la memoria a lungo termine. Ogni comando registra il nome dello store in agent.toml e crea lo store se non esiste.

Per collegare un archivio delle sessioni e un archivio di memoria, esegui quanto segue:

agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory

Passo 4: Visualizzare il tracciamento

Il tracciamento è attivo di default. agentbricks init associa un esperimento MLflow predefinito /Shared/agentbricks_traces/<project> e agentbricks dev e agentbricks deploy inviano a esso le tracce di ogni esecuzione.

Per elencare le tracce dopo che il tuo agente ne ha prodotte alcune, esegui quanto segue:

agentbricks tracing list

Per associare un esperimento specifico MLflow, esegui agentbricks tracing bind --experiment-id <experiment-id>. Per disattivare il tracciamento, esegui agentbricks tracing unbind.

Passo 5: Gestisci l'agente localmente

Esegui l'agente sul tuo computer per testarlo prima di metterlo in produzione.

agentbricks dev

Questo avvia un server locale sulla porta 8000 utilizzando lo stesso comando e ambiente dell'runtime dell'agente Azure Databricks. La CLI Agent Bricks collega l'agente al modello Azure Databricks che serve così che possa chiamare il modello localmente. Il template imposta MODEL come valore predefinito del modello in agent/agent.py. Per usare un modello diverso, modifica quel valore. Invia richieste a http://localhost:8000 per interagire con l'agente.

Passaggio 6: Distribuisci l'agente

Distribuisci l'agente nell'runtime dell'agente Azure Databricks. La CLI effettua il provisioning degli archivi associati, concede all'entità servizio dell'agente l'accesso a tali archivi e avvia la distribuzione. L'agente schierato si chiama agent-bricks-<name>.

agentbricks deploy my-agent

Quando la distribuzione termina, la CLI restituisce l'URL della distribuzione. Apri quell'URL per interagire con il tuo agente live, che viene automaticamente collegato a Azure Databricks model serving. Per gestire il dispiegamento successivo, si utilizzano i agentbricks deployments comandi, come agentbricks deployments logs e agentbricks deployments stop.

Porta un agente già esistente

Se hai già sviluppato un agente con LangGraph o OpenAI Agents SDK, usa il flag --existing per spostarlo nella CLI di Agent Bricks e DurableAgentServer. La CLI non riscrive il tuo codice. Invece, prepara istruzioni di migrazione che un agente di codifica, come Claude Code o Codex, segue per convertire il progetto.

Passo 1: Prepara la migrazione

Dalla directory del progetto dell'agente, prepara la migrazione. Passa il framework che l'agente utilizza: langgraph per LangGraph o openai per l'SDK OpenAI Agents.

agentbricks init --framework langgraph --existing .

La CLI scrive una agent-bricks-migrate/ directory che contiene le istruzioni di migrazione, un prompt per il tuo agente di codifica e un progetto di riferimento generato dai template della CLI. Aggiunge anche competenze in .claude/skills/ e .agent/skills/ che indirizzano gli agenti di codifica alle istruzioni. Il comando non cambia il codice dell'applicazione, le dipendenze o il file .env, e non crea risorse nel tuo spazio di lavoro.

Passo 2: Converti il progetto con il tuo agente di coding

Incolla il prompt da agent-bricks-migrate/ nel tuo agente di codifica. L'agente di codifica converte il progetto per utilizzare agent.toml e un entrypoint DurableAgentServer e verifica la conversione.

Passo 3: Controlla la conversione

Esegui agentbricks doctor nella directory del progetto:

agentbricks doctor .

agentbricks doctorispeziona i file del progetto senza eseguire il suo codice o contattare Azure Databricks. Ha successo quando il progetto ha un agent.toml valido, inizia DurableAgentServer con un gestore di invocazione e chiama l'adattatore per il suo framework. Un rapporto non riuscito significa che la conversione non è completata.

Passo 4: Pulire, eseguire e distribuire

Elimina agent-bricks-migrate/ e le due abilità che puntano a esso, e tienile fuori dai tuoi commit. Poi esegui l'agente con agentbricks dev e distribuiscilo con agentbricks deploy.

Considerazioni

• --existing supporta LangGraph e l'SDK degli agenti OpenAI con DurableAgentServer. Non supporta --server custom.
• Passare l'agente a un archivio delle sessioni gestito non sposta la cronologia delle conversazioni esistente. Le istruzioni di migrazione ti chiedono di decidere come gestire le conversazioni precedenti.
• Le opzioni --disable-chat-app, --memory-store e --session-store modellano il progetto di riferimento. Non creano risorse.

Aggiungi strumenti MCP

Se costruisci il tuo agente con la CLI Agent Bricks, aggiungi un servizio MCP integrato system.ai al tuo progetto con agentbricks tools add mcp. Il comando verifica che il servizio esista nel tuo spazio di lavoro e registra lo strumento in agent.toml. L'agent si connette allo strumento in runtime, quindi non scrivi alcun codice di connessione.

Per elencare i servizi MCP che puoi aggiungere, esegui il seguente comando:

agentbricks tools list --kind mcp

I seguenti esempi aggiungono servizi integrati comuni:

# Answer analytics questions across your workspace with Genie One.
agentbricks tools add mcp system.ai.genie_one_mcp

# Run SQL on a SQL warehouse.
agentbricks tools add mcp system.ai.dbsql

# Connect to third-party applications.
agentbricks tools add mcp system.ai.slack
agentbricks tools add mcp system.ai.github

Per impostazione predefinita, uno strumento funziona con i permessi dell'utente che ha inviato la richiesta al tuo agente. Per eseguirlo come entità servizio dell'app, aggiungi --auth app. Per Google Drive, Gmail, Google Calendar e Microsoft 365, ogni utente effettua un login OAuth una tantum prima della prima chiamata. Consulta applicazioni connesse.

Per rivedere o rimuovere gli strumenti, esegui agentbricks tools list o agentbricks tools remove mcp <service>.

Per altri strumenti, vedi le seguenti pagine:

• Tutti servizi integrati e cosa fanno: MCP forniti da Databricks.
• I tuoi server MCP esterni: server MCP esterni.
• Unity Catalog funziona da strumento: Crea strumenti agente usando le funzioni di Unity Catalog.
• Un unico Genie Agent curato: server MCP di Genie Agent (legacy).

agent.toml Riferimento

agent.toml è l'origine dichiarativa attendibile per le risorse gestite da Azure Databricks che il tuo agente utilizza. agentbricks init lo crea, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind, e agentbricks tracing bind lo aggiornano, e agentbricks deploy lo legge per fornire risorse e concedere accesso. Puoi anche modificarla direttamente.

Sezione o campo	Description
schema_version	La versione del formato agent.toml. I progetti generati utilizzano 1.
[agent] framework	Il modello di framework: langgraph oppure openai.
[agent] server	Il server dell'agente: agentbricks per DurableAgentServer, o custom per il tuo server personale.
[memory_store] name	L'archivio di memoria gestita che l'agente utilizza.
[session_store] name	L'archivio sessioni gestito usato dall'agente.
[tracing] experiment_name	L'esperimento MLflow per le tracce. Deseleziona la casella per disattivare il tracciamento.
[[tools]]	Un'associazione di strumenti. Ogni strumento ha un id, un valore auth di user o app, e un source che identifica lo strumento, più un opzionale policy.
[auth.user]	Richiedi l'autorizzazione dell'utente per gli strumenti che scrivi in codice: required e additional_api_scopes. Vedi "Richiesta - autorizzazione utente".

Il seguente esempio è il file che agentbricks init genera per un agente LangGraph chiamato my-agent:

schema_version = 1

[agent]
framework = "langgraph"
server = "agentbricks"

[memory_store]
name = "my-agent-memory"

[session_store]
name = "my-agent-session"

[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent"

Il seguente esempio mostra i binding degli strumenti che agentbricks tools add scrive: un servizio MCP integrato, un Genie Agent e un sandbox con ambito limitato a una sola tabella:

[[tools]]
id = "web_search"
auth = "user"
source = { kind = "mcp", service = "system.ai.web_search" }

[[tools]]
id = "genie_agent"
auth = "user"
source = { kind = "genie_agent", space_id = "<space-id>" }

[[tools]]
id = "sandbox"
auth = "user"
source = { kind = "sandbox", service = "system.ai.sandbox" }
policy = { downscope = [{ resource = "table:samples.nyctaxi.trips", permission = "read_only" }] }

Gli strumenti che chiamano una funzione del Catalogo Unity utilizzano source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } e supportano solo auth = "app".

Informazioni di riferimento sui comandi

Per il riferimento completo ai comandi up-to-date, inclusi tutti i comandi e i flag, consulta l'Agent Bricks CLI README su GitHub.

Risorse aggiuntive

• Strumenti per agenti e servizi MCP: MCP.
• Concetti di memoria e API di agente gestito: memoria gestita per agenti.
• Concetti e API delle sessioni dell'agente gestito.
• MLflow Tracciamento per agenti: panoramica del tracciamento.