databricks-agentbricks 0.4.0__tar.gz → 0.5.0__tar.gz

{databricks_agentbricks-0.4.0 → databricks_agentbricks-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: databricks-agentbricks
-Version: 0.4.0
+Version: 0.5.0
 Summary: Agent Bricks CLI and AgentKit SDK for custom agents on Databricks
 Author-email: Databricks <agent-feedback@databricks.com>
 License-File: NOTICE
@@ -103,19 +103,16 @@ The two ways to run an agent:
 
 ## Installation
 
-From PyPI:
-
 The `databricks-agentbricks` Python distribution installs the `agentbricks` command and AgentKit.
 
 ```sh
 pip install databricks-agentbricks
 ```
 
-From source:
-
-```sh
-pip install 'git+https://github.com/databricks/databricks-ai-bridge.git#subdirectory=integrations/agentbricks'
-```
+Install from PyPI rather than from this repository. Templates on `main` can depend on SDK changes that
+are not yet released, while generated projects install the released SDK from PyPI, so a CLI installed
+from source can scaffold projects that fail to start. To work on Agent Bricks itself, see
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 The base package includes the CLI, store SDK, and `DurableAgentServer` HTTP runtime. Generated projects
 declare their framework dependencies automatically.
@@ -153,7 +150,7 @@ The shortest path from a blank directory to a running and deployed agent:
 
 ```sh
 agentbricks login --profile <profile>
-agentbricks init my-agent
+agentbricks init my-agent       # Defaults to LangGraph; add --framework=openai for OpenAI Agents SDK
 cd my-agent
 agentbricks dev                 # run locally
 agentbricks deploy my-agent     # deploy to Databricks
@@ -180,6 +177,28 @@ it an HTTP request. MLflow tracing is on by default (`agentbricks init` binds a
 `.agentbricks/` and `agentbricks deploy` to the bound workspace experiment; `agentbricks tracing list` shows the
 available traces.
 
+## Inspect and clean up a project
+
+Read `agent.toml` for the recorded agent name, declared memory/session stores, tracing, and tool
+bindings. A declaration does not confirm that the resource exists or that the deployed app can use it.
+
+| Inspect | Command | Details |
+| --- | --- | --- |
+| Local onboarding checks | `agentbricks doctor .` | Offline; does not verify bindings or deployed resources. |
+| Agent Bricks apps in a workspace | `agentbricks -p <profile> deployments list` | Lists apps with the `agent-bricks-` prefix in the selected workspace, including other projects. |
+| App status and URL | `agentbricks -p <profile> deployments get agent-bricks-<name>` | Queries the selected workspace for the named app. |
+| Memory store IDs and details | `agentbricks -p <profile> memory stores list`, then `agentbricks -p <profile> memory stores get <resource-name>` | Workspace-wide; can include other projects' stores. Use the ID or resource name, not the display name. |
+| Session store names and details | `agentbricks -p <profile> sessions stores list`, then `agentbricks -p <profile> sessions stores get <name>` | Workspace-wide; can include other projects' stores. Use the store name. |
+
+Review each confirmation. Delete a store only after confirming that you own it and no other agent
+needs it, using the same profile and identifier used to inspect it.
+
+| Clean up | Command | Details |
+| --- | --- | --- |
+| Deployment | `agentbricks -p <profile> deployments delete agent-bricks-<name>` | Managed Runtime Store cleanup checks the app identity and runs before app deletion; a cleanup failure retains the app for retry. Memory/session stores, tracing experiments, tools, and source files are retained. |
+| [Memory store](cli.md#agentbricks-memory-stores-delete) | `agentbricks -p <profile> memory stores delete <resource-name>` | Soft-deletes the store after confirmation. |
+| [Session store](cli.md#agentbricks-sessions-stores-delete) | `agentbricks -p <profile> sessions stores delete <name>` | Deletes the store after confirmation. |
+
 ## Public names
 
 Use `agentbricks` for the CLI and `AgentKitClient` from `databricks_agentkit` for the Python SDK. New
@@ -460,6 +479,10 @@ agentbricks deploy my-agent
 ```
 
 Memory and session stores are independent resources: deleting one never affects the other.
+For projects with `agent.toml`, unbinding either store removes its declaration; the next deploy
+removes the corresponding `AGENT_MEMORY_STORE` or `AGENT_SESSION_STORE` entry from `app.yaml`.
+Unbinding does not delete the store or revoke an existing grant to the App's service principal.
+If access must be revoked, coordinate that separately with the store owner or workspace admin.
 
 ## Commands
 
@@ -624,7 +647,7 @@ add` updates only this file; direct TOML edits have the same behavior. Both mana
 adapters read the managed bindings at runtime without generating or patching agent source:
 
 ```sh
-agentbricks tools add sandbox --scope table:samples.nyctaxi.trips
+agentbricks tools add sandbox --scope volume:main.data.files
 agentbricks tools add mcp system.ai.web_search
 agentbricks tools add uc-function catalog.schema.lookup_ticket
 agentbricks tools add genie-one
@@ -662,9 +685,7 @@ user's permissions instead of the App service principal.
 | --- | --- |
 | UC function | Apps `uc_securable`: `FUNCTION` / `EXECUTE` |
 | Genie Agent space | Apps `genie_space`: `CAN_RUN` |
-| Sandbox table scope | Apps `uc_securable`: `TABLE` / `SELECT` or `MODIFY` |
 | Sandbox volume scope | Apps `uc_securable`: `VOLUME` / `READ_VOLUME` or `WRITE_VOLUME` |
-| Sandbox Workspace path | Workspace ACL: `CAN_READ` or `CAN_EDIT` |
 | External MCP service | Unity Catalog: effective `EXECUTE` plus `USE_SCHEMA` and `USE_CATALOG` on its named parents |
 | Built-in `system.ai` MCP service, including Sandbox and Genie One | Platform-managed access defaults; Agent Bricks does not mutate system securables |
 
@@ -673,7 +694,7 @@ grant. Use a Genie Agent binding when the App identity should be scoped to one e
 
 Apps-backed tool resources are named deterministically and reconciled to the manifest on each
 deploy: removing a binding removes that Agent Bricks-owned Apps resource while preserving Runtime
-Store, tracing, and user-owned resources. MCP and Workspace ACL grants are additive in this release
+Store, tracing, and user-owned resources. MCP grants are additive in this release
 because their permission APIs do not expose trustworthy Agent Bricks ownership metadata; removing
 those bindings does not revoke an independently valid grant.
 
@@ -882,8 +903,8 @@ If a manifest with `server = "agentbricks"` contains `source = { kind = "python"
 `[[tools]]` entry; the decorated tool in `agent/tools/` remains active. `agentbricks dev` and `agentbricks deploy`
 do not generate or patch Python tool code, and do not alter the manifest's `[[tools]]` bindings.
 
-Sandbox scopes default to read-only access. Repeat `--scope` to allow more than one resource, use
-`volume:` or `workspace:` for those resource types, and use `--permission read_write` only when the
+Sandbox scopes support volumes only and default to read-only access. Repeat `--scope` to allow more
+than one volume, use `volume:catalog.schema.volume`, and use `--permission read_write` only when the
 agent needs writes. Every sandbox call carries this fixed downscope in MCP `_meta`, outside the tool
 arguments controlled by the model. New sandbox bindings also expose the selected Databricks
 credential to sandbox code by default:
@@ -893,9 +914,17 @@ credential to sandbox code by default:
 id = "sandbox"
 auth = "user"
 source = { kind = "sandbox", service = "system.ai.sandbox" }
-policy = { downscope = [{ resource = "workspace:/Workspace/Shared", permission = "read_only" }], databricks_access_token_included = true }
+policy = { downscope = [{ resource = "volume:main.data.files", permission = "read_only" }], databricks_access_token_included = true }
 ```
 
+Table sandbox scopes are not supported yet because Databricks Connect does not support table
+downscoping. Workspace sandbox scopes are also not supported yet; they have not been validated
+against a live workspace. Use a volume instead. Existing `table:` and `workspace:` entries must be
+removed from `agent.toml` before using `agentbricks dev` or `agentbricks deploy`.
+
+The table implementation is retained behind a disabled code-level gate so it can be enabled when
+Databricks Connect supports table downscoping. There is no CLI option to bypass that gate.
+
 With `databricks_access_token_included = true`, the sandbox receives `DATABRICKS_HOST`, a short-lived
 `DATABRICKS_TOKEN`, and `DATABRICKS_AUTH_TYPE`, so code such as
 `WorkspaceClient().current_user.me()` can call workspace APIs. This policy does not choose the

{databricks_agentbricks-0.4.0 → databricks_agentbricks-0.5.0}/README.md

@@ -67,19 +67,16 @@ The two ways to run an agent:
 
 ## Installation
 
-From PyPI:
-
 The `databricks-agentbricks` Python distribution installs the `agentbricks` command and AgentKit.
 
 ```sh
 pip install databricks-agentbricks
 ```
 
-From source:
-
-```sh
-pip install 'git+https://github.com/databricks/databricks-ai-bridge.git#subdirectory=integrations/agentbricks'
-```
+Install from PyPI rather than from this repository. Templates on `main` can depend on SDK changes that
+are not yet released, while generated projects install the released SDK from PyPI, so a CLI installed
+from source can scaffold projects that fail to start. To work on Agent Bricks itself, see
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 The base package includes the CLI, store SDK, and `DurableAgentServer` HTTP runtime. Generated projects
 declare their framework dependencies automatically.
@@ -117,7 +114,7 @@ The shortest path from a blank directory to a running and deployed agent:
 
 ```sh
 agentbricks login --profile <profile>
-agentbricks init my-agent
+agentbricks init my-agent       # Defaults to LangGraph; add --framework=openai for OpenAI Agents SDK
 cd my-agent
 agentbricks dev                 # run locally
 agentbricks deploy my-agent     # deploy to Databricks
@@ -144,6 +141,28 @@ it an HTTP request. MLflow tracing is on by default (`agentbricks init` binds a
 `.agentbricks/` and `agentbricks deploy` to the bound workspace experiment; `agentbricks tracing list` shows the
 available traces.
 
+## Inspect and clean up a project
+
+Read `agent.toml` for the recorded agent name, declared memory/session stores, tracing, and tool
+bindings. A declaration does not confirm that the resource exists or that the deployed app can use it.
+
+| Inspect | Command | Details |
+| --- | --- | --- |
+| Local onboarding checks | `agentbricks doctor .` | Offline; does not verify bindings or deployed resources. |
+| Agent Bricks apps in a workspace | `agentbricks -p <profile> deployments list` | Lists apps with the `agent-bricks-` prefix in the selected workspace, including other projects. |
+| App status and URL | `agentbricks -p <profile> deployments get agent-bricks-<name>` | Queries the selected workspace for the named app. |
+| Memory store IDs and details | `agentbricks -p <profile> memory stores list`, then `agentbricks -p <profile> memory stores get <resource-name>` | Workspace-wide; can include other projects' stores. Use the ID or resource name, not the display name. |
+| Session store names and details | `agentbricks -p <profile> sessions stores list`, then `agentbricks -p <profile> sessions stores get <name>` | Workspace-wide; can include other projects' stores. Use the store name. |
+
+Review each confirmation. Delete a store only after confirming that you own it and no other agent
+needs it, using the same profile and identifier used to inspect it.
+
+| Clean up | Command | Details |
+| --- | --- | --- |
+| Deployment | `agentbricks -p <profile> deployments delete agent-bricks-<name>` | Managed Runtime Store cleanup checks the app identity and runs before app deletion; a cleanup failure retains the app for retry. Memory/session stores, tracing experiments, tools, and source files are retained. |
+| [Memory store](cli.md#agentbricks-memory-stores-delete) | `agentbricks -p <profile> memory stores delete <resource-name>` | Soft-deletes the store after confirmation. |
+| [Session store](cli.md#agentbricks-sessions-stores-delete) | `agentbricks -p <profile> sessions stores delete <name>` | Deletes the store after confirmation. |
+
 ## Public names
 
 Use `agentbricks` for the CLI and `AgentKitClient` from `databricks_agentkit` for the Python SDK. New
@@ -424,6 +443,10 @@ agentbricks deploy my-agent
 ```
 
 Memory and session stores are independent resources: deleting one never affects the other.
+For projects with `agent.toml`, unbinding either store removes its declaration; the next deploy
+removes the corresponding `AGENT_MEMORY_STORE` or `AGENT_SESSION_STORE` entry from `app.yaml`.
+Unbinding does not delete the store or revoke an existing grant to the App's service principal.
+If access must be revoked, coordinate that separately with the store owner or workspace admin.
 
 ## Commands
 
@@ -588,7 +611,7 @@ add` updates only this file; direct TOML edits have the same behavior. Both mana
 adapters read the managed bindings at runtime without generating or patching agent source:
 
 ```sh
-agentbricks tools add sandbox --scope table:samples.nyctaxi.trips
+agentbricks tools add sandbox --scope volume:main.data.files
 agentbricks tools add mcp system.ai.web_search
 agentbricks tools add uc-function catalog.schema.lookup_ticket
 agentbricks tools add genie-one
@@ -626,9 +649,7 @@ user's permissions instead of the App service principal.
 | --- | --- |
 | UC function | Apps `uc_securable`: `FUNCTION` / `EXECUTE` |
 | Genie Agent space | Apps `genie_space`: `CAN_RUN` |
-| Sandbox table scope | Apps `uc_securable`: `TABLE` / `SELECT` or `MODIFY` |
 | Sandbox volume scope | Apps `uc_securable`: `VOLUME` / `READ_VOLUME` or `WRITE_VOLUME` |
-| Sandbox Workspace path | Workspace ACL: `CAN_READ` or `CAN_EDIT` |
 | External MCP service | Unity Catalog: effective `EXECUTE` plus `USE_SCHEMA` and `USE_CATALOG` on its named parents |
 | Built-in `system.ai` MCP service, including Sandbox and Genie One | Platform-managed access defaults; Agent Bricks does not mutate system securables |
 
@@ -637,7 +658,7 @@ grant. Use a Genie Agent binding when the App identity should be scoped to one e
 
 Apps-backed tool resources are named deterministically and reconciled to the manifest on each
 deploy: removing a binding removes that Agent Bricks-owned Apps resource while preserving Runtime
-Store, tracing, and user-owned resources. MCP and Workspace ACL grants are additive in this release
+Store, tracing, and user-owned resources. MCP grants are additive in this release
 because their permission APIs do not expose trustworthy Agent Bricks ownership metadata; removing
 those bindings does not revoke an independently valid grant.
 
@@ -846,8 +867,8 @@ If a manifest with `server = "agentbricks"` contains `source = { kind = "python"
 `[[tools]]` entry; the decorated tool in `agent/tools/` remains active. `agentbricks dev` and `agentbricks deploy`
 do not generate or patch Python tool code, and do not alter the manifest's `[[tools]]` bindings.
 
-Sandbox scopes default to read-only access. Repeat `--scope` to allow more than one resource, use
-`volume:` or `workspace:` for those resource types, and use `--permission read_write` only when the
+Sandbox scopes support volumes only and default to read-only access. Repeat `--scope` to allow more
+than one volume, use `volume:catalog.schema.volume`, and use `--permission read_write` only when the
 agent needs writes. Every sandbox call carries this fixed downscope in MCP `_meta`, outside the tool
 arguments controlled by the model. New sandbox bindings also expose the selected Databricks
 credential to sandbox code by default:
@@ -857,9 +878,17 @@ credential to sandbox code by default:
 id = "sandbox"
 auth = "user"
 source = { kind = "sandbox", service = "system.ai.sandbox" }
-policy = { downscope = [{ resource = "workspace:/Workspace/Shared", permission = "read_only" }], databricks_access_token_included = true }
+policy = { downscope = [{ resource = "volume:main.data.files", permission = "read_only" }], databricks_access_token_included = true }
 ```
 
+Table sandbox scopes are not supported yet because Databricks Connect does not support table
+downscoping. Workspace sandbox scopes are also not supported yet; they have not been validated
+against a live workspace. Use a volume instead. Existing `table:` and `workspace:` entries must be
+removed from `agent.toml` before using `agentbricks dev` or `agentbricks deploy`.
+
+The table implementation is retained behind a disabled code-level gate so it can be enabled when
+Databricks Connect supports table downscoping. There is no CLI option to bypass that gate.
+
 With `databricks_access_token_included = true`, the sandbox receives `DATABRICKS_HOST`, a short-lived
 `DATABRICKS_TOKEN`, and `DATABRICKS_AUTH_TYPE`, so code such as
 `WorkspaceClient().current_user.me()` can call workspace APIs. This policy does not choose the

{databricks_agentbricks-0.4.0 → databricks_agentbricks-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "databricks-agentbricks"
-version = "0.4.0"
+version = "0.5.0"
 description = "Agent Bricks CLI and AgentKit SDK for custom agents on Databricks"
 authors = [
     { name="Databricks", email="agent-feedback@databricks.com" },

{databricks_agentbricks-0.4.0 → databricks_agentbricks-0.5.0}/src/databricks_agentbricks/cli/app.py

@@ -16,12 +16,13 @@ from databricks_agentbricks.cli.deploy import deploy, deployments
 from databricks_agentbricks.cli.dev import dev
 from databricks_agentbricks.cli.doctor import doctor
 from databricks_agentbricks.cli.endpoint import endpoint
-from databricks_agentbricks.cli.help import configure_help
 from databricks_agentbricks.cli.init import init
 from databricks_agentbricks.cli.memory import memory
 from databricks_agentbricks.cli.sessions import sessions
 from databricks_agentbricks.cli.tools import tools
 from databricks_agentbricks.cli.tracing import tracing
+from databricks_agentbricks.clients.api_client_provider import ApiClientProvider
+from databricks_agentbricks.presentation.help import configure_help
 from databricks_agentkit._api_client import _AgentBricksApiClient
 
 
@@ -31,12 +32,11 @@ class CliContext:
     def __init__(self, profile: Optional[str], output: str):
         self.profile = profile
         self.output = output
-        self._client: Optional[_AgentBricksApiClient] = None
+        self.api_client_provider = ApiClientProvider(profile)
 
     def client(self) -> _AgentBricksApiClient:
-        if self._client is None:
-            self._client = _AgentBricksApiClient(self.profile)
-        return self._client
+        """Compatibility accessor for commands not yet migrated to ``api_client_provider``."""
+        return self.api_client_provider.get()
 
 
 @click.group(name="agentbricks", context_settings={"help_option_names": ["-h", "--help"]})

{databricks_agentbricks-0.4.0 → databricks_agentbricks-0.5.0}/src/databricks_agentbricks/cli/auth.py

@@ -19,8 +19,8 @@ from typing import Optional
 
 import click
 
-from databricks_agentbricks import render
 from databricks_agentbricks.errors import AgentCliError
+from databricks_agentbricks.presentation import render
 from databricks_agentkit._api_client import _AgentBricksApiClient
 
 

databricks_agentbricks-0.5.0/src/databricks_agentbricks/cli/deploy.py

@@ -0,0 +1,243 @@
+"""`agentbricks deploy` and the `agentbricks deployments` group — manage agent deployments.
+
+`agentbricks deploy` is the integrated entry point: it provisions the memory/session stores
+bound in `agent.toml`, grants the app's service principal access to them, then rolls out
+the deployment. Agent Bricks Runtime deployments receive a persistent Runtime Store; a temporary rollout
+switch chooses between the legacy per-app Lakebase project and the service-managed database.
+`agent.toml` is the CLI's authoring source, resolved here into the `AGENT_MEMORY_STORE` /
+`AGENT_SESSION_STORE` env vars written into `app.yaml` — the runtime reads those, never
+`agent.toml`. `agentbricks deployments` covers the lifecycle verbs
+(`list`/`get`/`logs`/`start`/`stop`/`delete`).
+
+Every verb here is a thin adapter: it builds a `DeployService` from the CLI context, handles any
+terminal confirmation, calls one method, and hands the raw result to a presenter. The work itself
+lives in the service and its collaborators,
+including driving the Databricks Apps runtime via the `databricks apps` CLI (an implementation detail
+that is not part of the Agent Bricks CLI surface).
+"""
+
+from __future__ import annotations
+
+import click
+
+from databricks_agentbricks.clients.apps_client import AppsClient
+from databricks_agentbricks.clients.apps_user_auth_client import AppsUserAuthClient
+from databricks_agentbricks.clients.conversation_store_client import (
+    MemoryStoreClient,
+    SessionStoreClient,
+)
+from databricks_agentbricks.clients.databricks_cli import _databricks
+from databricks_agentbricks.clients.tracing_client import TracingClient
+from databricks_agentbricks.presentation import render
+from databricks_agentbricks.presentation.deploy import (
+    present_deleted,
+    present_deploy_result,
+    present_deployment_detail,
+    present_deployments_list,
+    present_started,
+    present_stopped,
+)
+from databricks_agentbricks.presentation.reporter import ClickReporter
+from databricks_agentbricks.projects.resolver import ProjectResolver
+from databricks_agentbricks.services.deploy_service import DeployRequest, DeployService
+from databricks_agentbricks.services.deployment.config import (
+    _DEFAULT_PIP_INDEX_URL,
+    _USE_MANAGED_RUNTIME_STORE,
+    TRACES_EXPERIMENT_ID_ENV,  # noqa: F401 - compatibility re-export
+    TRACES_TRACKING_URI_ENV,  # noqa: F401 - compatibility re-export
+    MlflowTracingConfig,  # noqa: F401 - compatibility re-export
+    mlflow_tracing_config,  # noqa: F401 - compatibility re-export
+)
+from databricks_agentbricks.services.deployment.names import (
+    DeploymentName,
+    _prefixed_name,  # noqa: F401 - compatibility re-export
+)
+from databricks_agentbricks.services.deployment.provisioners import (
+    AppProvisioner,
+    MemoryStoreProvisioner,
+    RuntimeStoreProvisioner,
+    SessionStoreProvisioner,
+    TracingProvisioner,
+)
+from databricks_agentbricks.services.deployment.tool_access_provisioner import ToolAccessProvisioner
+
+
+def build_deploy_service(obj) -> DeployService:
+    """Compose a deployment service for this CLI invocation without opening an API client."""
+    api_client_provider = obj.api_client_provider
+    apps_client = AppsClient(obj.profile, runner=_databricks)
+    apps_user_auth_client = AppsUserAuthClient(obj.profile)
+    reporter = ClickReporter()
+    return DeployService(
+        project_resolver=ProjectResolver(),
+        apps_client=apps_client,
+        api_client_provider=api_client_provider,
+        app_provisioner=AppProvisioner(
+            apps_client, api_client_provider, apps_user_auth_client, reporter
+        ),
+        memory_store_provisioner=MemoryStoreProvisioner(
+            MemoryStoreClient(api_client_provider), reporter
+        ),
+        session_store_provisioner=SessionStoreProvisioner(
+            SessionStoreClient(api_client_provider), reporter
+        ),
+        tracing_provisioner=TracingProvisioner(
+            TracingClient(api_client_provider, apps_client, obj.profile), reporter
+        ),
+        runtime_store_provisioner=RuntimeStoreProvisioner(
+            api_client_provider, apps_client, obj.profile, _USE_MANAGED_RUNTIME_STORE, reporter
+        ),
+        tool_access_provisioner=ToolAccessProvisioner(apps_client, obj.profile, reporter),
+        reporter=reporter,
+    )
+
+
+# --- agentbricks deploy -----------------------------------------------------------
+
+
+@click.command()
+@click.argument("name", required=False)
+@click.option(
+    "--source",
+    default=".",
+    type=click.Path(exists=True, file_okay=False),
+    help="Local source directory for the deployment (containing app.yaml). Defaults to the "
+    "current directory.",
+)
+@click.option(
+    "--pip-index-url",
+    default=_DEFAULT_PIP_INDEX_URL,
+    show_default=True,
+    help="Base URL of the Python Package Index. Defaults to public PyPI.",
+)
+@click.option(
+    "--workspace-path",
+    default=None,
+    help="Workspace destination for the synced source (defaults to a per-user path).",
+)
+@click.option(
+    "--instances",
+    "instance_count",
+    type=click.IntRange(min=1, max=5),
+    default=None,
+    help="Number of deployment instances.",
+)
+@click.option(
+    "--allow-user-scope-update",
+    is_flag=True,
+    help="Allow Agent Bricks to add missing user API scopes to an existing App from managed-tool "
+    "inference and [auth.user] additions. Once added, later deploys do not need this flag.",
+)
+@click.pass_obj
+def deploy(
+    obj,
+    name,
+    source,
+    pip_index_url,
+    workspace_path,
+    instance_count,
+    allow_user_scope_update,
+) -> None:
+    """Deploy your agent to Databricks Apps and get back a hosted URL to try it.
+
+    Rolls the agent out to Databricks Apps and prints the URL where you (or anyone you share it with)
+    can use it. The deployed agent reaches Databricks model serving through the AI Gateway using the
+    app's own identity — no model keys to configure — and `deploy` also reconciles the stores declared
+    in agent.toml and wires in any tracing.
+
+    NAME is recorded in agent.toml on the first deploy, so a later `agentbricks deploy` from the project
+    directory can omit it (passing NAME again updates the recorded name). New apps are named
+    `agent-bricks-<name>`. Use the full app name with the `agentbricks deployments` commands.
+
+    Any memory/session store declared in agent.toml (for example, by `agentbricks memory/sessions bind`)
+    is created if it doesn't exist yet; agent.toml itself is never modified for stores.
+
+    Scaling to multiple instances (--instances) uses best-effort sticky routing, so a browser
+    session automatically stays on one instance.
+
+    \b
+    To keep a session on one app replica (sticky routing), API clients must resend a stable
+    UUID (for example, their session id) in the X-Routing-Key request header on every request.
+    The header is a routing hint only - non-blank, no more than 128 UTF-8 bytes, used verbatim -
+    not authentication and not the session id itself (send the session id in the request body):
+      X-Routing-Key: <uuid>
+    """
+    request = DeployRequest(
+        name=name,
+        source=source,
+        pip_index_url=pip_index_url,
+        workspace_path=workspace_path,
+        instance_count=instance_count,
+        allow_user_scope_update=allow_user_scope_update,
+    )
+    result = build_deploy_service(obj).deploy(request)
+    present_deploy_result(result, output=obj.output)
+
+
+# --- agentbricks deployments <lifecycle> ------------------------------------------
+
+
+@click.group()
+def deployments() -> None:
+    """Inspect and manage deployed agents: list, get, stream logs, start, stop, or delete."""
+
+
+@deployments.command("list")
+@click.pass_obj
+def deployments_list(obj) -> None:
+    """List Agent Bricks deployments (apps named `agent-bricks-*`)."""
+    present_deployments_list(build_deploy_service(obj).list_deployments(), output=obj.output)
+
+
+@deployments.command("get")
+@click.argument("name", type=DeploymentName)
+@click.pass_obj
+def deployments_get(obj, name) -> None:
+    """Get an agent deployment's details."""
+    present_deployment_detail(build_deploy_service(obj).get(name), name, output=obj.output)
+
+
+@deployments.command("logs")
+@click.argument("name", type=DeploymentName)
+@click.pass_obj
+def deployments_logs(obj, name) -> None:
+    """Stream a deployment's logs."""
+    build_deploy_service(obj).logs(name)
+
+
+@deployments.command("start")
+@click.argument("name", type=DeploymentName)
+@click.pass_obj
+def deployments_start(obj, name) -> None:
+    """Start a deployment."""
+    build_deploy_service(obj).start(name)
+    present_started(name, output=obj.output)
+
+
+@deployments.command("stop")
+@click.argument("name", type=DeploymentName)
+@click.option("--yes", "-y", is_flag=True, help="Skip the confirmation prompt.")
+@click.pass_obj
+def deployments_stop(obj, name, yes) -> None:
+    """Stop a deployment."""
+    if not yes:
+        click.confirm(
+            f"Stop deployment '{name}'? This cannot be undone.", default=False, abort=True
+        )
+    build_deploy_service(obj).stop(name)
+    present_stopped(name, output=obj.output)
+
+
+@deployments.command("delete")
+@click.argument("name", type=DeploymentName)
+@click.option("--yes", "-y", is_flag=True, help="Skip the confirmation prompt.")
+@click.pass_obj
+def deployments_delete(obj, name, yes) -> None:
+    """Delete a deployment and, when managed provisioning is enabled, its Runtime Store."""
+    service = build_deploy_service(obj)
+    target = f"deployment '{name}'"
+    if not yes and service.deletes_runtime_store_data():
+        target += " and its Runtime Store data"
+    render.confirm_destroy(target, assume_yes=yes)
+    service.delete(name)
+    present_deleted(name, output=obj.output)