Databricks Uygulamalarında çok aracılı bir sistem oluşturma

Bir ajanın her şeyi yapması yerine, çok ajanlı bir orkestratör talepleri tek bir giriş noktasından uzman alt ajanlara yönlendirir.

Örneğin, yapılandırılmamış belgeleri sorgulayan bir RAG aracısını yapılandırılmış verileri sorgulayan bir Genie aracısı ile birleştirerek kullanıcıların birden çok kaynaktan yanıt almasına yardımcı olabilirsiniz.

Düzenleyici her bir alt aracı bir araç olarak ele alır ve istekleri doğru olana yönlendirmek için yönergelerini kullanır. Düzenleyici aşağıdaki alt aracı türlerini destekler:

• Databricks Apps aracıları: Databricks Uygulamaları olarak dağıtılan ve Yanıtlar API'si aracılığıyla çağrılan diğer aracılar.
• Genie Agents: Yerleşik Azure Databricks MCP sunucusu aracılığıyla doğal dil verilerini sorgulama.
• Uç noktaları sunma: Model Sunma'da Yanıtlar API'sini destekleyen bilgi yardımcıları, aracılar veya modeller.

Gereksinimler

• Databricks CLI yüklü ve kimliği doğrulanmış. Uygulamadan uygulamaya çağrılar OAuth gerektirir. Bkz. Databricks CLI'yı yükleme veya güncelleştirme.
• Python 3.11 veya üzeri.
• uv Paket yöneticisi. Bkz uv yüklemesi.
• Çalışma alanınızda etkinleştirilmiş Databricks Uygulamaları. Bkz. Databricks Apps çalışma alanınızı ve geliştirme ortamınızı ayarlama.
• Koordine edilecek en az bir alt aracı: bir Genie Aracısı, başka bir Databricks uygulaması, bir bilgi asistanı veya bir servis uç noktası.

Öncelikle Agent Supervisor'ı deneyin

Özel bir düzenleyici oluşturmadan önce, eşgüdümlü bir çok aracılı sistem oluşturmak için Gözetmen Aracısını kullanma konusunu göz önünde bulundurun. Bir kullanıcı arabirimi aracılığıyla sizin için çok aracılı sistemi oluşturur ve yönetir. Genie Aracıları, aracı uç noktaları, Unity Kataloğu işlevleri, MCP sunucuları ve özel aracılar arasında bağlantı kurabilir, ardından konu uzmanlarının doğal dil geri bildirimlerini kullanarak zaman içinde koordinasyon kalitesini geliştirebilirsiniz.

Aracı Gözetmeni'nin desteklemediği özel yönlendirme mantığına veya düzenleme davranışına ihtiyacınız varsa Databricks Uygulamalarında çok aracılı bir sistem oluşturun.

Çoklu aracılı düzenleyici şablonunu kopyala

Çok aracılı düzenleyici şablonu, OpenAI Aracıları SDK'sını kullanarak proje yapısı ve düzenleme mantığı için iskele sağlar. Ayrıca yapay zeka kodlama yardımcılarına düzenleyiciyi nasıl geliştireceklerini öğreten beceri dosyaları da içerir.

Şablonu kopyalayıp klasöre gidin:

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

Alt aracıları yapılandırma

Orkestratörün çağırabileceği her backend, SUBAGENTS listesinde agent_server/agent.py bir alt temsilci olarak tanımlanır.

İhtiyacınız olan girdilerdeki yorumları kaldırın ve yapılandırın. Alt aracıyı daha ayrıntılı bir şekilde açıklamak için açıklamayı güncelleştirin. Açıklama kalitesi doğrudan düzenleyicinin istekleri doğru alt aracıya ne kadar iyi yönlendirebileceğiyle ilgilidir:

SUBAGENTS = [
    {
        "name": "genie",
        "type": "genie",
        "space_id": "<YOUR-GENIE-SPACE-ID>",
        "description": (
            "Query a Genie Agent for structured data analysis. "
            "Use this for questions about data, metrics, and tables."
        ),
    },
    {
        "name": "app_agent",
        "type": "app",
        "endpoint": "<YOUR-APP-AGENT-NAME>",
        "description": (
            "Query a specialist agent deployed as a Databricks App. "
            "Use this for questions the specialist app agent handles."
        ),
    },
    {
        "name": "knowledge_assistant",
        "type": "serving_endpoint",
        "endpoint": "<YOUR-ENDPOINT>",
        "description": (
            "Query the knowledge-assistant endpoint on Model Serving. "
            "Use this for knowledge-base and documentation lookups. "
            "The endpoint must have task type agent/v1/responses."
        ),
    },
]

