Agent Bricks CLI

Ważna

Ta funkcja jest dostępna w wersji beta. Nie jest wymagane żadne ustawienie w przestrzeni roboczej, aby to umożliwić. Zainstaluj CLI Agent Bricks, aby zacząć.

Agent Bricks CLI (databricks-agentbricks) to narzędzie wiersza poleceń Azure Databricks dla programistów, którzy budują i wdrażają niestandardowych agentów w kodzie.

Agent Bricks CLI to oparte przede wszystkim na kodzie rozwiązanie do tworzenia niestandardowych agentów z poziomu terminala. CLI Agent Bricks stanowi fundament projektu wykorzystującego wbudowany framework oparty na najlepszych praktykach Databricks. Następnie może uruchomić projekt lokalnie do testów i wdrożyć go na środowisku uruchomieniowym agenta Azure Databricks. CLI umożliwia przejście z pustego katalogu do wdrożonego agenta bez ręcznego podłączania czasu działania, narzędzi, pamięci i zarządzanych zasobów. Aby poznać inne sposoby tworzenia niestandardowych agentów, w tym workflow oparty na aplikacjach, zobacz Uruchamiaj agentów w aplikacjach Databricks przy użyciu starszego serwera agentów.

Prerequisites

  • Databricks CLI, zainstalowany i dostępny na Twojej ścieżce.

  • Środowisko Python w wersji 3.11 lub nowszej. Pakiet CLI Agent Bricks instaluje się na Pythonie 3.10, ale projekty, które generuje, wymagają Pythona 3.11 lub nowszej wersji. Databricks poleca Python 3.12.

  • uv, który uruchamia wygenerowany projekt dla agentbricks init, agentbricks dev oraz agentbricks deploy.

  • Zainstaluj CLI Agent Bricks. Aby zainstalować go jako narzędzie uv, uruchom następujące polecenie:

    uv tool install databricks-agentbricks

    Aby zamiast tego zainstalować go za pomocą pip, uruchom pip install databricks-agentbricks. Jeśli instalacja się nie powiedzie, zobacz Rozwiązywanie problemów.

Przegląd: od logowania do wdrożonego agenta

Poniższa sekwencja podsumowuje kroki w Tworzenie nowego agenta:

databricks auth login --host "https://<your-workspace-url>" --profile my-workspace
agentbricks login --profile my-workspace
agentbricks init --framework langgraph my-agent
cd my-agent
agentbricks dev
agentbricks deploy my-agent

Wskazówka

Każde polecenie i każda grupa poleceń obsługuje --help. Na przykład uruchom agentbricks memory --help, aby wyświetlić polecenia pamięci i ich flagi.

Cykl życia Agent Bricks CLI

CLI Agent Bricks tworzy lokalny katalog wdrożalnego kodu agenta z szablonu frameworka, z już zainstalowanym interfejsem uruchomieniowym, testami i opcjonalnym interfejsem czatu. Ty piszesz logikę aplikacji (model, narzędzia i prompty), a CLI obsługuje jej uruchamianie lokalnie i wdrażanie na infrastrukturze Azure Databricks.

agent.tomljest deklaratywnym źródłem prawdy dla wszystkich zasobów zarządzanych przez Azure Databricks, na których polega Twój agent: wiązania narzędzi (piaskownica danych, usługi zarządzanego protokołu Model Context (MCP), funkcje katalogu Unity) oraz zasoby pamięci, sesji i śledzenia. agentbricks deploy Odczytuje go, żeby wszystko skonfigurować i podłączyć, więc to plik, a nie ręcznie napisany kod konfiguracyjny, jest tym, co się wdraża.

Trzy polecenia, które przenoszą agenta z pustego katalogu do produkcji:

  • agentbricks init tworzy szkielet projektu z dołączonego szablonu, opcjonalnie tworząc plik .env z profilem Databricks, dzięki czemu można od razu uruchomić projekt.
  • agentbricks dev uruchamia agenta lokalnie względem usługi obsługi modeli w Azure Databricks, dzięki czemu możesz go przetestować przed wdrożeniem.
  • agentbricks deploy udostępnia zasoby zadeklarowane w agent.toml i wdraża agenta w środowisku uruchomieniowym agenta Azure Databricks.

