Ügynök Bricks CLI

Important

Ez a funkció bétaverzióban érhető el. Ehhez nincs szükség munkatér beállításra. Telepítsd az Agent Bricks CLI-t a kezdéshez.

Az Agent Bricks CLI (databricks-agentbricks) egy Azure Databricks parancssoros eszköz fejlesztők számára, akik egyedi ügynököket építenek és telepítenek kódban.

Az Agent Bricks CLI egy kódalapú megközelítés egyedi ügynökök terminálból történő létrehozásához. Az Agent Bricks CLI egy beépített keretrendszerrel épít egy projektet, amely a Databricks legjobb gyakorlatain alapul. Ezután helyben futtathatja a projektet tesztelés céljából, és telepítheti az Azure Databricks ügynök futásidőben. A CLI lehetővé teszi, hogy egy üres könyvtárból egy telepített ügynökhöz menj anélkül, hogy kézzel csatlakoztatnád a futásidőt, eszközöket, memóriát és kezelt erőforrásokat. Az egyedi ügynökök létrehozásának további módjairól, beleértve az alkalmazásalapú munkafolyamatot is, lásd: Ügynökök futtatása Databricks Appsben a régi ügynökkiszolgáló használatával.

Prerequisites

  • A(z) Databricks CLI, telepítve és elérhető a PATH-ban.

  • Python 3.11 vagy újabb. Az Agent Bricks CLI csomag Python 3.10-re telepíthető, de az általa létrehozott projektek Python 3.11-et vagy annál magasabbat igényelnek. A Databricks a Python 3.12-t ajánlja.

  • uv, amely futtatja a generált projektet agentbricks init, agentbricks dev, és agentbricks deploy.

  • Telepítsd az Agent Bricks CLI-t. A(z) uv eszközként való telepítéséhez futtassa a következőt:

    uv tool install databricks-agentbricks

    A(z) pip helyett a telepítéshez futtasd a következőt: pip install databricks-agentbricks. Ha a telepítés meghiúsul, lásd a Hibaelhárítás részt.

Áttekintés: bejelentkezéstől egy üzembe helyezett ügynökig

Az alábbi sorozat összefoglalja a Új ügynök létrehozása lépéseit:

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

Jótanács

Minden parancs és parancscsoport támogatja a(z) --help elemet. Például futtassa a(z) agentbricks memory --help parancsot a memóriaparancsok és azok kapcsolóinak felsorolásához.

Az Agent Bricks CLI életciklusa

Az Agent Bricks CLI egy helyi telepíthető ügynökkód könyvtárat épít egy framework sablonból, ahol a futásidő, a tesztek és egy opcionális chat felület már be van kötve. Te írod az alkalmazáslogikát (modell, eszközök és promptok), a CLI pedig helyi futtatást és telepítést végzi az Azure Databricks infrastruktúrában.

agent.toml az ügynök által használt összes, Azure Databricks által kezelt erőforrás deklaratív hiteles forrása: eszközkapcsolatok (adat-homokozó, felügyelt Model Context Protocol (MCP) szolgáltatások, Unity Catalog-függvények), valamint memória-, munkamenet- és nyomkövetési erőforrások. agentbricks deploy beolvassa, hogy üzembe helyezzen és mindent összekössön, így a telepítést a fájl végzi, nem a kézzel írt beállítókód.

A három parancs, amely egy ügynököt egy üres könyvtárból a gyártásba visz:

  • agentbricks init egy csomagolt sablonból építi a projektet, opcionálisan egy .env fájlt is bevetve Databricks profilral, így a projekt azonnal elindul.
  • agentbricks dev lokálisan futtatja az ügynököt az Azure Databricks modellkiszolgálása ellenében, így az a telepítés előtt tesztelhető.
  • agentbricks deploy létrehozza a agent.toml fájlban deklarált erőforrásokat, és üzembe helyezi az ügynököt az Azure Databricks ügynök futtatókörnyezetében.

Ügynök Bricks CLI életciklusa: init, fejlesztés és telepítési fázisok kulcsfontosságú műveleteikkel együtt

Note

Eszközöket is hozzáadhatsz, és bármikor bekötheted a memória- és munkamenet-tárolókat, nem csak az init-en. Használd agentbricks tools add, agentbricks memory bind, és agentbricks sessions bind az ügynök konfigurációjának frissítéséhez bármelyik lépés között.

