Agent Bricks CLI

Important

Dieses Feature befindet sich in der Betaversion. Es ist keine Arbeitsbereichseinstellung erforderlich, um sie zu aktivieren. Installiere die Agent Bricks CLI, um loszulegen.

Die Agent Bricks CLI (databricks-agentbricks) ist ein Azure Databricks-Kommandozeilen-Tool für Entwickler, die benutzerdefinierte Agenten im Code erstellen und bereitstellen.

Die Agent Bricks CLI ist ein codeorientierter Ansatz zum Erstellen benutzerdefinierter Agenten über das Terminal. Die Agent Bricks CLI unterstützt ein Projekt mit einem integrierten Framework, das auf den besten Praktiken von Databricks basiert. Anschließend kann es das Projekt lokal zu Testzwecken ausführen und in der Azure-Databricks-Agent-Runtime bereitstellen. Die CLI ermöglicht es Ihnen, von einem leeren Verzeichnis zu einem bereitgestellten Agenten zu wechseln, ohne Laufzeit, Tools, Speicher und verwaltete Ressourcen manuell zu verdrahten. Für weitere Möglichkeiten, benutzerdefinierte Agenten zu erstellen, einschließlich des app-basierten Workflows, siehe Run agents on Databricks Apps using the legacy agent server.

Voraussetzungen

  • Die Databricks-CLI, installiert und in Ihrem PATH verfügbar.

  • Python 3.10 oder höher, mit pip.

  • Installiere die Agent Bricks CLI:

    pip install databricks-agentbricks

Der Agent Bricks CLI-Lebenszyklus

Die Agent Bricks CLI erstellt auf Basis einer Framework-Vorlage ein lokales Verzeichnis mit bereitstellbarem Agentencode, wobei die Laufzeit, Tests und eine optionale Chat-Benutzeroberfläche bereits vorkonfiguriert sind. Du schreibst die Anwendungslogik (Modell, Werkzeuge und Prompts), und die CLI übernimmt den lokalen Betrieb und die Bereitstellung auf der Azure Databricks-Infrastruktur.

agent.tomlist die deklarative Wahrheitsquelle für alle von Azure Databricks verwalteten Ressourcen, auf die Ihr Agent angewiesen ist: Tool-Bindings (Data Sandbox, verwaltete Model Context Protocol (MCP)-Dienste, Unity Catalog-Funktionen) sowie Speicher-, Session- und Tracing-Ressourcen. agentbricks deploy liest sie ein, um alles bereitzustellen und zu konfigurieren, sodass die Bereitstellung durch die Datei und nicht durch handgeschriebenen Setup-Code erfolgt.

Die drei Befehle, die einen Agenten von einem leeren Verzeichnis in die Produktion bringen:

  • agentbricks init erstellt das Projekt auf Grundlage einer mitgelieferten Vorlage und belegt optional eine .env-Datei mit einem Databricks-Profil vor, so dass das Projekt sofort ausgeführt werden kann.
  • agentbricks devführt den Agenten lokal gegen Azure Databricks Model Serving aus, damit du ihn vor der Bereitstellung testen kannst.
  • agentbricks deploy stellt die in agent.toml deklarierten Ressourcen bereit und stellt den Agent in der Azure Databricks-Agent-Laufzeitumgebung bereit.

Agent Bricks CLI-Lebenszyklus: Init-, Entwicklungs- und Deployment-Phasen mit ihren wichtigsten Aktionen

Note

Du kannst auch jederzeit Werkzeuge hinzufügen und Speicher- und Sitzungsspeicher binden, nicht nur bei init. Verwenden Sie agentbricks tools add, agentbricks memory bind und agentbricks sessions bind, um Ihre Agentenkonfiguration zwischen beliebigen dieser Schritte zu aktualisieren.

Agent Bricks CLI-Funktionen

