Agent Bricks CLI

Important

Bu özellik Beta sürümündedir. Bunu etkinleştirmek için herhangi bir çalışma alanı ayarı gerekmez. Başlamak için Agent Bricks CLI'sini kurun.

Agent Bricks CLI (databricks-agentbricks), kodda özel ajanlar oluşturan ve dağıtan geliştiriciler için Azure Databricks komut satırı aracıdır.

Agent Bricks CLI, terminalden özel ajanlar oluşturmak için kod öncelikli bir yoldur. Agent Bricks CLI, Databricks'in en iyi uygulamalarına dayanan yerleşik bir çerçeve kullanarak bir projeyi destekler. Ardından projeyi yerel olarak test edebilir ve Azure Databricks ajan çalışma zamanına dağıtabilir. CLI, boş bir dizinden dağıtımlı bir ajana geçmenizi sağlar; böylece çalışma zamanı, araçlar, bellek ve yönetilen kaynakları elle bağlamazsınız. Uygulama tabanlı iş akışı dahil özel ajanlar oluşturmanın diğer yolları için bkz. Eski ajan sunucusunu kullanarak Databricks Uygulamalarında ajanları çalıştır.

Prerequisites

  • Databricks CLI, kurulmuş ve yolunuzda kullanılabilir.

  • Python 3.10 veya üzeri, pip.

  • Agent Bricks CLI aracını yükleyin:

    pip install databricks-agentbricks

Agent Bricks CLI yaşam döngüsü

Agent Bricks CLI, bir framework şablonunu temel alarak, çalışma zamanı, testler ve isteğe bağlı bir sohbet kullanıcı arayüzü önceden yapılandırılmış dağıtıma hazır ajan kodlarını içeren yerel bir dizinin iskeletini oluşturur. Uygulama mantığını (model, araçlar ve istekler) yazıyorsunuz ve Komuta Sistemi bunu yerel olarak çalıştırıp Azure Databricks altyapısına dağıtmayı yönetiyor.

agent.tomlajanınızın bağımlı olduğu tüm Azure Databricks tarafından yönetilen kaynaklar için beyanlı doğruluk kaynağıdır: araç bağlamaları (veri sandbox, yönetilen Model Context Protocol (MCP) servisleri, Unity Kataloğu fonksiyonları) ve bellek, oturum ve takip kaynakları. agentbricks deploy her şeyi hazırlayıp bağlantılarını yapmak için bu dosyayı okur; yani devreye almayı gerçekleştiren şey, elle yazılmış kurulum kodu değil, dosyanın kendisidir.

Bir ajanı boş bir dizinden üretime götüren üç komut:

  • agentbricks init, projeyi birlikte gelen bir şablondan oluşturur ve isteğe bağlı olarak .env dosyasını bir Databricks profiliyle doldurarak projenin hemen çalışmasını sağlar.
  • agentbricks devAgent'i Azure Databricks model servisine karşı yerel olarak çalıştırır, böylece dağıtımdan önce test edebilirsiniz.
  • agentbricks deploy, agent.toml içinde bildirilen kaynakları hazırlar ve ajanı Azure Databricks ajan çalışma zamanına dağıtır.

Agent Bricks CLI yaşam döngüsü: başlatma, geliştirme ve dağıtma aşamaları temel eylemleriyle birlikte

Note

Ayrıca araçlar ekleyebilir ve bellek ile oturum depolarını yalnızca init sırasında değil, istediğiniz zaman da bağlayabilirsiniz. agentbricks tools addBu adımların herhangi biri arasında ajanınızın yapılandırmasını güncellemek için , agentbricks memory bind, ve agentbricks sessions bind kullanın.

Agent Bricks CLI yetenekleri