Agent Bricks CLI képességei

Capability Description
Hozzáférés a modellhez Az Agent Bricks CLI automatikusan biztosítja a modell-hozzáférést, így az ügynök képes lesz Azure Databricks által szolgált modellt hívni anélkül, hogy kezeli a hitelesítő adatokat vagy végpontokat. Lásd: Databricks Foundation Model API.
Menedzselt memória Hosszú távú emlékek, amelyeket egy ügynök írhat és kereshet, aktoronként felosztva, és menedzselt tárolókkal támogatva. Használd a memóriát a tények és preferenciák megőrzésére a munkamenetek között, és a agentbricks memory pipeline használatával emlékek kinyerésére a session store-ból. Lásd: Az ügynök memóriája és az ügynök memóriájának folyamatai.
Menedzselt ülések A beszélgetések átiratai kezelt munkamenettárolókban vannak tárolva, szereplő szerint particionálva, és támogatják a munkamenetek önálló másolatokra történő elágaztatását. Lásd a(z) ügynökmunkamenetek.
Tools Az agent.toml elemben a következők vannak deklarálva: egy korlátozott hatókörű Unity Catalog-homokozó, egy Azure Databricks által felügyelt MCP-szolgáltatás vagy egy Unity Catalog-függvény. Az egyedi Python eszközök közvetlenül a projekt kódjában íródnak. Lásd az MCP-ket.
Nyomkövetés Alapértelmezés szerint bekapcsolt MLflow nyomkövetés, amely az egyes futások nyomkövetési adatait projektenként külön MLflow-kísérletbe irányítja hibakereséshez és monitorozáshoz. Lásd: A nyomkövetés áttekintése.
Deployment Ügynököt telepít az Azure Databricks ügynök futásidőben, hozzáférést biztosít az ügynök szolgáltatásfő számára a kötött tárolókhoz, és kezeli a telepítési életciklust.

Új ügynök létrehozása

1. lépés: Hitelesítés az OAuth-nál és profil mentése

Az Agent Bricks CLI a Databricks CLI hitelesítést használja. Hitelesítse a munkahelyét OAuth-val (felhasználó-gép) és mentse el a hitelesítő adatokat névprofilként. Futtasd mindkét következő parancsot.

Note

A profil egy elnevezett kapcsolati beállításokból álló halmaz (egy munkaterület URL-je és annak hitelesítő adatai), amelyet a(z) ~/.databrickscfg helyen tárolnak. Az ezen oldalon található példák egy profilt használnak, amelynek neve my-workspace. Válassz bármilyen nevet, majd add át a(z) --profile használatával.

  1. Az OAuth folyamat elindításához futtasd a következőket, és cseréld le a hosztet a munkaterület URL-jére. A parancs megnyit egy böngészőt a bejelentkezés befejezéséhez, majd a ~/.databrickscfg profilt a következő helyre írja: my-workspace

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

  2. A profil érvényesítéséhez és az Agent Bricks CLI alapértelmezéseként való elmentéséhez, hogy a későbbi parancsok kihagyhassák --profile, futtasd a következőket:

    agentbricks login --profile my-workspace

    Ha a profil hitelesítési adatai hiányoznak vagy elutasítják őket, agentbricks login újra futtatja databricks auth login és újrapróbálkozik.

2. lépés: Építsd fel az ügynök projektjét

Hozz létre egy új ügynökprojektet, és a sablon kiválasztásához add meg a(z) --framework argumentumot. Ez a példa a LangGraph sablont használja, amely böngészős csevegőalkalmazást is tartalmaz:

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

A CLI minden keretrendszerhez egy csomagban csomagolt sablont szállít, és --framework kiválasztja, melyikből épít fel: langgraph a LangGraph vagy openai az OpenAI Agents SDK számára. A CLI a projekt kezelt erőforrásait és eszközhozzárendeléseit a agent.toml fájlba, a sablon származását pedig a .agentbricks/project.toml fájlba írja. A csak API-t használó háttérrendszer csevegőalkalmazás nélküli létrehozásához add hozzá a(z) --disable-chat-app elemet.

3. lépés: Csatold a felügyelt munkamenet- és memóriatárolókat

