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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: databricks-agentbricks
-Version: 0.3.0
+Version: 0.4.0
 Summary: Agent Bricks CLI and AgentKit SDK for custom agents on Databricks
 Author-email: Databricks <agent-feedback@databricks.com>
 License-File: NOTICE
@@ -10,6 +10,7 @@ Requires-Dist: databricks-ai-bridge[memory]>=0.22.0
 Requires-Dist: databricks-sdk>=0.124.0
 Requires-Dist: fastapi>=0.129.0
 Requires-Dist: mlflow-skinny>=3.10.1
+Requires-Dist: packaging>=23.2
 Requires-Dist: psycopg[binary]>=3.1
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.7
@@ -20,7 +21,7 @@ Requires-Dist: uvicorn>=0.20.0
 Provides-Extra: langgraph
 Requires-Dist: databricks-agents>=1.9.3; extra == 'langgraph'
 Requires-Dist: databricks-langchain>=0.17.0; extra == 'langgraph'
-Requires-Dist: langchain-mcp-adapters>=0.2.1; extra == 'langgraph'
+Requires-Dist: langchain-mcp-adapters>=0.3.0; extra == 'langgraph'
 Requires-Dist: langchain>=1.0.0; extra == 'langgraph'
 Requires-Dist: langgraph>=1.1.0; extra == 'langgraph'
 Requires-Dist: mlflow>=3.10.1; extra == 'langgraph'
@@ -162,9 +163,9 @@ agentbricks deploy my-agent     # deploy to Databricks
 local runtime so local behavior matches a deployment.
 
 `agentbricks deploy my-agent` deploys a Databricks App named `agent-bricks-my-agent`, provisions the
-stores declared in `agent.toml`, and grants the app's service principal access to them. Use
-`agentbricks deployments list` to find deployed apps, and `agentbricks deployments get agent-bricks-my-agent` to
-print an app's URL and status.
+stores declared in `agent.toml`, and grants the app's service principal access to the stores and
+direct App-auth tool resources declared there. Use `agentbricks deployments list` to find deployed
+apps, and `agentbricks deployments get agent-bricks-my-agent` to print an app's URL and status.
 
 `agentbricks init` declares default memory and session stores in `agent.toml`, so the deployed agent has
 long-term memory and durable conversation history. It creates `<name>-<6-letter-token>-memory` and
@@ -263,12 +264,16 @@ Each managed run is an **invocation**. Send a client-generated UUID `id` and you
 ```json
 {
   "id": "550e8400-e29b-41d4-a716-446655440000",
+  "session_id": "support-case-123",
   "input": {"messages": [{"role": "user", "content": "Hello"}]},
   "background": true,
   "stream": true
 }
 ```
 
+The optional top-level `session_id` groups invocations into one application session. It is distinct
+from the invocation `id` and from the `X-Routing-Key` sticky-routing header.
+
 | Endpoint | Behavior |
 | --- | --- |
 | `POST /api/invocations` | Defaults to synchronous execution: `200` with the result under `output`. `stream: true` returns SSE events. `background: true` returns `202` with a status URL; adding `stream: true` also includes an events URL. |
@@ -469,6 +474,7 @@ agentbricks [-p <profile>] [-o text|json]
                [--disable-chat-app]
                [--memory-store NAME] [--session-store NAME]
                [--existing] [--profile P] [directory]
+  doctor       [directory]
   dev          [--source PATH] [--prepare-environment] [--app-port PORT]
   memory
     bind         STORE [--source PATH]
@@ -485,7 +491,8 @@ agentbricks [-p <profile>] [-o text|json]
     unbind     [--source PATH]
     list | get [--experiment-name NAME | --experiment-id ID] [--source PATH]
   tools
-    add sandbox      --scope SCOPE [--scope SCOPE ...] [--source PATH]
+    add sandbox      --scope SCOPE [--scope SCOPE ...]
+                     [--no-databricks-access-token-included] [--source PATH]
     add mcp          SERVICE [--name NAME] [--source PATH]
     add uc-function  FUNCTION [--name NAME] [--source PATH]
     add genie-one    [--name NAME] [--auth user|app] [--source PATH]