Cykl życia CLI Agent Bricks: fazy init, dev oraz wdrażania wraz z ich kluczowymi działaniami

Note

Możesz też w dowolnym momencie dodawać narzędzia oraz podłączać pamięć i magazyny sesji, nie tylko podczas inicjalizacji. Użyj agentbricks tools add, agentbricks memory bind, oraz agentbricks sessions bind do aktualizacji konfiguracji agenta między tymi krokami.

Możliwości CLI Agent Bricks

Capability Description
Dostęp do modelu CLI Agent Bricks automatycznie udostępnia dostęp do modelu, dzięki czemu agent może wywołać model obsługiwany przez Azure Databricks bez konieczności zarządzania poświadczeniami uwierzytelniającymi czy punktami końcowymi. Zobacz Interfejsy API modelu bazowego Databricks.
Pamięć zarządzana Pamięć długoterminowa, do której agent może zapisywać dane i którą może przeszukiwać, podzielona według aktora i oparta na zarządzanych magazynach danych. Używaj pamięci do przechowywania faktów i preferencji między sesjami oraz użyj agentbricks memory pipeline, aby wyodrębnić wspomnienia z magazynu sesji. Zobacz Pamięć Agent i Potoki pamięci Agent.
Sesje zarządzane Transkrypcje rozmów przechowywane w zarządzanych repozytoriach sesji i podzielone na partycje według aktora, z obsługą rozwidlania sesji na niezależne kopie. Zobacz sesje agentów.
Tools Funkcje zarządzane przez Azure Databricks zadeklarowane w elemencie agent.toml: piaskownica Unity Catalog o ograniczonym zakresie uprawnień, usługa MCP zarządzana przez Azure Databricks lub funkcja Unity Catalog. Niestandardowe narzędzia w języku Python są tworzone bezpośrednio w kodzie projektu. Zobacz MCPs.
Śledzenie Domyślnie włączone śledzenie MLflow, które kieruje ślady każdego uruchomienia do osobnego eksperymentu MLflow dla każdego projektu na potrzeby debugowania i monitorowania. Zobacz przegląd Śledzenia.
Wdrożenie Wdraża agenta do środowiska uruchomieniowego agenta Azure Databricks, przyznaje jednostce usługi agenta dostęp do powiązanych magazynów oraz zarządza cyklem życia wdrożenia.

Stwórz nowego agenta

Krok 1: Uwierzytelnij się za pomocą OAuth i zapisz profil

Agent Bricks CLI wykorzystuje uwierzytelnianie Databricks CLI. Uwierzytelnij się do swojej przestrzeni roboczej za pomocą OAuth (user-to-machine) i zapisz dane uwierzytelniające jako nazwany profil. Wykonaj oba następujące polecenia.

Note

Profil to nazwany zestaw ustawień połączenia (URL przestrzeni roboczej i jego dane uwierzytelniające) zapisany w ~/.databrickscfg. Przykłady na tej stronie wykorzystują profil o nazwie my-workspace. Wybierz dowolną nazwę, a następnie przekaż ją --profile.

  1. Aby rozpocząć przepływ OAuth, uruchom poniższe polecenie, zastępując host adresem URL swojego obszaru roboczego. Polecenie otwiera przeglądarkę, aby zakończyć logowanie, a następnie zapisuje my-workspace profil do ~/.databrickscfg:

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

  2. Aby zweryfikować profil i zapisać go jako domyślny CLI Agent Bricks, aby późniejsze polecenia mogły pominąć --profile, wykonaj następujące czynności:

    agentbricks login --profile my-workspace

    Jeśli brakuje danych uwierzytelniających profilu lub zostały odrzucone, agentbricks login ponownie uruchamia databricks auth login i ponawia próbę.

Krok 2: Wzmocnij projekt agenta

Utwórz nowy projekt agenta i przekaż --framework, aby wybrać szablon. Ten przykład wykorzystuje szablon LangGraph, który zawiera aplikację czatu przeglądarkowego:

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

CLI zawiera po jednym dołączonym szablonie dla każdego frameworka, a --framework wybiera, z którego wygenerować szkielet: langgraph dla LangGraph lub openai dla OpenAI Agents SDK. CLI zapisuje zarządzane zasoby projektu i powiązania narzędzi w agent.toml, a informacje o pochodzeniu szablonu w .agentbricks/project.toml. Aby wygenerować szkielet backendu opartego wyłącznie na API, bez aplikacji czatowej, dodaj --disable-chat-app.

