Agent Bricks CLI

Agent Bricks CLI (databricks-agentbricks) är ett kommandoradsverktyg för Azure Databricks för utvecklare som bygger och distribuerar anpassade agenter i kod.

Agent Bricks CLI är ett kodfokuserat sätt att bygga anpassade agenter via terminalen. Agent Bricks CLI bygger upp ett projekt med ett inbyggt ramverk baserat på Databricks bästa praxis. Den kan sedan köra projektet lokalt för testning och distribuera det till Azure Databricks agentens runtime. CLI:n gör det möjligt att gå från en tom katalog till en distribuerad agent utan att koppla ihop runtime, verktyg, minne och hanterade resurser manuellt. För andra sätt att bygga anpassade agenter, inklusive appbaserade arbetsflöden, se Kör agenter på Databricks Apps med den äldre agentservern.

Förutsättningar

• Databricks CLI, installerat och tillgängligt i din PATH.

• Python 3.10 eller högre, med pip.

• Installera Agent Bricks CLI:

  pip install databricks-agentbricks
  

Agent Bricks CLI-livscykel

Agent Bricks CLI bygger upp en lokal katalog med distribuerbar agentkod från en ramramsmall, med runtime, tester och ett valfritt chattgränssnitt redan kopplat. Du skriver applikationslogiken (modell, verktyg och prompts), och CLI:n hanterar att köra den lokalt och distribuera den till Azure Databricks infrastruktur.

agent.tomlär den deklarativa sanningskällan för alla Azure Databricks-hanterade resurser som din agent är beroende av: verktygsbindningar (datasandbox, hanterade Model Context Protocol (MCP)-tjänster, Unity Catalog-funktioner) samt minnes-, sessions- och spårningsresurser. agentbricks deploy läser den för att provisionera och koppla ihop allt, så filen, inte handskriven installationskod, är det som distribueras.

De tre kommandon som tar en agent från en tom katalog till produktion:

• agentbricks init skapar projektet utifrån en medföljande mall och kan eventuellt förifylla en .env-fil med en Databricks-profil så att projektet kan köras direkt.
• agentbricks devkör agenten lokalt mot Azure Databricks modelltjänst så att du kan testa den innan du distribuerar.
• agentbricks deploytillhandahåller de resurser som deklarerats i agent.toml och rullar ut agenten till Azure Databricks agentruntime.

Agent Bricks CLI-funktioner

Skapa en ny agent

Steg 1: Autentisera med OAuth och spara en profil

Agent Bricks CLI använder Databricks CLI-autentisering. Autentisera dig mot din arbetsyta med OAuth (user-to-machine) och spara inloggningsuppgifterna som en namngiven profil.

För att starta OAuth-flödet kör du följande och ersätter värdnamnet med arbetsytans URL. Kommandot öppnar en webbläsare för att slutföra inloggningen, och skriver sedan profilen till ~/.databrickscfg:

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

För att sätta den profilen som CLI:s standard så att senare kommandon kan utelämnas --profile, kör följande:

agentbricks login --profile <profile>

agentbricks login Validerar profilens behörighet. Om de saknas eller avvisas kör CLI:t om databricks auth login och försöker igen.

Steg 2: Bygg upp agentprojektet

Skapa ett nytt agentprojekt och ange --framework för att välja mallen. Detta exempel använder LangGraph-mallen, som inkluderar en webbläsarchattapp:

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

CLI:n levererar en medföljande mall per ramverk och --framework väljer vilken som ska byggas från: langgraph för LangGraph eller openai för OpenAI Agents SDK. CLI:n skriver projektets hanterade resurser och verktygsbindningar till agent.toml och mallproveniens till .agentbricks/project.toml. För att skapa ett API-baserat backend utan chattappen, lägg till --disable-chat-app.

Steg 3: Bifoga hanterade sessions- och minneslagringar

Anslut hanterade lagringsplatser så att din agent kan spara samtalshistorik och långtidsminne. Varje kommando registrerar butikens namn agent.toml och skapar butiken om det inte finns.

För att koppla en sessionslagring till en minneslagring, kör följande:

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

Steg 4: Visa spårning

Spårning är påslagen som standard. agentbricks init binder ett standardexperiment /Shared/agentbricks_traces/<project> i MLflow, och agentbricks dev och agentbricks deploy skickar spåren från varje körning dit.

Om du vill lista spårningar efter att din agent har genererat några, kör följande:

agentbricks tracing list

För att binda ett specifikt MLflow-experiment, kör agentbricks tracing bind --experiment-id <experiment-id>. För att stänga av spårningen, spring.agentbricks tracing unbind

Steg 5: Kör agenten lokalt

Kör agenten på din dator för att testa den innan du distribuerar.

agentbricks dev

Detta startar en lokal server på port 8000 med samma kommando och miljö som Azure Databricks agents runtime. Agent Bricks CLI kopplar agenten till Azure Databricks modellserving så att den kan anropa modellen lokalt. Mallen sätter en standardmodell som MODEL värdet i agent/agent.py. För att använda en annan modell, redigera det värdet. Skicka förfrågningar till http://localhost:8000 för att interagera med agenten.

Steg 6: Sätt ut agenten

Distribuera agenten till Azure Databricks agentruntime. CLI tillhandahåller de bundna lagrena, ger agentens tjänstehuvudperson tillgång till dem och rullar ut distributionen. Den utplacerade agenten heter agent-bricks-<name>.