@@ -508,6 +515,26 @@ agentbricks init --framework langgraph --existing .
 agentbricks init --framework openai --existing .
 ```
 
+Before or after the conversion, inspect its progress without changing the repository or contacting
+Databricks:
+
+```sh
+agentbricks doctor .
+agentbricks -o json doctor .
+```
+
+Doctor exits 0 only when the project has a valid Agent Bricks manifest and matching project
+metadata, uses the Agent Bricks server, declares the framework-appropriate `databricks-agentbricks`
+extra and a non-empty `app.yaml` command, constructs `DurableAgentServer` with an `invoke` hook, and
+calls a recognized adapter for the selected framework in production Python source. Test, example, and
+old/stale directories do not count as source evidence. A failed report is the normal result for a
+project that still needs migration; run
+`agentbricks init --framework <framework_name> --existing <directory>` with the appropriate framework
+to prepare the migration instructions. Doctor never imports or executes the target's source, and a
+bounded source scan that exceeds a limit is reported while the evidence it already found still counts.
+Its findings are static repository evidence, not proof that the configured startup command executes
+the files it finds.
+
 This writes `agent-bricks-migrate/` containing a skill, a prompt to paste into your coding agent,
 `references/migration.json`, and a reference project generated from the templates bundled with the
 installed CLI. The bundle sits outside any single agent's configuration directory; `.claude/skills/`
@@ -544,11 +571,11 @@ server.
 ```sh
 agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
   --path /api/invocations \
-  --json '{"id":"00000000-0000-4000-8000-000000000001","input":[{"role":"user","content":"Hello"}]}'
+  --json '{"id":"00000000-0000-4000-8000-000000000001","session_id":"support-case-123","input":[{"role":"user","content":"Hello"}]}'
 
 agentbricks endpoint invoke --url http://localhost:8000 \
   --path /api/invocations \
-  --json '{"id":"00000000-0000-4000-8000-000000000001","input":[{"role":"user","content":"Hello"}]}'
+  --json '{"id":"00000000-0000-4000-8000-000000000001","session_id":"support-case-123","input":[{"role":"user","content":"Hello"}]}'
 ```
 
 The JSON body remains explicit even for generated agents. For example, managed runtime agents require
@@ -556,21 +583,26 @@ a client-generated invocation ID, and streaming servers require their own stream
 `--sse` so the CLI consumes the response as Server-Sent Events.
 
 ```sh
+SESSION_ID=$(uuidgen)
 INVOCATION_ID=$(uuidgen)
 agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
   --path /api/invocations \
-  --json "{\"id\":\"$INVOCATION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Run the report\"}]}"
+  --routing-key "$SESSION_ID" \
+  --json "{\"id\":\"$INVOCATION_ID\",\"session_id\":\"$SESSION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Run the report\"}]}"
 
+INVOCATION_ID=$(uuidgen)
 agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
   --path /api/invocations \
+  --routing-key "$SESSION_ID" \
   --sse \