A menedzselt tárolók lehetővé teszik, hogy az ügynököd megőrizze a beszélgetési előzményt és a hosszú távú memóriát. agentbricks init létrehoz egy session store-t és egy memóriatárolót - agent.tomlben, amelyet a projekt után nevez el, véletlenszerű toldalékkal, például my-agent-cuzvas-memory. agentbricks deploy létrehoz bármilyen deklarált tárolót, amely még nem létezik, és hozzáférést biztosít ahhoz a telepített ügynöknek, így a legtöbb ügynök kihagyhatja ezt a lépést.

Ha másik boltot használsz, kösd hozzá név szerint. Minden parancs lecseréli az üzlet nevét agent.toml. Ez nem hozza létre a tárolót. A my-agent-sessions nevű session store és a my-agent-memory nevű memóriatároló összekapcsolásához futtassa a következőt:

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

Az ügynök már a tárolóban lévő emlékekkel való indításához hozd létre a tárolót, és adj hozzá bejegyzéseket a telepítés előtt. Lásd az Agent Bricks CLI lapot az Ismerkedés az ügynökmemóriával című cikkben.

4. lépés: Nyomkövetés megtekintése

A követés alapértelmezetten be van kapcsolva. agentbricks init egy alapértelmezett /Shared/agentbricks_traces/<project>-<suffix> MLflow kísérletet köt, és agentbricks devagentbricks deploy minden futás nyomait küldi neki.

Az ügynök által létrehozott nyomok listázásához futtassa a következőt:

agentbricks tracing list

Egy adott MLflow-kísérlet hozzárendeléséhez futtassa a következőt: agentbricks tracing bind --experiment-id <experiment-id> A nyomkövetés kikapcsolásához futtassa a(z) agentbricks tracing unbind parancsot.

5. lépés: Indítsd el az ügynököt helyben

Futtasd az ügynökprogramot a számítógépeden, hogy teszteld, mielőtt üzembe helyeznéd.

agentbricks dev

Ez egy helyi szervert indít el a 8000-es porton, ugyanazzal a parancsmal és környezettel, mint az Azure Databricks ügynök runtime-ja. Az Agent Bricks CLI összekapcsolja az ügynököt az Azure Databricks modell szolgáltatásával, így helyben hívhatja a modellt. A sablon alapértelmezett modellt állít be az MODEL értékként .agent/agent.py Ha más modellt szeretnél használni, akkor módosítsd azt az értéket. Küldj kéréseket az http://localhost:8000 ügynökkel való kapcsolatfelvételhez.

Note

agentbricks dev Nem csatlakozik memória- vagy munkamenettárolókhoz. A hosszú távú memória ki van kapcsolva, és a beszélgetési előzmények csak addig maradnak meg, amíg a helyi szerver fut. A csevegőalkalmazás helyi memóriára Nincs csatlakoztatva üzenetet jelenít meg még akkor is, ha egy tároló hozzá van kötve. A memória agentbricks deploy után csatlakozik.

6. lépés: Telepítsd az ügynököt

Telepítsd az ügynököt az Azure Databricks ügynök runtime-re. A CLI biztosítja a kötött raktárokat, hozzáférést biztosít az ügynök szolgáltatási főszereplőjének, és bevezeti a telepítést. A telepített ügynök neve agent-bricks-<name>.

agentbricks deploy my-agent

Amikor a telepítés befejeződik, a CLI visszaadja a telepítés URL-jét. Nyisd meg azt az URL-t, hogy kapcsolatba léphess az élő ügynököddel, amely automatikusan csatlakozik az Azure Databricks modell szolgáltatáshoz. A telepítés későbbi kezeléséhez használd a agentbricks deployments parancsokat, mint agentbricks deployments logs például és agentbricks deployments stop.

Meglévő agent hozzáadása

Ha már építettél ügynököt LangGraph-tal vagy az OpenAI Agents SDK-val, használd a --existing jelzőt, hogy áthelyezd az Agent Bricks CLI-be, és DurableAgentServer. A CLI nem írja át a kódodat. Ehelyett migrációs utasításokat készít elő, amelyeket egy kódíró ágens, például a Claude Code vagy a Codex követ a projekt átalakításához.

1. lépés: Készítsd elő a migrációt

Az ügynök projektkönyvtárából készítsd elő a migrációt. Adja meg az ügynök által használt keretrendszert: langgraph a LangGraphhoz vagy openai az OpenAI Agents SDK-hoz.

