Агент Брик CLI

Important

Эта функция доступна в бета-версии. Настройка рабочего пространства не требуется, чтобы это включить. Установите CLI Agent Bricks, чтобы начать.

Agent Bricks CLI (databricks-agentbricks) — это командный инструмент Azure Databricks для разработчиков, которые создают и внедряют пользовательские агенты в коде.

CLI Agent Bricks — это путь, ориентированный на код, для создания пользовательских агентов из терминала. CLI Agent Bricks поддерживает проект с использованием встроенной структуры, основанной на лучших практиках Databricks. Затем можно запустить проект локально для тестирования и развернуть его в среде выполнения агента Azure Databricks. CLI позволяет перейти от пустой папки к развернутому агенту без ручного подключения среды выполнения, инструментов, памяти и управляемых ресурсов. Для других способов создания пользовательских агентов, включая рабочий процесс на основе приложений, см. «Запуск агентов в Databricks Apps с использованием устаревшего сервера агентов».

Необходимые условия

• Databricks CLI, установленный и доступный на вашем пути.

• Python 3.10 или выше, с pip.

• Установите интерфейс командной строки (CLI) Agent Bricks:

  pip install databricks-agentbricks
  

Жизненный цикл Agent Bricks CLI

Agent Bricks CLI генерирует локальный каталог с кодом агента, готовым к развёртыванию, на основе шаблона фреймворка, с уже настроенными средой выполнения, тестами и опциональным чат-интерфейсом. Вы пишете логику приложения (модель, инструменты и запросы), а CLI отвечает за локальный запуск и развертывание в инфраструктуре Azure Databricks.

agent.tomlявляется декларативным источником истины для всех ресурсов, управляемых Azure Databricks, от которых зависит ваш агент: связки инструментов (песочница данных, сервисы управляемого Model Context Protocol (MCP), функции Unity Catalog), а также ресурсы памяти, сессий и трассировки. agentbricks deploy читает его, чтобы подготовить инфраструктуру и настроить все связи, так что именно файл, а не написанный вручную код настройки, выполняет развёртывание.

Три команды, которые переводят агента из пустого каталога в продакшн:

• agentbricks init создаёт структуру проекта на основе встроенного шаблона и при необходимости также создаёт файл .env с профилем Databricks, чтобы проект можно было запустить сразу.
• agentbricks dev Запускает агент локально через службу Model Serving в Azure Databricks, чтобы вы могли протестировать его перед его развертыванием.
• agentbricks deploy подготавливает ресурсы, указанные в agent.toml, и разворачивает агент в среде выполнения агента Azure Databricks.

Note

Вы также можете добавлять инструменты и привязывать память и хранилища сессий в любое время, не только в Init. Используйте agentbricks tools add, agentbricks memory bind, и agentbricks sessions bind для обновления конфигурации агента между этими шагами.

Возможности CLI Agent Bricks

Capability	Description
Доступ к модели	CLI Agent Bricks автоматически предоставляет доступ к модели, чтобы ваш агент мог вызвать модель, обслуживаемую Azure Databricks, без управления учетными данными или конечными точками. См. API модели Databricks Foundation.
Управляемая память	Записи долговременной памяти, которые агент может сохранять и искать, разделённые по акторам и хранящиеся в управляемых хранилищах. Используйте память для сохранения фактов и предпочтений между сессиями, а также используйте agentbricks memory pipeline для выделения воспоминаний из хранилища сессий. См. Память агента и конвейеры памяти агента.
Управляемые сессии	Транскрипты разговоров, хранящиеся в управляемых хранилищах сессий и разделённые по акторам, с поддержкой разветвления сессий на независимые копии. См. сессии агентов.
Tools	возможности, управляемые Azure Databricks, объявленные в agent.toml: песочница Unity Catalog с ограниченной областью действия, служба MCP, управляемая Azure Databricks, или функция Unity Catalog. Кастомные инструменты Python пишутся непосредственно в коде проекта. См. MCPs.
Tracing	Трассировка MLflow, включенная по умолчанию, направляет трассировки каждого запуска в отдельный эксперимент MLflow для каждого проекта для отладки и мониторинга. См. обзор трассировки.
Развертывание	Развёртывает агент в среде выполнения агента Azure Databricks, предоставляет субъекту-службе агента доступ к связанным хранилищам и управляет жизненным циклом развертывания.

Создайте нового агента

Шаг 1: Аутентифицируйтесь с помощью OAuth и сохраните профиль

CLI Agent Bricks использует аутентификацию Databricks CLI. Аутентифицируйтесь в вашем рабочем пространстве с помощью OAuth (user-to-machine) и сохраняйте учетные данные как именованный профиль.

Чтобы начать поток 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 для OpenAI Agents SDK. 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

Это запускает локальный сервер на порте 8000, используя ту же команду и ту же среду, что и среда выполнения агента Azure Databricks. CLI Agent Bricks соединяет агента с сервисом модели 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, такие как agentbricks deployments logs и agentbricks deployments stop.

Подключите существующего агента

Если вы уже создали агент с помощью LangGraph или OpenAI Agents SDK, используйте флаги --existing и DurableAgentServer, чтобы переместить его в CLI Agent Bricks. CLI не переписывает ваш код. Вместо этого он готовит инструкции по миграции, которым следует агент для программирования, такой как Claude Code или Codex, для преобразования проекта.

Шаг 1: Подготовьте миграцию

Из каталога проекта агента подготовьте миграцию. Передайте фреймворк, который использует агент: langgraph для LangGraph или openai для SDK агентов OpenAI.

agentbricks init --framework langgraph --existing .

CLI создает каталог agent-bricks-migrate/, содержащий инструкции по миграции, запрос для вашего кодирующего агента и референсный проект, сгенерированный из шаблонов CLI. Также добавляются навыки в .claude/skills/ и .agent/skills/, которые направляют агентов по написанию кода к инструкциям. Эта команда не меняет код вашего приложения, зависимости или файл .env и не создаёт ресурсов в вашем рабочем пространстве.

Шаг 2: Конвертируйте проект с помощью вашего агента для программирования

Вставьте промпт из agent-bricks-migrate/ в ваш ИИ-агент для программирования. Агент кодирования переводит проект на использование agent.toml и точки входа DurableAgentServer, а также проверяет преобразование.

Шаг 3: Проверьте преобразование

Запустите agentbricks doctor в каталоге проекта:

agentbricks doctor .

agentbricks doctorпроверяет файлы проекта без запуска его кода и обращения в Azure Databricks. Это выполняется успешно, когда у проекта есть допустимый agent.toml, запускает DurableAgentServer с обработчиком invoke и вызывает адаптер для своего фреймворка. Отчет со статусом ошибки означает, что преобразование не завершено.

Шаг 4: Очистка, запуск и развертывание

Удалите agent-bricks-migrate/ и два навыка, которые на это указывают, и не включайте их в свои коммиты. Затем запустите агент с agentbricks dev и разверните его с agentbricks deploy.

Considerations

• --existing поддерживает LangGraph и SDK OpenAI Agents с помощью DurableAgentServer. Это не поддерживает --server custom.
• Переключение агента на управляемое хранилище сессий не переносит его существующую историю разговоров. Инструкции по миграции просят вас решить, как обработать предыдущие разговоры.
• Параметры --session-store, --disable-chat-app и --memory-store формируют эталонный проект. Они не создают ресурсы.

Добавить инструменты MCP

Если вы создаёте агента с помощью Agent Bricks CLI, добавьте в проект встроенный system.ai сервис MCP с agentbricks tools add mcp. Команда проверяет, существует ли сервис в вашем рабочем пространстве, и записывает инструмент в 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>.

Для других инструментов см. следующие страницы:

• Все встроенные сервисы и их функции: MCP, предоставленные Databricks.
• Ваши собственные внешние MCP-серверы: внешние MCP-серверы.
• Функции Unity Catalog служат инструментами: Создавайте агентные инструменты с помощью функций Unity Catalog.
• Один отобранный агент Genie: сервер Genie Agent MCP.

agent.toml Ссылка

agent.tomlявляется декларативным источником истины для ресурсов, управляемых Azure Databricks, которые использует ваш агент. agentbricks init создаёт его, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind и agentbricks tracing bind обновляют, а agentbricks deploy читает его для предоставления ресурсов и предоставления доступа. Вы также можете редактировать его напрямую.

Раздел или поле	Description
schema_version	Версия формата agent.toml. Генерируемые проекты используют 1.
[agent] framework	Шаблон фреймворка: langgraph или openai.
[agent] server	Агент-сервер: agentbricks для DurableAgentServer, или custom для вашего собственного сервера.
[memory_store] name	Управляемое хранилище памяти, которое использует агент.
[session_store] name	Управляемое хранилище сессий, которое использует агент.
[tracing] experiment_name	Эксперимент MLflow для трассировки. Удалите раздел, чтобы отключить трассировку.
[[tools]]	Привязка инструмента. У каждого инструмента есть auth, значение app, равное user или source, и policy, идентифицирующий инструмент, а также необязательный id.
[auth.user]	Запрашивайте авторизацию пользователя для инструментов, которые вы пишете в коде: required и additional_api_scopes. См. Авторизация пользователя по запросу.

Следующий пример — это файл, который генерирует agentbricks init для агента LangGraph с именем my-agent:

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 Catalog, используют source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } и поддерживают только auth = "app".

Справочник команд

Актуальный полный справочник по командам, включая все команды и флаги, см. в Agent Bricks CLI README на GitHub.

Дополнительные ресурсы

• Агентские инструменты и услуги MCP: MCP.
• Концепции памяти агента и API: память агента.
• Концепции сессий агентов и API: сессии агентов.
• Преобразовать историю сессии в долгосрочную память: конвейеры памяти агентов.
• MLflow Tracing для агентов: обзор трассировки.