Agent Bricks CLI

Important

Tato funkce je v beta verzi. K jeho zapnutí není potřeba žádné nastavení pracovního prostoru. Nainstalujte CLI Agent Bricks a začněte s tím.

Agent Bricks CLI (databricks-agentbricks) je příkazový nástroj Azure Databricks pro vývojáře, kteří vytvářejí a nasazují vlastní agenty v kódu.

CLI Agent Bricks je kódově orientovaná cesta pro tvorbu vlastních agentů z terminálu. CLI Agent Bricks podporuje projekt využívající vestavěný framework založený na osvědčených postupech Databricks. Poté může projekt spustit lokálně pro testování a nasadit ho do běhu agenta Azure Databricks. CLI vám umožňuje přejít z prázdného adresáře na nasazeného agenta bez nutnosti ručně zapojovat runtime, nástroje, paměť a spravované zdroje. Další způsoby vytváření vlastních agentů, včetně workflow založeného na aplikacích, viz Spustit agenty v Databricks aplikacích pomocí legacy serveru agentů.

Předpoklady

  • Databricks CLI, nainstalovaný a dostupný na vaší cestě.

  • Python 3.10 nebo vyšší, s pip.

  • Nainstalujte CLI Agent Bricks:

    pip install databricks-agentbricks

Životní cyklus CLI Agent Bricks

CLI Agent Bricks vytváří lokální adresář s nasaditelným agentním kódem z šablony frameworku, přičemž runtime, testy a volitelné chatovací rozhraní jsou již zapojené. Vy píšete aplikační logiku (model, nástroje a prompty) a CLI zajišťuje její lokální spuštění a nasazení do infrastruktury Azure Databricks.

agent.tomlje deklarativním zdrojem pravdy pro všechny zdroje spravované Azure Databricks, na kterých váš agent spoléhá: nástroje (datový sandbox, služby spravovaného Model Context Protocol (MCP), funkce Unity Catalog) a paměť, relace a trasovací zdroje. agentbricks deploy ho načte, aby vše zprovoznil a propojil, takže nasazení provádí soubor, nikoli ručně psaný konfigurační kód.

Tři příkazy, které přenášejí agenta z prázdného adresáře do produkce:

  • agentbricks init vytvoří základ projektu z přibalené šablony a volitelně doplní soubor .env o profil Databricks, aby šel projekt ihned spustit.
  • agentbricks devAgent běží lokálně proti Azure Databricks Model Serving, abyste ho mohli otestovat před nasazením.
  • agentbricks deploy zřídí prostředky deklarované v agent.toml a nasadí agenta do běhového prostředí agenta Azure Databricks.

Životní cyklus CLI Agent Bricks: fáze iniciace, vývoje a nasazení s jejich klíčovými akcemi

Note

Můžete také kdykoli přidávat nástroje a vázat paměť a ukládání relací, nejen na začátku. Použijte agentbricks tools add, agentbricks memory bind a agentbricks sessions bind k aktualizaci konfigurace agenta mezi kterýmikoli z těchto kroků.

Možnosti rozhraní příkazového řádku Agent Bricks

Capability Description
Přístup k modelu CLI Agent Bricks automaticky umožňuje přístup k modelu, takže váš agent může volat model obsluhovaný Azure Databricks bez nutnosti spravovat přihlašovací údaje nebo koncové body. Viz rozhraní API modelů Databricks Foundation.
Spravovaná paměť Dlouhodobé paměti, které agent může zapisovat a vyhledávat, rozdělené podle aktérů a kryté spravovanými úložišti. Používejte paměť k uchovávání faktů a preferencí napříč relacemi a použijte agentbricks memory pipeline k destilaci paměti z úložiště relací. Viz paměť agenta a kanály paměti agenta.
Řízené sezení Přepisy konverzací uložené ve spravovaných úložištích relací a rozdělené podle aktorů s podporou větvení relací na nezávislé kopie. Vizte Relace agentů.
Tools Funkce spravované službou Azure Databricks deklarované v agent.toml: omezené izolované prostředí Unity Catalog, služba MCP spravovaná službou Azure Databricks nebo funkce Unity Catalog. Vlastní nástroje v Python jsou psány přímo v kódu projektu. Viz MCPs.
Tracing MLflow traceing, který je ve výchozím nastavení zapnutý, směruje stopy každého běhu do experimentu MLflow pro každý projekt pro ladění a monitorování. Viz přehled trasování.
Nasazení Nasadí agenta do běhového prostředí agenta Azure Databricks, udělí instančnímu objektu služby agenta přístup k připojeným úložištím a spravuje životní cyklus nasazení.

Vytvořte nového agenta