agentbricks deploy my-agent

När distributionen är klar returnerar CLI:n distributionens URL. Öppna den URL:en för att interagera med din live-agent, som automatiskt är kopplad till Azure Databricks modellserving. För att hantera utplaceringen efteråt, använd kommandona agentbricks deployments , såsom agentbricks deployments logs och agentbricks deployments stop.

Ta med en befintlig agent

Om du redan har byggt en agent med LangGraph eller OpenAI Agents SDK, använd flaggan --existing för att flytta den till Agent Bricks CLI och använda DurableAgentServer. CLI:n skriver inte om din kod. Istället förbereder den migreringsinstruktioner som en kodagent, såsom Claude Code eller Codex, följer för att konvertera projektet.

Steg 1: Förbered migrationen

Från agentens projektkatalog, förbered migreringen. Ange ramverket som agenten använder: langgraph för LangGraph eller openai för OpenAI Agents SDK.

agentbricks init --framework langgraph --existing .

CLI:n skriver en agent-bricks-migrate/ katalog som innehåller migreringsinstruktionerna, en prompt för din kodagent och ett referensprojekt genererat från CLI:ns mallar. Det lägger också till färdigheter i .claude/skills/ och .agent/skills/ som vägleder kodningsagenter till instruktionerna. Kommandot ändrar inte din applikationskod, beroenden eller .env fil, och skapar inga resurser i din arbetsyta.

Steg 2: Konvertera projektet med din kodningsagent

Klistra in prompten från agent-bricks-migrate/ i din kodagent. Kodningsagenten omvandlar projektet för att använda agent.toml och en DurableAgentServer entrypoint, och verifierar konverteringen.

Steg 3: Kontrollera konverteringen

Kör agentbricks doctor i projektkatalogen:

agentbricks doctor .

agentbricks doctorinspekterar projektets filer utan att köra dess kod eller kontakta Azure Databricks. Det lyckas när projektet har en giltig agent.toml, startar DurableAgentServer med en invoke handler och anropar adaptern för dess ramverk. En misslyckad rapport betyder att konverteringen inte är klar.

Steg 4: Städa, köra och driftsätta

Ta bort agent-bricks-migrate/ och de två skills som pekar på det, och håll dem utanför dina commits. Kör sedan agenten med agentbricks dev och distribuera den med agentbricks deploy.

Considerations

• --existing stöder LangGraph och OpenAI Agents SDK med DurableAgentServer. Den stöder inte --server custom.
• Att byta agenten till en hanterad sessionsbutik flyttar inte dess befintliga konversationshistorik. Migreringsinstruktionerna ber dig bestämma hur du ska hantera tidigare samtal.
• --disable-chat-app, --memory-store och --session-store-alternativen formar referensprojektet. De skapar inte resurser.

Lägg till MCP-verktyg

Om du bygger din agent med Agent Bricks CLI, lägg till en inbyggd system.ai MCP-tjänst i ditt projekt med agentbricks tools add mcp. Kommandot kontrollerar att tjänsten finns i din arbetsyta och registrerar verktyget i agent.toml. Agenten ansluter till verktyget vid körning, så du skriver ingen anslutningskod.

För att lista de MCP-tjänster du kan lägga till, kör följande kommando:

agentbricks tools list --kind mcp

Följande exempel lägger till vanliga inbyggda tjänster:

# 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

Som standard körs ett verktyg med behörigheterna för den användare som skickade förfrågan till din agent. För att köra den som appens service principal i stället, lägg till --auth app. För Google Drive, Gmail, Google Kalender och Microsoft 365 genomför varje användare en engångsinloggning med OAuth innan det första anropet. Se Anslutna applikationer.

För att granska eller ta bort verktyg, kör agentbricks tools list eller agentbricks tools remove mcp <service>.

För andra verktyg, se följande sidor:

• Alla inbyggda tjänster och vad de gör: Databricks-levererade MCP:er.
• Dina egna externa MCP-servrar: Externa MCP-servrar.
• Unity Catalog fungerar som verktyg: Skapa agentverktyg med hjälp av Unity Catalog-funktioner.
• En enda kurerad Genie Agent: Genie Agent MCP-server (legacy).

agent.toml Referens

agent.tomlär den deklarativa sanningskällan för de Azure Databricks-hanterade resurser som din agent använder. agentbricks init skapar den, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind, och agentbricks tracing bind uppdaterar den, och agentbricks deploy läser den för att provisionera resurser och ge åtkomst. Du kan också redigera det direkt.

Följande exempel är filen som agentbricks init genererar för en LangGraph-agent med namnet 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"

Följande exempel visar verktygsbindningar som agentbricks tools add skapar: en inbyggd MCP-tjänst, en Genie Agent och en sandlåda begränsad till en tabell:

[[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" }] }

Verktyg som anropar en Unity-katalogfunktion använder source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } och stöder endast auth = "app".

Referens för kommandon

För den fullständiga och aktuella kommandoreferensen med alla kommandon och flaggor, se Agent Bricks CLI README på GitHub.

Ytterligare resurser

• Agentverktyg och MCP-tjänster: MCP:er.
• Koncept och API för hanterat agentminne: Hanterat agentminne.
• Koncept för hanterade agentsessioner och API: Hanterade agentsessioner.
• MLflow Tracing för agenter: Översikt över spårning.