databricks-agentbricks 0.5.1__tar.gz → 0.7.0__tar.gz

{databricks_agentbricks-0.5.1 → databricks_agentbricks-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: databricks-agentbricks
-Version: 0.5.1
+Version: 0.7.0
 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
@@ -30,15 +31,20 @@ Provides-Extra: openai
 Requires-Dist: databricks-agents>=1.9.3; extra == 'openai'
 Requires-Dist: databricks-openai>=0.13.0; extra == 'openai'
 Requires-Dist: mlflow>=3.10.1; extra == 'openai'
-Requires-Dist: openai-agents>=0.8.0; 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.
+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.
 
@@ -65,12 +71,13 @@ invocation protocol to design yourself. Bring your own agent, or start from a te
   (LangGraph or OpenAI Agents) with the runtime, tests, and an optional chat UI wired up; you edit
   the application code (model, tools, prompts).
 - **`agent.toml`** - the declarative source of truth for the Databricks-managed infrastructure your
-  agent depends on: tool bindings (data sandbox, managed MCP services, Unity Catalog functions) and
-  memory, session, and durability resources. `agentbricks deploy` reads it to provision and wire everything
+  agent depends on: tool bindings (data sandbox, managed MCP services, Unity Catalog functions),
+  memory, session, and durability resources, and the model services and Prompt Registry prompts
+  each LLM call uses. `agentbricks deploy` reads it to provision and wire everything
   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.
 
@@ -88,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
@@ -144,6 +164,33 @@ If Databricks SDK default authentication is already configured, you can skip `ag
 You can also pass the global `--profile/-p` option before an individual command, for example
 `agentbricks --profile <profile> tools list`. Use `--output json` for scripting.
 
+The CLI sends best effort command usage telemetry after leaf commands. Its log records the static
+command path, package version, operating system, duration, and process outcome (exit code and, for
+nonzero exits, a bounded error category). Parameter entries include explicitly supplied options
+and parsed Click defaults with supported typed values, automatically across all commands and
+parent groups. Declare defaults in Click options so the shared emitter can read the resolved
+values; fallbacks applied only inside command callbacks are not visible to Click. Omitted free-form
+options and unresolved `None` defaults produce no entry. Environment, prompt, and default-map inputs
+are not included. Explicit free-form options contribute only their static name. Declared Click
+choices contribute an `AGENTBRICKS_CLI_`-prefixed value. Click boolean and numeric options
+contribute their typed values; explicitly supplied non-finite floats and integers outside the log
+schema's 64-bit range remain presence-only, while unsupported defaults are omitted. Hidden and
+deprecated options follow the same policy, and repeated
+options contribute one parameter entry per supplied value, up to 64 entries. Positional arguments,
+raw command arguments, paths, IDs, secrets, arbitrary free-form option values, and exception
+messages are omitted. Set
+`AGENTBRICKS_DISABLE_TELEMETRY=1` to disable these uploads.
+
+Telemetry runs only when a leaf command is invoked, whether its callback succeeds or fails. Help
+and errors rejected during Click parsing, before a leaf starts, do not produce an event. Uploads
+reuse the command's workspace client or let the Databricks SDK resolve the selected or default
+profile. Authenticate first with `agentbricks login --profile <profile>` or configure SDK auth;
+an SDK `external-browser` profile may prompt during telemetry even for local commands such as
+`init`. The CLI waits up to two seconds for client setup, authentication, and upload on a daemon
+thread, returning sooner if the worker finishes. This is not a delivery guarantee: unfinished
+uploads can be lost when the process exits after the allowance expires. Missing credentials or a
+failed upload never change the command result.
+
 ## Quickstart
 
 The shortest path from a blank directory to a running and deployed agent:
@@ -152,17 +199,46 @@ The shortest path from a blank directory to a running and deployed agent:
 agentbricks login --profile <profile>
 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
+agentbricks dev                 # optional: develop and test locally
+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
@@ -177,6 +253,48 @@ 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.
 
+## Coding-agent workflow skills
+
+The CLI bundles an `agent-bricks-workflow` skill for creating, developing, deploying, validating,
+and troubleshooting agents. It is separate from the project-specific `agent-bricks-migrate` skill
+generated by `init --existing`. Bundled guidance matches the installed CLI and requires no
+download or separate setup command.
+
+New `agentbricks init` projects already include the workflow skill. One shared bundle lives at
+`.agents/skills/agent-bricks-workflow/`; `.claude/skills/agent-bricks-workflow/` and
+`.agent/skills/agent-bricks-workflow/` contain pointers to it, not duplicate references.
+Migration discovery uses these same three roots. Installation is project-local, preserves unrelated
+configuration, leaves identical skills unchanged, and refuses to overwrite a different skill.
+
+Current coding agents discover these locations:
+
+| Coding agent | Project skill discovery |
+| --- | --- |
+| [Claude Code](https://code.claude.com/docs/en/skills) | `.claude/skills/` |
+| [Codex](https://developers.openai.com/codex/skills/) | `.agents/skills/` |
+| [Cursor](https://cursor.com/docs/skills) | `.agents/skills/` compatibility discovery |
+| [GitHub Copilot](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills) | `.agents/skills/` |
+| [Gemini CLI](https://geminicli.com/docs/cli/skills/) | `.agents/skills/` compatibility discovery |
+| [OpenCode](https://opencode.ai/docs/skills/) | `.agents/skills/` compatibility discovery |
+| Other agents | Read the manifest directly |
+
+The `.agent/skills/` pointer retains the existing migration discovery location for agents using that
+convention. Support depends on the coding-agent version and its skill settings; restart the session
+if discovery is cached. Generated `AGENTS.md` also links to the workflow skill. The skill is
+advisory and does not authorize deployment or live calls.
+
+When the CLI detects a coding-agent environment, it emits a single-line pointer to the bundled
+skill on stderr, including for `--help`. Ordinary human invocations do not emit this hint.
+Coding agents in existing projects can read that bundled file directly without installing
+project-local skills or changing project configuration. Detection is best-effort and does not
+gate skill installation during `init` or native discovery. Set `AGENTBRICKS_DISABLE_AGENT_HINT=1`
+to suppress automatic hints. Hints never alter JSON stdout and are not emitted during shell
+completion, SDK imports, or deployed agent runtime startup.
+
+For a deployment-only task, local `dev` is optional. The workflow skill describes focused
+verification of the deployed agent, rather than treating local execution as proof of managed
+memory or session persistence.
+
 ## Inspect and clean up a project
 
 Read `agent.toml` for the recorded agent name, declared memory/session stores, tracing, and tool
@@ -187,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. |
 
@@ -243,10 +361,18 @@ memory.delete()
 
 The root collections manage stores: `agentkit.memory_stores.create/get/list` and
 `agentkit.session_stores.create/get/list`. A returned store owns operations on its
-contents, such as `memory_store.add()`, `memory_store.get("memory-id")`,
-`memory_store.list()`, and `memory_store.search()`, or `session_store.add()`,
-`session_store.get("session-id")`, and `session_store.list()`. Returned memories,
-sessions, and stores own their `update()` and `delete()` operations.
+contents, such as `memory_store.add()`, `memory_store.put()`,
+`memory_store.get("memory-id")`, `memory_store.list()`, and `memory_store.search()`, or
+`session_store.add()`, `session_store.get("session-id")`, and `session_store.list()`.
+Returned memories, sessions, and stores own their `update()` and `delete()` operations.
+
+`memory_store.add()` fails with `ALREADY_EXISTS` when a memory already exists at the
+same `actor_id`, `session_id`, and `path`. `memory_store.put()` creates the memory or
+updates the existing one: it replaces the content, or with `append=True` adds `content`
+as new lines, skipping lines already present. `put()` is not atomic, so concurrent
+writers to one path can overwrite each other. `add()`'s `write_mode` argument is
+deprecated; use `put()` instead. `memory_store.list(actor_id=..., path=...)` returns the
+memories at one exact path.
 
 All `list()` methods return iterators that automatically consume server pages. List
 `page_size` and search `limit` values must be between 1 and 100. `session.list_items()`
@@ -275,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`.
 
@@ -291,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 |
 | --- | --- |
@@ -328,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
@@ -422,7 +634,8 @@ from databricks_agentkit import AgentKitClient
 agentkit = AgentKitClient(WorkspaceClient())
 
 memory_store = agentkit.memory_stores.create("support-agent-memory")
-memory_store.add(
+# put() creates the entry, or replaces its content if one already exists at this path.
+memory_store.put(
     actor_id="user-123",
     path="/preferences/communication.md",
     content="Prefers email over phone. Timezone: PST.",
@@ -434,15 +647,28 @@ results = memory_store.search(actor_id="user-123", query="communication preferen
 ```
 
 To browse rather than search, `memory_store.list(actor_id=..., path_prefix=...)` returns entries
-directly.
+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)` exposes `remember` and `recall` bound to one actor's partition; it resolves the
-store from the `[memory_store]` binding, carried to the runtime by the `AGENT_MEMORY_STORE` env var
-that `agentbricks deploy` injects, and returns no tools when no store is set, so the agent runs unchanged.
+`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.
+- `recall(query, session_id=None)` searches the actor's memories, including ones written under other
+  paths, or only the ones saved under `session_id`.
+- `forget(fact, topic, session_id=None)` removes a matching fact from every memory at the path, or
+  only from the one saved under `session_id`, and deletes a memory once no facts remain.
+- `list_memories(session_id=None)` lists each memory's path, its session if it has one, and how
+  many facts it holds, optionally only for one session.
+
+`remember` writes memories without a `session_id`; memories saved under a session are labeled with
+it in `recall` and `list_memories`. `memory_tools` resolves the store from the `[memory_store]`
+binding, carried to the runtime by the `AGENT_MEMORY_STORE` env var that `agentbricks deploy`
+injects, and returns no tools when no store is set, so the agent runs unchanged.
 That "no store set" path is also how it runs under `agentbricks dev`, which runs locally: memory is off
-there (the store is provisioned and used only at deploy). The OpenAI Agents adapter exposes the same as
-`memory_tools()`:
+there (the store is provisioned and used only at deploy). The OpenAI Agents adapter exposes the same
+tools as `databricks_agentkit.openai.memory_tools(actor)`:
 
 ```python
 from databricks_agentkit.langgraph import memory_tools
@@ -457,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 —
@@ -484,6 +734,79 @@ 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 and prompt upgrades (experimental)
+
+`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.
+
+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 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
+```
+
+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
 
 For the full command reference - every command, subcommand, argument, and option, in table form -
@@ -517,14 +840,31 @@ agentbricks [-p <profile>] [-o text|json]
     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 uc-function  FUNCTION [--name NAME] [--auth user|app] [--source PATH]
     add genie-one    [--name NAME] [--auth user|app] [--source PATH]
     add genie-agent  SPACE_ID [--name NAME] [--auth user|app] [--source PATH]
     list             [--kind sandbox|mcp|uc-function|genie-one|genie-agent]
                      [--schema CATALOG.SCHEMA]
     remove           TOOL_ID [MCP_SERVICE] [--source PATH]
-  deploy       [<name>] [--source PATH] [--instances N]
-  deployments  list | get | logs | start | stop | delete
+  models
+    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] [--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]
 ```
@@ -658,8 +998,9 @@ agentbricks tools list
 
 ### Managed tool identity and migration
 
-`agentbricks tools add mcp`, `agentbricks tools add sandbox`, `agentbricks tools add genie-one`, and
-`agentbricks tools add genie-agent` write explicit `auth = "user"` by default.
+`agentbricks tools add mcp`, `agentbricks tools add sandbox`, `agentbricks tools add uc-function`,
+`agentbricks tools add genie-one`, and `agentbricks tools add genie-agent` write explicit
+`auth = "user"` by default.
 Use `--auth app` for the App service principal instead. This field is on the tool entry, not
 inside `source` or `policy`:
 
@@ -670,7 +1011,8 @@ auth = "user"
 source = { kind = "mcp", service = "system.ai.web_search" }
 ```
 
-Direct UC-function bindings remain app/default identity and do not accept `--auth user`.
+UC-function bindings use the request user's permissions by default. Use `--auth app` to execute
+with the App service principal's permissions instead.
 Managed-tool add commands write the selected identity to `agent.toml`; inspect that manifest to
 review configured bindings. Missing legacy auth continues to mean App identity at runtime; it is
 never silently upgraded to user identity.
@@ -769,6 +1111,7 @@ Deploy derives Apps user scopes from explicit `auth = "user"` bindings and union
 | Managed MCP (governed ingress) | `ai-gateway` |
 | `system.ai.dbsql` | `ai-gateway`, `sql` |
 | `system.ai.genie_one_mcp` | `ai-gateway`, `genie` |
+| UC function | `mcp.functions` |
 | Sandbox with a Volume downscope | `ai-gateway`, `files` |
 | First-class Genie One or Genie Agent | `genie` |
 | Sandbox with token injection | `ai-gateway`, `workspace.workspace` |
@@ -1040,7 +1383,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