agentbricks init --framework langgraph --existing .

A CLI létrehoz egy agent-bricks-migrate/ könyvtárat, amely tartalmazza a migrációs utasításokat, egy promptot a kódoló ügynökhöz, valamint egy referencia projektet, amelyet a CLI sablonjaiból generálnak. Emellett készségeket ad hozzá a .claude/skills/ és a .agent/skills/ elemben, amelyek a kódoló ügynököket az utasításokhoz irányítják. A parancs nem változtatja meg az alkalmazás kódját, függőségeit vagy a .env fájlt, és nem hoz létre erőforrásokat a munkaterületen.

2. lépés: Konvertáld a projektet a kódolási asszisztenseddel

Illeszd be a(z) agent-bricks-migrate/ promptot a kódolási ügynökbe. A kódoló ügynök átalakítja a projektet úgy, hogy agent.toml-t és egy DurableAgentServer belépési pontot használjon, és ellenőrzi az átalakítást.

3. lépés: Ellenőrizd a konverziót

Futtasd agentbricks doctor a projektkönyvtárban:

agentbricks doctor .

agentbricks doctora projekt fájljait ellenőrzi anélkül, hogy futtatná a kódját vagy kapcsolatba lépne az Azure Databricks-szel. Ez akkor sikeres, ha a projektnek van érvényes agent.toml, egy invoke handlerrel indul DurableAgentServer, és meghívja a keretrendszer adapterét. A sikertelen jelentéskészítés azt jelenti, hogy az átalakítás nem fejeződött be.

4. lépés: Tisztítás, futtatás és telepítés

Töröld a agent-bricks-migrate/ elemet és a két képességet, ami rá utal, és hagyd ki őket a commitjaidból. Ezután futtassa az ügynököt a(z) agentbricks dev paranccsal, és telepítse a(z) agentbricks deploy paranccsal.

Considerations

  • --existing támogatja a LangGraph-ot és az OpenAI Agents SDK-t a(z) DurableAgentServer használatával. Nem támogatja --server custom.
  • Az ügynök átváltása egy menedzselt session store-ra nem mozgatja a meglévő beszélgetési előzményeit. A migrációs utasítások arra kérnek, hogy eldöntsd, hogyan kezeld a korábbi beszélgetéseket.
  • A --disable-chat-app, --memory-store, és --session-store opciók alakítják a referencia projektet. Nem teremtenek forrásokat.

MCP eszközök hozzáadása

Ha az ügynököt az Agent Bricks CLI-val építed, adj hozzá beépített system.ai MCP szolgáltatást a projektedhez agentbricks tools add mcp. A parancs ellenőrzi, hogy a szolgáltatás létezik-e a munkaterületeden, és rögzíti az eszközt agent.toml. Az ügynök futásidőben csatlakozik az eszközhöz, így nem írsz kapcsolati kódot.

A hozzáadható MCP-szolgáltatások listázásához futtasd a következő parancsot:

agentbricks tools list --kind mcp

Az alábbi példák hozzáadják a gyakori beépített szolgáltatásokat:

# 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

Alapértelmezés szerint az eszköz annak a felhasználónak a jogosultságaival fut, aki a kérést az ügynöködnek küldte. Ha ehelyett az alkalmazás szolgáltatásneveként futtatod, add hozzá --auth app. A Google Drive, Gmail, Google Calendar és Microsoft 365 esetén minden felhasználó egyszer hajt végre OAuth-bejelentkezést az első hívás előtt. Lásd Csatlakoztatott alkalmazások.

Az eszközök átvizsgálásához vagy eltávolításához futtassa a agentbricks tools list vagy agentbricks tools remove mcp <service> parancsot.

További eszközökért lásd az alábbi oldalakat:

agent.toml Hivatkozás

agent.toml az Azure Databricks által kezelt erőforrások deklaratív igazságforrása, amelyeket az ügynök használ. agentbricks init létrehozza, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind és agentbricks tracing bind frissítik, agentbricks deploy pedig beolvassa, hogy erőforrásokat építsen ki és hozzáférést biztosítson. Közvetlenül is szerkesztheted.

