メインコンテンツまでスキップ
に最終更新

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.10 以降 (pip を含む)。

  • Agent Bricks CLI をインストールします。

    Bash
    pip install databricks-agentbricks

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 エージェントランタイムにロールアウトします。

Agent Bricks CLI のライフサイクル: 初期化、開発、デプロイの各フェーズと主要なアクション

注記

初期化時だけでなく、いつでもツールを追加し、メモリやセッションストアをバインドすることができます。agentbricks tools add、agentbricks memory bind、およびagentbricks sessions bindを使用して、これらのステップの間でエージェントの設定を更新します。

Agent Bricks CLI の機能​

機能

説明

モデルアクセス

Agent Bricks CLI は、資格情報や Endpoint を管理することなくエージェントが Databricks でサービングされるモデルを呼び出せるように、モデルアクセスを自動的にプロビジョニングします。See Databricks 基盤モデル APIs.

マネージドメモリ

アクターごとに分割され、マネージドストアを基盤とする、エージェントが書き込みや検索を行える長期メモリ。セッションをまたいで事実や好みを保持するにはメモリを使用し、セッションストアからメモリを抽出するにはagentbricks memory pipelineを使用します。エージェントメモリとエージェントメモリパイプラインをご覧ください。

マネージドセッション

管理されたセッション ストアに保持され、アクターによってパーティション分割された会話トランスクリプト。セッションを独立したコピーにフォークする機能もサポートしています。「エージェントセッション」をご覧ください。

ツール

agent.tomlで宣言されたDatabricks管理機能：スコープダウンされたUnity Catalogサンドボックス、Databricks管理のMCPサービス、またはUnity Catalog関数。カスタムPythonツールは、プロジェクトコードに直接記述されます。MCPを参照してください。

トレーシング

MLflowトレースはdefaultで有効になっており、各ランのトレースをデバッグとモニタリングのためにプロジェクトごとのMLflowエクスペリメントにルーティングします。トレーシングの概要を参照してください。

デプロイメント

エージェントを Databricks エージェントランタイムにデプロイし、エージェントの Service Principal にバインドされたストアへのアクセス権を付与し、デプロイライフサイクルを管理します。

機能

説明

モデルアクセス

Agent Bricks CLI は、資格情報や Endpoint を管理することなくエージェントが Databricks でサービングされるモデルを呼び出せるように、モデルアクセスを自動的にプロビジョニングします。See Databricks 基盤モデル APIs.

マネージドメモリ

アクターごとに分割され、マネージドストアを基盤とする、エージェントが書き込みや検索を行える長期メモリ。セッションをまたいで事実や好みを保持するにはメモリを使用し、セッションストアからメモリを抽出するにはagentbricks memory pipelineを使用します。エージェントメモリとエージェントメモリパイプラインをご覧ください。

マネージドセッション

管理されたセッション ストアに保持され、アクターによってパーティション分割された会話トランスクリプト。セッションを独立したコピーにフォークする機能もサポートしています。「エージェントセッション」をご覧ください。

ツール

agent.tomlで宣言されたDatabricks管理機能：スコープダウンされたUnity Catalogサンドボックス、Databricks管理のMCPサービス、またはUnity Catalog関数。カスタムPythonツールは、プロジェクトコードに直接記述されます。MCPを参照してください。

トレーシング

MLflowトレースはdefaultで有効になっており、各ランのトレースをデバッグとモニタリングのためにプロジェクトごとのMLflowエクスペリメントにルーティングします。トレーシングの概要を参照してください。

デプロイメント

エージェントを Databricks エージェントランタイムにデプロイし、エージェントの Service Principal にバインドされたストアへのアクセス権を付与し、デプロイライフサイクルを管理します。

新しいエージェントを作成​

ステップ 1: OAuth を使用した認証とプロファイルの保存​

Agent Bricks CLI では、Databricks CLI の認証が使用されます。OAuth (ユーザーマシン間) でワークスペースに対する認証を行い、資格情報を名前付きプロファイルとして保存します。

OAuth のフローを開始するには、次のコマンドを実行し、ホストをワークスペースの URL に置き換えます。このコマンドを実行すると、ブラウザが起動してサインインが完了し、プロフィールが ~/.databrickscfg に書き込まれます。

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

そのプロファイルをCLIのdefaultに設定して、以降のコマンドで--profileを省略できるようにするには、次を実行します。

Bash
agentbricks login --profile <profile>

agentbricks login プロファイルの資格情報を検証します。それらが欠落している場合や拒否された場合、CLI は databricks auth login を再実行してリトライします。

ステップ 2: エージェントプロジェクトをスキャフォールディングする​

新しいエージェントプロジェクトをスキャフォールディングし、--framework を渡してTemplateを選択します。この例では、ブラウザチャットアプリが含まれている LangGraph Template を使用します:

Bash
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: 管理対象セッションおよびメモリストアをアタッチする​

マネージドストアをバインドすると、エージェントが会話履歴と長期記憶を永続化できるようになります。各コマンドは、ストア名を agent.toml に記録し、ストアが存在しない場合は作成します。

