Databricks 앱에서 다중 에이전트 시스템 빌드

다중 에이전트 오케스트레이터는 모든 작업을 수행하는 하나의 에이전트를 빌드하는 대신 단일 진입점에서 특수한 스바겐트로 요청을 라우팅합니다.

예를 들어 구조화된 데이터를 쿼리하는 Genie 에이전트와 구조화되지 않은 문서를 쿼리하는 RAG 에이전트를 결합하여 사용자가 여러 원본에서 답변을 얻을 수 있습니다.

오케스트레이터는 각 스바겐트를 도구로 처리하고 해당 지침을 사용하여 요청을 올바른 도구로 라우팅합니다. 오케스트레이터는 다음과 같은 스바겐트 형식을 지원합니다.

• Databricks Apps 에이전트: Databricks 앱으로 배포된 다른 에이전트는 응답 API를 통해 호출됩니다.
• 제니 공간: 기본 제공 Azure Databricks MCP 서버를 통해 쿼리하는 자연어 데이터입니다.
• 서비스 엔드포인트: 응답 API를 지원하는 모델 제공의 기술 도우미, 에이전트 또는 모델

요구 사항

• Databricks CLI가 설치 및 인증되었습니다. 앱 대 앱 호출에는 OAuth가 필요합니다. Databricks CLI 설치 또는 업데이트를 참조하세요.
• Python 3.11 이상
• uv 패키지 관리자. uv 설치를 참조하세요.
• 작업 공간에서 활성화된 Databricks 앱. Databricks Apps 작업 영역 및 개발 환경 설정을 참조하세요.
• Genie Space, 다른 Databricks 앱, 지식 도우미 또는 서비스 엔드포인트 등 오케스트레이션할 하위 에이전트가 하나 이상 있습니다.

먼저 에이전트 감독자를 시도해 보세요

사용자 지정 오케스트레이터를 빌드하기 전에 감독자 에이전트를 사용하여 조정된 다중 에이전트 시스템을 만드는 것이 좋습니다. UI를 통해 다중 에이전트 시스템을 빌드하고 관리합니다. Genie Spaces, 에이전트 엔드포인트, Unity 카탈로그 함수, MCP 서버 및 사용자 지정 에이전트를 연결한 다음, 주제 전문가의 자연어 피드백을 사용하여 시간이 지남에 따라 조정 품질을 향상시킬 수 있습니다.

에이전트 감독자가 지원하지 않는 사용자 지정 라우팅 논리 또는 오케스트레이션 동작이 필요한 경우 Databricks Apps에서 다중 에이전트 시스템을 빌드합니다.

다중 에이전트 오케스트레이터 템플릿 복제

다중 에이전트 오케스트레이터 템플릿은 OpenAI 에이전트 SDK를 사용하여 프로젝트 구조 및 오케스트레이션 논리에 대한 스캐폴딩을 제공합니다. 또한 AI 코딩 도우미에게 오케스트레이터를 개발하는 방법을 가르치는 기술 파일도 포함되어 있습니다.

템플릿을 복제하고 폴더로 이동합니다.

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

구성원 에이전트 설정

오케스트레이터가 호출할 수 있는 각 백엔드는 SUBAGENTS에 있는 각 리스트에서 하위 에이전트로 정의됩니다 agent_server/agent.py.

필요한 항목의 주석 처리를 제거하고 구성합니다. 설명을 업데이트하기 위해 서브에이전트를 더 자세히 설명하도록 합니다. 설명 품질은 오케스트레이터가 요청을 올바른 스바겐트로 라우팅할 수 있는 정도와 직접 관련이 있습니다.

SUBAGENTS = [
    {
        "name": "genie",
        "type": "genie",
        "space_id": "<YOUR-GENIE-SPACE-ID>",
        "description": (
            "Query a Genie Space 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."
        ),
    },
]

각 항목은 자동으로 오케스트레이터가 호출할 수 있는 도구가 됩니다. 하나 이상의 서브에이전트를 활성화시켜야 합니다.

다음 표에서는 각 스바겐트 유형에 대해 설명합니다.

오케스트레이터 사용자 지정

오케스트레이터 에이전트는 create_orchestrator_agent() 함수에서 생성됩니다. 특정 도구 및 각 도구를 사용하는 시기를 설명하도록 지침을 업데이트합니다.

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,
)

리소스 및 권한 구성

오케스트레이터에 필요한 리소스를 선언합니다.databricks.yml 각 서브에이전트 유형은 고유한 리소스 항목을 필요로 합니다.

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

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

databricks.yml의 자리 표시자 값을 agent_server/agent.py에서 구성한 서브에이전트와 일치하도록 업데이트합니다.

대상 Databricks 앱에 대한 오케스트레이터 액세스 권한 부여

오케스트레이터가 스바겐트 Databricks 앱을 호출하는 경우 대상 앱에 대한 오케스트레이터 앱의 서비스 주체 CAN_USE 권한을 수동으로 부여해야 합니다. 이 권한은 번들 리소스로 선언할 수 없으며 배포 후에 적용해야 합니다.

1. 오케스트레이터 앱의 서비스 주체 클라이언트 ID를 찾습니다.

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

2. 대상 앱에 대한 오케스트레이터 앱의 서비스 주체 CAN_USE 권한을 부여합니다.

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

로컬에서 테스트

로컬 환경을 설정하고 에이전트를 시작합니다.

uv run quickstart
uv run start-app

이 스크립트는 quickstart Azure Databricks 인증을 구성하고 추적을 위한 MLflow 실험을 만듭니다. 설치 후 start-app 에이전트 서버를 시작하고 http://localhost:8000에서 채팅 UI를 실행합니다.

Databricks 앱에 배포

선언적 자동화 번들을 사용하여 오케스트레이터를 배포합니다.

1. 번들 구성의 유효성을 검사합니다.

   databricks bundle validate
   

2. 작업 공간에 번들을 배포하세요.

   databricks bundle deploy
   

3. 앱을 시작합니다.

   databricks bundle run agent_openai_agents_sdk_multiagent
   

다음 단계

오케스트레이터를 배포한 후 다음 리소스를 탐색합니다.

• AI 에이전트 작성 및 Databricks 앱에 배포
• AI 에이전트에 대한 인증
• 배포된 AI 에이전트 디버그