Fähigkeit Description
Modellzugang Die Agent Bricks CLI stellt automatisch den Zugriff auf das Modell bereit, sodass Ihr Agent ein Azure Databricks-Servated-Modell aufrufen kann, ohne Zugangsdaten oder Endpunkte verwalten zu müssen. Siehe Databricks Foundation Model-APIs.
Verwalteter Speicher Langzeitspeicher, die ein Agent schreiben und durchsuchen kann, nach Akteuren partitioniert und von verwalteten Speichern gesichert. Nutze das Gedächtnis, um Fakten und Präferenzen über die Sitzungen hinweg zu speichern. Siehe verwalteter Agentspeicher.
Verwaltete Sitzungen Gesprächstranskripte werden in verwalteten Sitzungsspeichern gehalten und nach Akteuren partitioniert, mit Unterstützung für das Aufteilen von Sitzungen in unabhängige Kopien. Siehe Managed Agent-Sitzungen.
Tools Azure Databricks-verwaltete Fähigkeiten, deklariert in agent.toml: einer verkleinerten Unity-Catalog-Sandbox, einem von Azure Databricks verwalteten MCP-Service oder einer Unity-Catalog-Funktion. Benutzerdefinierte Python-Tools sind direkt im Projektcode geschrieben. Siehe MCPs.
Ablaufverfolgung Das standardmäßig aktivierte MLflow-Tracing leitet die Traces jedes Durchlaufs zur Fehlerbehebung und Überwachung an ein eigenes MLflow-Experiment pro Projekt weiter. Siehe Übersicht zur Nachverfolgung.
Einsatz Stellt einen Agenten in der Azure-Databricks-Agent-Laufzeitumgebung bereit, gewährt dem Dienstprinzipal des Agenten Zugriff auf zugeordneten Speicher und verwaltet den Bereitstellungslebenszyklus.

Erstelle einen neuen Agenten

Schritt 1: Authentifizieren Sie sich bei OAuth und speichern Sie ein Profil

Die Agent Bricks CLI verwendet die Databricks CLI-Authentifizierung. Authentifiziere dich in deinem Arbeitsbereich mit OAuth (User-to-Machine) und speichere die Zugangsdaten als benanntes Profil.

Um den OAuth-Flow zu starten, führe Folgendes aus und ersetze den Host durch deine Workspace-URL. Der Befehl öffnet einen Browser, um die Anmeldung abzuschließen, und schreibt dann das Profil nach ~/.databrickscfg:

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

Um dieses Profil als Standardprofil der CLI festzulegen, sodass Sie --profile in späteren Befehlen weglassen können, führen Sie Folgendes aus:

agentbricks login --profile <profile>

agentbricks login überprüft die Profildaten. Wenn sie fehlen oder abgelehnt werden, führt die CLI databricks auth login erneut aus und versucht es erneut.

Schritt 2: Unterstützen Sie das Agentenprojekt

Erstellen Sie ein neues Agentenprojekt, und geben Sie --framework an, um die Vorlage auszuwählen. Dieses Beispiel verwendet die LangGraph-Vorlage, die eine Browser-Chat-App enthält:

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

Die CLI enthält pro Framework eine mitgelieferte Vorlage, und --framework wählt aus, welche davon als Grundlage für das Gerüst verwendet wird: langgraph für LangGraph oder openai für das OpenAI Agents SDK. Die CLI schreibt die verwalteten Ressourcen und Werkzeugbindungen des Projekts auf agent.toml und die Vorlagenherkunft auf .agentbricks/project.toml. Um das reine API-Backend ohne die Chat-App zu generieren, fügen Sie --disable-chat-app hinzu.

Schritt 3: Verwaltete Sitzungs- und Arbeitsspeicher einbinden

Binden Sie verwaltete Stores ein, damit Ihr Agent die Gesprächshistorie und das Langzeitgedächtnis dauerhaft speichern kann. Jeder Befehl speichert den Store-Namen in agent.toml und erstellt den Store, falls er noch nicht vorhanden ist.

Um einen Session-Speicher und einen Speicherspeicher zu binden, führen Sie Folgendes aus:

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

Schritt 4: Ablaufverfolgung anzeigen

Das Nachverfolgen ist standardmäßig aktiviert. agentbricks init verknüpft ein Standard-/Shared/agentbricks_traces/<project> MLflow-Experiment, und agentbricks dev und agentbricks deploy senden die Ablaufverfolgungen jeder Ausführung dorthin.

Um Ablaufverfolgungen aufzulisten, nachdem Ihr Agent welche erstellt hat, führen Sie Folgendes durch:

agentbricks tracing list