Krok 3: Dołącz zarządzane sesje i magazyny pamięci

Zarządzane magazyny danych pozwalają agentowi zachować historię rozmów i pamięć długoterminową. agentbricks init deklaruje magazyn sesji oraz magazyn pamięci w agent.toml, nazwany od nazwy projektu z losowym sufiksem, takim jak my-agent-cuzvas-memory. agentbricks deploy tworzy każdy zadeklarowany store, który jeszcze nie istnieje, i przyznaje wdrożonemu agentowi dostęp do niego, więc większość agentów może pominąć ten krok.

Aby użyć innego sklepu, powiąż go po nazwie. Każde polecenie zastępuje nazwę magazynu w agent.toml. Nie tworzy sklepu. Aby powiązać magazyn sesji o nazwie my-agent-sessions i magazyn pamięci o nazwie my-agent-memory, wykonaj następujące:

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

Aby uruchomić agenta z wpisami pamięci już w sklepie, utwórz sklep i dodaj wpisy przed wdrożeniem. Zobacz zakładkę CLI Agent Bricks w sekcji Rozpocznij pracę z pamięcią agenta.

Krok 4: Śledzenie widoku

Śledzenie jest domyślnie włączone. agentbricks init wiąże domyślny /Shared/agentbricks_traces/<project>-<suffix> eksperyment MLflow i agentbricks devagentbricks deploy wysyła do niego ślady każdego uruchomienia.

Aby wyświetlić listę śladów po ich wygenerowaniu przez agenta, uruchom poniższe polecenie:

agentbricks tracing list

Aby związać konkretny eksperyment MLflow, uruchom agentbricks tracing bind --experiment-id <experiment-id>. Aby wyłączyć śledzenie, uruchom agentbricks tracing unbind.

Krok 5: Uruchom agenta lokalnie

Uruchom agenta na swoim komputerze, aby przetestować go przed wdrożeniem.

agentbricks dev

Uruchamia to lokalny serwer na porcie 8000, używając tych samych poleceń i środowiska co środowisko uruchomienia agenta Azure Databricks. CLI Agent Bricks łączy agenta z modelem Azure Databricks, dzięki czemu może wywołać model lokalnie. Szablon ustawia model domyślny jako wartość MODEL w agent/agent.py. Aby użyć innego modelu, edytuj tę wartość. Wyślij żądania do http://localhost:8000, aby wchodzić w interakcję z agentem.

Note

agentbricks dev Nie łączy się z pamięcią ani magazynami sesji. Pamięć długoterminowa jest wyłączona, a historia rozmów trwa tylko podczas działania lokalnego serwera. Aplikacja czatu pokazuje Nie połączono dla pamięci lokalnej, nawet gdy magazyn danych jest powiązany. Pamięć nawiązuje połączenie po agentbricks deploy.

Krok 6: Wdroż agenta

Wdróż agenta w środowisku uruchomieniowym agenta Azure Databricks. Interfejs CLI tworzy powiązane magazyny, przyznaje do nich dostęp jednostce usługi agenta i przeprowadza wdrożenie. Wdrożony agent nazywa się agent-bricks-<name>.

agentbricks deploy my-agent

Po zakończeniu wdrożenia CLI zwraca adres URL wdrożenia. Otwórz ten adres URL, aby korzystać z agenta na żywo, który jest automatycznie połączony z obsługą modeli Azure Databricks. Aby zarządzać wdrożeniem po operacji, użyj poleceń agentbricks deployments , takich jak agentbricks deployments logs i agentbricks deployments stop.

Dodaj istniejącego agenta

Jeśli już utworzyłeś agenta w LangGraph lub OpenAI Agents SDK, użyj flagi --existing , aby przenieść go do Agent Bricks CLI i DurableAgentServer. CLI nie przepisuje kodu. Zamiast tego przygotowuje instrukcje migracji, których agent programistyczny, taki jak Claude Code lub Codex, używa do konwersji projektu.

Krok 1: Przygotuj migrację