Capability Description
Model erişimi Agent Bricks CLI, otomatik olarak model erişimini sağlar, böylece ajanınız kimlik bilgilerini veya uç noktalarını yönetmeden Azure Databricks tarafından hizmet verilen bir modeli çağırabilir. Bkz. Databricks Foundation Model API'leri.
Yönetilen bellek Bir ajanın yazabildiği ve arayabildiği, aktör bazında bölümlenmiş ve yönetilen depolarla desteklenen uzun süreli bellek. Oturumlar arasında bilgileri ve tercihleri kalıcı tutmak için belleği kullanın ve oturum deposundan anıları çıkarmak için agentbricks memory pipeline kullanın. Ajan belleği ve Ajan bellek işlem hatları sayfalarına bakınız.
Yönetilen oturumlar Yönetilen oturum depolarında tutulan ve aktörlere göre bölünmüş konuşma transkriptleri, oturumların bağımsız kopyalara ayrılması desteğiyle desteklenir. Bkz. Agent oturumları.
Tools agent.toml içinde bildirilen Azure Databricks tarafından yönetilen özellikler: kapsamı daraltılmış bir Unity Catalog korumalı alanı, Azure Databricks tarafından yönetilen bir MCP hizmeti veya bir Unity Catalog işlevi. Özel Python araçları doğrudan proje kodunda yazılır. MCP'lere Bkz.
İz sürme Varsayılan olarak açık olan MLflow izleme, her çalıştırmanın izlerini hata ayıklama ve izleme için proje başına bir MLflow deneyine yönlendirir. Takip genel bakışına bakınız.
Deployment Azure Databricks ajan çalışma zamanı ortamına bir ajan dağıtır, ajanın hizmet sorumlusuna ilişkilendirilmiş depolara erişim verir ve dağıtım yaşam döngüsünü yönetir.

Yeni bir aracı oluştur

Adım 1: OAuth ile kimlik doğrulaması yapın ve profilinizi kaydedin

Agent Bricks CLI, Databricks CLI doğrulamasını kullanır. OAuth (kullanıcıdan makineye) ile çalışma alanınıza kimlik doğrulaması yapın ve kimlik bilgilerini adlandırılmış bir profil olarak kaydedin.

OAuth akışını başlatmak için aşağıdaki uygulamayı çalıştırın, hostu çalışma alanı URL'niz ile değiştirin. Komut, giriş sürecini tamamlamak için bir tarayıcı açar ve ardından profili şu adrese ~/.databrickscfgyazar:

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

Bu profili CLI'nın varsayılan olarak ayarlamak ve sonraki komutların --profileatlayabileceği için aşağıdaki işlemi yapın:

agentbricks login --profile <profile>

agentbricks login profilin kimlik bilgilerini doğrular. Eksikse veya reddedildiyse, CLI databricks auth login komutunu yeniden çalıştırır ve yeniden dener.

Adım 2: Ajan projesinin iskeletini oluşturun

Yeni bir ajan projesi oluşturun ve şablonu seçmek için --framework parametresini verin. Bu örnek, tarayıcı sohbet uygulamasını içeren LangGraph şablonunu kullanır:

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

CLI, her çerçeve için birlikte gelen bir şablon sunar ve --framework iskeletin hangisinden oluşturulacağını seçer: LangGraph için langgraph veya OpenAI Agents SDK için openai. CLI, projenin yönetilen kaynaklarını ve araç bağlamalarını agent.toml konumuna, şablonun kaynağını ise .agentbricks/project.toml konumuna yazar. Sohbet uygulaması olmadan yalnızca API arka ucunun iskeletini oluşturmak için --disable-chat-app ekleyin.

Adım 3: Yönetilen oturum ve bellek depolarını bağlayın

Yönetilen mağazaları bağlayın ki ajanınız konuşma geçmişini ve uzun vadeli hafızasını koruyabilsin. Her komut, mağaza adını agent.toml içine kaydeder ve mağaza henüz mevcut değilse onu oluşturur.

Bir oturum deposu ile bellek deposunu bağlamak için aşağıdakileri çalıştırın:

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

Adım 4: İzlemeyi görüntüleme

İzleme varsayılan olarak etkindir. agentbricks init, varsayılan /Shared/agentbricks_traces/<project> MLflow denemesini bağlar ve agentbricks dev ile agentbricks deploy, her çalıştırmanın izlerini buna gönderir.

