Agent Server
エージェントサーバーとは、エージェントコードをサービスに変換するライブラリのことです。エージェントループをHTTPサーバー内にラップし、クライアントがエージェントを実行するために呼び出すAPIを定義し、クライアント接続を管理し、ランが中断されたときの動作を決定します。エージェントサーバーはエージェントランタイム上で実行されます。レイヤーがどのように組み合わされているかについては、Databricksでのエージェントのデプロイを参照してください。
新しいエージェントの場合、Databricks では、このページで説明されている AgentKit が提供するエージェント サーバーをお勧めします。レガシーエージェントサーバーとの比較については、「Databricks上のエージェントサーバーの比較」を参照してください。
要件
- Python 3.10 以降。
- AgentKitを含む
databricks-agentbricksパッケージ。agentbricks initで作成するプロジェクトは、依存関係として宣言します。 agentbricks devでサーバーをローカルでランするには、uv を使用します。
AgentKit
AgentKit は、Agent ランタイム で実行されるエージェントを構築するための Agent Bricks ライブラリです。これは、エージェントを提供するエージェントサーバーに加え、エージェントメモリ、エージェントセッション、トレース、および認証用のクライアントとヘルパーを提供します。Agent Bricks CLI で作成するプロジェクトでは、default で AgentKit が使用されます。
エージェントサーバー
AgentKit は、 DurableAgentServer クラスを通じてエージェント サーバーを提供します。エージェント サーバーは、エージェント ループを HTTP サーバーでラップして、呼び出し API を提供し、各ランを追跡し、クラッシュや再起動によって中断されたランを回復します。以下の機能を提供します。
- すべてのリクエストモードに対応する単一のAPI : 同期、ストリーミング、バックグラウンドの呼び出しに加え、ストリームの再接続もすべて同じハンドラーによって処理されます。
- べき等な呼び出し : クライアントが生成した呼び出し ID により、リトライされたリクエストが重複するランを起動しないよう保証されます。
- 順序付きセッション :同じセッション内の呼び出しは、順番に1つずつ実行されます。
- 永続ラン状態 : デプロイ時、ランのステータス、イベント、結果はワーカーの再起動後も保持されます。
- クラッシュリカバリ :サーバーは中断されたランを検出し、代替試行を起動します。
- リクエストユーザー認証 :ツールは、リクエストを送信したユーザーの権限で実行できます。
- カスタムEndpoint :エージェントサーバーはFastAPIアプリケーションであるため、独自のルートを追加できます。
AgentKit に含まれるもの
AgentKitはdatabricks_agentkitのPythonライブラリです。次の内容をエクスポートします:
エクスポート | 説明 |
|---|---|
| エージェントサーバーと、それが呼び出しおよびリカバリハンドラーに渡すコンテキスト。 |
| エージェントメモリストアとエージェントセッションストア用のクライアント。ストアを作成して取得し、ストアのメモリとセッションを |
| エージェントの MLflow トレースを設定し、作業単位の周囲でトレースを起動します。 |
| エージェントの環境から、認証済みDatabricks SDK |
| エージェントが Unity Gateway を介して呼び出すことができるモデルサービスを一覧表示します。 |
ライブラリにはdatabricks_agentkit.langgraphおよびdatabricks_agentkit.openaiのフレームワークヘルパーも含まれており、生成されたテンプレートはこれらを使用して各フレームワークをセッションストアに接続します。メモリおよびセッション APIs については、 エージェントメモリ および エージェントセッションを参照してください。
エージェントを登録する
agentbricks init を使用してプロジェクトを作成すると、CLI が自動的にこれを実行します。生成された runtime/main.py はサーバーを作成し、テンプレートの呼び出しおよびリカバリハンドラーを登録するため、agent/ 内のエージェントコードのみを編集します。既存のエージェントを持ち込むか、独自のハンドラーを記述するには、このセクションのステップに従ってください。
DurableAgentServer を作成し、@app.invoke に非同期呼び出しハンドラーを登録する。ハンドラーは、リクエストの input と呼び出しコンテキストを受け取り、JSON シリアル化可能な結果を返します。context.emit を使用して進捗をイベントとして公開します。
from databricks_agentkit import DurableAgentServer, InvocationContext
app = DurableAgentServer()
@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
await context.emit({"type": "status", "message": "Looking that up"})
answer = await run_my_agent(input, session_id=context.session_id)
return {"answer": answer}
登録できるinvocation handlerは1つであり、ハンドラーがないとサーバーは起動しません。ハンドラーはすべてのリクエストモードに対応しており、クライアントは結果を待つか、イベントをストリームするか、バックグラウンドで実行するかを選択できます。
サーバーをローカルで実行するには、agentbricks devでサーバーを起動します。agentbricks initを使用して作成するプロジェクトには、Uvicornを使用してサーバーをランするエントリーポイントと、デプロイ後に同じエントリーポイントを起動するapp.yamlファイルが含まれています。手動でプロジェクトを作成する場合は、最小限のプロジェクトファイルにファイルを作成してください。
最小限のプロジェクトファイル
agentbricks initで作成するプロジェクトには、これらのファイルが既に含まれています。agentbricks devは databricks apps run-localをラップするため、 app.yamlをローカルで読み取り、その中でコマンドを起動します。初回ラン時に uvを使用してプロジェクトの環境をビルドするため、 uvがインストールされている必要があります。
最小限のプロジェクトには、エージェントコードに加えて、以下のLayoutがあります。
my-agent/
├── agent.toml
├── app.yaml
├── pyproject.toml
└── runtime/
├── __init__.py
└── main.py
app.yaml プロジェクトのstart-serverスクリプトをランします:
command: ['uv', 'run', 'start-server']
pyproject.toml 依存関係を宣言し、start-serverをエントリーポイントにマップします:
[project]
name = "my-agent"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
"databricks-agentbricks[openai]",
"uvicorn",
]
[project.scripts]
start-server = "runtime.main:main"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["runtime"]
runtime/main.py サーバーを作成し、ハンドラーを登録し、PORT環境変数内のポートでUvicornを使用してサーバーを実行するmain()関数を定義します:
import os
import uvicorn
from databricks_agentkit import DurableAgentServer, InvocationContext
app = DurableAgentServer()
@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
answer = await run_my_agent(input, session_id=context.session_id)
return {"answer": answer}
def main():
uvicorn.run("runtime.main:app", host="0.0.0.0", port=int(os.getenv("PORT", "8000")))
agent.toml プロジェクトを宣言する:
schema_version = 1
[agent]
framework = "openai"
server = "agentbricks"
schema_versionは1である必要があります。framework必須で、openaiまたはlanggraphを受け入れます。ハンドラーがどちらのフレームワークも使用していない場合でも、設定してください。その場合は、openaiを使用します。server = "agentbricks"DurableAgentServerを選択します。
プロジェクトディレクトリからagentbricks devをランします。defaultでは、サーバーはhttp://localhost:8000でリッスンします。
呼び出しコンテキスト
ハンドラーの 2 番目の引数は InvocationContext です。
属性 | 説明 |
|---|---|
| この呼び出しに対してクライアントが送信した ID。 |
| 呼び出しが属するセッション、またはクライアントが送信しなかった場合は |
| 試行回数。最初の試行は |
|
|
| JSON イベントを保存し、ストリーミング クライアントに配信し、ストリーム内のイベントの位置を返します。 |
| エージェントが リクエストユーザー認証を必要とする場合のリクエストユーザー資格情報リゾルバー。それ以外の場合は、 |
Invocation API
DurableAgentServer は、/api/invocations で呼び出しAPIを提供します。
POST /api/invocations呼び出しを起動します。defaultでは、リクエストは結果を待ちます。イベントを Server-Sent Events として受信するにはstreamを設定し、ステータス URL とともに即座に応答するにはbackgroundを設定します。GET /api/invocations/<id>インボケーションのステータスを返し、完了後に出力を返します。GET /api/invocations/<id>/events?after=<event-id>保存されたイベントをストリームするため、クライアントは接続が切断された後に再接続できます。
呼び出しが完了すると、そのストリームは出力を含まない run.completed イベントで終了します。結果を読み取るには、ストリームが終了した後に GET /api/invocations/<id> を呼び出します。
リクエストフィールド、例、およびレスポンスのフォーマットについては、Databricks 上にデプロイされたエージェントのクエリーを参照してください。
べき等性
クライアントは、呼び出しごとに UUID id を送信します。サーバーは呼び出し記録を保持している間、IDを冪等性キーとして扱います。同じリクエストを再送信すると、エージェントを再度実行する代わりに既存の呼び出しが返されます。キーは input と session_id の両方をカバーします。異なる input を持つ ID、または異なるもしくは欠落した session_id を持つ ID を再利用すると、 409 エラーが返されます。
失敗した呼び出しは、その ID の下では失敗したままになります。同じリクエストを再送信すると、エージェントを再度実行する代わりに、保存された失敗が返されます。失敗した呼び出しを再試行するには、新しい id を指定して送信します。
セッション
クライアントは session_id を送信して、呼び出しを1つの会話にグループ化できます。サーバーはセッションIDを input とは別に保存し、context.session_id としてハンドラーに渡し、セッションIDを共有する呼び出しを1つずつ順番に実行します。サーバーは、呼び出しIDまたは入力からセッションを推論しません。セッションIDがない場合、呼び出しはセッションレスになります。
ランのステータス
DurableAgentServer 各呼び出しのリクエスト、ステータス、ハートビート、イベント、および結果をランタイムストア(Runtime Store)に保存します。
- ローカルでの開発 :
agentbricks devはインプロセス ランタイム ストアを使用します。呼び出し API の動作は同様ですが、プロセスが停止するとランのステータスが失われ、サーバーは中断された作業を再起動しません。 - デプロイ済みエージェント :
agentbricks deployは、Databricks が管理する Lakebase プロジェクト内の各デプロイの ランタイム Store 用に専用のデータベースをプロビジョニングし、再デプロイ時にそれを再利用します。ランタイム Store に独自の Lakebase プロジェクトを使用することはできません。また、自分で作成したりバインドしたりすることもできません。結果とイベントはワーカーの再起動後も保持され、エージェントのどのインスタンスでもステータスや再接続のリクエストを処理できます。agentbricks deployments deleteはデプロイ時にランタイム ストアを削除します。
ランタイムストアには、サーバーの実行状態が保持されます。これは、エージェントが会話履歴や長期記憶に使用するセッションおよびメモリストアとは別個のものです。
クラッシュリカバリ
ワーカーのクラッシュや再起動によって中断されたランを回復するには、リカバリハンドラーを @app.recover に登録します。デプロイされたサーバーがランのハートビートの停止を検出すると、利用可能なワーカーで置き換えの試行を起動し、元の入力を使用してリカバリハンドラーを呼び出します。
@app.recover
async def recover(input, context: InvocationContext) -> dict:
# Resume from the agent's last checkpoint in the session store,
# or replay the input if that's safe for your agent.
return await resume_my_agent(input, session_id=context.session_id)
リカバリーハンドラーを登録しない場合、自動リカバリーは無効になります。デプロイされたエージェントが使用する永続的なランタイム Storeがある場合、サーバーは起動時に警告をログに記録します。agentbricks devを使用すると、サーバーは警告をログに記録しません。
リカバリは次のように動作します。
- リカバリの起動時 :実行中の各試行は、数秒ごとにハートビートを送信します。ハートビートが停止した場合(ワーカーのクラッシュ、再起動、または再デプロイ中の置き換えなど)、サーバーは数秒以内に古いランを検出し、代替の試行を開始します。
- リカバリが起動しない場合 :ハンドラーが例外をスローすると、呼び出しは失敗し、サーバーは再試行しません。リカバリは中断されたワーカーを対象としており、エージェントコードのエラーは対象外です。
- 試行回数 : サーバーはリカバリ試行回数を制限しません。置換試行を行うたびに、
context.attemptが1つずつ増加します。指定した回数の試行後に停止するには、リカバリハンドラーでcontext.attemptを確認し、エラーを発生させます。 - 手動リカバリ :手動でリカバリをTriggerすることはできません。同じ呼び出し ID でリクエストを再送信すると、新しい試行を開始する代わりに既存の呼び出しが返されます。
リカバリは、同じ呼び出しに対してエージェントコードを2回以上ランする場合があります。中断された試行によって、置換の試行が起動される前に外部システムが既に呼び出されている可能性があるため、それらの呼び出しをべき等にしてください。
ユーザー承認をリクエストする
defaultでは、エージェントのツールはアプリの Service Principal の権限で実行されます。リクエストを送信したユーザーの権限でツールをランするには、agent.toml でユーザー認可を宣言します。
-
管理対象ツールの場合、ツールエントリで
auth = "user"を設定します。MCPサーバー、サンドボックス、およびGenieエージェント用のagentbricks tools addコマンドは、defaultでauth = "user"を書き込みます。代わりに--auth appを渡して、アプリのIDを使用します。 -
コードで記述するツールについては、要件とAgent Bricksで推論できないAPIスコープを宣言します。
Toml[auth.user]required = trueadditional_api_scopes = ["sql"]
エージェントにユーザー認可が必要な場合、DurableAgentServer は信頼できる Databricks Apps の要求ヘッダーからユーザーの資格情報を読み取り、アクティブな試行の間のみメモリに保持します。ランタイム Store は資格情報を保存しません。ハンドラーで、context.request_auth からユーザーのワークスペースクライアントを取得します。
@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
user_client = context.request_auth.client_for("user")
me = user_client.current_user.me()
return {"answer": f"Hello, {me.user_name}"}
client_for("app") アプリのService Principalを使用するクライアントを返します。リゾルバーは試行の終了時にクローズするため、クライアントを保存する代わりにハンドラー内で呼び出してください。agentbricks dev と一緒にエージェントをローカルで実行する場合、client_for("user") はローカルの資格情報を使用します。
デプロイ時に、agentbricks deploy はツールに必要な Databricks Apps ユーザー スコープを要求します。既存のアプリに不足しているスコープを追加するには、--allow-user-scope-update を渡します。Databricks アプリで認可の設定をするを参照してください。
ユーザーリクエストによる呼び出しでは、同期、ストリーミング、バックグラウンド、および再接続の各APIが同じように使用されます。サーバーはユーザーの資格情報を保存しないため、中断されたユーザーリクエストによる呼び出しを復元することはできません。ハンドラーがランする前に、置換の試行が MCP_USER_AUTH_RECOVERY_UNSUPPORTED エラーで失敗します。
カスタムEndpointを追加する
DurableAgentServer は FastAPI アプリケーションです。任意の FastAPI アプリケーションに追加するのと同様の方法で、呼び出し API とともにルートを追加します。
@app.get("/status")
async def status() -> dict:
return {"ready": True}
フレームワーク Template
agentbricks init 2つのディレクトリを生成します。
agent/フレームワークコード(モデル、プロンプト、ツール)が含まれます。runtime/フレームワークをDurableAgentServerに接続するアダプターと、アダプターの invoke および recovery ハンドラーを登録するエントリーポイントが含まれます。
アダプターは、各呼び出しをフレームワークのエージェントループへの呼び出しに変換し、フレームワークの出力をイベントと結果に変換します。両方のTemplateはリカバリーハンドラーを登録します。LangGraph Templateはセッションストアの最後のチェックポイントから再開し、OpenAI Agents SDK Templateは同じセッションでリクエストをリプレイします。既存のエージェントを導入するには、アダプターと DurableAgentServer エントリポイントを追加し、最小限のプロジェクトファイルにファイルを作成します。
Databricksのエージェントサーバーの比較
Databricksは、AgentKitエージェントサーバーと、以前のアプリテンプレートで使用されていた2つのレガシーエージェントサーバーの3つのエージェントサーバーを提供します。
エージェントサーバー | パッケージ | クライアント API | 耐久性のある実行 | 使用先 |
|---|---|---|---|---|
AgentKit ( |
|
|
| Agent Bricks CLIで作成するプロジェクト |
|
|
| 構成する Lakebase データベースにおけるランの状態。クラッシュ後、新しい試行によって、中断された試行のイベントLogsからランが続行されます。 |
|
MLflow |
|
| なし | ベースアプリTemplate(次など) |
LongRunningAgentServer は MLflow AgentServer を拡張し、両方とも MLflow ResponsesAgent インターフェイスを実装するエージェントを提供します。それらのいずれかを使用するエージェントをデプロイおよび保守するには、レガシーエージェントサーバーを使用して Databricks Apps でエージェントをランするを参照してください。これらのサーバーのいずれかでエージェントをクエリーするには、Databricks にデプロイされたエージェントをクエリーするを参照してください。
制限事項
- 既存のデプロイのエージェントサーバーは変更できません。
DurableAgentServerと独自のサーバーを切り替えるには、必要なagentbricks init --serverオプションを使用して新しいプロジェクトを作成し、新しい名前でデプロイします。 agent.toml内のserverフィールドを変更しても、既存のサーバー コードがDurableAgentServerに変換されるわけではありません。- リクエストユーザーの承認には
server = "agentbricks"が必要です。