Z katalogu projektu agenta przygotuj migrację. Podaj framework, którego używa agent: langgraph dla LangGraph lub openai dla OpenAI Agents SDK.

agentbricks init --framework langgraph --existing .

CLI zapisuje agent-bricks-migrate/ katalog zawierający instrukcje migracji, prompt dla agenta kodującego oraz projekt referencyjny wygenerowany z szablonów CLI. Dodaje też umiejętności w .claude/skills/ i .agent/skills/, które kierują agentów kodujących do instrukcji. Polecenie nie zmienia kodu aplikacji, zależności ani pliku .env i nie tworzy żadnych zasobów w twojej przestrzeni roboczej.

Krok 2: Przekonwertuj projekt za pomocą swojego agenta kodującego

Wklej prompt z agent-bricks-migrate/ do swojego agenta kodowego. Agent kodujący konwertuje projekt, aby używać agent.toml oraz punktu wejścia DurableAgentServer, i weryfikuje konwersję.

Krok 3: Sprawdź konwersję

Uruchom agentbricks doctor w katalogu projektu:

agentbricks doctor .

agentbricks doctor sprawdza pliki projektu bez uruchamiania kodu lub kontaktowania się z Azure Databricks. Powodzenie następuje, gdy projekt ma prawidłowe agent.toml, uruchamia DurableAgentServer za pomocą procedury obsługi invoke i wywołuje adapter dla swojego frameworka. Raport zakończony niepowodzeniem oznacza, że konwersja nie jest zakończona.

Krok 4: Posprzątaj, uruchom i wdroż

Usuń agent-bricks-migrate/ i dwa skille, które do niego prowadzą, i nie uwzględniaj ich w swoich commitach. Następnie uruchom agenta za pomocą agentbricks dev i wdróż go za pomocą agentbricks deploy.

Considerations

  • --existingwspiera LangGraph oraz pakiet SDK OpenAI Agents z DurableAgentServer. Nie obsługuje --server custom.
  • Przełączenie agenta do zarządzanego magazynu sesji nie przenosi jego istniejącej historii rozmów. Instrukcje migracji proszą cię, byś zdecydował, jak poradzić sobie z wcześniejszymi rozmowami.
  • Opcje --disable-chat-app, --memory-store i --session-store kształtują projekt referencyjny. Nie tworzą zasobów.

Dodaj narzędzia MCP

Jeśli budujesz agenta z CLI Agent Bricks, dodaj wbudowaną usługę system.ai MCP do swojego projektu z agentbricks tools add mcp. Polecenie sprawdza, czy usługa istnieje w twoim obszarze roboczym i rejestruje narzędzie w agent.toml. Agent łączy się z narzędziem w czasie działania, więc nie piszesz żadnego kodu połączenia.

Aby wypisać usługi MCP, które możesz dodać, wykonaj następujące polecenie:

agentbricks tools list --kind mcp

Poniższe przykłady dodają typowe wbudowane usługi:

# 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

Domyślnie narzędzie uruchamia się z uprawnieniami użytkownika, który wysłał żądanie do Twojego agenta. Aby uruchomić go jako jednostkę usługi aplikacji, dodaj --auth app. Dla Google Drive, Gmaila, Google Kalendarza i Microsoft 365 każdy użytkownik wykonuje jednorazowe logowanie OAuth przed pierwszym wywołaniem. Zobacz Aplikacje połączone.

Aby przeglądać lub usuwać narzędzia, uruchom agentbricks tools list lub agentbricks tools remove mcp <service>.

Inne narzędzia można znaleźć na następujących stronach:

agent.toml odniesienie

agent.tomljest deklaratywnym źródłem prawdy dotyczącym zasobów zarządzanych przez Azure Databricks, których używa Twój agent. agentbricks init tworzy go, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind i agentbricks tracing bind aktualizują go, a następnie agentbricks deploy odczytuje go, aby udostępnić zasoby i przyznać dostęp. Możesz też edytować ją bezpośrednio.

