Agent Bricks CLI

Important

이 기능은 베타 버전으로 제공됩니다. 이 기능을 활성화하기 위해 작업 공간 설정이 필요하지 않습니다. Agent Bricks CLI를 설치해서 시작하세요.

Agent Bricks CLI(databricks-agentbricks)는 사용자 지정 에이전트를 코드로 구축하고 배포하는 개발자를 위한 Azure Databricks 명령줄 도구입니다.

Agent Bricks CLI는 터미널에서 커스텀 에이전트를 구축하기 위한 코드 우선 경로입니다. Agent Bricks CLI는 Databricks 모범 사례를 기반으로 한 내장 프레임워크를 사용하여 프로젝트를 스캐폴딩합니다. 그 후 프로젝트를 로컬에서 실행해 테스트하고 Azure Databricks 에이전트 런타임에 배포할 수 있습니다. CLI는 빈 디렉터리에서 배포된 에이전트로 이동할 수 있게 해주며, 런타임, 도구, 메모리, 관리 자원을 직접 배선하지 않고도 가능합니다. 앱 기반 워크플로우를 포함한 다른 맞춤형 에이전트 구축 방법에 대해서는 레거시 에이전트 서버를 이용한 Databricks 앱에서 에이전트 실행을 참조하세요.

사전 요구 사항

  • Databricks CLI가 설치되어 있고 PATH에서 사용할 수 있어야 합니다.

  • Python 3.10 이상, pip 포함.

  • 에이전트 브릭 CLI 설치:

    pip install databricks-agentbricks

에이전트 브릭 CLI 수명주기

Agent Bricks CLI는 프레임워크 템플릿에서 배포 가능한 에이전트 코드의 로컬 디렉터리를 스캐폴드하며, 런타임, 테스트, 선택적 채팅 UI가 이미 유선되어 있습니다. 애플리케이션 로직(모델, 도구, 프롬프트)을 작성하고, CLI가 이를 로컬에서 실행하고 Azure Databricks 인프라에 배포합니다.

agent.toml는 에이전트가 의존하는 모든 Azure Databricks 관리 리소스에 대한 선언적 진실의 출처입니다: 도구 바인딩(데이터 샌드박스, 관리형 모델 컨텍스트 프로토콜(MCP) 서비스, Unity 카탈로그 함수), 메모리, 세션, 트레이싱 리소스. agentbricks deploy가 이를 읽어 프로비저닝하고 모든 것을 연결하므로, 손수 작성한 설정 코드가 아니라 이 파일이 배포를 수행합니다.

에이전트를 빈 디렉터리에서 프로덕션으로 전환하는 세 가지 명령어:

  • agentbricks init는 번들로 제공되는 템플릿에서 프로젝트를 생성하고, 선택적으로 .env 파일에 Databricks 프로필을 미리 채워 넣어 프로젝트를 바로 실행할 수 있도록 합니다.
  • agentbricks dev에이전트를 Azure Databricks 모델 서빙에 대해 로컬에서 실행하므로 배포 전에 테스트할 수 있습니다.
  • agentbricks deploy는 agent.toml에 선언된 리소스를 프로비저닝하고 에이전트를 Azure Databricks 에이전트 런타임에 배포합니다.

에이전트 브릭 CLI 수명주기: init, dev, deploy 단계와 주요 작업

메모

도구를 추가하거나 메모리와 세션 저장소를 언제든지 바인딩할 수 있으며, init 때뿐만 아니라 이 단계들 사이에 에이전트 구성을 업데이트하려면 , agentbricks memory bindagentbricks sessions bind 를 사용agentbricks tools add하세요.

에이전트 브릭스 CLI 기능