セッションストアとメモリストアをバインドするには、次のコマンドを実行します。

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

ステップ 4: トレーシングの表示​

トレースはdefaultで有効になっています。agentbricks init は default /Shared/agentbricks_traces/<project> MLflow エクスペリメントにバインドされ、agentbricks dev および agentbricks deploy は各ランのトレースをそれに送信します。

エージェントがトレースを生成した後に一覧表示するには、次のコマンドを実行します。

Bash
agentbricks tracing list

特定のMLflowエクスペリメントをバインドするには、agentbricks tracing bind --experiment-id <experiment-id>を実行します。トレーシングをオフにするには、agentbricks tracing unbindを実行します。

ステップ 5: エージェントをローカルでランする​

デプロイする前に、マシン上でエージェントを実行してテストします。

Bash
agentbricks dev

これにより、Databricks エージェントランタイムと同じコマンドと環境を使用して、ポート 8000 でローカルサーバーが起動します。Agent Bricks CLI は、エージェントを Databricks のモデルサービングに接続し、モデルをローカルで呼び出せるようにします。Template は、agent/agent.py の MODEL 値として default モデルを設定します。別のモデルを使用するには、その値を編集します。http://localhost:8000 にリクエストを送信して、エージェントとやり取りします。

ステップ 6: エージェントをデプロイする​

エージェントをDatabricksエージェントランタイムにデプロイします。CLIは、バインドされたストアをプロビジョニングし、エージェントのService Principalにそれらへのアクセス権を付与して、デプロイを展開します。デプロイされたエージェントの名前はagent-bricks-<name>です。

Bash
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を指定します。

Bash
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 ランを実行します。

Bash
agentbricks doctor .

agentbricks doctor コードを実行したりDatabricksに連絡したりせずに、プロジェクトのファイルを検査します。プロジェクトに有効なagent.tomlがあり、invokeハンドラでDurableAgentServerを起動し、そのフレームワークのバインディング（アダプター）を呼び出すと成功します。失敗したレポートは、変換が完了していないことを意味します。

ステップ 4: クリーンアップ、ラン、デプロイ​

agent-bricks-migrate/ とそれを指す2つのスキルを削除し、commitに含まれないようにします。次に、agentbricks dev でエージェントをランし、agentbricks deploy でデプロイします。

考慮事項​

  • --existing DurableAgentServer を使用して 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サービスを一覧表示するには、次のコマンドを実行します：

Bash
agentbricks tools list --kind mcp

次の例では、一般的な組み込みサービスを追加します。

Bash
# 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>をランします。

その他のツールについては、次のページを参照してください。

agent.toml リファレンス​

agent.toml は、エージェントが使用するDatabricksマネージドリソースの宣言型の信頼できるソースです。agentbricks initが作成し、agentbricks tools add、agentbricks memory bind、agentbricks sessions bind、およびagentbricks tracing bindが更新し、agentbricks deployが読み取ってリソースをプロビジョニングし、アクセスを付与します。直接編集することもできます。

セクションまたはフィールド

説明

schema_version

agent.toml フォーマットのバージョン。生成されたプロジェクトでは 1 を使用します。

[agent] framework

フレームワークTemplate: langgraph または openai。

[agent] server

エージェントサーバー: DurableAgentServer の場合は agentbricks、独自のサーバーの場合は custom。

[memory_store] name

エージェントが使用するマネージドメモリストア。

[session_store] name

エージェントが使用するマネージドセッションストア。

[tracing] experiment_name

トレース用のMLflowエクスペリメント。トレーシングをオフにするには、セクションを削除します。

[[tools]]

ツールバインディング。各ツールには、id、userまたはappのauth値、およびツールを識別するsourceがあり、さらにオプションでpolicyがあります。

[auth.user]

コード内で作成するツールのユーザー認証をリクエストする：required および additional_api_scopes。ユーザー認証のリクエストを参照してください。

セクションまたはフィールド

説明

schema_version

agent.toml フォーマットのバージョン。生成されたプロジェクトでは 1 を使用します。

[agent] framework

フレームワークTemplate: langgraph または openai。

[agent] server

エージェントサーバー: DurableAgentServer の場合は agentbricks、独自のサーバーの場合は custom。

[memory_store] name

エージェントが使用するマネージドメモリストア。

[session_store] name

エージェントが使用するマネージドセッションストア。

[tracing] experiment_name

トレース用のMLflowエクスペリメント。トレーシングをオフにするには、セクションを削除します。

[[tools]]

ツールバインディング。各ツールには、id、userまたはappのauth値、およびツールを識別するsourceがあり、さらにオプションでpolicyがあります。

[auth.user]

コード内で作成するツールのユーザー認証をリクエストする：required および additional_api_scopes。ユーザー認証のリクエストを参照してください。

次の例は、agentbricks init が my-agent という名前の LangGraph エージェント用に生成するファイルです。

Toml
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 Agent、および 1 つのテーブルにスコープ指定されたサンドボックス：

Toml
[[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 を参照してください。

その他のリソース​

このページの見出し