databricks-agentbricks 0.6.0__tar.gz → 0.7.1__tar.gz

{databricks_agentbricks-0.6.0 → databricks_agentbricks-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: databricks-agentbricks
-Version: 0.6.0
+Version: 0.7.1
 Summary: Agent Bricks CLI and AgentKit SDK for custom agents on Databricks
 Author-email: Databricks <agent-feedback@databricks.com>
 License-File: NOTICE
@@ -13,6 +13,7 @@ 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: requests<3,>=2.28.1
 Requires-Dist: rich>=13.7
 Requires-Dist: sqlalchemy[asyncio]>=2.0
 Requires-Dist: tomli>=2.0
@@ -32,14 +33,18 @@ Requires-Dist: databricks-openai>=0.13.0; extra == 'openai'
 Requires-Dist: mlflow>=3.10.1; extra == 'openai'
 Requires-Dist: openai-agents>=0.15.0; extra == 'openai'
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0; extra == 'openai'
+Provides-Extra: upgrade
+Requires-Dist: gepa>=0.0.26; extra == 'upgrade'
+Requires-Dist: litellm>=1.64.0; extra == 'upgrade'
+Requires-Dist: mlflow>=3.11.0; extra == 'upgrade'
 Description-Content-Type: text/markdown
 
 # Agent Bricks CLI (`agentbricks`)
 
 Agent Bricks CLI is an experimental command-line interface for building and deploying custom
 agents on Databricks. It manages memory, sessions, tracing, and deployments from one authenticated
-command. Under `agentbricks experimental`, it also binds each of the agent's LLM calls to a model
-service you own, so the model behind it can change without a code change or redeploy.
+command. Under `agentbricks experimental`, it also picks the model and prompt behind each of the
+agent's LLM calls by searching candidates on your own eval set.
 
 > The underlying APIs are in preview and may need workspace enablement.
 
@@ -72,7 +77,7 @@ invocation protocol to design yourself. Bring your own agent, or start from a te
   up (detailed under [Agent tools](#agent-tools)).
 - **`agentbricks deploy`** - provisions the bound stores, grants the app's service principal access to
   them, provisions the durable-runtime database when durability is on, configures tracing, and rolls
-  out the app. `agentbricks deployments` covers the lifecycle (list, get, logs, start, stop, delete).
+  out the app. `agentbricks deployments` covers the lifecycle (list, get, wait, logs, start, stop, delete).
 - **`agentbricks dev`** - runs your agent from the same manifest the deployment uses, so local behavior
   matches what ships.
 
@@ -90,6 +95,19 @@ The two ways to run an agent:
   server with no `DurableAgentServer`: you define your own endpoints, request/response shapes, and protocol.
   `agentbricks dev` and `agentbricks deploy` run and ship it the same way.
 
+Both managed framework templates support human approval with request-user (OBO) tools. A new
+invocation from the same authenticated user resumes the saved state with that request's tool
+credentials; the browser can use its existing valid login session.
+
+| Framework | Interactive OBO approval decisions |
+| --- | --- |
+| LangGraph | Approve, edit, or reject according to the middleware policy |
+| OpenAI Agents SDK | Approve or reject, with the pending tool call's `call_id` |
+
+Automatic OBO failure recovery remains unsupported. Existing generated apps need the corresponding
+template source updates; upgrading the installed package does not rewrite their agent or adapter.
+Custom servers own their authentication and approval protocol.
+
 ## Prerequisites
 
 - **Python ≥3.10** — the `agentbricks` CLI installs and runs on any Python 3.10+. The
@@ -182,16 +200,45 @@ agentbricks login --profile <profile>
 agentbricks init my-agent       # Defaults to LangGraph; add --framework=openai for OpenAI Agents SDK
 cd my-agent
 agentbricks dev                 # optional: develop and test locally
-agentbricks deploy my-agent     # deploy to Databricks
+agentbricks deploy              # deploy to Databricks as agent-bricks-my-agent
 ```
 
 `agentbricks dev` runs the agent locally on `http://localhost:8000`, wrapping the Databricks Apps
 local runtime so local behavior matches a deployment.
 
-`agentbricks deploy my-agent` deploys a Databricks App named `agent-bricks-my-agent`, provisions the
+`agentbricks init` records the deployment name in `agent.toml`, so `agentbricks deploy` from the
+project directory 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 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.
+Databricks App names cap at 30 characters, so a deployment name can be up to 17 characters after
+the `agent-bricks-` prefix. `init` shortens a longer directory name to fit (for example
+`caj-langgraph-agent` becomes `caj-langgr-<token>`); pass `agentbricks init --name <name>` to choose
+it yourself, or `agentbricks deploy <name>` to change it later.
+
+The app's compute starts first and boots while the other resources are provisioned. If a first
+deploy stops partway, the app it created is kept: re-run `agentbricks deploy` to resume, or remove
+it with `agentbricks deployments delete agent-bricks-my-agent`.
+
+### Deploying from a coding agent
+
+A first deploy takes ~3 min (mostly starting app compute); redeploys are faster. Either run
+`agentbricks deploy` in the foreground with a long command timeout (for example, Claude Code's Bash
+`timeout: 600000`), or start it in the background and wait on it:
+
+```sh
+agentbricks deploy my-agent --no-wait            # quick checks, then deploys in the background
+agentbricks deployments wait agent-bricks-my-agent
+```
+
+`deployments wait` returns within 100 seconds (`--timeout`). Exit 0 means the agent is deployed and
+running, and it prints the URL; exit 1 means the deploy failed, and it prints the error and the end
+of the deploy log; exit 75 means it is still deploying, so run the same command again. Don't poll
+with `sleep`. Progress lines with the elapsed time go to stderr, also under `-o json`, whose stdout
+is a single JSON document. A second `deploy` of the same app is refused while one is still running
+from the project; the deploy's state and background log are in `.agentbricks/deploy-<app>.json` and
+`.agentbricks/deploy-<app>.log`. If the App is busy with another operation, `deploy` retries for
+about two minutes before failing.
 
 `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
@@ -258,15 +305,15 @@ bindings. A declaration does not confirm that the resource exists or that the de
 | 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. |
+| Memory store IDs and details | `agentbricks -p <profile> memory stores get <name>`, or `agentbricks -p <profile> memory stores list --name <part-of-name>` | Pass the display name from `agent.toml`, the ID, or the resource name. If several stores share a display name, `get` lists them; pass one resource name. `list` is workspace-wide and paged; `--name` and `--all` read every page. |
+| Session store names and details | `agentbricks -p <profile> sessions stores get <name>`, or `agentbricks -p <profile> sessions stores list --name <part-of-name>` | Pass the store name from `agent.toml`. `list` is workspace-wide and paged; `--name` and `--all` read every page. |
 
 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. |
+| Deployment | `agentbricks -p <profile> deployments delete agent-bricks-<name> [--delete-source]` | Managed Runtime Store cleanup checks the app identity and runs before app deletion; a cleanup failure retains the app for retry. Returns once the app is gone. The workspace folder its source was uploaded to is kept unless you pass `--delete-source`, which deletes it once the app is confirmed gone; otherwise delete prints the command to remove it. Exits 1 if the app isn't confirmed gone or a requested folder delete fails. Memory/session stores, tracing experiments and tools 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. |
 
@@ -354,6 +401,10 @@ agentbricks dev
 agentbricks --profile <profile> deploy my-agent
 ```
 
+Use the URL `agentbricks dev` prints (port 8000, or `--app-port`). The `localhost:8001` line from the
+wrapped `databricks apps run-local` is its proxy to the same app. Requests can fail with HTTP 500 for
+a few seconds while the app starts.
+
 Use `--framework openai` for OpenAI Agents. Templates keep agent code separate from the runtime
 adapter and declare default Session and Memory Store bindings in `agent.toml`.
 
@@ -370,7 +421,9 @@ Each managed run is an **invocation**. Send a client-generated UUID `id` and you
 ```
 
 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.
+from the invocation `id` and from the `X-Routing-Key` sticky-routing header. The framework templates
+require it, and read `input.actor` to choose whose long-term memory to use (see
+[How sessions and memory are keyed](#how-sessions-and-memory-are-keyed)).
 
 | Endpoint | Behavior |
 | --- | --- |
@@ -407,6 +460,86 @@ scaffold a new project with the desired `agentbricks init --server` option and d
 See the [runtime guide](src/databricks_agentkit/runtime/README.md) for agent hooks, full API examples,
 and recovery behavior.
 
+### Call an agent from an external browser (CORS)
+
+An external frontend, such as a React app at `https://chat.example.com`, has a different origin
+from the agent's Databricks Apps URL. Enable CORS for its exact origin when deploying:
+
+```sh
+agentbricks deploy my-agent \
+  --allowed-origin https://chat.example.com \
+  --allowed-origin http://localhost:3000
+```
+
+This replaces the allowlist and records it in `agent.toml`:
+
+```toml
+[cors]
+allowed_origins = ["https://chat.example.com", "http://localhost:3000"]
+```
+
+Later `agentbricks deploy` calls reuse the recorded origins. Direct edits to this table also
+apply to `agentbricks dev` and the next deployment. To revoke browser access, use
+`agentbricks deploy --clear-allowed-origins` or set `allowed_origins = []` and redeploy.
+CORS is off by default. Origins include scheme, hostname, and optional port; paths, wildcards,
+and `null` origins are rejected. For internationalized hostnames, supply the browser's ASCII/punycode
+origin (for example, `https://xn--fa-hia.example` for `https://faß.example`); Unicode input is rejected
+to avoid changing the allowed hostname. You can copy `window.location.origin` from the frontend's
+browser console. IPv6 addresses are compressed to match browser origins. List every intended origin
+when replacing the allowlist and remove development origins before production deployment.
+
+The customer journey is:
+
+1. Deploy the managed agent server with the external frontend's allowed origin.
+2. Authenticate the frontend user and obtain a Databricks user OAuth token. For an external IdP
+   such as Microsoft Entra, configure [account-wide token federation](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-federation)
+   and exchange the user's IdP JWT for a Databricks user token. An IdP login alone is insufficient.
+3. Send the token to the agent's `/api/` endpoints using `fetch`. The caller needs Apps `CAN USE`
+   permission and the required OAuth scopes. User-authorized tools also need Apps user-token
+   forwarding enabled, `auth = "user"` bindings, and the caller's resource permissions.
+4. Receive JSON or stream SSE events directly in the browser:
+
+```javascript
+const response = await fetch(`${agentUrl}/api/invocations`, {
+  method: "POST",
+  credentials: "omit",
+  headers: {
+    Authorization: `Bearer ${databricksUserToken}`,
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    id: crypto.randomUUID(),
+    input: { messages: [{ role: "user", content: "Hello" }] },
+    stream: true,
+  }),
+});
+if (!response.ok || !response.body) throw new Error(`Invocation failed: ${response.status}`);
+const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+while (true) {
+  const { value, done } = await reader.read();
+  if (done) break;
+  console.log(value); // Feed these SSE chunks to the frontend's SSE parser.
+}
+```
+
+The runtime allows `GET`/`POST` and the `Authorization`, `Content-Type`, `X-Routing-Key`, and
+`Last-Event-ID` request headers. It answers preflight without invoking the agent and adds CORS
+headers to JSON, SSE, polling, and agent-generated error responses. Use `fetch` for authenticated
+SSE; native `EventSource` cannot set the bearer Authorization header. Cross-origin cookie
+authentication is not enabled. The bundled chat UI uses same-origin requests and needs no allowlist.
+
+CORS controls browser access to responses; it does not replace authentication or prevent non-browser
+clients from calling the API. Apps ingress must allow unauthenticated `OPTIONS` requests through.
+Errors generated by ingress, including rejected tokens, do not pass through runtime middleware and
+can appear as generic browser CORS failures. Verify a deployed App's preflight and authenticated
+stream before relying on this path; a same-origin backend proxy is an alternative when ingress
+cannot satisfy the browser contract.
+
+Both the CLI and the agent project's `databricks-agentbricks` dependency must contain this feature;
+upgrading the CLI alone does not upgrade an already resolved runtime dependency. Before release,
+follow [the unreleased SDK instructions](CONTRIBUTING.md#testing-sdk--runtime-changes-in-a-scaffold).
+The flags require `server = "agentbricks"`; custom servers configure their own CORS middleware.
+
 ## Memory and sessions
 
 To hold context, an agent needs two kinds of state: the state of the interaction it is handling right
@@ -517,7 +650,8 @@ To browse rather than search, `memory_store.list(actor_id=..., path_prefix=...)`
 directly, and `memory_store.list(actor_id=..., path=...)` returns the entries at one exact path.
 
 In an agent configured with `server = "agentbricks"`, add the memory tools so the model can read and write memory during a run.
-`memory_tools(actor)` returns four tools bound to one actor's partition:
+`memory_tools(actor)` returns four tools bound to one actor's partition (the templates pass
+`input.actor`; see [How sessions and memory are keyed](#how-sessions-and-memory-are-keyed)):
 
 - `remember(fact, topic)` appends the fact to one memory per topic, `/{topic}.md`, with the topic
   reduced to a safe path segment. Remembering a fact that is already there is a no-op.
@@ -549,6 +683,30 @@ agent = create_agent(model=..., tools=[*your_tools, *memory_tools(actor)])
 > `session_store.grant_permission(principal_id)` or `memory_store.grant_permission(principal_id)`;
 > `agentbricks deploy` does this for the deployed app automatically.
 
+### How sessions and memory are keyed
+
+In an agent generated by `agentbricks init`, each invocation picks its session and its memory
+partition:
+
+- **Session store:** one conversation's state, keyed by the invocation's top-level `session_id`.
+- **Memory store:** facts recalled across conversations, keyed by `input.actor`.
+
+If a request leaves out `actor`, it defaults to the `session_id`, so long-term memory won't carry
+across conversations. For memory that persists, pass a stable `actor`, such as the end user's ID, from
+trusted application context. The chat app sends the signed-in user; HTTP clients, including
+`agentbricks endpoint invoke`, have to send it themselves. With a request-user (`auth = "user"`) tool
+bound, the runtime also namespaces a supplied `actor` to the signed-in user.
+
+Memory is off under `agentbricks dev`, so try this against a deployed agent: two conversations, one
+actor.
+
+```sh
+ask() { agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent --path /api/invocations \
+  --json "{\"id\":\"$(uuidgen)\",\"session_id\":\"$(uuidgen)\",\"input\":{\"actor\":\"user-123\",\"messages\":[{\"role\":\"user\",\"content\":\"$1\"}]}}"; }
+ask "Remember that I prefer answers as bullet points."  # conversation 1 saves a fact
+ask "How do I like my answers formatted?"                # conversation 2 recalls it
+```
+
 ### Declaring and provisioning stores
 
 For a deployed agent, `agent.toml` declares which stores it uses and `agentbricks deploy` provisions them —
@@ -576,31 +734,78 @@ removes the corresponding `AGENT_MEMORY_STORE` or `AGENT_SESSION_STORE` entry fr
 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.
 
-## Model services and prompts (experimental)
+## Model and prompt upgrades (experimental)
 
-`agentbricks experimental models` and `agentbricks experimental prompts` bind each LLM call in
-your agent to a Unity Gateway model service you own (Unity Gateway was formerly AI Gateway), and
-declare the Prompt Registry prompts it loads. They live under `experimental` because their flags
-and output may still change between releases without a deprecation period. The agent.toml tables
-they write live under `[experimental]` too.
+`agentbricks experimental models` and `agentbricks experimental prompts` find the best model and
+prompt for each LLM call in your agent and swap them in. They live under `experimental` because
+their flags and output may still change between releases without a deprecation period. The
+agent.toml tables they write live under `[experimental]` too.
 
-A one-model agent binds one service. A compound agent binds one per call site, each under a role:
+Point each of the agent's LLM calls at a Unity Gateway model service you own (Unity Gateway was
+formerly AI Gateway), and the models behind them can change without a code change or redeploy. A
+one-model agent binds one service. A compound agent binds one per call site, each under a role,
+and declares the Prompt Registry prompts it loads so the search can rewrite them too:
 
 ```sh
 agentbricks experimental models bind main.my_agent.router_llm --role router --default system.ai.claude-haiku-4-5
 agentbricks experimental models bind main.my_agent.writer_llm --role writer --default system.ai.claude-sonnet-4-5
 agentbricks experimental prompts bind main.my_agent.writer
 agentbricks deploy my-agent      # creates the services and grants the app access to them and the prompt
-agentbricks experimental models status                              # the model behind each service
-agentbricks experimental models set claude-haiku-4-5 --role writer  # switch one, no redeploy
+agentbricks experimental models upgrade -c router=claude-haiku-4-5,gpt-5-4-nano -c writer=claude-haiku-4-5 \
+  --predict agent.eval:predict --train-data agent.eval:TRAIN --val-data agent.eval:VAL \
+  --scorer agent.eval:SCORERS
+agentbricks experimental models status        # the job's state, then its recommendation
+agentbricks experimental models apply         # switch to it
 ```
 
-Each LLM call must use its role's service, `resolve_model_service("<role>")`, which reads the
-`AGENT_MODEL_SERVICE_<ROLE>` env var that deploy sets. Deploy creates a service that doesn't exist
-yet, routed to its `--default` model, and never repoints one that does, so a redeploy can't undo a
-switch. For bound prompts, deploy grants the app the schema privileges the Prompt Registry requires
-to load them (USE SCHEMA, EXECUTE, CREATE FUNCTION, and MANAGE). `agentbricks experimental prompts
-list` shows each bound prompt and the version its `@production` alias points at.
+By default `models upgrade` uploads the project to your workspace and runs the search as a
+serverless Databricks job, because a search can take hours. `--run-on local` runs it in your
+terminal instead, which needs the `upgrade` extra and the agent's dependencies installed. Each call
+takes longer from a laptop than on a serverless job, and a record slower than `--latency-gate` (60
+seconds by default) scores 0, so raise it if a local run warns that records went over the gate. The job imports the `predict_fn`,
+eval data, and scorers you name from the project (the same inputs `optimize_prompts_and_models`
+takes, below) and runs each eval record once per candidate, against a temporary `<service>_exp_<id>`
+clone. Each LLM call must use its role's service, `resolve_model_service("<role>")`, which reads the
+`AGENT_MODEL_SERVICE_<ROLE>` env var that deploy (and the job, before importing your code) sets.
+GEPA also rewrites every prompt bound with `prompts bind` for each candidate model. Pass
+`--prompt` to pick specific prompts instead, or `--models-only` to leave prompts alone. `models apply` switches
+to the best quality / latency / cost trade-off and registers any rewritten prompts (prior versions
+keep `@production_previous`). `models rollback` undoes the whole last apply: it switches every
+model back and moves each prompt's alias back to its prior version. Apply refuses recommendations
+whose prompt aliases changed during the search; rollback checks those aliases against the versions
+recorded when the recommendation was applied. If rollback fails partway through, run it again
+to finish the remaining changes. Each search owns its temporary clones, so overlapping jobs can
+evaluate different models independently.
+
+The search is `databricks_agentkit.model_upgrades`, which you can also call directly (for example
+from a notebook) to tune several model services and MLflow Prompt Registry prompts together:
+
+```python
+from databricks_agentkit.model_upgrades import optimize_prompts_and_models, promote_to_prod
+
+result = optimize_prompts_and_models(
+    predict,  # predict(inputs: dict) -> answer
+    train_data,  # [{"inputs": {...}, "expectations": {"expected_response": ...}}, ...]
+    val_data,
+    prompt_uris=["prompts:/main.my_agent.router@production"],
+    gateway_endpoints={
+        "main.my_agent.router_llm": ["claude-haiku-4-5", "gpt-5-4-mini"],
+        "main.my_agent.writer_llm": ["claude-sonnet-4-5", "claude-haiku-4-5"],
+    },
+    scorers=scorers,  # MLflow scorers, or (inputs, expectations, answer) -> float
+    max_metric_calls=200,
+)
+promote_to_prod(result)  # repoints the services, registers and aliases the winning prompts
+```
+
+Model choices use a UCB1 bandit by default (`model_selection="reflection"` asks the reflection LLM
+instead); prompts are rewritten by GEPA's reflection loop, which uses Claude Opus 5.5. Both need the `upgrade` extra:
+`pip install 'databricks-agentbricks[upgrade]'`.
+
+Prompts the agent loads from the MLflow Prompt Registry go under `[experimental.prompts]`
+(`agentbricks experimental prompts bind main.my_agent.writer`), and deploy grants the app
+the schema privileges the registry requires to load them. `agentbricks experimental prompts list`
+shows each bound prompt and the version its `@production` alias points at.
 
 ## Commands
 
@@ -632,7 +837,7 @@ 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 ...]
+    add sandbox      [--name NAME] [--auth user|app]
                      [--no-databricks-access-token-included] [--source PATH]
     add mcp          SERVICE [--name NAME] [--source PATH]
     add uc-function  FUNCTION [--name NAME] [--auth user|app] [--source PATH]
@@ -645,12 +850,21 @@ agentbricks [-p <profile>] [-o text|json]
     bind       SERVICE [--role ROLE] [--default MODEL] [--source PATH]
     unbind | list | status
     set        MODEL [--role ROLE] [--yes]
+    rollback   [--role ROLE] [--yes]
+    upgrade    [--candidates [ROLE=]MODEL[,...] [...]] [--prompt URI ... | --models-only] --predict REF --train-data REF --val-data REF
+               --scorer REF [...] [--budget N] [--quality-weight Q] [--latency-weight L] [--cost-weight C]
+               [--timeout-hours H]
+               [--run-on job|local] [--apply never|ask|auto] [--wait]
+    apply      [--yes]
   prompts
     bind       PROMPT [--key KEY] [--source PATH]
     unbind     KEY [--source PATH]
     list       [--source PATH]
-  deploy       [<name>] [--source PATH] [--instances N]
-  deployments  list | get | logs | start | stop | delete
+  deploy       [<name>] [--source PATH] [--instances N] [--no-wait]
+               [--allowed-origin ORIGIN ... | --clear-allowed-origins]
+  deployments
+    wait       [<name>] [--timeout SECONDS] [--source PATH]
+    list | get | logs | start | stop | delete
   endpoint
     invoke      [APP] --path PATH [--url URL] [--json JSON] [--sse]
 ```
@@ -773,7 +987,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 volume:main.data.files
+agentbricks tools add sandbox
 agentbricks tools add mcp system.ai.web_search
 agentbricks tools add uc-function catalog.schema.lookup_ticket
 agentbricks tools add genie-one
@@ -970,9 +1184,9 @@ points to that project's file. JSON add output includes its path in `manifest`.
 
 `agentbricks tools list` discovers **available integrations to add**, not configured bindings. By default
 it shows built-in add recipes and caller-visible MCP Services in `system.ai`. A recipe may still
-need your resources: sandbox scopes, a concrete UC function name, or a Genie Space ID. Genie One
-needs no additional argument. `system.ai.sandbox` is represented by its scoped recipe rather than
-a second unscoped add command. The list does not enumerate every workspace schema, individual
+need your resources: a concrete UC function name or a Genie Space ID. Sandbox and Genie One need no
+additional argument. `system.ai.sandbox` is represented by the `tools add sandbox` recipe rather
+than a generic `tools add mcp` command. The list does not enumerate every workspace schema, individual
 operations inside MCP services, or custom Python tools.
 
 `agentbricks tools add mcp` looks up the service in the selected workspace before writing `agent.toml`.
@@ -1032,22 +1246,41 @@ 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 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:
+Sandbox code runs with the selected identity's own Unity Catalog access: the request user for
+`auth = "user"` (the default) or the App service principal for `auth = "app"`. Grant that identity
+only the data the agent needs. 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 = "volume:main.data.files", permission = "read_only" }], databricks_access_token_included = true }
+policy = { 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
+Every sandbox call carries this fixed policy in MCP `_meta`, outside the tool arguments controlled
+by the model, with an empty `downscope`.
+
+Sandbox resource scopes are not supported: the Sandbox API backend of `system.ai.sandbox` rejects any
+non-empty `_meta.downscope`. The scoping implementation (`--scope`, `--permission`, and
+`policy.downscope`) is retained behind a disabled code-level gate, `SANDBOX_DOWNSCOPE_ENABLED`, so it
+can be enabled when the backend supports resource policies. There is no CLI option to bypass that
+gate. While it is disabled, `agentbricks tools add sandbox --scope ...` fails without changing the
+project, and `agentbricks dev`, `agentbricks deploy`, and the runtime reject a manifest that still
+declares `policy.downscope`:
+
+```text
+Tool 'sandbox' declares policy.downscope, which system.ai.sandbox does not support: sandbox code
+runs with the selected identity's own Unity Catalog access. Remove policy.downscope from the
+[[tools]] entry with id = 'sandbox' in agent.toml.
+```
+
+To fix an existing project, delete the `downscope = [...]` entry from that tool's `policy` table and
+keep `databricks_access_token_included`. Then grant the sandbox identity access to the data it needs.
+
+When scopes are enabled, table sandbox scopes remain unsupported 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`.
 
@@ -1169,7 +1402,8 @@ via the `AGENT_MEMORY_STORE` env var that `deploy` injects; `agentbricks dev` ru
 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, sends it as the
-invocation's top-level `session_id`, and creates a fresh invocation UUID per turn. The chat app also
+invocation's top-level `session_id`, sends the signed-in user as `input.actor`, 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