Sekcja lub pole Description
schema_version Wersja formatu agent.toml. Generowane projekty wykorzystują 1.
[agent] framework Szablon frameworka: langgraph lub openai.
[agent] server Serwer agenta: agentbricks dla DurableAgentServer lub custom na własnym serwerze.
[memory_store] name Zarządzany magazyn pamięci, z którego korzysta agent.
[session_store] name Zarządzany magazyn sesji, którego używa agent.
[tracing] experiment_name Eksperyment MLflow dotyczący śladów. Usuń fragment, aby wyłączyć śledzenie.
[[tools]] Powiązanie narzędzia. Każde narzędzie ma id, wartość authuser lub app, oraz source, która identyfikuje narzędzie, plus opcjonalny policy.
[auth.user] Żądaj autoryzacji użytkownika dla narzędzi, które piszesz w kodzie: required oraz additional_api_scopes. Zobacz Autoryzację użytkownika żądania.

Poniższy przykład to plik, który generuje agentbricks init dla agenta LangGraph o nazwie my-agent:

schema_version = 1

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

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

[session_store]
name = "my-agent-cuzvas-sessions"

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

Losowy sufiks (cuzvas w tym przykładzie) jest inny dla każdego projektu, więc projekty o tej samej nazwie nie współdzielą magazynów danych ani eksperymentów.

Poniższy przykład pokazuje przypisania narzędzi, które są zapisywane przez agentbricks tools add: wbudowaną usługę MCP, agenta Genie oraz piaskownicę przypisaną do jednej tabeli:

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

Narzędzia wywołujące funkcję Unity Catalog używają source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } i obsługują tylko auth = "app".

Referencja poleceń

Poniższa tabela przedstawia polecenia CLI Agent Bricks.

Command Description
agentbricks login Uwierzytelnij profil i zapisz go jako domyślny.
agentbricks logout Zapomnij o zapisanym domyślnym profilu bez usuwania jego danych uwierzytelniających.
agentbricks init Utworzyć szkielet projektu nowego agenta lub przygotować istniejącego agenta do migracji przy użyciu --existing.
agentbricks doctor Sprawdź, czy istniejący agent jest skonfigurowany dla CLI Agent Bricks.
agentbricks dev Uruchom agenta lokalnie za pomocą interfejsu czatu.
agentbricks memory Zarządzanie pamięcią długotrwałą: powiąż lub odłącz magazyn oraz zarządzaj magazynami, wpisami i potokami pamięci.
agentbricks sessions Zarządzaj sesjami rozmów: przypisuj lub odłącz magazyn oraz zarządzaj magazynami sesji.
agentbricks tools Wyświetl, dodaj i usuń narzędzia agenta.
agentbricks mcp Odkryj zarządzane usługi MCP.
agentbricks tracing Powiąż, odwiąż i sprawdź śledzenie.
agentbricks deploy Wdróż agenta w środowisku uruchomieniowym agenta Azure Databricks.
agentbricks deployments Zarządzaj rozmieszczonymi agentami: list, get, wait, logs, start, stop oraz delete.
agentbricks endpoint Wywołaj punkt końcowy HTTP.
agentbricks experimental Polecenia eksperymentalne, które mogą się zmieniać bez zapowiedzi: experimental models oraz experimental prompts.

Dla każdej flagi i opcji zobacz referencję do poleceń Agent Bricks CLI na GitHub.

Troubleshooting

Instalacja nie powodzi się na komputerze Mac z procesorem Intel podczas budowania cryptography

Jeśli instalacja nie powiedzie się na komputerze Mac z procesorem Intel podczas kompilowania pakietu cryptography ze źródeł, zamiast tego zainstaluj gotowe pakiety. Aby zainstalować za pomocą pip, uruchom następujące polecenie:

pip install --only-binary :all: databricks-agentbricks

Instalacja lub agentbricks dev kończy się niepowodzeniem z powodu wersji Pythona

Jeśli instalacja lub agentbricks dev nie powiedzie się podczas budowania zależeń, sprawdź wersję Python za pomocą python3 --version. Projekty utworzone z użyciem szablonu wymagają języka Python w wersji 3.11 lub nowszej, a Databricks zaleca Python 3.12. W nowszych wersjach Python niektóre zależności mogą nie mieć gotowych pakietów. Aby zainstalować CLI w Pythonie 3.12, uruchom następujące polecenie:

uv tool install --python 3.12 databricks-agentbricks

Dodatkowe zasoby

  • Ostatnia aktualizacja o