Her girdi otomatik olarak düzenleyicinin çağırabileceği bir araç haline gelir. En az bir alt aracı etkinleştirmeniz gerekir.

Aşağıdaki tabloda her alt aracı türü açıklanmaktadır:

Düzenleyiciyi özelleştirme

Orkestratör aracısı create_orchestrator_agent() işlevi içinde oluşturulur. Belirli araçlarınızı ve bunların ne zaman kullanılacağını açıklamak için yönergeleri güncelleştirin:

Agent(
    name="Orchestrator",
    instructions=(
        "You are an orchestrator agent. Route the user's request to the "
        "most appropriate tool or data source:\n"
        "- Use the Genie MCP tools for questions about structured data in <dataset_name> that contains information about <topic>\n"
        "- Use query_app_agent for questions or tasks that the specialist app agent handles for ...\n"
        "- Use query_knowledge_assistant for knowledge-base lookups about <topic>.\n"
        "If unsure, ask the user for clarification."
    ),
    model="databricks-claude-sonnet-4-5",
    mcp_servers=[mcp_server] if mcp_server else [],
    tools=subagent_tools,
)

Kaynakları ve izinleri yapılandırma

orkestratörünüzün ihtiyaç duyduğu kaynakları databricks.yml içerisinde bildirin. Her alt aracı türü kendi kaynak girişini gerektirir:

resources:
  - name: 'genie_space'
    genie_space:
      name: 'Genie Agent'
      space_id: '<YOUR-GENIE-SPACE-ID>'
      permission: 'CAN_RUN'

  - name: 'serving_endpoint'
    serving_endpoint:
      name: '<YOUR-ENDPOINT>'
      permission: 'CAN_QUERY'

databricks.yml içindeki yer tutucu değerlerini agent_server/agent.py içinde yapılandırdığınız alt temsilcilerle eşleşecek şekilde güncelleyin.

Düzenleyiciye hedef Databricks uygulamasına erişim verme

Orkestratörünüz bir subagent Databricks uygulamasını çağırırsa, orkestratör uygulamasının hizmet sorumlusuna CAN_USE hedef uygulama üzerinde izinleri manuel olarak vermeniz gerekir. Bu izin paket kaynağı olarak bildirilemez ve dağıtımdan sonra uygulanmalıdır.

1. Orchestrator uygulamasının hizmet sorumlusu istemci kimliğini bulun:

   databricks apps get <YOUR-ORCHESTRATOR-APP-NAME> --output json | jq -r '.service_principal_client_id'
   

2. Orchestrator uygulamasının hizmet sorumlusuna CAN_USE hedef uygulama üzerinde izin verin:

   databricks apps update-permissions <TARGET-APP-NAME> \
     --json '{"access_control_list": [{"service_principal_name": "<SP-CLIENT-ID>", "permission_level": "CAN_USE"}]}'
   

Yerel olarak test et

Yerel ortamınızı ayarlayın ve aracıyı başlatın:

uv run quickstart
uv run start-app

Betik quickstart, Azure Databricks kimlik doğrulamasını yapılandırarak izlemeyi gerçekleştirmek amacıyla bir MLflow denemesi oluşturur. Kurulumdan sonra, start-app konumunda arac sunucusunu ve http://localhost:8000 konumunda bir sohbet kullanıcı arabirimini başlatır.

Databricks Uygulamalarına Dağıtma

Bildirim temelli Otomasyon Paketlerini kullanarak düzenleyiciyi dağıtın:

1. Paket yapılandırmasını doğrulayın:

   databricks bundle validate
   

2. Paketi çalışma alanınıza dağıtın:

   databricks bundle deploy
   

3. Uygulamayı başlatın:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Ek kaynaklar

Orkestratörünüzü dağıttığınızda aşağıdaki kaynakları keşfedin:

• Bir yapay zeka aracısı yazma ve Databricks Uygulamalarında dağıtma
• Yapay zeka aracıları için kimlik doğrulaması
• Özel kod aracısının hatalarını ayıklama