Capability Description
모델 접근 Agent Bricks CLI는 자동으로 모델 접근 권한을 프로비저닝하여 에이전트가 자격 증명이나 엔드포인트를 관리하지 않고도 Azure Databricks 지원 모델을 호출할 수 있게 합니다. Databricks Foundation 모델 API를 참조하세요.
관리 메모리 에이전트가 작성하고 검색할 수 있는 장기 메모리들로, 액터별로 분할되고 관리되는 저장소로 뒷받침됩니다. 메모리를 사용해 세션 전반에 사실과 선호도를 유지하세요. 관리되는 에이전트 메모리를 참조하세요.
관리 세션 대화 전사는 관리되는 세션 저장소에 저장되고 액터별로 분할되며, 세션을 독립 복사본으로 분기할 수 있는 기능을 지원합니다. 관리 에이전트 세션을 참조하세요.
Tools agent.toml에 선언된 Azure Databricks 관리 기능: 다운스코프된 Unity Catalog 샌드박스, Azure Databricks가 관리하는 MCP 서비스 또는 Unity Catalog 함수. 커스텀 Python 도구는 프로젝트 코드에 직접 작성됩니다. MCP들을 참고하세요.
추적 기본적으로 켜져 있는 MLflow 추적으로, 각 실행 경로의 추적을 프로젝트별 MLflow 실험으로 라우팅하여 디버깅과 모니터링을 수행합니다. 추적 개요를 참조하세요.
Deployment 에이전트를 Azure Databricks 에이전트 런타임에 배포하고, 에이전트의 서비스 주체에 바운드 스토어에 대한 접근 권한을 부여하며, 배포 라이프사이클을 관리합니다.

새로운 에이전트를 생성하세요

1단계: OAuth로 인증하고 프로필을 저장하세요

Agent Bricks CLI는 Databricks CLI 인증을 사용합니다. OAuth(사용자-머신)로 워크스페이스에 인증하고 자격 증명을 이름 있는 프로필로 저장하세요.

OAuth 플로우를 시작하려면 호스트를 워크스페이스 URL로 교체하는 다음 과정을 실행하세요. 이 명령어는 로그인을 완료하기 위해 브라우저를 열고, 그 후 프로필을 다음과 같이 ~/.databrickscfg작성합니다:

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

해당 프로필을 CLI의 기본값으로 설정하여 이후 명령어에서 생략 --profile할 수 있게 하려면 다음을 실행합니다:

agentbricks login --profile <profile>

agentbricks login 이 기능은 프로필의 자격 증명을 검증합니다. 누락되었거나 거부되면 CLI는 databricks auth login를 다시 실행한 후 다시 시도합니다.

2단계: 에이전트 프로젝트 스캐폴드 구축

새 에이전트 프로젝트를 생성하고 템플릿을 선택하려면 --framework을 전달하세요. 이 예시는 브라우저 채팅 앱을 포함하는 LangGraph 템플릿을 사용합니다:

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

CLI는 프레임워크별로 번들된 템플릿 하나를 제공하며, --framework LangGraph의 경우 langgraph, OpenAI Agents SDK의 경우 openai 중에서 스캐폴딩할 템플릿을 선택합니다. CLI는 프로젝트의 관리되는 리소스와 도구 바인딩을 agent.toml에 기록하고, 템플릿의 출처 정보를 .agentbricks/project.toml에 기록합니다. 채팅 앱 없이 API 전용 백엔드를 생성하려면 --disable-chat-app을 추가하세요.

3단계: 관리된 세션 저장소와 메모리 저장소를 부착하기

관리자 저장소를 묶어 상담원이 대화 기록과 장기 기억을 유지할 수 있도록 하세요. 각 명령어는 스토어 agent.toml 이름을 기록하고, 존재하지 않으면 스토어를 생성합니다.

세션 저장소와 메모리 저장소를 묶으려면 다음을 실행하세요:

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

4단계: 추적 보기

추적은 기본적으로 켜져 있습니다. agentbricks init은 기본 /Shared/agentbricks_traces/<project> MLflow 실험에 바인딩되고, agentbricks dev 및 agentbricks deploy는 각 실행의 트레이스를 해당 실험으로 전송합니다.

에이전트가 일부 트레이스를 생성한 후 이를 나열하려면 다음을 실행하세요:

agentbricks tracing list

특정 MLflow 실험을 연결하려면 agentbricks tracing bind --experiment-id <experiment-id>을(를) 실행하세요. 트레이싱을 끄려면 agentbricks tracing unbind를 실행하세요.

5단계: 에이전트를 로컬에서 실행

배포 전에 컴퓨터에서 에이전트를 실행해 테스트하세요.

agentbricks dev

이 방법은 Azure Databricks 에이전트 런타임과 동일한 명령어와 환경을 사용하여 포트 8000에서 로컬 서버를 시작합니다. Agent Bricks CLI는 에이전트를 Azure Databricks 모델 서빙에 연결하여 모델을 로컬에서 호출할 수 있게 합니다. 템플릿은 MODEL에서 agent/agent.py 값을 기본 모델로 설정합니다. 다른 모델을 사용하려면 그 값을 수정하세요. 에이전트와 상호작용할 요청을 http://localhost:8000 보내세요.

6단계: 에이전트 배치

에이전트를 Azure Databricks 에이전트 런타임에 배포하세요. CLI는 바인딩 저장소를 프로비저딩하고, 에이전트의 서비스 주체에 접근 권한을 부여하며, 배포를 실행합니다. 배포된 에이전트는 이름이 agent-bricks-<name>입니다.

agentbricks deploy my-agent

배포가 완료되면 CLI는 배포의 URL을 반환합니다. 그 URL을 열어 라이브 에이전트와 상호작용하세요. 에이전트는 자동으로 Azure Databricks 모델 서빙에 연결되어 있습니다. 이후 배포를 관리하려면 agentbricks deployments stop 명령(예: agentbricks deployments logs, agentbricks deployments)을 사용하세요.

기존 에이전트 가져오기

이미 LangGraph나 OpenAI Agents SDK로 에이전트를 구축했다면, --existing 플래그를 사용해 이를 Agent Bricks CLI로 이동해 DurableAgentServer. CLI는 코드를 다시 작성하지 않습니다. 대신, Claude Code나 Codex 같은 코딩 에이전트가 프로젝트를 변환하기 위해 따르는 마이그레이션 지침을 준비합니다.

1단계: 마이그레이션 준비

에이전트의 프로젝트 디렉터리에서 마이그레이션을 준비하세요. 에이전트가 사용하는 프레임워크를 전달하세요: LangGraph의 경우 langgraph, OpenAI Agents SDK의 경우 openai.

agentbricks init --framework langgraph --existing .

CLI는 마이그레이션 지침, 코딩 에이전트에 대한 프롬프트, 그리고 CLI 템플릿에서 생성된 참조 프로젝트를 포함하는 agent-bricks-migrate/ 디렉터리를 생성합니다. 또한 코딩 에이전트가 지시를 가리키는 기술을 .claude/skills/ 및 .agent/skills/에 추가해줍니다. 이 명령어는 사용자의 애플리케이션 코드, 의존성 또는 .env 파일을 변경하지 않으며, 작업 공간에 리소스를 생성하지도 않습니다.

2단계: 코딩 에이전트를 사용해 프로젝트를 변환하기

프롬프트 agent-bricks-migrate/ 를 코딩 에이전트에 붙여넣으세요. 코딩 에이전트는 프로젝트가 agent.toml 및 DurableAgentServer 진입점을 사용하도록 변환하고, 변환을 검증합니다.

3단계: 변환 확인

프로젝트 디렉터리에서 agentbricks doctor를 실행합니다:

agentbricks doctor .

agentbricks doctor코드를 실행하거나 Azure Databricks에 연결하지 않고 프로젝트 파일을 검사합니다. 프로젝트가 유효agent.toml하고, 인보크 핸들러로 DurableAgentServer 시작하며, 해당 프레임워크용 어댑터를 호출할 때 성공합니다. 보고서가 실패했다는 것은 변환이 완료되지 않았다는 의미입니다.

4단계: 정리, 실행, 배치

agent-bricks-migrate/와 그것을 가리키는 두 스킬을 삭제하고, 커밋에 포함시키지 마세요. 그 다음 에이전트를 agentbricks dev로 실행하고 agentbricks deploy로 배포합니다.