Krok 1: Ověřte se pomocí OAuth a uložte si profil

CLI Agent Bricks používá autentizaci Databricks CLI. Ověřte se do svého pracovního prostoru pomocí OAuth (uživatel-stroj) a uložte přihlašovací údaje jako pojmenovaný profil.

Chcete-li zahájit tok OAuth, spusťte následující příkaz a nahraďte hostitele adresou URL vaší pracovní oblasti. Příkaz otevře prohlížeč pro dokončení přihlášení a poté zapíše profil na :~/.databrickscfg

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

Pro nastavení tohoto profilu jako výchozího CLI, aby pozdější příkazy mohly vynechat --profile, spusťte následující:

agentbricks login --profile <profile>

agentbricks login Ověřuje přihlašovací údaje profilu. Pokud chybí nebo jsou zamítnuty, CLI znovu spustí databricks auth login a pokus opakuje.

Krok 2: Vytvořte základní strukturu projektu agenta

Vytvořte nový projekt agenta a pro výběr šablony předejte --framework. Tento příklad používá šablonu LangGraph, která obsahuje chatovací aplikaci v prohlížeči:

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

CLI dodává jednu šablonu na každý framework a --framework vybírá, ze které šablony se bude stavět: langgraph pro LangGraph nebo openai pro OpenAI Agents SDK. CLI zapisuje spravované prostředky projektu a vazby nástrojů do agent.toml a původ šablony do .agentbricks/project.toml. Chcete-li vygenerovat backend pouze pro API bez chatové aplikace, přidejte --disable-chat-app.

Krok 3: Připojte spravovaná úložiště relací a paměti

Svázejte spravované úložiště, aby váš agent mohl uchovávat historii konverzací a dlouhodobou paměť. Každý příkaz zaznamenává název úložiště v agent.toml a vytvoří úložiště, pokud neexistuje.

Chcete-li propojit úložiště relací a paměťové úložiště, spusťte následující příkaz:

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

Krok 4: Zobrazení trasování

Trasování je zapnuté ve výchozím nastavení. agentbricks init váže /Shared/agentbricks_traces/<project> výchozí experiment MLflow a agentbricks dev posílá agentbricks deploy do něj stopy každého běhu.

Chcete-li uvést stopy poté, co váš agent nějaké vytvořil, použijte následující:

agentbricks tracing list

Pro navázání konkrétního experimentu MLflow spusť agentbricks tracing bind --experiment-id <experiment-id>. Pro vypnutí trasování spusťte agentbricks tracing unbind.

Krok 5: Spusťte agenta lokálně

Spusť agenta na svém počítači, abys ho otestoval před nasazením.

agentbricks dev

Tím se spustí lokální server na portu 8000 se stejným příkazem a prostředím jako běh agenta Azure Databricks. Rozhraní příkazového řádku Agent Bricks propojuje agenta se službou Azure Databricks Model Serving, aby mohl model volat lokálně. Šablona nastaví výchozí model jako MODEL hodnotu v agent/agent.py. Pro použití jiného modelu upravte tuto hodnotu. Posílejte požadavky na http://localhost:8000 pro interakci s agentem.

Krok 6: Nasadit agenta

Nasaďte agenta do běhového prostředí agenta Azure Databricks. CLI poskytuje vázaná úložiště, dává agentovi přístup k nim jako principu služby a spustí nasazení. Nasazený agent se jmenuje agent-bricks-<name>.

agentbricks deploy my-agent

Po dokončení nasazení CLI vrátí URL implementace. Otevřete tuto URL pro interakci s vaším živým agentem, který je automaticky propojen s modelem servisujícím Azure Databricks. Pro správu nasazení po operaci použijte příkazy agentbricks deployments jako agentbricks deployments logs a agentbricks deployments stop.

Přidat existujícího agenta

Pokud jste už vytvořili agenta pomocí LangGraph nebo OpenAI Agents SDK, použijte příznak --existing k přesunu agenta do Agent Bricks CLI a DurableAgentServer. CLI nepřepisuje váš kód. Místo toho připravuje migrační instrukce, kterými se kódovací agent, jako je Claude Code nebo Codex, řídí při převodu projektu.

Krok 1: Připravte migraci

Z adresáře projektu agenta připravte migraci. Předejte framework, který agent používá: langgraph pro LangGraph nebo openai pro OpenAI Agents SDK.

agentbricks init --framework langgraph --existing .

CLI vytvoří agent-bricks-migrate/ adresář, který obsahuje instrukce k migraci, výzvu pro vašeho kódovacího agenta a referenční projekt generovaný ze šablon CLI. Také přidává dovednosti v .claude/skills/ a .agent/skills/, které nasměrují kódovací agenty k instrukcím. Příkaz nemění kód aplikace, závislosti ani soubor .env a nevytváří žádné zdroje ve vašem pracovním prostoru.