Um ein bestimmtes MLflow-Experiment zu binden, führe agentbricks tracing bind --experiment-id <experiment-id>. Um das Tracing zu deaktivieren, führen Sie agentbricks tracing unbind aus.

Schritt 5: Führen Sie den Agenten lokal aus

Führe den Agenten auf deinem Rechner aus, um ihn vor der Bereitstellung zu testen.

agentbricks dev

Dies startet einen lokalen Server auf Port 8000 mit demselben Befehl und derselben Umgebung wie die Laufzeitumgebung des Azure Databricks Agenten. Die Agent Bricks CLI verbindet den Agenten mit dem Azure Databricks Model Serving und kann das Modell lokal aufrufen. Die Vorlage setzt ein Standardmodell als den MODEL Wert in agent/agent.py. Um ein anderes Modell zu verwenden, bearbeite diesen Wert. Senden Sie Anfragen an http://localhost:8000, um mit dem Agenten zu interagieren.

Schritt 6: Setzen Sie den Agenten ein

Deploye den Agenten in der Azure Databricks Agent-Runtime. Die CLI stellt die zugeordneten Speicherressourcen bereit, gewährt dem Service Principal des Agents Zugriff darauf und führt die Bereitstellung durch. Der eingesetzte Agent heißt agent-bricks-<name>.

agentbricks deploy my-agent

Wenn die Bereitstellung abgeschlossen ist, gibt die CLI die URL der Bereitstellung zurück. Öffnen Sie diese URL, um mit Ihrem Live-Agenten zu interagieren, der automatisch mit der Modellbereitstellung von Azure Databricks verbunden ist. Um die anschließende Bereitstellung zu verwalten, verwenden Sie die agentbricks deployments Befehle wie agentbricks deployments logs und agentbricks deployments stop.

Bringen Sie einen bestehenden Agenten mit

Wenn du bereits einen Agenten mit LangGraph oder dem OpenAI Agents SDK gebaut hast, nutze das --existing-Flag, um ihn in die Agent Bricks CLI zu verschieben und DurableAgentServer. Die CLI schreibt deinen Code nicht um. Stattdessen bereitet es Migrationsanweisungen vor, die ein Codierungsagent wie Claude Code oder Codex befolgt, um das Projekt zu konvertieren.

Schritt 1: Bereite die Migration vor

Bereite aus dem Projektverzeichnis des Agenten die Migration vor. Übergeben Sie das Framework, das der Agent verwendet: langgraph für LangGraph oder openai für das OpenAI Agents SDK.

agentbricks init --framework langgraph --existing .

Die CLI schreibt ein agent-bricks-migrate/ Verzeichnis, das die Migrationsanweisungen, einen Prompt für Ihren Coding-Agenten und ein Referenzprojekt enthält, das aus den CLI-Vorlagen generiert wurde. Es fügt außerdem Fähigkeiten in .claude/skills/ und .agent/skills/ hinzu, die Codierungsagenten auf die Anweisungen verweisen. Der Befehl ändert weder deinen Anwendungscode, deine Abhängigkeiten noch die .env-Datei und erzeugt keine Ressourcen in deinem Arbeitsbereich.

Schritt 2: Konvertiere das Projekt mit deinem Coding-Agenten

Füge den Prompt aus agent-bricks-migrate/ in deinen Coding-Agenten ein. Der Coding-Agent wandelt das Projekt für die Verwendung von agent.toml und einem DurableAgentServer-Einstiegspunkt um und überprüft die Umwandlung.

Schritt 3: Überprüfe die Umwandlung

Führen Sie agentbricks doctor im Projektverzeichnis aus:

agentbricks doctor .

agentbricks doctor überprüft die Projektdateien, ohne den Code des Projekts auszuführen oder Azure Databricks zu kontaktieren. Dies funktioniert, wenn das Projekt ein gültiges agent.toml hat, mit DurableAgentServer mit einem Aufruf-Handler startet und den Adapter für sein Framework aufruft. Ein fehlgeschlagener Status bedeutet, dass die Umwandlung nicht abgeschlossen ist.

Schritt 4: Aufräumen, ausführen und bereitstellen