Considerations

  • --existing는 DurableAgentServer와 함께 LangGraph와 OpenAI 에이전트 SDK를 지원합니다. --server custom을 지원하지 않습니다.
  • 에이전트를 관리형 세션 스토어로 전환해도 기존 대화 기록이 이동하지 않습니다. 마이그레이션 지침에서는 이전 대화를 어떻게 처리할지 결정하라고 합니다.
  • --session-store, --disable-chat-app, 그리고 --memory-store 옵션이 참조 프로젝트를 형성합니다. 그들은 자원을 만들지 않습니다.

MCP 도구 추가

Agent Bricks CLI로 에이전트를 구축한다면, 프로젝트에 내장된 agentbricks tools add mcp MCP 서비스를 system.ai로 추가하세요. 이 명령어는 해당 서비스가 작업 공간에 존재하는지 확인하고 도구를 agent.toml에 기록합니다. 에이전트는 런타임에 툴에 연결되기 때문에 연결 코드를 작성할 필요가 없습니다.

추가할 수 있는 MCP 서비스를 나열하려면 다음 명령을 실행하세요:

agentbricks tools list --kind mcp

다음 예시들은 일반적인 내장 서비스를 추가합니다:

# 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

기본적으로 도구는 요청을 에이전트에게 보낸 사용자의 권한으로 실행됩니다. 대신 앱의 서비스 프린시펄로 실행하려면 --auth app를 추가하세요. Google Drive, Gmail, Google Calendar, Microsoft 365의 경우, 각 사용자는 첫 번째 호출 전에 일회성 OAuth 로그인을 완료합니다. 연결 애플리케이션을 확인하세요.

도구를 검토하거나 제거하려면 agentbricks tools list 또는 agentbricks tools remove mcp <service>을 실행하세요.

기타 도구에 대해서는 다음 페이지를 참조하세요:

agent.toml 참조

agent.toml는 에이전트가 사용하는 Azure Databricks 관리 리소스의 선언적 단일 정보 원본입니다. agentbricks init이 이를 생성하고, agentbricks tracing bind, agentbricks tools add, agentbricks deploy 및 agentbricks sessions bind가 이를 업데이트하며, agentbricks memory bind가 이를 읽어 리소스를 프로비저닝하고 액세스 권한을 부여합니다. 직접 편집할 수도 있습니다.

섹션 또는 필드 Description
schema_version agent.toml 포맷의 버전입니다. 생성된 프로젝트는 1를 사용합니다.
[agent] framework 프레임워크 템플릿: langgraph 또는 openai.
[agent] server 에이전트 서버: DurableAgentServer용 agentbricks 또는 자체 서버용 custom.
[memory_store] name 에이전트가 사용하는 관리 메모리 저장소입니다.
[session_store] name 에이전트가 사용하는 관리 세션 저장소입니다.
[tracing] experiment_name 트레이스를 위한 MLflow 실험입니다. 트레이싱을 끄려면 해당 섹션을 제거하세요.
[[tools]] 도구 바인딩. 각 도구는 id, app 또는 user 값의 auth, 도구를 식별하는 source, 그리고 선택적 policy를 가집니다.
[auth.user] 코드로 작성한 도구에 대한 사용자 승인 요청: required 및 additional_api_scopes. 요청-사용자 권한 부여를 참조하세요.

다음 예시는 my-agent이(가) agentbricks init라는 이름의 LangGraph 에이전트를 위해 생성하는 파일입니다:

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"

다음 예시는 agentbricks tools add가 작성하는 도구 바인딩, 즉 내장된 MCP 서비스, Genie 에이전트, 그리고 하나의 테이블로 범위가 지정된 샌드박스를 보여줍니다:

[[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 카탈로그 함수를 호출하는 도구는 source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" }를 사용하며 auth = "app"만 지원합니다.

명령어 참조

모든 명령과 플래그를 포함하는 최신 전체 명령 참조는 GitHub에 있는 Agent Bricks CLI README를 참조하세요.

추가 리소스

  • 에 마지막으로 업데이트됨