Krok 2: Převeďte projekt pomocí svého kódovacího agenta

Vložte prompt z agent-bricks-migrate/ do svého kódovacího agenta. Kódující agent převede projekt tak, aby používal agent.toml a vstupní bod DurableAgentServer, a ověří konverzi.

Krok 3: Zkontrolujte konverzi

Spusťte agentbricks doctor v adresáři projektu:

agentbricks doctor .

agentbricks doctor kontroluje soubory projektu, aniž by spustil jeho kód nebo kontaktoval Azure Databricks. Funguje to, když má projekt platný agent.toml, spouští DurableAgentServer s obslužnou rutinou invoke a volá adaptér pro svůj framework. Nezdařený report znamená, že konverze není dokončena.

Krok 4: Uklidit, spustit a nasadit

Smažte agent-bricks-migrate/ a dvě dovednosti, které na něj ukazují, a nechte je mimo své commity. Pak spusťte agenta pomocí agentbricks dev a nasaďte ho pomocí agentbricks deploy.

Considerations

  • --existing podporuje LangGraph a OpenAI Agents SDK prostřednictvím DurableAgentServer. To --server customnepodporuje.
  • Přepnutí agenta do spravovaného úložiště relací nepřesune jeho stávající historii konverzací. Instrukce pro migraci vás žádají, abyste se rozhodli, jak řešit předchozí konverzace.
  • Možnosti --disable-chat-app, --memory-store a --session-store formují referenční projekt. Nevytvářejí zdroje.

Přidat nástroje MCP

Pokud vytvoříte svého agenta pomocí Agent Bricks CLI, přidejte do svého projektu vestavěnou službu MCP system.ai pomocí agentbricks tools add mcp. Příkaz kontroluje, zda služba existuje ve vašem pracovním prostoru, a zaznamenává nástroj v agent.toml. Agent se k nástroji připojuje za běhu, takže nepíšete žádný kód pro připojení.

Pro seznam MCP služeb, které můžete přidat, spusťte následující příkaz:

agentbricks tools list --kind mcp

Následující příklady přidávají běžné vestavěné služby:

# 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

Ve výchozím nastavení nástroj běží s oprávněními uživatele, který poslal požadavek vašemu agentovi. Pro spuštění jako instanční objekt služby aplikace přidejte --auth app. Pro Google Drive, Gmail, Google Kalendář a Microsoft 365 každý uživatel provádí jednorázové přihlášení přes OAuth před prvním voláním. Viz Propojené aplikace.

Pro kontrolu nebo odstranění nástrojů spusťte agentbricks tools list nebo agentbricks tools remove mcp <service>.

Pro další nástroje viz následující stránky:

agent.toml reference

agent.toml je autoritativním zdrojem pro prostředky spravované službou Azure Databricks, které váš agent používá. agentbricks init ji vytvoří, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind a agentbricks tracing bind ji aktualizují a agentbricks deploy ji čte, aby poskytla zdroje a udělila přístup. Můžete ji také upravovat přímo.

Sekce nebo pole Description
schema_version Verze formátu agent.toml . Generované projekty používají 1.
[agent] framework Šablona frameworku: langgraph nebo openai.
[agent] server Agentní server: agentbricks pro DurableAgentServer, nebo custom pro váš vlastní server.
[memory_store] name Úložiště spravované paměti, které agent používá.
[session_store] name Spravované úložiště relací, které agent používá.
[tracing] experiment_name Experiment MLflow pro trasování. Odstraňte sekci, abyste vypnuli trasování.
[[tools]] Vazba nástroje. Každý nástroj má app, hodnotu sourcepolicy nebo user a auth, která identifikuje nástroj, plus volitelný id.
[auth.user] Požádejte uživatele o autorizaci pro nástroje, které píšete v kódu: required a additional_api_scopes. Viz také Autorizace uživatele pro požadavek.

Následující příklad ukazuje soubor, který agentbricks init generuje pro agenta LangGraph s názvem 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"

Následující příklad ukazuje přiřazení nástrojů, která zapisuje agentbricks tools add: vestavěnou službu MCP, agenta Genie a sandbox zaměřený na jednu tabulku:

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

Nástroje, které volají funkci Unity Catalog, používají source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } a podporují pouze auth = "app".

Referenční informace k příkazům

Úplnou a aktuální referenci ke všem příkazům a přepínačům najdete v souboru Agent Bricks CLI README na GitHubu.

Dodatečné zdroje

  • Poslední aktualizace v