Szakasz vagy mező Description
schema_version A(z) agent.toml formátum verziója. A létrehozott projektek a(z) 1 elemet használják.
[agent] framework A keretrendszer sablonja: langgraph vagy openai.
[agent] server Az ügynök szerver: agentbricks a következőhöz: DurableAgentServer, vagy custom a saját szerveredhez.
[memory_store] name Az ügynök által használt menedzselt memória tároló.
[session_store] name Az ügynök által használt kezelt session tároló.
[tracing] experiment_name Az MLflow-kísérlet a nyomkövetésekhez. Távolítsd el ezt a részt a nyomkövetés kikapcsolásához.
[[tools]] Egy eszközkötés. Minden eszköznek van egy id, egy auth értéke user vagy app, és egy source, amely azonosítja az eszközt, plusz egy opcionális policy.
[auth.user] Felhasználói engedély kérése olyan eszközökhöz, amelyeket kódban létrehozol: required és additional_api_scopes. Lásd a Felhasználói engedélyezés kérése elemet.

A következő példa az a fájl, amelyet agentbricks init generál egy my-agent nevű LangGraph-ügynök számára:

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"

A véletlenszerű toldalék (cuzvas ebben a példában) minden projektnél más, így az azonos nevű projektek nem osztanak meg tárolókat vagy teszteket.

A következő példa olyan eszközkötéseket mutat, amelyeket a agentbricks tools add ír ki: egy beépített MCP szolgáltatás, egy Genie Agent és egy sandbox, amely egy táblára korlátozott:

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

Azok az eszközök, amelyek Unity Catalog függvényt hívnak, a auth = "app" elemet használják, és csak a source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } elemet támogatják.

Parancshivatkozás

Az alábbi táblázat felsorolja az Agent Bricks CLI parancsait.

Command Description
agentbricks login Hitelesíts egy profilt, és mentsd el alapértelmezettként.
agentbricks logout Felejtsd el a mentett alapértelmezett profilt anélkül, hogy törölnéd a hitelesítő adatokat.
agentbricks init Építs fel egy új ügynökprojektet, vagy készíts elő egy meglévő ügynököt migrációra --existing használatával.
agentbricks doctor Ellenőrizd, hogy egy meglévő ügynök be van állítva az Agent Bricks CLI-hez.
agentbricks dev Futtasd az ügynököt helyben, chat felülettel.
agentbricks memory Hosszú távú memória kezelése: kössön vagy oldjon le egy tárolót, valamint kezelje a tárolókat, bejegyzéseket és memória-folyamatcsatornákat.
agentbricks sessions A beszélgetések kezelése: kösd be vagy oldj le egy tárolót, és kezeld a session store-okat.
agentbricks tools Listázd fel, add hozzá és távolítsd el az ügynök eszközeit.
agentbricks mcp Fedezd fel a menedzselt MCP szolgáltatásokat.
agentbricks tracing Kösd össze, oldd meg és vizsgáld meg a nyomkövetést.
agentbricks deploy Telepítsd az ügynököt az Azure Databricks ügynök runtime-re.
agentbricks deployments Kezeld a telepített ügynököket: list, get, wait, start, logs, stop, és delete.
agentbricks endpoint HTTP-végpont meghívása
agentbricks experimental Kísérleti parancsok, amelyek előzetes értesítés nélkül változhatnak: experimental models és experimental prompts.

Az összes kapcsolóról és opcióról lásd az Agent Bricks CLI parancshivatkozást a GitHubon.

Troubleshooting

A telepítés Intel Mac-en építés közben kudarcot vall cryptography

Ha a telepítés Intel Mac-en nem működik, miközben a cryptography csomagot forrásból építi, telepíts inkább előre lefordított csomagokat. A(z) pip használatával történő telepítéshez futtasd a következőket:

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

A telepítés vagy a agentbricks dev meghiúsul a Python verziója miatt

Ha a telepítés vagy a(z) agentbricks dev meghiúsul a függőségek építése közben, ellenőrizd a Python-verziódat a(z) python3 --version paranccsal. A sablonból létrehozott projektekhez Python 3.11 vagy annál magasabb verzió szükséges, a Databricks pedig a Python 3.12-t ajánlja. Az újabb Python-kiadásoknál előfordulhat, hogy néhány függőséghez nem állnak rendelkezésre előre összeállított csomagok. A CLI telepítéséhez Python 3.12-vel futtassa az alábbiakat:

uv tool install --python 3.12 databricks-agentbricks

További erőforrások

  • Utolsó frissítés időpontja: