Bir yapay zeka aracısı yazma ve Databricks Uygulamalarında dağıtma

Databricks Uygulamalarını kullanarak bir yapay zeka aracısı oluşturun ve dağıtın. Databricks Apps aracı kodu, sunucu yapılandırması ve dağıtım iş akışı üzerinde tam denetim sağlar. Özel sunucu davranışı, git tabanlı sürüm oluşturma veya yerel IDE geliştirmesi gerektiğinde bu yaklaşım idealdir.

Tavsiye

Aracınız yalnızca Azure Databricks barındırılan araçları kullanıyorsa ve araç çağrıları arasında özel mantığa ihtiyacınız yoksa, aracı döngüsünü sizin yerinize Azure Databricks yönetmesine izin vermek için Supervisor API (Beta) kullanabilirsiniz.

Aracı sohbeti kullanıcı arabirimi önizlemesi

Her konuşma aracısı şablonu , ek kurulum gerektirmeden yerleşik bir sohbet kullanıcı arabirimi (yukarıda gösterilmiştir) içerir. Sohbet kullanıcı arabirimi akış yanıtlarını, markdown işlemeyi, Databricks kimlik doğrulamasını ve isteğe bağlı kalıcı sohbet geçmişini destekler.

Gereksinimler

Çalışma alanınızda Databricks Uygulamalarını etkinleştirin. Bkz. Databricks Apps çalışma alanınızı ve geliştirme ortamınızı ayarlama.

Adım 1. Aracı uygulama şablonunu kopyalayın

Databricks uygulama şablonları deposundan önceden oluşturulmuş bir aracı şablonu kullanarak başlayın.

Bu öğretici, aşağıdakileri içeren agent-openai-agents-sdk şablonunu kullanır:

  • OpenAI Aracısı SDK'sı kullanılarak oluşturulan bir aracı
  • Konuşma REST API'siyle ve etkileşimli sohbet kullanıcı arabirimiyle aracı uygulaması için başlangıç kodu
  • MLflow kullanarak aracıyı değerlendirme kodu

Şablonu ayarlamak için aşağıdaki yollardan birini seçin:

Çalışma Alanı Kullanıcı Arabirimi

Çalışma Alanı kullanıcı arabirimini kullanarak uygulama şablonunu yükleyin. Bu işlem uygulamayı yükler ve çalışma alanınızdaki bir işlem kaynağına dağıtır. Daha sonra daha fazla geliştirme için uygulama dosyalarını yerel ortamınızla eşitleyebilirsiniz.

  1. Databricks çalışma alanınızda + Yeni Uygulama'ya> tıklayın.

  2. Agentler>Custom Agent (OpenAI SDK)'ye tıklayın.

  3. Adıyla openai-agents-template yeni bir MLflow denemesi oluşturun ve şablonu yüklemek için kurulumun geri kalanını tamamlayın.

  4. Uygulamayı oluşturduktan sonra, sohbet kullanıcı arabirimini açmak için uygulama URL'sine tıklayın.

Uygulamayı oluşturduktan sonra, kaynak kodu özelleştirmek için yerel makinenize indirin:

  1. Dosyaları eşitle altındaki ilk komutu kopyalayın

    Dosyaları eşitleme Databricks Uygulamaları

  2. Yerel terminalde kopyalanan komutu çalıştırın.

GitHub'dan kopyalama

Yerel bir ortamdan başlamak için aracı şablonu deposunu kopyalayın ve dizinini agent-openai-agents-sdk açın:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Adım 2. Aracı uygulamasını anlama

Ajan şablonu, bu temel bileşenlerle üretime hazır bir mimari gösterir. Her bileşen hakkında daha fazla ayrıntı için aşağıdaki bölümleri açın:

Uygulamada Aracı basit diyagramı

Her bileşen hakkında daha fazla ayrıntı için aşağıdaki bölümleri açın:

Sohbet simgesi Yerleşik sohbet kullanıcı arabirimi

Aracı şablonu, sohbet uygulaması şablonunu ön yüzü olarak otomatik olarak getirir ve çalıştırır. Bu sohbet kullanıcı arabirimi aynı Databricks Apps dağıtımında paketlenmiştir ve aracınızla birlikte sunulur, bu nedenle ek kurulum gerekmez.

Sohbet kullanıcı arabirimini doğrudan projenizde özelleştirebilirsiniz. Kalıcı sohbet geçmişini etkinleştirme ve kullanıcı geri bildirim toplama dahil olmak üzere sohbet uygulamasının özellikleri hakkında daha fazla bilgi için bkz. Databricks Apps ile sohbet kullanıcı arabirimi oluşturma ve paylaşma.

Yonga simgesi. MLflow AgentServer

Yerleşik izleme ve gözlemlenebilirlik ile ajan isteklerini işleyen zaman uyumsuz bir FastAPI sunucusu. AgentServer, aracınızı sorgulamak için bir uç nokta sağlar ve istek yönlendirmeyi, günlük kaydını ve hata işlemeyi otomatik olarak yönetir.

Köşeli ayraç kare simgesi. ResponsesAgent Arayüz

Databricks, aracılar oluşturmak için MLflow ResponsesAgent önerir. ResponsesAgent ajanları herhangi bir üçüncü taraf çerçevesiyle oluşturmanıza ve ardından güçlü günlüğe kaydetme, izleme, değerlendirme, dağıtım ve izleme yetenekleri için Databricks AI'nin özellikleriyle entegre etmenize olanak tanır.

ResponsesAgent, Databricks uyumluluğu için mevcut aracıları kolayca sarmalar.

Bir ResponsesAgent oluşturmayı öğrenmek için, MLflow belgelerinde yer alan örneklere göz atın - Model Sunma için ResponsesAgent.

ResponsesAgent aşağıdaki avantajları sağlar:

  • Gelişmiş ajan yetenekleri

    • Çok aracılı destek
    • Akış çıkışı: Çıkışı daha küçük öbekler halinde akışla aktarın.
    • Kapsamlı araç arama ileti geçmişi: Gelişmiş kalite ve konuşma yönetimi için ara araç arama iletileri de dahil olmak üzere birden çok ileti döndürebilirsiniz.
    • Araç çağırma onayı desteği
    • Uzun süre çalışan araç desteği
  • Kolaylaştırılmış geliştirme, dağıtım ve izleme

    • Herhangi bir çerçeve kullanarak aracılar yazma: Mevcut herhangi bir aracı, kullanıcıya hazır uyumluluk sağlamak amacıyla AI Playground, Aracı Değerlendirmesi ve Aracı İzleme ile arabirim kullanarak sarmalayın.
    • Tipli yazma arabirimleri: IDE ve notebook otomatik tamamlama özelliğinden yararlanarak, tipli Python sınıflarını kullanarak aracı kodu yazın.
    • Otomatik izleme: MLflow, daha kolay değerlendirme ve görüntüleme için akışlı yanıtları izlemelerde otomatik olarak toplar.
    • OpenAI Responses şemasıyla uyumlu: Bkz. OpenAI: Yanıtlar ve ChatCompletion.
Robot simgesi. OpenAI Aracıları SDK'sı

Şablon, konuşma yönetimi ve araç düzenleme için aracı çerçevesi olarak OpenAI Aracıları SDK'sını kullanır. Herhangi bir çerçeveyi kullanarak aracılar yazabilirsiniz. Anahtar, aracınızı MLflow ResponsesAgent arabirimiyle sarmaktır.

Mcp simgesi. MCP (Model Bağlam Protokolü) sunucuları

Şablon, aracılara araçlara ve veri kaynaklarına erişim vermek için Databricks MCP sunucularına bağlanır. Bkz. Azure Databricks model bağlam protokolü (MCP).

Yapay zeka kodlama asistanlarını kullanarak ajanlar geliştirme

Databricks, ajanlar oluşturmak için Claude, Cursor ve Copilot gibi yapay zeka tabanlı kodlama yardımcılarının kullanılmasını önerir. Yapay zeka yardımcılarının proje yapısını, /.claude/skillskullanılabilir araçları ve AGENTS.md en iyi yöntemleri anlamasına yardımcı olmak için içinde sağlanan aracı becerilerini ve dosyasını kullanın. Aracılar, Databricks Uygulamalarını geliştirmek ve dağıtmak için bu dosyaları otomatik olarak okuyabilir.

Adım 3. Temsilcinize araçlar ekleyin

Aracınıza veritabanlarını sorgulama, belge arama veya dış API'leri MCP sunucularına bağlayarak çağırma gibi özellikler verin. Aracı şablonu varsayılan bir MCP sunucu bağlantısı içerir. Daha fazla araç eklemek için aracı kodunuzda ek MCP sunucuları yapılandırın ve içinde databricks.ymlgerekli izinleri verin.

Desteklenen araç türleri ve kod örnekleri için bkz. Aracıları araçlara bağlama .

Yerel Python işlev araçlarını tanımlama

Dış veri kaynakları veya API'ler gerektirmeyen işlemler için araçları doğrudan aracı kodunuzda tanımlayın. Bu araçlar aracınızla aynı işlemde çalışır ve veri dönüştürmeleri, hesaplamalar veya yardımcı program işlemleri için kullanışlıdır.

OpenAI Aracıları SDK'sı

OpenAI Ajanları SDK'sından @function_tool dekoratörünü kullanın.

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

LangChain'den @tool dekoratör kullanın:

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

Yerel işlev araçları, ajan süreci içinde çalıştırıldığından, databricks.yml'de kaynak ataması gerektirmez.

Adım 4. Unity AI Gateway ile Databricks Uygulamalarındaki aracılarınızdan LLM kullanımını yönetme

Aracınızın LLM çağrılarını Unity AI Gateway (Beta) aracılığıyla yönlendirerek hangi sağlayıcının yanıt verdiğine bakılmaksızın her isteğin aynı denetimler tarafından yönetilmesini sağlayın. İstek yolundaki ağ geçidiyle, aracı kodunu veya sağlayıcı kimlik bilgilerini değiştirmeden, izinleri merkezileştirebilir, uygulama başına maliyeti atayabilir, modelleri değiştirip trafiği inceleyebilir veya tekrar yürütme işlemi yapabilirsiniz.

Important

Bu özellik Beta sürümündedir. Çalışma alanı yöneticileri Bu özelliğe erişimi Önizlemeler sayfasından denetleyebilir. Bkz. Azure Databricks önizlemelerini yönetme.

  1. Çalışma alanınızda Unity AI Gateway'i etkinleştirin. Unity AI Gateway, Beta süresince isteğe bağlıdır. Ağ geçidi uç noktalarını oluşturabilmeniz veya sorgulayabilmeniz için önce hesap yöneticisinin hesap konsolu Önizlemeler sayfasından açması gerekir. Bkz. Azure Databricks önizlemelerini yönetme.

  2. Ajanınızı bir Unity AI Gateway uç noktasına yönlendirin. Aracı kodunda, Unity AI Gateway uç noktası adını model bağımsız değişkeni olarak iletin ve Azure Databricks LLM istemcisinde use_ai_gateway=True değerini ayarlayın. İstemci trafiği ağ geçidi üzerinden yönlendirir ve kimlik doğrulamasını otomatik olarak işler.

    OpenAI

    from agents import Agent, set_default_openai_api, set_default_openai_client
    from databricks_openai import AsyncDatabricksOpenAI
    
    set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
    set_default_openai_api("chat_completions")
    
    agent = Agent(
        name="Agent",
        instructions="You are a helpful assistant.",
        model="<ai-gateway-endpoint>",
    )
    

    LangGraph

    from databricks_langchain import ChatDatabricks
    
    llm = ChatDatabricks(
        model="<ai-gateway-endpoint>",
        use_ai_gateway=True,
    )
    

    Ek API’ler (OpenAI Responses API, Anthropic Messages API, Google Gemini) ve REST örnekleri için bkz. Model hizmetlerini sorgulama.

Gelişmiş yazma konuları

Akış yanıtları

Akış yanıtları

Akış, aracıların yanıtların tamamını beklemek yerine gerçek zamanlı parçalar halinde göndermesine olanak tanır. Akış uygulamak için ResponsesAgent kullanarak bir dizi delta olayını ve son olarak bir tamamlama olayını yayınlayın.

  1. Delta olayları yay: Metin öbeklerini gerçek zamanlı olarak akışa almak için aynı output_text.delta olan birden çok item_id olay gönderin.
  2. Bitti olayıyla bitir: Tam son response.output_item.done çıkış metnini içeren delta olaylarıyla aynı item_id son olayı gönderin.

Her bir delta olayı, istemciye bir metin parçasını akıtır. Son tamamlanan olay, tam yanıt metnini içerir ve Databricks'e aşağıdakileri yapması için sinyal verir:

  • MLflow izleme ile aracınızın çıktısını izleyin
  • Unity AI Gateway çıkarım tablolarında akışlı yanıtları toplama
  • AI Playground kullanıcı arabiriminde tam çıkışı gösterme

Akış hatası yayma

Azure Databricks, akış sırasında karşılaşılan hataları databricks_output.error altındaki son belirteçle iletir. Bu hatayı düzgün bir şekilde işlemek ve ortaya çıkarabilmek çağıran istemciye bağlı.

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}
Özel girişler ve çıkışlar

Özel girişler ve çıkışlar

Bazı senaryolarda, client_type ve session_id gibi ilave aracı girişleri veya gelecekteki etkileşimler için sohbet geçmişine dahil edilmemesi gereken alma kaynağı bağlantıları gibi çıkışlar gerekebilir.

Bu senaryolar için MLflow ResponsesAgentcustom_inputs ve custom_outputsalanlarını yerel olarak destekler. Özel girişlere yukarıdaki çerçeve örneklerinden request.custom_inputs erişebilirsiniz.

Aracı Değerlendirme gözden geçirme uygulaması, ek giriş alanları olan aracılar için işleme izlemelerini desteklemez.

AI Playground ve inceleme uygulamasında sağlacustom_inputs

Eğer temsilciniz custom_inputs alanını kullanarak ek girişleri kabul ediyorsa, bu girişleri hem AI Playground hem de inceleme uygulamasında manuel olarak sağlayabilirsiniz.

  1. AI Playground veya Aracı İnceleme Uygulaması'nda dişli simgesini Dişli simgesi seçin.

  2. özel girişlerietkinleştirin.

  3. Aracınızın tanımlı giriş şemasıyla eşleşen bir JSON nesnesi sağlayın.

    Yapay zeka oyun alanında özelleştirilmiş girdiler sağlayın.

5. Adım. Aracı uygulamasını yerel olarak çalıştırma

Yerel ortamınızı ayarlayın:

  1. uv (Python paket yöneticisi), nvm (Node sürüm yöneticisi) ve Databricks CLI'yi yükleyin:

  2. agent-openai-agents-sdk dizinine geçin.

  3. Bağımlılıkları yüklemek, ortamınızı ayarlamak ve uygulamayı başlatmak için sağlanan hızlı başlangıç betiklerini çalıştırın.

    uv run quickstart
    uv run start-app
    

Tarayıcıda yerleşik sohbet kullanıcı arabirimini açmak için adresine gidin http://localhost:8000 ve aracıyla sohbet etmeye başlayın.

Adım 6. Kimlik doğrulamasını yapılandırma

Aracınızın Azure Databricks kaynaklara erişmek için kimlik doğrulamasına ihtiyacı vardır. Databricks Apps iki kimlik doğrulama yöntemi sağlar: uygulama yetkilendirmesi (hizmet sorumlusu) ve kullanıcı yetkilendirmesi (kullanıcı adına). Çalışma alanı kullanıcı arabirimi aracılığıyla veya databricks.yml içinde Deklaratif Otomasyon Paketleri ile deklaratif olarak birini yapılandırabilirsiniz. Aracı şablonları, databricks.yml ile birlikte gönderildiğinden, şablondan başladığınızda varsayılan yol budur.

Desteklenen tüm kaynak türleri, izin değerleri ve uçtan uca databricks.yml kılavuz dahil olmak üzere tam başvuru için bkz. Yapay zeka aracıları için kimlik doğrulaması.

Uygulama yetkilendirmesi (varsayılan)

Azure Databricks, uygulamanız için otomatik olarak bir hizmet sorumlusu kullanarak uygulama yetkilendirmesi yapar. Tüm kullanıcılar aynı izinleri paylaşır.

aracının kullandığı her kaynağı resources.apps.<app>.resources altında databricks.yml içinde bildirin. Hizmet sorumlusuna bildirilen izinleri vermek için paketi dağıtın:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'
databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Kaynak türlerinin tam listesi için bkz. Uygulama yetkilendirme.

Kullanıcı yetkilendirmesi

Kullanıcı yetkilendirmesi, aracınızın her kullanıcının bireysel izinleri ile işlem yapmasını sağlar. Kullanıcı başına erişim denetimine veya denetim izlerine ihtiyacınız olduğunda bunu kullanın.