-  --json "{\"id\":\"$INVOCATION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"stream\":true}"
+  --json "{\"id\":\"$INVOCATION_ID\",\"session_id\":\"$SESSION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"stream\":true}"
 ```
 
-`--session-id` preserves one application session across calls by setting the Databricks Apps routing
-cookie. This also works with a direct App URL and with the generated runtime on localhost. OAuth and
-session headers are managed by the runtime; arbitrary custom request headers are intentionally not exposed
-by this command.
+`--routing-key` keeps a session on one app replica (sticky routing): set it to your stable session id
+and it is sent verbatim in the `X-Routing-Key` request header. It is routing only and is never used
+as the session id - put the session id at the top level of the `--json` body for session continuity. This
+also works with a direct App URL and with the generated runtime on localhost. OAuth and session headers are managed by
+the runtime; arbitrary custom request headers are intentionally not exposed by this command.
 
 ## Command help
 
@@ -620,9 +652,79 @@ Managed-tool add commands write the selected identity to `agent.toml`; inspect t
 review configured bindings. Missing legacy auth continues to mean App identity at runtime; it is
 never silently upgraded to user identity.
 
-`DurableAgentServer` derives its request-auth policy directly from the managed tool bindings in `agent.toml`.
-Projects do not maintain a separate request-auth contract marker: the presence of any managed tool
-with `auth = "user"` makes the invocation require a transient request-user credential.
+### Automatic App-identity access on deploy
+
+`agentbricks deploy` reconciles least-privilege access for resources explicitly declared by App/default
+identity tool bindings. It skips every `auth = "user"` binding because those calls use the request
+user's permissions instead of the App service principal.
+
+| Explicit `agent.toml` resource | Automatic App service-principal access |
+| --- | --- |
+| 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 |
+
+Native Genie One has no resource identifier in its binding, so it does not add a resource-specific
+grant. Use a Genie Agent binding when the App identity should be scoped to one explicit Genie Space.
+
+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
+because their permission APIs do not expose trustworthy Agent Bricks ownership metadata; removing
+those bindings does not revoke an independently valid grant.
+
+Only direct resources are automatic. Agent Bricks never discovers or grants tables and warehouses
+used by a Genie Space, objects called by a UC function, or resources wrapped by an MCP service.
+Grant those transitive dependencies manually when the called service uses the App identity. If any
+required direct grant cannot be read, applied, or verified, deploy stops before source upload and
+leaves the currently deployed version untouched.
+
+`DurableAgentServer` derives its request-auth policy directly from the managed tool bindings in
+`agent.toml`. Projects do not maintain a separate request-auth contract marker: a managed tool with
+`auth = "user"` requires a transient request-user credential. Code-first tools can declare any
+additional API scopes that Agent Bricks cannot infer from Python:
+
+```toml
+[auth.user]
+required = true
+additional_api_scopes = ["sql"]
+```
+
+`additional_api_scopes` is additive: deploy unions it with scopes inferred from managed bindings,
+deduplicates the result, and preserves unrelated scopes already configured on the App. Scope names
+are not restricted to a client-side allowlist; Databricks Apps validates whether a requested scope
+is supported. Entries must be non-empty strings without surrounding whitespace or control
+characters, and a non-empty list requires `required = true`. This request-auth contract is supported
+only with `[agent].server = "agentbricks"`.
+
+Generated framework adapters pass the request-bound resolver to agent construction. A code-first
+tool should obtain its user client from that resolver inside the active invocation rather than
+creating or persisting a user credential:
+
+```python
+from langchain_core.tools import tool
+
+
+def sql_tools(workspace_client_for):
+    @tool
+    def run_statement(statement: str) -> str:
+        client = workspace_client_for("user")
+        response = client.statement_execution.execute_statement(
+            warehouse_id="...",
+            statement=statement,
+        )
+        return str(response.result)
+
+    return [run_statement]
+```
+
+The resolver is request-bound and closes after the attempt. Agent Bricks does not inject it into
+arbitrary auto-discovered decorated tools; build those tools from the resolver passed to the
+generated request-aware agent function.
 
 Request-user invocations use the same synchronous, streaming, background, status, event-replay,
 and idempotency APIs as app-auth invocations. The Runtime Store records only token-free request
@@ -638,13 +740,18 @@ upgrade copied Python adapter code. Outdated adapters fail closed rather than si
 identity. App-only legacy projects and generic bring-your-own source directories keep the existing
 path.
 
-Deploy derives Apps user scopes from explicit `auth = "user"` bindings:
+Deploy derives Apps user scopes from explicit `auth = "user"` bindings and unions them with
+`[auth.user].additional_api_scopes`:
 
 | Binding | Requested Apps scopes |
 | --- | --- |
 | Managed MCP (governed ingress) | `ai-gateway` |
+| `system.ai.dbsql` | `ai-gateway`, `sql` |
 | `system.ai.genie_one_mcp` | `ai-gateway`, `genie` |
+| Sandbox with a Volume downscope | `ai-gateway`, `files` |
 | First-class Genie One or Genie Agent | `genie` |
+| Sandbox with token injection | `ai-gateway`, `workspace.workspace` |
+| Sandbox with token injection disabled | `ai-gateway` |
 
 For example, bind Genie tools in a current project with `server = "agentbricks"`:
 
@@ -653,7 +760,8 @@ agentbricks tools add mcp system.ai.genie_one_mcp --auth user
 agentbricks tools add genie-agent SPACE_ID --auth user
 ```
 