Ajanınız bazı izler oluşturduktan sonra izleri listelemek için aşağıdakıları çalıştırın:

agentbricks tracing list

Belirli bir MLflow deneyini bağlamak için agentbricks tracing bind --experiment-id <experiment-id>çalıştırın. İzlemeyi kapatmak için agentbricks tracing unbind komutunu çalıştırın.

Adım 5: Ajanı yerel olarak çalıştırın

Aracıyı dağıtıma almadan önce makinenizde çalıştırıp test edin.

agentbricks dev

Bu, Azure Databricks ajanı çalışma zamanında kullanılan aynı komut ve ortamı kullanarak port 8000'de yerel bir sunucu başlatır. Agent Bricks CLI, ajanı Azure Databricks model servisine bağlayarak modeli yerel olarak çağırabilir. Şablon, agent/agent.py içinde varsayılan model olarak MODEL değerini ayarlar. Farklı bir model kullanmak için o değeri düzenleyin. Temsilciyle etkileşim kurmak için istekleri http://localhost:8000 gönderin.

Adım 6: Ajanı Yerleştirin

Agenti Azure Databricks agent runtime'ına dağıtın. CLI, bağlı depoları sağlar, ajanın hizmet yöneticisine onlara erişim tanır ve dağıtımı başlatır. Konuşlandırılan ajanın adı agent-bricks-<name>.

agentbricks deploy my-agent

Dağıtım tamamlandığında, Komut Sistemi dağıtımın URL'sini döndürür. Canlı ajanınızla etkileşime girmek için bu URL'yi açın; bu otomatik olarak Azure Databricks model serving'ine bağlanır. Sonrasında dağıtımı yönetmek için, agentbricks deployments ve agentbricks deployments stopgibi komutları agentbricks deployments logs kullanın.

Mevcut bir agent getirin

Eğer zaten LangGraph veya OpenAI Agents SDK ile bir ajan oluşturduysanız, bunu Agent Bricks CLI'sına taşımak ve DurableAgentServer için --existing bayrağını kullanın. CLI kodunuzu yeniden yazmaz. Bunun yerine, Claude Code veya Codex gibi bir kodlama ajanının projeyi dönüştürmek için takip ettiği geçiş talimatlarını hazırlar.

Adım 1: Göçü hazırlayın

Ajanın proje dizininden, migrasyonu hazırlayın. Ajanın kullandığı çerçeveyi belirtin: LangGraph için langgraph veya OpenAI Agents SDK için openai.

agentbricks init --framework langgraph --existing .

CLI, göç talimatlarını, kodlama ajanınız için bir istemi ve CLI'nın şablonlarından oluşturulan bir referans projesini içeren bir agent-bricks-migrate/ dizini oluşturur. Ayrıca, kodlama ajanlarını yönergelere yönlendiren becerileri .claude/skills/ ve .agent/skills/ içine ekler. Komut, uygulama kodunuzu, bağımlılıklarınızı veya .env dosyanızı değiştirmez ve çalışma alanınızda herhangi bir kaynak oluşturmaz.

Adım 2: Projeyi kodlama ajanınızla dönüştürün

agent-bricks-migrate/ içindeki istemi kodlama ajanınıza yapıştırın. Kodlama ajanı projeyi agent.toml ve bir DurableAgentServer giriş noktası kullanacak şekilde dönüştürür ve dönüşümü doğrular.

Adım 3: Dönüşümü kontrol edin

Proje dizininde agentbricks doctor çalıştırın:

agentbricks doctor .

agentbricks doctorProjenin dosyalarını kodunu çalıştırmadan veya Azure Databricks ile iletişime geçmeden denetler. Proje, geçerli bir agent.toml öğesine sahip olduğunda, DurableAgentServer öğesini bir çağırma işleyicisiyle başlattığında ve çerçevesi için adaptörü çağırdığında başarılı olur. Başarısız bir rapor, dönüşümün tamamlanmadığı anlamına gelir.

Adım 4: Temizle, çalıştır ve konuşlandır

