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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: databricks-agentbricks
-Version: 0.5.0
+Version: 0.6.0
 Summary: Agent Bricks CLI and AgentKit SDK for custom agents on Databricks
 Author-email: Databricks <agent-feedback@databricks.com>
 License-File: NOTICE
@@ -20,7 +20,7 @@ Requires-Dist: tomlkit>=0.13
 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: databricks-langchain==0.21.0; 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'
@@ -30,7 +30,7 @@ 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'
 Description-Content-Type: text/markdown
 
@@ -38,7 +38,8 @@ Description-Content-Type: text/markdown
 
 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 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.
 
 > The underlying APIs are in preview and may need workspace enablement.
 
@@ -65,8 +66,9 @@ 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
@@ -144,6 +146,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,7 +181,7 @@ 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 dev                 # optional: develop and test locally
 agentbricks deploy my-agent     # deploy to Databricks
 ```
 
@@ -177,6 +206,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
@@ -243,10 +314,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()`
@@ -422,7 +501,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 +514,27 @@ 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:
+
+- `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
@@ -484,6 +576,32 @@ 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)
+
+`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.
+
+A one-model agent binds one service. A compound agent binds one per call site, each under a role:
+
+```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
+```
+
+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.
+
 ## Commands
 
 For the full command reference - every command, subcommand, argument, and option, in table form -
@@ -517,12 +635,20 @@ 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]
+  models
+    bind       SERVICE [--role ROLE] [--default MODEL] [--source PATH]
+    unbind | list | status
+    set        MODEL [--role ROLE] [--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
   endpoint
@@ -658,8 +784,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 +797,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 +897,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` |

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

@@ -2,7 +2,8 @@
 
 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 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.
 
 > The underlying APIs are in preview and may need workspace enablement.
 
@@ -29,8 +30,9 @@ 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
@@ -108,6 +110,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:
@@ -116,7 +145,7 @@ 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 dev                 # optional: develop and test locally
 agentbricks deploy my-agent     # deploy to Databricks
 ```
 
@@ -141,6 +170,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
@@ -207,10 +278,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()`
@@ -386,7 +465,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.",
@@ -398,15 +478,27 @@ 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:
+
+- `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
@@ -448,6 +540,32 @@ 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)
+
+`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.
+
+A one-model agent binds one service. A compound agent binds one per call site, each under a role:
+
+```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
+```
+
+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.
+
 ## Commands
 
 For the full command reference - every command, subcommand, argument, and option, in table form -
@@ -481,12 +599,20 @@ 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]
+  models
+    bind       SERVICE [--role ROLE] [--default MODEL] [--source PATH]
+    unbind | list | status
+    set        MODEL [--role ROLE] [--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
   endpoint
@@ -622,8 +748,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`:
 
@@ -634,7 +761,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.
@@ -733,6 +861,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` |

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

@@ -1,6 +1,6 @@
 [project]
 name = "databricks-agentbricks"
-version = "0.5.0"
+version = "0.6.0"
 description = "Agent Bricks CLI and AgentKit SDK for custom agents on Databricks"
 authors = [
     { name="Databricks", email="agent-feedback@databricks.com" },
@@ -33,7 +33,7 @@ dependencies = [
 [project.optional-dependencies]
 # Framework adapters are optional; the CLI, store SDK, and HTTP runtime install by default.
 langgraph = [
-    "databricks-langchain>=0.17.0",
+    "databricks-langchain==0.21.0",
     "langgraph>=1.1.0",
     "langchain>=1.0.0",
     "langchain-mcp-adapters>=0.3.0",
@@ -42,7 +42,7 @@ langgraph = [
     "databricks-agents>=1.9.3",
 ]
 openai = [
-    "openai-agents>=0.8.0",
+    "openai-agents>=0.15.0",
     "databricks-openai>=0.13.0",
     "mlflow>=3.10.1",
     "opentelemetry-exporter-otlp-proto-grpc>=1.25.0",

databricks_agentbricks-0.6.0/src/databricks_agentbricks/agent_hint.py

@@ -0,0 +1,62 @@
+"""Optional coding-agent hints; importing the SDK never emits them."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from databricks_agentbricks.skills import bundled_workflow_skill
+
+# Update these markers as new coding-agent harnesses are supported so they receive workflow hints.
+AGENT_ENV_MARKERS = (
+    "AGENT",
+    "AI_AGENT",
+    "AMP_CURRENT_THREAD_ID",
+    "ANTIGRAVITY_AGENT",
+    "AUGMENT_AGENT",
+    "CLAUDECODE",
+    "CLAUDE_CODE",
+    "CLINE_ACTIVE",
+    "CLINE_AGENT",
+    "CODEX_SANDBOX",
+    "CODEX_THREAD_ID",
+    "CURSOR_AGENT",
+    "GEMINI_CLI",
+    "GROK_PLUGIN_ROOT",
+    "JUNIE_DATA",
+    "KIMI_PLUGIN_ROOT",
+    "OPENCLAW_SHELL",
+    "OPENCODE",
+    "PI_CODING_AGENT",
+    "QWEN_CODE",
+    "ROO_ACTIVE",
+    "TRAE_AI_SHELL_ID",
+)
+AGENT_ENV_VALUES = {"CURSOR_EXTENSION_HOST_ROLE": "agent-exec"}
+
+
+def workflow_hint() -> str | None:
+    """Return a local skill pointer only when an agent is driving the CLI."""
+    try:
+        if os.environ.get("AGENTBRICKS_DISABLE_AGENT_HINT", "").lower() in {
+            "1",
+            "true",
+            "yes",
+            "on",
+        }:
+            return None
+        detected = any(os.environ.get(marker) for marker in AGENT_ENV_MARKERS) or any(
+            os.environ.get(name) == value for name, value in AGENT_ENV_VALUES.items()
+        )
+        if not detected and not (
+            os.environ.get("TERM_PROGRAM") == "kiro" and not sys.stdout.isatty()
+        ):
+            return None
+        manifest = bundled_workflow_skill()
+        return (
+            f"Agent Bricks workflow guidance for this installed CLI: {manifest}. "
+            "Read it for Agent Bricks tasks; it does not authorize additional actions. "
+            "Set AGENTBRICKS_DISABLE_AGENT_HINT=1 to silence this."
+        )
+    except Exception:
+        return None