Lösche agent-bricks-migrate/ und die beiden Verweise, die darauf hinweisen, und halte sie aus deinen Commits raus. Dann führe den Agenten mit agentbricks dev aus und deploye ihn mit agentbricks deploy.

Considerations

  • --existing unterstützt LangGraph und das OpenAI Agents SDK mit DurableAgentServer. Es unterstützt --server custom nicht.
  • Das Wechseln des Agenten in einen verwalteten Sitzungsspeicher überträgt seine bestehende Konversationshistorie nicht. Die Migrationsanweisungen bitten Sie, zu entscheiden, wie Sie mit früheren Unterhaltungen umgehen.
  • Die Optionen --memory-store, --disable-chat-app und --session-store prägen das Referenzprojekt. Sie schaffen keine Ressourcen.

MCP-Werkzeuge hinzufügen

Wenn Sie Ihren Agent mit der Agent Bricks CLI erstellen, fügen Sie Ihrem Projekt mit system.ai einen integrierten agentbricks tools add mcp MCP-Service hinzu. Der Befehl prüft, ob der Dienst in Ihrem Arbeitsbereich existiert, und erfasst das Tool in agent.toml. Der Agent verbindet sich zur Laufzeit mit dem Tool, sodass du keinen Verbindungscode schreibst.

Um die MCP-Dienste aufzulisten, die Sie hinzufügen können, führen Sie folgenden Befehl aus:

agentbricks tools list --kind mcp

Die folgenden Beispiele fügen gemeinsame integrierte Dienste hinzu:

# 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

Standardmäßig läuft ein Tool mit den Berechtigungen des Benutzers, der die Anfrage an deinen Agenten gesendet hat. Um sie stattdessen als Service Principal der App auszuführen, füge --auth app hinzu. Für Google Drive, Gmail, Google Kalender und Microsoft 365 führt jeder Nutzer vor dem ersten Aufruf einen einmaligen OAuth-Login durch. Siehe Verknüpfte Anwendungen.

Um Werkzeuge zu überprüfen oder zu entfernen, starte agentbricks tools list oder agentbricks tools remove mcp <service>.

Weitere Werkzeuge finden Sie auf den folgenden Seiten:

agent.toml Referenz

agent.tomlist die deklarative Wahrheitsquelle für die von Azure Databricks verwalteten Ressourcen, die dein Agent verwendet. agentbricks init erstellt es, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind und agentbricks tracing bind aktualisieren es, und agentbricks deploy liest es, um Ressourcen bereitzustellen und Zugriff zu gewähren. Du kannst es auch direkt bearbeiten.

Abschnitt oder Feld Description
schema_version Die Version des Formats agent.toml . Generierte Projekte verwenden 1.
[agent] framework Die Rahmenvorlage: langgraph oder openai.
[agent] server Der Agent-Server: agentbricks für DurableAgentServer, oder custom für Ihren eigenen Server.
[memory_store] name Der verwaltete Speicher, den der Agent verwendet.
[session_store] name Der verwaltete Sitzungsspeicher, den der Agent verwendet.
[tracing] experiment_name Das MLflow-Experiment für Traces. Heben Sie die Auswahl auf, um das Nachzeichnen auszuschalten.
[[tools]] Eine Tool-Zuordnung. Jedes Werkzeug hat einen id, einen auth Wert von user oder app, und ein source, der das Werkzeug identifiziert, plus ein optionales policy.
[auth.user] Benutzerautorisierung für Werkzeuge anfordern, die du im Code schreibst: required und additional_api_scopes. Siehe Benutzerautorisierung anfordern.

Das folgende Beispiel ist die Datei, die agentbricks init für einen LangGraph-Agenten mit dem Namen my-agent generiert:

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"

Das folgende Beispiel zeigt Tool-Bindings, die agentbricks tools add erstellt: einen integrierten MCP-Service, einen Genie-Agent und eine auf eine Tabelle beschränkte Sandbox:

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

Tools, die eine Unity Catalog-Funktion aufrufen, verwenden source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } und unterstützen nur auth = "app".

Befehlsreferenz

Die vollständige, aktuelle Befehlsreferenz einschließlich aller Befehle und Flags finden Sie in der Agent Bricks CLI README auf GitHub.

Weitere Ressourcen

  • Zuletzt aktualisiert um