-Mixed bindings request the union. App-auth and legacy bindings add no user scopes. These are
+Mixed bindings and explicit additions request the union. App-auth and legacy bindings add no user
+scopes. These are
 explicit service-consent scopes, not a claim that gateway access alone authorizes the downstream
 resource. OAuth consent does not grant Unity Catalog privileges: the user still needs access to
 the configured Genie Space and its underlying data.
@@ -670,10 +778,15 @@ The `system.ai.dbsql` managed MCP additionally requests the Apps `sql` user scop
 API consent, not `sql:restricted-query`; read-only enforcement remains the service policy plus the
 requesting user's Unity Catalog grants. DBSQL does not use Databricks Connect.
 
-A sandbox binding with a Volume downscope additionally requests the Apps `files` user scope.
+When a user-auth sandbox has `databricks_access_token_included = true`, it requests the Apps
+`workspace.workspace` user scope so the injected credential can call workspace APIs. A sandbox
+binding with a Volume downscope additionally requests the Apps `files` user scope.
 OAuth consent does not grant Volume access: the requesting user still needs the corresponding
-Unity Catalog privileges, and the sandbox downscope remains authoritative. Table-only sandbox
-bindings request `ai-gateway` but do not request `files`.
+Unity Catalog privileges, and the sandbox downscope remains authoritative. A sandbox binding with
+token injection disabled does not request `workspace.workspace`; its other resource-derived scopes
+still apply. Databricks Apps rejects the legacy bare `workspace` scope, so Agent Bricks requests
+`workspace.workspace`. These scopes are requested only for `auth = "user"`; `auth = "app"` uses
+the App service principal's permissions instead.
 
 Review the target App's scopes and coordinate with its other owners before allowing the update. Once
 those scopes are present, later deploys do not need the flag. The CLI preserves unrelated scopes,
@@ -772,7 +885,24 @@ do not generate or patch Python tool code, and do not alter the manifest's `[[to
 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
 agent needs writes. Every sandbox call carries this fixed downscope in MCP `_meta`, outside the tool
-arguments controlled by the model.
+arguments controlled by the model. New sandbox bindings also expose the selected Databricks
+credential to sandbox code by default:
+
+```toml
+[[tools]]
+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 }
+```
+
+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
+identity: `auth = "user"` uses the request user's OBO credential, while `auth = "app"` uses the
+Databricks App service principal. Use `--no-databricks-access-token-included` when adding a sandbox that
+does not need workspace API access. Existing manifests that omit `databricks_access_token_included`
+remain disabled until explicitly updated.
 
 ### Genie tools
 
@@ -880,10 +1010,12 @@ store and grants the app's service principal access to it. The memory store id f
 via the `AGENT_MEMORY_STORE` env var that `deploy` injects; `agentbricks dev` runs locally with memory off
 and does not inject it. The id is not persisted in `agent.toml`.)
 
-The chat UI generates a stable application session UUID in browser local storage, places it inside
-the invocation's opaque `input`, and creates a fresh invocation UUID per turn. The
-`__Host-databricks-app-router` cookie remains independent: API clients may reuse it for sticky
-replica routing, but it is neither authentication nor the template's application session state.
+The chat UI generates a stable application session UUID in browser local storage, sends it as the
+invocation's top-level `session_id`, and creates a fresh invocation UUID per turn. The chat app also
+sends this session UUID in the `X-Routing-Key` request header, which is used verbatim to pin
+the session to one app replica (it must be non-blank and no more than 128 UTF-8 bytes). The header is neither
+authentication nor the template's application session state; it is independent sticky-routing
+plumbing.
 
 The generated `README.md` documents every request the client makes: config discovery, sync and SSE
 invocations, background submission and polling, session transcript loading, HITL resume, and memory

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

@@ -127,9 +127,9 @@ agentbricks deploy my-agent     # deploy to Databricks
 local runtime so local behavior matches a deployment.
 
 `agentbricks deploy my-agent` deploys a Databricks App named `agent-bricks-my-agent`, provisions the
-stores declared in `agent.toml`, and grants the app's service principal access to them. Use
-`agentbricks deployments list` to find deployed apps, and `agentbricks deployments get agent-bricks-my-agent` to
-print an app's URL and status.
+stores declared in `agent.toml`, and grants the app's service principal access to the stores and
+direct App-auth tool resources declared there. Use `agentbricks deployments list` to find deployed
+apps, and `agentbricks deployments get agent-bricks-my-agent` to print an app's URL and status.
 
 `agentbricks init` declares default memory and session stores in `agent.toml`, so the deployed agent has
 long-term memory and durable conversation history. It creates `<name>-<6-letter-token>-memory` and
@@ -228,12 +228,16 @@ Each managed run is an **invocation**. Send a client-generated UUID `id` and you
 ```json
 {
   "id": "550e8400-e29b-41d4-a716-446655440000",
+  "session_id": "support-case-123",
   "input": {"messages": [{"role": "user", "content": "Hello"}]},
   "background": true,
   "stream": true
 }
 ```
 
+The optional top-level `session_id` groups invocations into one application session. It is distinct
+from the invocation `id` and from the `X-Routing-Key` sticky-routing header.
+
 | Endpoint | Behavior |
 | --- | --- |
 | `POST /api/invocations` | Defaults to synchronous execution: `200` with the result under `output`. `stream: true` returns SSE events. `background: true` returns `202` with a status URL; adding `stream: true` also includes an events URL. |
@@ -434,6 +438,7 @@ agentbricks [-p <profile>] [-o text|json]
                [--disable-chat-app]
                [--memory-store NAME] [--session-store NAME]
                [--existing] [--profile P] [directory]
+  doctor       [directory]
   dev          [--source PATH] [--prepare-environment] [--app-port PORT]
   memory
     bind         STORE [--source PATH]
@@ -450,7 +455,8 @@ agentbricks [-p <profile>] [-o text|json]
     unbind     [--source PATH]
     list | get [--experiment-name NAME | --experiment-id ID] [--source PATH]
   tools
-    add sandbox      --scope SCOPE [--scope SCOPE ...] [--source PATH]
+    add sandbox      --scope SCOPE [--scope SCOPE ...]
+                     [--no-databricks-access-token-included] [--source PATH]
     add mcp          SERVICE [--name NAME] [--source PATH]
     add uc-function  FUNCTION [--name NAME] [--source PATH]
     add genie-one    [--name NAME] [--auth user|app] [--source PATH]
@@ -473,6 +479,26 @@ agentbricks init --framework langgraph --existing .
 agentbricks init --framework openai --existing .
 ```
 
+Before or after the conversion, inspect its progress without changing the repository or contacting
+Databricks:
+
+```sh
+agentbricks doctor .
+agentbricks -o json doctor .
+```
+
+Doctor exits 0 only when the project has a valid Agent Bricks manifest and matching project
+metadata, uses the Agent Bricks server, declares the framework-appropriate `databricks-agentbricks`
+extra and a non-empty `app.yaml` command, constructs `DurableAgentServer` with an `invoke` hook, and
+calls a recognized adapter for the selected framework in production Python source. Test, example, and
+old/stale directories do not count as source evidence. A failed report is the normal result for a
+project that still needs migration; run
+`agentbricks init --framework <framework_name> --existing <directory>` with the appropriate framework
+to prepare the migration instructions. Doctor never imports or executes the target's source, and a
+bounded source scan that exceeds a limit is reported while the evidence it already found still counts.
+Its findings are static repository evidence, not proof that the configured startup command executes
+the files it finds.
+
 This writes `agent-bricks-migrate/` containing a skill, a prompt to paste into your coding agent,
 `references/migration.json`, and a reference project generated from the templates bundled with the
 installed CLI. The bundle sits outside any single agent's configuration directory; `.claude/skills/`
@@ -509,11 +535,11 @@ server.
 ```sh
 agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
   --path /api/invocations \