agent-bricks-migrate/ öğesini ve ona işaret eden iki yeteneği silin ve bunları commit'lerinizin dışında tutun. Sonra ajanı agentbricks dev ile çalıştırın ve agentbricks deploy ile dağıtın.

Considerations

  • --existingLangGraph ve DurableAgentServer ile OpenAI Agents SDK'yı destekler. Bunu desteklemiyor --server custom.
  • Ajanı yönetilen bir oturum deposuna geçirmek, mevcut konuşma geçmişini taşımaz. Göç talimatları, önceki konuşmaları nasıl yöneteceğinize karar vermenizi istiyor.
  • --memory-store, --session-store ve --disable-chat-app seçenekleri referans projesini şekillendirir. Kaynak yaratmazlar.

MCP araçları ekleyin

Ajanınızı Agent Bricks CLI ile inşa ederseniz, projenize system.ai yerleşik bir MCP Hizmeti agentbricks tools add mcp ile ekleyin. Komut, hizmetin çalışma alanınızda var olup olmadığını kontrol eder ve aracı agent.toml içine kaydeder. Ajan, çalışma zamanında araca bağlanır, bu nedenle herhangi bir bağlantı kodu yazmanız gerekmez.

Ekleyebileceğiniz MCP Hizmetlerini listelemek için aşağıdaki komutu çalıştırın:

agentbricks tools list --kind mcp

Aşağıdaki örnekler yaygın yerleşik hizmetleri ekler:

# 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

Varsayılan olarak, bir araç isteği ajanınıza gönderen kullanıcının izinleriyle çalışır. Bunun yerine uygulamanın servis sorumlusu olarak çalıştırmak için --auth app ekleyin. Google Drive, Gmail, Google Calendar ve Microsoft 365 için, her kullanıcı ilk aramadan önce bir kez OAuth girişini tamamlar. Bağlı uygulamalara bakın.

Araçları incelemek veya kaldırmak için agentbricks tools list veya agentbricks tools remove mcp <service> çalıştırın.

Diğer araçlar için aşağıdaki sayfalara bakınız:

agent.toml Referans

agent.toml öğesi, ajanınızın kullandığı Azure Databricks tarafından yönetilen kaynaklar için bildirimsel doğruluk kaynağıdır. agentbricks init onu oluşturur, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind ve agentbricks tracing bind onu günceller ve agentbricks deploy kaynak sağlamak ve erişim vermek için onu okur. Ayrıca bunu doğrudan düzenleyebilirsiniz.

Bölüm veya alan Description
schema_version Formatın agent.toml versiyonu. Oluşturulan projeler 1 kullanır.
[agent] framework Çerçeve şablonu: langgraph veya openai.
[agent] server Ajan sunucusu: DurableAgentServer için agentbricks, ya da kendi sunucun için custom.
[memory_store] name Ajanın kullandığı yönetilen bellek deposu.
[session_store] name Ajanın kullandığı yönetilen oturum deposu.
[tracing] experiment_name İzlere yönelik MLflow deneyi. İzlemeyi kapatmak için bölümü çıkarın.
[[tools]] Bir araç bağlama. Her aracın bir id, user veya app değerine sahip bir auth, aracı tanımlayan bir source ve isteğe bağlı bir policy vardır.
[auth.user] Kodla yazdığınız araçlar için kullanıcı yetkilendirmesi isteyin: required ve additional_api_scopes. Bkz. Kullanıcı yetkilendirmesi isteği.

Aşağıdaki örnek, agentbricks init tarafından adı my-agent olan bir LangGraph ajanı için oluşturulan dosyadır:

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"

Aşağıdaki örnek, agentbricks tools add tarafından yazılan araç bağlamalarını gösterir: yerleşik bir MCP servisi, bir Genie Agent ve tek bir tabloyla sınırlı bir 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" }] }

Unity Kataloğu fonksiyonu çağıran araçlar auth = "app" kullanır ve yalnızca source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } destekler.

Komut Referansı

Tüm komutları ve bayrakları içeren eksiksiz ve güncel komut başvurusu için GitHub’daki Agent Bricks CLI README dosyasına bakın.

Ek kaynaklar

  • Son güncelleştirme: