Important
この機能は ベータ版です。 ワークスペース設定は必要ありません。 Agent BricksのCLIをインストールして始めてください。
Agent Bricks CLI(databricks-agentbricks)は、コード内でカスタムエージェントを構築・展開する開発者向けのAzure Databricksコマンドラインツールです。
Agent Bricks CLIは、ターミナルからカスタムエージェントを構築するためのコードファーストパスです。 Agent Bricks CLIは、Databricksのベストプラクティスに基づく組み込みフレームワークを用いてプロジェクトを支えています。 その後、プロジェクトをローカルで実行してテストし、Azure Databricksエージェントのランタイムにデプロイできます。 CLIは、空のディレクトリからデプロイ済みエージェントへと移行し、ランタイムやツール、メモリ、管理リソースを手作業で配線する必要がなくなります。 アプリベースのワークフローを含むカスタムエージェントを構築する他の方法については、「 レガシーエージェントサーバーを使ったDatabricks Apps上でエージェントを実行する」をご覧ください。
前提条件
Databricks CLIがインストールされ、あなたのパス上で利用可能になっています。
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 それを読み込んでプロビジョニングや配線を行うので、手書きのセットアップコードではなくファイル自体がデプロイされます。
エージェントを空のディレクトリから本番環境に移す3つのコマンド:
-
agentbricks initバンドルされたテンプレートからプロジェクトをスキャフォールディングし、オプションでDatabricksプロファイルを.envファイルにシードしてプロジェクトをすぐに実行できるようにします。 -
agentbricks devエージェントはAzure Databricksのモデルサービングに対してローカルで実行されるため、デプロイ前にテストできます。 -
agentbricks deployagent.tomlで宣言されたリソースをプロビジョニングし、エージェントをAzure Databricksエージェントのランタイムにロールアウトします。
Note
また、ツールを追加したり、メモリやセッションストアをinit時だけでなくいつでもバインディングできます。 これらのステップの間に、 agentbricks tools add、 agentbricks memory bind、 agentbricks sessions bind を使ってエージェントの設定を更新してください。
エージェントブリックスのCLI機能
| 能力 | Description |
|---|---|
| モデルアクセス | Agent Bricks CLIはモデルアクセスを自動的にプロビジョニングし、エージェントが認証情報やエンドポイントを管理せずにAzure Databricksで提供されたモデルを呼び出せるようにします。 Databricks Foundation モデル API を参照してください。 |
| マネージドメモリ | エージェントが書き込み検索できる長期メモリで、アクターごとに分割され、マネージドストアによって裏付けられています。 記憶を使って事実や好みをセッション間で永続化しましょう。 「マネージド エージェント のメモリ」を参照してください。 |
| マネージドセッション | 管理されたセッションストア内に保持され、アクターごとに分割された会話の記録。セッションを独立したコピーにフォークすることもサポートします。 管理対象エージェント セッションを参照してください。 |
| Tools |
agent.tomlで宣言されたAzure Databricks管理機能:ダウンスコープ化されたUnity Catalogサンドボックス、Azure Databricks管理MCPサービス、またはUnity Catalog関数。 カスタムPythonツールはプロジェクトコードに直接書かれます。
MCPsを参照してください。 |
| トレース | デフォルトでオンの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はフレームワークごとに1つのテンプレートをバンドルし、 --framework どのテンプレートからスキャフォールドするかを選びます:LangGraph用の langgraph かOpenAIエージェント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 はデフォルトの MLflow 実験 /Shared/agentbricks_traces/<project> を関連付け、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モデルのサーバーに接続し、ローカルでモデルを呼び出せるようにします。 テンプレートはagent/agent.pyのMODEL値をデフォルトモデルとして設定します。 別のモデルを使う場合は、その値を編集してください。 エージェントとやり取りするリクエストを http://localhost:8000 に送ります。
ステップ6:エージェントを展開する
エージェントをAzure Databricksエージェントランタイムにデプロイしてください。 CLI は、関連付けられたストアをプロビジョニングし、エージェントのサービス プリンシパルにそれらへのアクセス権を付与して、デプロイを実行します。 展開されたエージェントは agent-bricks-<name>と名付けられます。
agentbricks deploy my-agent
デプロイメントが完了すると、CLIはデプロイメントのURLを返します。 そのURLを開くと、自動的にAzure Databricksモデルのサービスに接続されたライブエージェントとやり取りできます。 展開後の管理には、agentbricks deployments logsやagentbricks deployments stopなどのagentbricks deploymentsコマンドを使いましょう。
既存のエージェントを追加
もしすでにLangGraphやOpenAI Agents SDKでエージェントを構築しているなら、--existing フラグを使ってAgent Bricks CLI に移行し、DurableAgentServer します。 CLIはコードを書き換えるわけではありません。 代わりに、Claude CodeやCodexなどのコーディングエージェントがコードベースを変換するために従うマイグレーション指示を作成します。
ステップ1:移行の準備
エージェントのプロジェクトディレクトリから移行の準備をしてください。 エージェントが使用するフレームワークとして、langgraph（LangGraph）または openai（OpenAI Agents SDK）を渡してください。
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/とそれを指す2つの参照を削除し、コミットに含めないでください。 その後、 agentbricks dev でエージェントを実行し、 agentbricks deployでデプロイします。
Considerations
-
--existingは、DurableAgentServerを使用して LangGraph および OpenAI エージェント SDK をサポートしています。 これは--server customをサポートしていません。 - エージェントをマネージドセッションストアに切り替えても、既存の会話履歴は移動しません。 移行の指示では、以前の会話の処理方法を決めるように求められています。
-
--disable-chat-app、--memory-store、--session-storeの選択肢がリファレンスプロジェクトを形作ります。 彼らは資源を創出しません。
MCPツールの追加
エージェントをAgent Bricks CLIでビルドする場合は、system.aiでプロジェクトに組み込みのagentbricks tools add mcpMCPサービスを追加してください。 このコマンドは、サービスがワークスペースに存在しているかを確認し、ツールを 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カレンダー、Microsoft 365では、各ユーザーは最初の呼び出し前に一度だけOAuthログインを行います。
接続アプリケーションを参照してください。
ツールを確認または削除するには、agentbricks tools list または agentbricks tools remove mcp <service> を実行します。
その他のツールについては、以下のページをご覧ください。
- すべての組み込みのサービスとそれらが何をするか: Databricksが提供するMCPs。
- 独自の外部MCPサーバー: 外部MCPサーバー。
- Unity Catalogはツールとして機能します: Unity Catalog関数を使ってエージェントツールを作成できます。
- 単一のキュレーションされたGenie Agent: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]] |
ツールのバインド 各工具にはid、値がappまたはauthであるuser、工具を識別するsource、さらにオプションのpolicyがあります。 |
[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エージェント、そして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"のみをサポートします。
コマンド リファレンス
すべてのコマンドとフラグを含む完全かつ最新のコマンド リファレンスについては、GitHub 上のAgent Bricks CLI READMEを参照してください。
その他のリソース
- エージェントツールとMCPサービス: MCP。
- マネージドエージェントメモリの概念とAPI: マネージドエージェントメモリ。
- マネージドエージェントセッションの概念とAPI: マネージドエージェントセッション。
- エージェント向けMLflowトレーシング: トレーシングの概要。