-  --json '{"id":"00000000-0000-4000-8000-000000000001","input":[{"role":"user","content":"Hello"}]}'
+  --json '{"id":"00000000-0000-4000-8000-000000000001","session_id":"support-case-123","input":[{"role":"user","content":"Hello"}]}'
 
 agentbricks endpoint invoke --url http://localhost:8000 \
   --path /api/invocations \
-  --json '{"id":"00000000-0000-4000-8000-000000000001","input":[{"role":"user","content":"Hello"}]}'
+  --json '{"id":"00000000-0000-4000-8000-000000000001","session_id":"support-case-123","input":[{"role":"user","content":"Hello"}]}'
 ```
 
 The JSON body remains explicit even for generated agents. For example, managed runtime agents require
@@ -521,21 +547,26 @@ a client-generated invocation ID, and streaming servers require their own stream
 `--sse` so the CLI consumes the response as Server-Sent Events.
 
 ```sh
+SESSION_ID=$(uuidgen)
 INVOCATION_ID=$(uuidgen)
 agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
   --path /api/invocations \
-  --json "{\"id\":\"$INVOCATION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Run the report\"}]}"
+  --routing-key "$SESSION_ID" \
+  --json "{\"id\":\"$INVOCATION_ID\",\"session_id\":\"$SESSION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Run the report\"}]}"
 
+INVOCATION_ID=$(uuidgen)
 agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
   --path /api/invocations \
+  --routing-key "$SESSION_ID" \
   --sse \
