Agent Bricks CLI
ベータ版
この機能はベータ版です。有効にするためにワークスペースの設定は必要ありません。始めるには Agent Bricks CLI をインストールします。
Agent Bricks CLI（databricks-agentbricks）は、コードでカスタムエージェントを構築およびデプロイする開発者向けの Databricks コマンドラインツールです。
Agent Bricks CLI は、ターミナルからカスタムエージェントを構築するためのコードファーストなパスです。Agent Bricks CLI は、Databricks のベストプラクティスに基づく組み込みフレームワークを使用してプロジェクトをスキャフォールディングします。その後、プロジェクトをローカルで実行してテストし、Databricks エージェントランタイムにデプロイできます。CLI を使用すると、ランタイム、ツール、メモリ、マネージド1リソースを手動で配線することなく、空のディレクトリからデプロイ済みエージェントへと移行できます。アプリベースのワークフローを含め、カスタムエージェントを構築するその他の方法については、レガシーエージェントサーバーを使用した Databricks Apps でのエージェントのランを参照してください。
前提条件
-
インストール済みであり、パスが通っている Databricks CLI。
-
Python 3.11 以降。Agent Bricks CLIパッケージはPython 3.10でインストールされますが、スキャフォールディングされるプロジェクトにはPython 3.11以降が必要です。DatabricksではPython 3.12を推奨しています。
-
uv。これは、agentbricks init、agentbricks dev、agentbricks deployの足場となるプロジェクトをランします。 -
Agent Bricks CLIをインストールします。
uvツールとしてインストールするには、以下をランします。Bashuv tool install databricks-agentbricks代わりに
pipでインストールするには、pip install databricks-agentbricksをランを実行します。インストールが失敗した場合は、「トラブルシューティング」を参照してください。
概要: サインインからデプロイされたエージェントまで
次の手順で、新しいエージェントの作成のステップを要約します。
databricks auth login --host "https://<your-workspace-url>" --profile my-workspace
agentbricks login --profile my-workspace
agentbricks init --framework langgraph my-agent
cd my-agent
agentbricks dev
agentbricks deploy my-agent
すべてのコマンドおよびコマンドグループは --help をサポートしています。たとえば、 agentbricks memory --help をランすると、メモリコマンドとそのフラグが一覧表示されます。
Agent Bricks CLI のライフサイクル
Agent Bricks CLI は、ランタイム、テスト、およびオプションのチャット UI がすでに組み込まれたフレームワークTemplateから、デプロイ可能なエージェントコードのローカルディレクトリをスキャフォールディングします。アプリケーションロジック (モデル、ツール、プロンプト) を記述すると、CLI がそれをローカルで実行し、Databricks インフラストラクチャにデプロイする処理を行います。
agent.toml は、エージェントが依存するすべてのDatabricks管理リソース（ツールバインディング（データサンドボックス、マネージド Model Context Protocol（MCP）サービス、Unity Catalog関数）、メモリ、セッション、トレーシングリソースなど）の宣言型の信頼できる情報源（シングル・ソース・オブ・トゥルース）です。agentbricks deployはそれを読み取ってすべてをプロビジョニングし、配線するため、手書きのセットアップコードではなくファイルがデプロイされるものとなります。
エージェントを空のディレクトリから本番運用へ導く 3 つのコマンド:
agentbricks initは、バンドルされたTemplateからプロジェクトをスキャフォールドし、オプションで Databricks プロファイルを使用して.envファイルをシードすることで、プロジェクトがすぐに実行できるようにします。agentbricks devは、デプロイ前にテストできるように、Databricks モデルサービングに対してエージェントをローカルで実行します。agentbricks deployは、agent.tomlで宣言されたリソースをプロビジョニングし、エージェントを Databricks エージェントランタイムにロールアウトします。
初期化時だけでなく、いつでもツールを追加し、メモリやセッションストアをバインドすることができます。agentbricks tools add、agentbricks memory bind、およびagentbricks sessions bindを使用して、これらのステップの間でエージェントの設定を更新します。
Agent Bricks CLI の機能
機能 | 説明 |
|---|---|
モデルアクセス | Agent Bricks CLI は、資格情報や Endpoint を管理することなくエージェントが Databricks でサービングされるモデルを呼び出せるように、モデルアクセスを自動的にプロビジョニングします。See Databricks 基盤モデル APIs. |
マネージドメモリ | アクターごとに分割され、マネージドストアを基盤とする、エージェントが書き込みや検索を行える長期メモリ。セッションをまたいで事実や好みを保持するにはメモリを使用し、セッションストアからメモリを抽出するには |
マネージドセッション | 管理されたセッション ストアに保持され、アクターによってパーティション分割された会話トランスクリプト。セッションを独立したコピーにフォークする機能もサポートしています。「エージェントセッション」をご覧ください。 |
ツール |
|
トレーシング | MLflowトレースはdefaultで有効になっており、各ランのトレースをデバッグとモニタリングのためにプロジェクトごとのMLflowエクスペリメントにルーティングします。トレーシングの概要を参照してください。 |
デプロイメント | エージェントを Databricks エージェントランタイムにデプロイし、エージェントの Service Principal にバインドされたストアへのアクセス権を付与し、デプロイライフサイクルを管理します。 |
新しいエージェントを作成
ステップ 1: OAuth を使用した認証とプロファイルの保存
エージェントブリックス CLI は Databricks CLI 認証を使用します。OAuth (ユーザー・ツー・マシン) を使用してワークスペースに対する認証を行い、認証情報を名前付きプロファイルとして保存します。次の両方のコマンドをランします。
プロファイル とは、~/.databrickscfg に保存される、名前付きの接続設定（ワークスペース URL とその認証情報）のセットです。このページの例では、名前が my-workspace のプロファイルを使用します。任意の名前を選択し、--profile とともに渡してください。
-
OAuthフローを起動するには、次のコマンドを実行し、ホストをワークスペースのURLに置き換えます。コマンドはブラウザを開いてサインインを完了し、
my-workspaceプロファイルを~/.databrickscfgに書き込みます。Bashdatabricks auth login --host "https://<your-workspace-url>" --profile my-workspace -
プロファイルを検証し、エージェントBricks CLIのdefaultとして保存して、その後のコマンドで
--profileを省略できるようにするには、次のコマンドを実行します。Bashagentbricks login --profile my-workspaceプロファイルの認証情報が見つからない場合や拒否された場合は、
agentbricks loginがdatabricks auth loginを再実行して再試行します。
ステップ 2: エージェントプロジェクトをスキャフォールディングする
新しいエージェントプロジェクトをスキャフォールディングし、--framework を渡してTemplateを選択します。この例では、ブラウザチャットアプリが含まれている LangGraph Template を使用します:
agentbricks init --framework langgraph my-agent
cd my-agent
CLI にはフレームワークごとに 1 つのバンドルされた Template が付属しており、--framework はスキャフォールディング元の Template を選択します。LangGraph の場合は langgraph、OpenAI Agents SDK の場合は openai となります。CLI は、プロジェクトの管理対象リソースとツールバインドを agent.toml に書き込み、Template の出所を .agentbricks/project.toml に書き込みます。チャットアプリなしで API のみのバックエンドをスキャフォールディングするには、--disable-chat-app を追加します。
ステップ 3: 管理対象セッションおよびメモリストアをアタッチする
マネージドストアにより、エージェントは会話履歴と長期記憶を保持できます。agentbricks initはagent.tomlにセッションストアとメモリストアを宣言し、プロジェクト名にmy-agent-cuzvas-memoryのようなランダムなサフィックスを付けます。agentbricks deployは宣言されたストアでまだ存在しないものを作成し、デプロイされたエージェントにそのアクセス権を付与するため、ほとんどのエージェントはこのステップをスキップできます。
別のストアを使用するには、名前でバインドします。各コマンドは、agent.toml のストア名を置き換えます。ストアは作成されません。my-agent-sessions という名前のセッションストアと my-agent-memory という名前のメモリストアをバインドするには、以下をランします。
agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory
ストアにメモリを保持したままエージェントを起動するには、デプロイの前にストアを作成し、エントリを追加します。「 Agent Bricks CLI 」エージェントメモリの概要のtabを参照してください。
ステップ 4: トレーシングの表示
トレースはdefaultで有効になっています。agentbricks init は default /Shared/agentbricks_traces/<project>-<suffix> MLflow エクスペリメントにバインドされ、agentbricks dev および agentbricks deploy は各ランのトレースをそれに送信します。
エージェントがトレースを生成した後に一覧表示するには、次のコマンドを実行します。
agentbricks tracing list
特定のMLflowエクスペリメントをバインドするには、agentbricks tracing bind --experiment-id <experiment-id>を実行します。トレーシングをオフにするには、agentbricks tracing unbindを実行します。
ステップ 5: エージェントをローカルでランする
デプロイする前に、マシン上でエージェントを実行してテストします。
agentbricks dev
これにより、Databricks エージェントランタイムと同じコマンドと環境を使用して、ポート 8000 でローカルサーバーが起動します。Agent Bricks CLI は、エージェントを Databricks のモデルサービングに接続し、モデルをローカルで呼び出せるようにします。Template は、agent/agent.py の MODEL 値として default モデルを設定します。別のモデルを使用するには、その値を編集します。http://localhost:8000 にリクエストを送信して、エージェントとやり取りします。
agentbricks dev メモリまたはセッションストアに接続しません。長期メモリはオフになっており、会話履歴はローカルサーバーが実行されている間のみ保持されます。チャットアプリは、ストアがバインドされている場合でも、ローカルでメモリに対して 接続されていません と表示します。メモリは agentbricks deploy の後に接続されます。
ステップ 6: エージェントをデプロイする
エージェントをDatabricksエージェントランタイムにデプロイします。CLIは、バインドされたストアをプロビジョニングし、エージェントのService Principalにそれらへのアクセス権を付与して、デプロイを展開します。デプロイされたエージェントの名前はagent-bricks-<name>です。
agentbricks deploy my-agent
デプロイが完了すると、CLI はデプロイの URL を返します。その URL を開いてライブエージェントとやり取りします。エージェントは Databricks モデルサービングに自動的に接続されます。後でデプロイを管理するには、agentbricks deployments などの agentbricks deployments logs および agentbricks deployments stop のコマンドを使用します。
既存のエージェントを持ち込む
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のTemplateから生成されたリファレンスプロジェクトを含むagent-bricks-migrate/ディレクトリを書き込みます。また、.claude/skills/や.agent/skills/に、コーディングエージェントに指示を示すスキルを追加します。このコマンドは、アプリケーションコード、依存関係、または.envファイルを変更せず、ワークスペースにリソースを作成しません。
ステップ2：コーディングエージェントを使用してプロジェクトを変換する
agent-bricks-migrate/ のプロンプトをコーディングエージェントに貼り付けます。コーディングエージェントは、プロジェクトを変換して agent.toml と DurableAgentServer のエントリポイントを使用するようにし、変換を検証します。
ステップ3：変換を確認する
プロジェクトディレクトリで agentbricks doctor ランを実行します。
agentbricks doctor .
agentbricks doctor コードを実行したりDatabricksに連絡したりせずに、プロジェクトのファイルを検査します。プロジェクトに有効なagent.tomlがあり、invokeハンドラでDurableAgentServerを起動し、そのフレームワークのバインディング（アダプター）を呼び出すと成功します。失敗したレポートは、変換が完了していないことを意味します。
ステップ 4: クリーンアップ、ラン、デプロイ
agent-bricks-migrate/ とそれを指す2つのスキルを削除し、commitに含まれないようにします。次に、agentbricks dev でエージェントをランし、agentbricks deploy でデプロイします。
考慮事項
--existingDurableAgentServerを使用して LangGraph および OpenAI Agents SDK をサポートします。--server customはサポートしていません。- エージェントを管理対象のセッションストアに切り替えても、既存の会話履歴は移動されません。移行手順では、以前の会話の処理方法を決定するよう求められます。
--disable-chat-app、--memory-store、および--session-storeのオプションによって、参照プロジェクトが形成されます。これらはリソースを作成しません。
MCPツールを追加
Agent Bricks CLI でエージェントを構築する場合は、agentbricks tools add mcp を使用してプロジェクトに組み込みの system.ai MCP サービスを追加します。このコマンドは、サービスがワークスペースに存在することを確認し、agent.toml にツールを記録します。エージェントはランタイムにツールに接続するため、接続コードを記述する必要はありません。
追加できるMCPサービスを一覧表示するには、次のコマンドを実行します：
agentbricks tools list --kind mcp
次の例では、一般的な組み込みサービスを追加します。
# Search the public web.
agentbricks tools add mcp system.ai.web_search
# 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
defaultでは、ツールはエージェントにリクエストを送信したユーザーの権限で実行されます。代わりにアプリのService Principalとして実行するには、--auth appを追加します。Google Drive、Gmail、Google Calendar、およびMicrosoft 365の場合、最初の手順の前に、各ユーザーが1回限りのOAuthログインを完了します。接続されているアプリケーションを参照してください。
ツールを確認または削除するには、agentbricks tools listまたはagentbricks tools remove mcp <service>をランします。
その他のツールについては、次のページを参照してください。
- すべての組み込みサービスとその機能については、Databricks提供のMCPをご覧ください。
- 独自の外部MCPサーバー: 外部MCPサーバー。
- Unity Catalog 関数をツールとして使用する: Unity Catalog 関数を使用したエージェントツールの作成。
- 単一のキュレーションされた Genie Agent: Genie Agent MCP サーバー。
agent.toml リファレンス
agent.toml は、エージェントが使用するDatabricksマネージドリソースの宣言型の信頼できるソースです。agentbricks initが作成し、agentbricks tools add、agentbricks memory bind、agentbricks sessions bind、およびagentbricks tracing bindが更新し、agentbricks deployが読み取ってリソースをプロビジョニングし、アクセスを付与します。直接編集することもできます。
セクションまたはフィールド | 説明 |
|---|---|
|
|
| フレームワークTemplate: |
| エージェントサーバー: |
| エージェントが使用するマネージドメモリストア。 |
| エージェントが使用するマネージドセッションストア。 |
| トレース用のMLflowエクスペリメント。トレーシングをオフにするには、セクションを削除します。 |
| ツールバインディング。各ツールには、 |
| コード内で作成するツールのユーザー認証をリクエストする： |
次の例は、agentbricks init が my-agent という名前の LangGraph エージェント用に生成するファイルです。
schema_version = 1
[agent]
framework = "langgraph"
server = "agentbricks"
[memory_store]
name = "my-agent-cuzvas-memory"
[session_store]
name = "my-agent-cuzvas-sessions"
[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent-cuzvas"
ランダムサフィックス（この例ではcuzvas）はプロジェクトごとに異なるため、同じ名前のプロジェクトでストアやエクスペリメントを共有することはありません。
次の例は、agentbricks tools add が書き込むツール バインディングを示しています：組み込みの MCP サービス、Genie Agent、および 1 つのテーブルにスコープ指定されたサンドボックス：
[[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コマンドを示します。
コマンド | 説明 |
|---|---|
| プロファイルを認証し、defaultとして保存します。 |
| 保存されているdefaultプロファイルを資格情報を削除せずに削除します。 |
| 新しいエージェントプロジェクトのスケルトンを作成するか、 |
| Agent Bricks CLI用に既存のエージェントが設定されていることを確認します。 |
| チャットUIを使用してローカルでエージェントをラン。 |
| 長期記憶を管理します。ストアのバインドまたはバインド解除、ストア、エントリ、メモリパイプラインの管理を行います。 |
| 会話セッションの管理：ストアのバインドまたはバインド解除、セッションストアの管理。 |
| エージェントのツールのリスト表示、追加、削除を行います。 |
| マネージドMCP サービスを検出します。 |
| トレースのバインド、バインド解除、検査。 |
| エージェントを Databricks エージェントランタイムにデプロイします。 |
| デプロイ済みエージェントを管理： |
| HTTP Endpointを呼び出します。 |
| 予告なしに変更される可能性がある実験的コマンド: |
すべてのフラグとオプションについては、GitHubの Agent Bricks CLI コマンドリファレンス を参照してください。
トラブルシューティング
Intel Macでビルド中にインストールが失敗する cryptography
Intel Mac でソースから cryptography パッケージをビルドしているときにインストールに失敗した場合は、代わりに事前にビルドされたパッケージをインストールしてください。pip でインストールするには、次を実行します：
pip install --only-binary :all: databricks-agentbricks
Pythonのバージョンが原因でインストールまたはagentbricks devが失敗する
依存関係の構築中にインストールまたは agentbricks dev が失敗した場合は、 python3 --version で Python のバージョンを確認してください。スケルトン プロジェクトには Python 3.11 以上が必要です。Databricks では Python 3.12 が推奨されます。新しい Python リリースでは、一部の依存関係にビルド済みのパッケージが存在しない場合があります。Python 3.12 で CLI をインストールするには、次を実行します。
uv tool install --python 3.12 databricks-agentbricks
その他のリソース
- エージェントツールとMCPサービス：MCP。
- エージェントメモリの概念とAPI：エージェントメモリ。
- エージェントセッションの概念と API： エージェントセッション。
- セッション履歴を長期記憶に抽出するには、エージェントメモリパイプラインをご覧ください。
- MLflow Tracing for agents: Tracing overview.