Bu kodu aracınıza ekleyin:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Important

Uygulama başlatma sırasında değil, get_user_workspace_client() veya @invoke işlevlerinizin içinde @stream başlatın. Kullanıcı kimlik bilgileri yalnızca bir isteği işlerken bulunur.

user_api_scopes'da uygulamadaki databricks.yml altına kapsamlar ekleyerek aracının kullanıcı adına hangi Azure Databricks API'lerini çağırabileceğini yapılandırın:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - genie
        - model-serving
databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Kullanılabilir kapsamların listesi ve tam kurulum yönergeleri için bkz. Kullanıcı yetkilendirmesi.

7. Adım. Temsilciyi değerlendir

Şablon aracı değerlendirme kodunu içerir. Daha fazla bilgi için bkz. agent_server/evaluate_agent.py. Bir terminalde aşağıdakileri çalıştırarak aracınızın yanıtlarının uygunluğunu ve güvenliğini değerlendirin.

uv run agent-evaluate

8. Adım. Ajanjı Databricks Uygulamalarına dağıtın

Kimlik doğrulamasını yapılandırdıktan sonra aracınızı Azure Databricks dağıtın. Aracı şablonları, dağıtım için Databricks Varlık Paketleri'ni (DABs) kullanır. databricks.yml Şablondaki dosya, uygulama yapılandırmasını ve kaynak izinlerini tanımlar. Databricks CLI'nın yüklü ve yapılandırılmış olduğundan emin olun.

Note

Uygulamanızı 1. Adımda Çalışma Alanı kullanıcı arabirimi aracılığıyla oluşturduysanız, mevcut uygulamayı paketinize bağlamak için dağıtmadan önce komutunu çalıştırın databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve . Aksi takdirde, databricks bundle deploy "Aynı ada sahip bir uygulama zaten var" hata verir.

  1. Dağıtmadan önce hataları yakalamak için paket yapılandırmasını doğrulayın:

    databricks bundle validate
    
  2. Paketi dağıtın. Bu, kodunuzu karşıya yükler ve databricks.yml'da tanımlanan kaynakları (MLflow denemesi, servis uç noktaları vb.) yapılandırır.

    databricks bundle deploy
    
  3. Uygulamayı başlatın veya yeniden başlatın:

    databricks bundle run agent_openai_agents_sdk
    

    Note

    bundle deploy yalnızca dosyaları karşıya yükler ve kaynakları yapılandırır. bundle run yeni kodla uygulamayı başlatmak veya yeniden başlatmak için gereklidir.

Gelecekteki güncellemeler için, databricks bundle deploy komutunu ve ardından databricks bundle run agent_openai_agents_sdk komutunu çalıştırarak yeniden dağıtım yapın.

Adım 9. Dağıtılan aracıyı sorgula

Aşağıdaki örnek, OAuth belirteci ile hızlı curl bir istek kullanır. Databricks Uygulamaları için kişisel erişim belirteçleri (PAT) desteklenmez.

Databricks OpenAI İstemcisi ve REST API dahil olmak üzere sorgu yöntemlerinin tam listesi için bkz. Azure Databricks'te dağıtılan aracıyı sorgulama.

Databricks CLI kullanarak bir OAuth belirteci oluşturun:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Temsilciyi sorgulamak için belirteci kullanın.

curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Azure Databricks özellikleriyle uyumluluğu sağlamak için model imzalarını anlama

Azure Databricks, aracıların giriş ve çıkış şemasını tanımlamak için MLflow Model İmzalarını kullanır. AI Playground gibi ürün özellikleri, temsilcinizin desteklenen model imzalarından birine sahip olduğunu varsayar.

ResponsesAgent arabirimini kullanarak aracı yazma konusunda önerilen yaklaşımı izlerseniz, MLflow aracınız için Azure Databricks ürün özellikleriyle uyumlu bir imzayı otomatik olarak çıkaracaktır.

Limitations

Sonraki Adımlar

Temsilciniz geliştirme aşamasında çalıştığında, aracıyı üretime alın. Önerilen sıra için Databricks Apps aracınızı üretime alma bölümüne bakın: CI/CD, yük testi ve ardından Unity AI Gateway.