-  --json "{\"id\":\"$INVOCATION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"stream\":true}"
+  --json "{\"id\":\"$INVOCATION_ID\",\"session_id\":\"$SESSION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"stream\":true}"
 ```
 
-`--session-id` preserves one application session across calls by setting the Databricks Apps routing
-cookie. This also works with a direct App URL and with the generated runtime on localhost. OAuth and
-session headers are managed by the runtime; arbitrary custom request headers are intentionally not exposed
-by this command.
+`--routing-key` keeps a session on one app replica (sticky routing): set it to your stable session id
+and it is sent verbatim in the `X-Routing-Key` request header. It is routing only and is never used
+as the session id - put the session id at the top level of the `--json` body for session continuity. This
+also works with a direct App URL and with the generated runtime on localhost. OAuth and session headers are managed by
+the runtime; arbitrary custom request headers are intentionally not exposed by this command.
 
 ## Command help
 
@@ -585,9 +616,79 @@ Managed-tool add commands write the selected identity to `agent.toml`; inspect t
 review configured bindings. Missing legacy auth continues to mean App identity at runtime; it is
 never silently upgraded to user identity.
 
-`DurableAgentServer` derives its request-auth policy directly from the managed tool bindings in `agent.toml`.
-Projects do not maintain a separate request-auth contract marker: the presence of any managed tool
-with `auth = "user"` makes the invocation require a transient request-user credential.
+### Automatic App-identity access on deploy
+
+`agentbricks deploy` reconciles least-privilege access for resources explicitly declared by App/default
+identity tool bindings. It skips every `auth = "user"` binding because those calls use the request
+user's permissions instead of the App service principal.
+
+| Explicit `agent.toml` resource | Automatic App service-principal access |
+| --- | --- |
+| 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 |
+
+Native Genie One has no resource identifier in its binding, so it does not add a resource-specific
+grant. Use a Genie Agent binding when the App identity should be scoped to one explicit Genie Space.
+
+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
+because their permission APIs do not expose trustworthy Agent Bricks ownership metadata; removing
+those bindings does not revoke an independently valid grant.
+
+Only direct resources are automatic. Agent Bricks never discovers or grants tables and warehouses
+used by a Genie Space, objects called by a UC function, or resources wrapped by an MCP service.
+Grant those transitive dependencies manually when the called service uses the App identity. If any
+required direct grant cannot be read, applied, or verified, deploy stops before source upload and
+leaves the currently deployed version untouched.
+
+`DurableAgentServer` derives its request-auth policy directly from the managed tool bindings in
+`agent.toml`. Projects do not maintain a separate request-auth contract marker: a managed tool with
+`auth = "user"` requires a transient request-user credential. Code-first tools can declare any
+additional API scopes that Agent Bricks cannot infer from Python:
+
+```toml
+[auth.user]
+required = true
+additional_api_scopes = ["sql"]
+```
+
+`additional_api_scopes` is additive: deploy unions it with scopes inferred from managed bindings,
+deduplicates the result, and preserves unrelated scopes already configured on the App. Scope names
+are not restricted to a client-side allowlist; Databricks Apps validates whether a requested scope
+is supported. Entries must be non-empty strings without surrounding whitespace or control
+characters, and a non-empty list requires `required = true`. This request-auth contract is supported
+only with `[agent].server = "agentbricks"`.
+
+Generated framework adapters pass the request-bound resolver to agent construction. A code-first
+tool should obtain its user client from that resolver inside the active invocation rather than
+creating or persisting a user credential:
+
+```python
+from langchain_core.tools import tool
+
+
+def sql_tools(workspace_client_for):
+    @tool
+    def run_statement(statement: str) -> str:
+        client = workspace_client_for("user")
+        response = client.statement_execution.execute_statement(
+            warehouse_id="...",
+            statement=statement,
+        )
+        return str(response.result)
+
+    return [run_statement]
+```
+
+The resolver is request-bound and closes after the attempt. Agent Bricks does not inject it into
+arbitrary auto-discovered decorated tools; build those tools from the resolver passed to the
+generated request-aware agent function.
 
 Request-user invocations use the same synchronous, streaming, background, status, event-replay,
 and idempotency APIs as app-auth invocations. The Runtime Store records only token-free request
@@ -603,13 +704,18 @@ upgrade copied Python adapter code. Outdated adapters fail closed rather than si
 identity. App-only legacy projects and generic bring-your-own source directories keep the existing
 path.
 
-Deploy derives Apps user scopes from explicit `auth = "user"` bindings:
+Deploy derives Apps user scopes from explicit `auth = "user"` bindings and unions them with
+`[auth.user].additional_api_scopes`:
 
 | Binding | Requested Apps scopes |
 | --- | --- |
 | Managed MCP (governed ingress) | `ai-gateway` |
+| `system.ai.dbsql` | `ai-gateway`, `sql` |
 | `system.ai.genie_one_mcp` | `ai-gateway`, `genie` |
+| Sandbox with a Volume downscope | `ai-gateway`, `files` |
 | First-class Genie One or Genie Agent | `genie` |
+| Sandbox with token injection | `ai-gateway`, `workspace.workspace` |
+| Sandbox with token injection disabled | `ai-gateway` |
 
 For example, bind Genie tools in a current project with `server = "agentbricks"`:
 
@@ -618,7 +724,8 @@ agentbricks tools add mcp system.ai.genie_one_mcp --auth user
 agentbricks tools add genie-agent SPACE_ID --auth user
 ```
 
-Mixed bindings request the union. App-auth and legacy bindings add no user scopes. These are
+Mixed bindings and explicit additions request the union. App-auth and legacy bindings add no user
+scopes. These are
 explicit service-consent scopes, not a claim that gateway access alone authorizes the downstream
 resource. OAuth consent does not grant Unity Catalog privileges: the user still needs access to
 the configured Genie Space and its underlying data.
@@ -635,10 +742,15 @@ The `system.ai.dbsql` managed MCP additionally requests the Apps `sql` user scop
 API consent, not `sql:restricted-query`; read-only enforcement remains the service policy plus the
 requesting user's Unity Catalog grants. DBSQL does not use Databricks Connect.
 
-A sandbox binding with a Volume downscope additionally requests the Apps `files` user scope.
+When a user-auth sandbox has `databricks_access_token_included = true`, it requests the Apps
+`workspace.workspace` user scope so the injected credential can call workspace APIs. A sandbox
+binding with a Volume downscope additionally requests the Apps `files` user scope.
 OAuth consent does not grant Volume access: the requesting user still needs the corresponding
-Unity Catalog privileges, and the sandbox downscope remains authoritative. Table-only sandbox
-bindings request `ai-gateway` but do not request `files`.
+Unity Catalog privileges, and the sandbox downscope remains authoritative. A sandbox binding with
+token injection disabled does not request `workspace.workspace`; its other resource-derived scopes
+still apply. Databricks Apps rejects the legacy bare `workspace` scope, so Agent Bricks requests
+`workspace.workspace`. These scopes are requested only for `auth = "user"`; `auth = "app"` uses
+the App service principal's permissions instead.
 
 Review the target App's scopes and coordinate with its other owners before allowing the update. Once
 those scopes are present, later deploys do not need the flag. The CLI preserves unrelated scopes,
@@ -737,7 +849,24 @@ do not generate or patch Python tool code, and do not alter the manifest's `[[to
 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
 agent needs writes. Every sandbox call carries this fixed downscope in MCP `_meta`, outside the tool
-arguments controlled by the model.
+arguments controlled by the model. New sandbox bindings also expose the selected Databricks
+credential to sandbox code by default:
+
+```toml
+[[tools]]
+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 }
+```
+
+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
+identity: `auth = "user"` uses the request user's OBO credential, while `auth = "app"` uses the
+Databricks App service principal. Use `--no-databricks-access-token-included` when adding a sandbox that
+does not need workspace API access. Existing manifests that omit `databricks_access_token_included`
+remain disabled until explicitly updated.
 
 ### Genie tools
 
@@ -845,10 +974,12 @@ store and grants the app's service principal access to it. The memory store id f
 via the `AGENT_MEMORY_STORE` env var that `deploy` injects; `agentbricks dev` runs locally with memory off
 and does not inject it. The id is not persisted in `agent.toml`.)
 
-The chat UI generates a stable application session UUID in browser local storage, places it inside
-the invocation's opaque `input`, and creates a fresh invocation UUID per turn. The
-`__Host-databricks-app-router` cookie remains independent: API clients may reuse it for sticky
-replica routing, but it is neither authentication nor the template's application session state.
+The chat UI generates a stable application session UUID in browser local storage, sends it as the
+invocation's top-level `session_id`, and creates a fresh invocation UUID per turn. The chat app also
+sends this session UUID in the `X-Routing-Key` request header, which is used verbatim to pin
+the session to one app replica (it must be non-blank and no more than 128 UTF-8 bytes). The header is neither
+authentication nor the template's application session state; it is independent sticky-routing
+plumbing.
 
 The generated `README.md` documents every request the client makes: config discovery, sync and SSE
 invocations, background submission and polling, session transcript loading, HITL resume, and memory

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

@@ -1,6 +1,6 @@
 [project]
 name = "databricks-agentbricks"
-version = "0.3.0"
+version = "0.4.0"
 description = "Agent Bricks CLI and AgentKit SDK for custom agents on Databricks"
 authors = [
     { name="Databricks", email="agent-feedback@databricks.com" },
@@ -22,6 +22,7 @@ dependencies = [
     # so this is a base dependency. Auth rides on databricks-sdk (above), so the heavier
     # mlflow[databricks] extra (boto3/azure/gcs/databricks-agents, for artifact blob I/O) isn't needed.
     "mlflow-skinny>=3.10.1",
+    "packaging>=23.2",
     "psycopg[binary]>=3.1",
     "PyYAML>=6.0",
     "rich>=13.7",
@@ -35,7 +36,7 @@ langgraph = [
     "databricks-langchain>=0.17.0",
     "langgraph>=1.1.0",
     "langchain>=1.0.0",
-    "langchain-mcp-adapters>=0.2.1",
+    "langchain-mcp-adapters>=0.3.0",
     "mlflow>=3.10.1",
     "opentelemetry-exporter-otlp-proto-grpc>=1.25.0",
     "databricks-agents>=1.9.3",