Metadata-Version: 2.5
Name: databricks-agentbricks
Version: 0.2.0
Summary: Agent Bricks CLI and AgentKit SDK for custom agents on Databricks
Author-email: Databricks <agent-feedback@databricks.com>
License-File: NOTICE
Requires-Python: >=3.10
Requires-Dist: click>=8.4
Requires-Dist: databricks-ai-bridge[memory]>=0.22.0
Requires-Dist: databricks-sdk>=0.124.0
Requires-Dist: fastapi>=0.129.0
Requires-Dist: mlflow-skinny>=3.10.1
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: tomli>=2.0
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: langchain-mcp-adapters>=0.2.1; extra == 'langgraph'
Requires-Dist: langchain>=1.0.0; extra == 'langgraph'
Requires-Dist: langgraph>=1.1.0; extra == 'langgraph'
Requires-Dist: mlflow>=3.10.1; extra == 'langgraph'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25.0; extra == 'langgraph'
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: opentelemetry-exporter-otlp-proto-grpc>=1.25.0; extra == 'openai'
Description-Content-Type: text/markdown

# Agent Bricks CLI (`ab`)

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.

> The underlying APIs are in preview and may need workspace enablement.

## Overview

A managed path from your custom agent code to a production-ready, scalable, durable agent hosted on
Databricks in minutes - with no server framework to build, no infrastructure to provision, and no
invocation protocol to design yourself. Bring your own agent, or start from a template.

- **Deployment** - a guided lifecycle (scaffold, run locally, deploy) that turns an agent project
  into a hosted endpoint. Databricks provisions the compute, the stores your agent binds (session,
  memory), and the access grants, so you ship application code and get a running endpoint.
- **Runtime** - a managed HTTP invocation contract (synchronous, streaming, background) plus optional
  durable execution (persistence, heartbeats, crash recovery) backed by Databricks Lakebase, with no
  database or job queue to operate. Use the opinionated `DurableAgentServer` to get it out of the box,
  or bring your own server for full control. `AgentApp` remains available as a deprecated
  compatibility alias; new code should use `DurableAgentServer`.

**Deployment**

![Deployment: from a blank directory to a running service](docs/deployment.svg)

- **Agent project** - `ab init` scaffolds a deployable project from a framework template
  (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. `ab deploy` reads it to provision and wire everything
  up (detailed under [Agent tools](#agent-tools)).
- **`ab 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. `ab deployments` covers the lifecycle (list, get, logs, start, stop, delete).
- **`ab dev`** - runs your agent from the same manifest the deployment uses, so local behavior
  matches what ships.

**Runtime**

![Runtime: one FastAPI server, run as DurableAgentServer or your own implementation](docs/runtime.svg)

The two ways to run an agent:

- **`DurableAgentServer` - opinionated, batteries included.** Register one handler and get the managed
  invocation contract (synchronous, streaming, background). Enable the durable runtime so
  long-running and background work survives restarts, redeploys, and crashes. The framework
  templates are thin layers over `DurableAgentServer` (HTTP contract detailed under [Runtime](#runtime)).
- **Custom server - generic, full control.** `ab init --server custom` scaffolds a minimal FastAPI
  server with no `DurableAgentServer`: you define your own endpoints, request/response shapes, and protocol.
  `ab dev` and `ab deploy` run and ship it the same way.

## Prerequisites

- **Python ≥3.10** — the `ab` CLI installs and runs on any Python 3.10+. The
  `memory`, `sessions`, `tools`, and `ab tracing bind`/`unbind` commands need nothing else.
- **[`uv`](https://docs.astral.sh/uv/)** — needed to scaffold, run, and deploy an
  agent (`ab init` → `ab dev` → `ab deploy`): the scaffolded project builds
  its environment and launches with `uv run`, both locally and in the deployed Apps
  runtime. The store/session/tools commands and `ab tracing bind`/`unbind` don't need it;
  `ab tracing list`/`get` do, to read `ab dev`'s local trace store.
- **[Databricks CLI](https://docs.databricks.com/dev-tools/cli/)** — needed for
  browser-based `ab login`. If a profile is already authenticated, the CLI uses it
  directly and the Databricks CLI is optional.

## Installation

From PyPI:

The `databricks-agentbricks` Python distribution installs the `ab` command and AgentKit.

```sh
pip install databricks-agentbricks
```

From source:

```sh
pip install 'git+https://github.com/databricks/databricks-ai-bridge.git#subdirectory=integrations/agentbricks'
```

The base package includes the CLI, store SDK, and `DurableAgentServer` HTTP runtime. Generated projects
declare their framework dependencies automatically.

## Shell completion
Add this to `~/.zshrc`:
```sh
eval "$(_AB_COMPLETE=zsh_source ab)"
```

## Authentication

Agent Bricks CLI uses [Databricks authentication](https://docs.databricks.com/aws/en/dev-tools/cli/authentication).
Ask the CLI to authenticate and remember a named profile:

```sh
ab login --profile <profile>
ab sessions stores list
```

`ab login` validates existing credentials first. If credentials are missing or rejected in
an interactive terminal, the CLI runs `databricks auth login --profile <profile>`, revalidates the
profile, and stores the selection in the existing `~/.agentbricks/config.json` state file. This
browser-based setup requires the Databricks CLI. In non-interactive environments, authenticate the
profile before running `ab`. `ab logout` forgets the saved selection without revoking the underlying
credentials.

If Databricks SDK default authentication is already configured, you can skip `ab login`.
You can also pass the global `--profile/-p` option before an individual command, for example
`ab --profile <profile> tools list`. Use `--output json` for scripting.

## Quickstart

The shortest path from a blank directory to a running and deployed agent:

```sh
ab login --profile <profile>
ab init my-agent
cd my-agent
ab dev                 # run locally
ab deploy my-agent     # deploy to Databricks
```

`ab dev` runs the agent locally on `http://localhost:8000`, wrapping the Databricks Apps
local runtime so local behavior matches a deployment.

`ab deploy my-agent` deploys a Databricks App named `agent-bricks-my-agent`, provisions the
stores declared in `agent.toml`, and grants the app's service principal access to them. Use
`ab deployments list` to find deployed apps, and `ab deployments get agent-bricks-my-agent` to
print an app's URL and status.

`ab 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
`<name>-<6-letter-token>-sessions`, and records both names in `agent.toml`.
`ab deploy` creates them if they don't exist yet. Point the agent at stores you already have with
`ab memory bind <name>` / `ab sessions bind <name>`, or scaffold without stores using
`ab init --server custom` (see [Initialize the chat app demo](#initialize-the-chat-app-demo)).

To exercise the agent (locally under `ab dev` or once deployed), `ab endpoint invoke` sends
it an HTTP request. MLflow tracing is on by default (`ab init` binds a default
`/Shared/agentbricks_traces/<project>` experiment): `ab dev` traces to a local MLflow server under
`.agentbricks/` and `ab deploy` to the bound workspace experiment; `ab tracing list` shows the
available traces.

## Public names

Use `ab` for the CLI and `AgentKitClient` from `databricks_agentkit` for the Python SDK. New
projects store local state under `.agentbricks/` and `~/.agentbricks/`, use
`server = "agentbricks"` in `agent.toml`, and deploy apps with the `agent-bricks-` prefix.

## AgentKit SDK

`AgentKitClient` adds a small resource-oriented layer over AgentKit APIs. Pass it an
authenticated Databricks `WorkspaceClient`, or omit the argument to use the
Databricks SDK's default authentication resolution:

```python
from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

agentkit = AgentKitClient(WorkspaceClient(profile="my-workspace"))

session_store = agentkit.session_stores.create("support-agent-sessions")
session = session_store.add(actor_id="customer-123", session_id="case-456")
session.append_items(
    [
        {"type": "message", "role": "user", "content": "I need help with my cluster."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)

memory_store = agentkit.memory_stores.create("coding-agent-memory")
memory = memory_store.add(
    actor_id="alice",
    path="/preferences/style.md",
    content="The user prefers concise answers.",
)
results = memory_store.search(
    actor_id="alice",
    query="response preferences",
    limit=10,
)
memory = memory.update(content="The user prefers very concise answers.")
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.

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()`
also auto-pages. `session.fork(...)` creates an independent copy, optionally through
a specific item. Deleting a session with descendants requires
`session.delete(force=True)` to cascade the deletion.

The resource layer intentionally does not mirror every API method. Its private
transport will be replaced by the generated `WorkspaceClient.mason` service when that
is released, without changing this public surface. Deployment, sandbox, tracing, and
the existing CLI commands remain separate.

## Runtime

`DurableAgentServer` runs your agent through one HTTP API for synchronous, streaming, and background
invocations. Register an `@app.invoke` handler, publish progress with `await context.emit(event)`,
and return a JSON result. You can also add your own FastAPI endpoints.

Start from a template, edit the agent code in `agent/`, and run it locally before deploying:

```sh
ab init my-agent --framework langgraph --server agentbricks --profile <profile>
cd my-agent
ab dev
# Stop the local server when ready to deploy.
ab --profile <profile> deploy my-agent
```

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`.

Each managed run is an **invocation**. Send a client-generated UUID `id` and your agent's `input`:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "input": {"messages": [{"role": "user", "content": "Hello"}]},
  "background": true,
  "stream": true
}
```

| Endpoint | Behavior |
| --- | --- |
| `POST /api/invocations` | Defaults to synchronous execution: `200` with the result under `output`. `stream: true` returns SSE events. `background: true` returns `202` with a status URL; adding `stream: true` also includes an events URL. |
| `GET /api/invocations/{id}` | Returns the invocation status and, when completed, its output. |
| `GET /api/invocations/{id}/events?after={cursor}` | Streams events after the last received event ID, allowing clients to reconnect. |

The UUID also acts as an idempotency key: repeating the same request reuses the existing invocation
while its record is retained; using the ID for a different request returns `409`.

`ab dev` keeps execution state in process and loses it on restart. For projects with
`[agent].server = "agentbricks"`, `ab deploy` provisions a persistent Runtime Store for requests,
status, events, and results. Register `@app.recover` to restart interrupted app-auth work after
worker failures. Recovery is at-least-once, so external side effects must be idempotent. Session
and Memory Stores separately preserve the state used by your agent.

The managed path uses the internal Runtime Store API to create a dedicated database in the
workspace's shared Lakebase project and give the app SP ownership. The managed runtime initializes its schema and
tables; no manual Lakebase grant or Postgres app-resource attachment is needed. Backend selection
is an internal rollout detail, not a user-facing setting; the current implementation retains the legacy
per-app Lakebase project by default. Once enabled, redeploy reads the stored backend and verifies
the app identity, and `ab deployments delete` removes the managed store before deleting the app.
The switch does not migrate existing deployments between backends. Managed cleanup errors retain
the app for retry. Direct app deletion bypasses managed store cleanup.

For a tool using `auth = "user"`, the Runtime Store still records token-free invocation state,
events, and results. The forwarded user credential remains process-local for the active attempt and
is never written to the Runtime Store. A replacement attempt after failure recovery stops with
`MCP_USER_AUTH_RECOVERY_UNSUPPORTED` because the original request credential is no longer present.

Use `server = "custom"` to deploy your own HTTP server without provisioning a Runtime Store.
Changing the server type of an existing deployment is not supported. To use a different server,
scaffold a new project with the desired `ab init --server` option and deploy it under a new name.
See the [runtime guide](src/databricks_agentkit/runtime/README.md) for agent hooks, full API examples,
and recovery behavior.

## Memory and sessions

To hold context, an agent needs two kinds of state: the state of the interaction it is handling right
now, and the durable knowledge it carries from one conversation to the next. Databricks provides a
fully managed store for each, both backed by Lakebase and usable from agents built on any framework:

- **Managed agent sessions** store an agent's session state: the state an agent or framework keeps
  for one interaction. Most commonly this is the conversation history (the ordered transcript of
  messages, tool calls, and results), but it can be any state a framework persists, such as a
  LangGraph graph. The agent reads it at the start of a turn and appends to it as the interaction
  runs.
- **Managed agent memory** stores durable facts, preferences, and decisions that an agent recalls in
  later, separate conversations, retrieved by semantic search.

The examples below use the [`AgentKitClient` Python SDK](#agentkit-sdk); the same operations are available
as `ab sessions` / `ab memory` CLI commands.

![Sessions and memory: the agent reads and appends one conversation's transcript in the session store, and recalls and saves durable facts in the memory store, which outlive any single conversation.](docs/sessions_and_memory.png)

### Sessions

A **session store** holds **sessions**, and each session holds an ordered list of **session items**. A
session is one interaction — typically a conversation thread — grouped under an `actor_id` (who it
belongs to; set this from trusted application context, never a model- or user-supplied value) and
identified by a caller-chosen `session_id` (the service generates one if you omit it). Each item is an
opaque, JSON-compatible `data` value — a message, tool call, result, or reasoning block — that
Databricks stores and returns verbatim, in order, and never mutates once appended.

Create a store, start a session, append the conversation's turns, and read the history back on a later
request:

```python
from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

agentkit = AgentKitClient(WorkspaceClient())

session_store = agentkit.session_stores.create("support-agent-sessions")
session = session_store.add(actor_id="customer-123", session_id="case-456")

session.append_items(
    [
        {"type": "message", "role": "user", "content": "I need help with my cluster."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)

# On a later turn, reload the session and read its full history in order.
session = session_store.get("case-456")
history = [item.data for item in session.list_items()]  # list_items auto-pages
```

A session can be **forked** into an independent branch: a new session seeded with the original's
history, linked back to its origin by `parent_session_id`. Fork the full history, or only up to a
specific item, to explore an alternate continuation without disturbing the original thread:

```python
branch = session.fork(actor_id="customer-123")  # add up_to_item_id=... to branch up to one item
```

Deleting a session that has such descendants requires `session.delete(force=True)` to cascade.

In an agent configured with `server = "agentbricks"`, you don't call these directly — the framework adapter reads and appends
session state for you. With LangGraph, pass `checkpointer()` when you build the agent and scope each
run with `thread_config(session_id)`; the OpenAI Agents adapter exposes the same as
`session_store(session_id)`:

```python
from databricks_agentkit.langgraph import checkpointer, thread_config

agent = create_agent(model=..., tools=[...], checkpointer=checkpointer())
result = await agent.ainvoke(inputs, config=thread_config(session_id))
```

### Memory

A **memory store** holds **memory entries**. Each entry is a free-form `content` string plus a short
`description` used for retrieval, keyed by three fields: `actor_id` (whose memory it is — set from
trusted application context, never a model- or user-supplied value), `path` (a filesystem-like key
within an actor, such as `/preferences/response-style.md`), and an optional `session_id` (the session
an entry came from, for provenance). An entry is uniquely identified by its `actor_id`, `path`, and
optional `session_id`.

Write an entry when the agent learns something durable, then recall it in a later, separate
conversation with a natural-language search — results are ranked by full-text (BM25) relevance, up to
100 entries, with no pagination or vector similarity:

```python
from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

agentkit = AgentKitClient(WorkspaceClient())

memory_store = agentkit.memory_stores.create("support-agent-memory")
memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST.",
    description="User 123 communication preferences",
)

# In a later, separate conversation, recall what the agent knows about this user.
results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)
```

To browse rather than search, `memory_store.list(actor_id=..., path_prefix=...)` returns entries
directly.

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 `ab 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 `ab 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()`:

```python
from databricks_agentkit.langgraph import memory_tools

agent = create_agent(model=..., tools=[*your_tools, *memory_tools(actor)])
```

> **`actor_id` partitions data; it is not access control.** Both stores are workspace-scoped and
> authorized at the store level, so any principal that can reach a store can read and write every
> actor's entries. For strict isolation between tenants or users, use a separate store per boundary.
> Grant another principal — such as your app's service principal — access with
> `session_store.grant_permission(principal_id)` or `memory_store.grant_permission(principal_id)`;
> `ab deploy` does this for the deployed app automatically.

### Declaring and provisioning stores

For a deployed agent, `agent.toml` declares which stores it uses and `ab deploy` provisions them —
you don't create stores by hand. `ab init` declares a default memory and session store named from
the project; override those names, point at stores you already have, or let `deploy` create them:

```sh
# Scaffold a project with default memory and session stores declared in agent.toml.
ab init my-agent

# Override the declared store names at init time.
ab init my-agent --memory-store support-agent-memory --session-store support-agent-sessions

# Or point an existing project at specific stores (edits agent.toml only; creates nothing).
ab sessions bind support-agent-sessions
ab memory bind support-agent-memory

# deploy creates any declared-but-missing store and grants the app's service principal access.
ab deploy my-agent
```

Memory and session stores are independent resources: deleting one never affects the other.

## Commands

For the full command reference - every command, subcommand, argument, and option, in table form -
see [`cli.md`](cli.md). The tree below is a quick overview.

```text
ab [-p <profile>] [-o text|json]
  login        [--profile P]
  logout
  init         [--framework openai|langgraph] [--server agentbricks|custom]
               [--disable-chat-app]
               [--memory-store NAME] [--session-store NAME]
               [--existing] [--profile P] [directory]
  dev          [--source PATH] [--prepare-environment] [--app-port PORT]
  memory
    bind         STORE [--source PATH]
    unbind       [--source PATH]
    stores     create | list | get | update | delete
    entries    create | get | list | search | update | delete
  sessions     create | list | get | update | delete | fork
    bind         STORE [--source PATH]
    unbind       [--source PATH]
    stores     create | list | get | update | delete
    items      list | append | pop | clear
  tracing
    bind       (--experiment-name NAME | --experiment-id ID) [--source PATH]
    unbind     [--source PATH]
    list | get [--experiment-name NAME | --experiment-id ID] [--source PATH]
  tools
    add sandbox      --scope SCOPE [--scope SCOPE ...] [--source PATH]
    add mcp          SERVICE [--name NAME] [--source PATH]
    add uc-function  FUNCTION [--name NAME] [--source PATH]
    add genie-one    [--name NAME] [--auth user|app] [--source PATH]
    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
  endpoint
    invoke      [APP] --path PATH [--url URL] [--json JSON] [--sse]
```

## Bring an existing agent

From the existing project, prepare a migration for your coding agent:

```sh
ab init --framework langgraph --existing .
ab init --framework openai --existing .
```

This writes `agent-bricks-migrate/` containing a skill, a prompt to paste into your coding agent,
`references/migration.json`, and a reference project generated from the templates bundled with the
installed CLI. The bundle sits outside any single agent's configuration directory; `.claude/skills/`
and `.agent/skills/` each receive a small skill that points at it, so Claude Code, Codex, and
similar tools discover the same instructions without duplicating the reference. Agent Bricks CLI
prepares the instructions; the coding agent performs and verifies the conversion. Init leaves application
source, dependencies, `.env`, and existing `.agentbricks/project.toml` configuration intact and refuses to overwrite
existing migration files.

The bundle is scaffolding for the migration, not part of the application: delete `agent-bricks-migrate/`
and the two pointer skills once the conversion is done, and keep them out of commits meanwhile.

The skill follows the shared managed-runtime contract for the selected framework, included in new projects and
migration references:
[LangGraph](src/databricks_agentbricks/templates/agent-langgraph/AGENTKIT_CONTRACT.md) or
[OpenAI Agents SDK](src/databricks_agentbricks/templates/agent-openai/AGENTKIT_CONTRACT.md). It explicitly
handles existing history, custom state and output, recovery, and client/session contracts. For
LangGraph, switching checkpointers does not migrate old conversations (likewise, the OpenAI Agents
SDK keeps prior Session transcripts and RunState behind); unresolved transitions require a user
decision.

The reference honors `--disable-chat-app`, `--memory-store`, `--session-store`, and the selected
profile. These are migration intent; init does not provision resources or change the existing
application. Migration supports LangGraph and the OpenAI Agents SDK with the managed server (`server = "agentbricks"`);
`--server custom` is not supported for `--existing`.

## Invoke HTTP endpoints

`ab endpoint invoke` is a low-level HTTP command. It resolves and authenticates a deployed
Databricks App, or targets localhost and arbitrary servers through `--url`. It does not assume an
agent protocol: provide the method, path, query parameters, and complete JSON body required by the
server.

```sh
ab --profile <profile> endpoint invoke agent-bricks-my-agent \
  --path /api/invocations \
  --json '{"id":"00000000-0000-4000-8000-000000000001","input":[{"role":"user","content":"Hello"}]}'

ab endpoint invoke --url http://localhost:8000 \
  --path /api/invocations \
  --json '{"id":"00000000-0000-4000-8000-000000000001","input":[{"role":"user","content":"Hello"}]}'
```

The JSON body remains explicit even for generated agents. For example, managed runtime agents require
a client-generated invocation ID, and streaming servers require their own streaming field plus
`--sse` so the CLI consumes the response as Server-Sent Events.

```sh
INVOCATION_ID=$(uuidgen)
ab --profile <profile> endpoint invoke agent-bricks-my-agent \
  --path /api/invocations \
  --json "{\"id\":\"$INVOCATION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Run the report\"}]}"

ab --profile <profile> endpoint invoke agent-bricks-my-agent \
  --path /api/invocations \
  --sse \
  --json "{\"id\":\"$INVOCATION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"stream\":true}"
```

`--session-id` preserves one application session across calls by setting the Databricks Apps routing
cookie. This also works with a direct App URL and with the generated runtime on localhost. OAuth and
session headers are managed by the runtime; arbitrary custom request headers are intentionally not exposed
by this command.

## Command help

Use the conventional help flag at any command level. Every command's help includes runnable
examples:

```sh
ab --help
ab deploy --help
ab sessions items append --help
```

## Agent tools

For projects with `[agent].server = "agentbricks"` (the default from `ab init`), `agent.toml` is the
declarative source of truth for Databricks-managed infrastructure: the Runtime Store, sandbox,
managed MCP, Genie and Unity Catalog function bindings, plus memory and session resources. `ab tools
add` updates only this file; direct TOML edits have the same behavior. Both managed-server framework
adapters read the managed bindings at runtime without generating or patching agent source:

```sh
ab tools add sandbox --scope table:samples.nyctaxi.trips
ab tools add mcp system.ai.web_search
ab tools add uc-function catalog.schema.lookup_ticket
ab tools add genie-one
ab tools add genie-agent SPACE_ID
ab tools remove mcp system.ai.web_search
ab tools list
```

### Managed tool identity and migration

`ab tools add mcp`, `ab tools add sandbox`, `ab tools add genie-one`, and
`ab 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`:

```toml
[[tools]]
id = "web_search"
auth = "user"
source = { kind = "mcp", service = "system.ai.web_search" }
```

Direct UC-function bindings remain app/default identity and do not accept `--auth user`.
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.

`DurableAgentServer` derives its request-auth policy directly from the managed tool bindings in `agent.toml`.
Projects do not maintain a separate request-auth contract marker: the presence of any managed tool
with `auth = "user"` makes the invocation require a transient request-user credential.

Request-user invocations use the same synchronous, streaming, background, status, event-replay,
and idempotency APIs as app-auth invocations. The Runtime Store records only token-free request
state, events, and results. The forwarded credential stays process-local for the active first
attempt and closes when that attempt completes, fails, or is cancelled. A replacement attempt after
failure recovery stops with `MCP_USER_AUTH_RECOVERY_UNSUPPORTED` because no user credential is
available; neither the invoke nor recovery handler runs for that attempt.

Before deploying user-auth tools from an older project, migrate its request handler and framework
adapter to the current request-auth-aware `DurableAgentServer` template, then explicitly choose `user` or
`app` on **every** managed MCP, sandbox, or Genie entry. Changing `agent.toml` alone does not
upgrade copied Python adapter code. Outdated adapters fail closed rather than silently using App
identity. App-only legacy projects and generic bring-your-own source directories keep the existing
path.

Deploy derives Apps user scopes from explicit `auth = "user"` bindings:

| Binding | Requested Apps scopes |
| --- | --- |
| Managed MCP (governed ingress) | `ai-gateway` |
| `system.ai.genie_one_mcp` | `ai-gateway`, `genie` |
| First-class Genie One or Genie Agent | `genie` |

For example, bind Genie tools in a current project with `server = "agentbricks"`:

```sh
ab tools add mcp system.ai.genie_one_mcp --auth user
ab tools add genie-agent SPACE_ID --auth user
```

Mixed bindings request the union. App-auth and legacy bindings add no user scopes. These are
explicit service-consent scopes, not a claim that gateway access alone authorizes the downstream
resource. OAuth consent does not grant Unity Catalog privileges: the user still needs access to
the configured Genie Space and its underlying data.

For a new App, deploy explicitly enables user-token forwarding and includes these scopes in the
initial typed SDK create request before uploading source. An existing App that is missing a required
scope needs one-time explicit permission:

```sh
ab --profile my-workspace deploy my-agent --allow-user-scope-update
```

The `system.ai.dbsql` managed MCP additionally requests the Apps `sql` user scope. This is full SQL
API consent, not `sql:restricted-query`; read-only enforcement remains the service policy plus the
requesting user's Unity Catalog grants. DBSQL does not use Databricks Connect.

A sandbox binding with a Volume downscope additionally requests the Apps `files` user scope.
OAuth consent does not grant Volume access: the requesting user still needs the corresponding
Unity Catalog privileges, and the sandbox downscope remains authoritative. Table-only sandbox
bindings request `ai-gateway` but do not request `files`.

Review the target App's scopes and coordinate with its other owners before allowing the update. Once
those scopes are present, later deploys do not need the flag. The CLI preserves unrelated scopes,
updates only user scopes and any explicitly requested instance counts, and checks requested **and
effective** scopes before source rollout. It checks for scope changes since preflight, but Apps
read/write is **not atomic**; this is not a lock or a compare-and-swap guarantee. Polling is bounded
and a mismatch stops source deployment.
Users may need to sign out and **re-consent** after changing scopes; effective-scope verification
does not refresh an existing user's consent.

Apps may report `iam.access-control:read` and `iam.current-user:read` as implicit effective
scopes. The CLI permits these platform defaults during verification but does not request them
as configurable scopes. Explicitly disabled user-token forwarding stops deployment; enable
forwarding and restart the App compute before retrying.

Removing a tool or switching back to app-only auth **does not remove Apps scopes**. Remove
unneeded scopes explicitly in Databricks Apps, and verify both configured and effective scopes
before declaring removal complete. The CLI does not send empty-list scope updates: the SDK's
`App.as_dict()` omits empty lists, so that would not prove removal succeeded. No scopes are
managed for generic bring-your-own apps without this managed user contract.

App-auth tools execute with workload privileges. Restrict App `CAN USE` to callers trusted
for **all** App-auth tools, or deploy those tools separately. Models, custom MCP servers,
Memory/Session Stores, and tracing keep their existing credentials.

For MCP services, the remove command accepts the same service name as the add command. You can also
remove any binding by its `id` in `agent.toml`, for example `ab tools remove web_search`.
Every successful add (including an already-configured no-op) points you to the target project's
`agent.toml` to review configured managed tools and MCP bindings. With `--source`, the message
points to that project's file. JSON add output includes its path in `manifest`.

`ab 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
operations inside MCP services, or custom Python tools.

`ab tools add mcp` looks up the service in the selected workspace before writing `agent.toml`.
Use `ab --profile <profile> tools add mcp <service>` to select a workspace. A missing service or
failed lookup (including authentication or permission errors) leaves the project unchanged. This
checks service metadata access, not whether every tool can be executed at runtime. Removing local
bindings does not require workspace access.

```sh
ab tools list
ab tools list --kind mcp
ab tools list --kind mcp --schema main.tools
ab tools list --kind sandbox
ab tools list --kind genie-one
ab tools list --kind genie-agent
ab --output json tools list
```

No agent project is required for discovery. MCP discovery uses your Databricks profile; the
`sandbox`, `uc-function`, `genie-one`, and `genie-agent` kind filters show local recipes without
authentication. `--schema` requires `--kind mcp` and replaces the default `system.ai` scope. An
API/authentication failure returns nonzero and marks discovery incomplete, while retaining local
recipes; it is not reported as an empty successful discovery. Listing metadata does not verify
runtime execution permissions.

**Migration:** the former configured `tools list` view and its `--source` option are removed.
Read `agent.toml` (its `[[tools]]` entries) to inspect configured bindings. Discovery JSON uses
`schema_version: 2`, with `available_tools` (`name`, `kind`, `add_command`), `mcp_schema` (null for
local-only recipes), `complete`, and `errors`. Replace old scripts that read configured-list JSON
with TOML inspection. Replace `ab mcp list [--schema catalog.schema]` with
`ab tools list --kind mcp [--schema catalog.schema]`; the former command is removed. Use
`ab tools list --help` for the new discovery contract.

Read-only live discovery can be checked against the installed wheel without creating a project
or deploying an agent:

```sh
AGENTBRICKS_E2E_PROFILE=<profile> .venv-functional/bin/pytest tests/e2e/tool_discovery_test.py -v
```

The live checks compare default and MCP-filtered discovery with the compatibility service list.
Set `AGENTBRICKS_E2E_SCHEMA=catalog.schema` to exercise an additional schema. The installed CLI's local
add/review/remove flows and all updated help pages are covered by `tests/functional/cli_smoke_test.py`.

In managed-server templates, custom Python tools are code-first. Write them with the framework's native
decorator in `agent/tools/`: LangGraph uses `@tool`, while OpenAI Agents uses `@function_tool`. The
templates auto-discover decorated tools from that package and add them to the agent; there is no CLI
command or `agent.toml` entry to keep in sync. Customer-managed MCP servers are likewise ordinary
code in `agent/mcps.py` and are joined with the managed bindings by `mcp_tools(...)` or
`mcp_servers(...)`.

Projects created with `--server custom` do not auto-discover `agent/tools/` or load managed tool
bindings from `agent.toml`, so `ab tools add` rejects those projects. Wire framework-native Python
tools and MCP servers directly in `agent/agent.py` instead.

If a manifest with `server = "agentbricks"` contains `source = { kind = "python", ... }`, remove that
`[[tools]]` entry; the decorated tool in `agent/tools/` remains active. `ab dev` and `ab deploy`
do not generate or patch Python tool code, and do not alter the manifest's `[[tools]]` bindings.

Sandbox scopes default to read-only access. Repeat `--scope` to allow more than one resource, use
`volume:` or `workspace:` for those resource types, and use `--permission read_write` only when the
agent needs writes. Every sandbox call carries this fixed downscope in MCP `_meta`, outside the tool
arguments controlled by the model.

### Genie tools

Genie One and Genie Agent support ship with Agent Bricks CLI, but bindings are opt-in, like sandbox tools.
Installing the current `databricks-agentbricks` distribution does not configure a Genie Space ID or enable a Genie binding. Add only the
capabilities your agent needs:

```sh
ab tools add genie-one --name genie_one --auth user
ab tools add genie-agent SPACE_ID --name genie_agent --auth user
ab tools list --kind genie-one
ab tools list --kind genie-agent
ab tools remove genie_one
ab tools remove genie_agent
```

`--name` is optional and defaults to `genie_one` or `genie_agent`, respectively. `--auth` defaults
to `user`; choose `--auth app` deliberately for App service-principal execution. Existing manifests
without `auth` preserve App/default identity. Both add commands and `remove` accept `--source PATH`
to select a project instead of the current directory. Discovery needs no project; read that
project's `agent.toml` to inspect configured bindings. For scripted output, put the global
`-o json` option before `tools`, as in
`ab -o json tools add genie-one --source ./my-agent`. Adding a binding is offline: it updates
`agent.toml` without contacting Genie or checking permissions. The corresponding sources are:

```toml
[[tools]]
id = "genie_one"
auth = "user"
source = { kind = "genie_one" }

[[tools]]
id = "genie_agent"
auth = "user"
source = { kind = "genie_agent", space_id = "<your-space-id>" }
```

Replace `SPACE_ID` or `<your-space-id>` with an existing space's 32-character lowercase hexadecimal
ID. `genie-one` connects to the workspace-wide MCP endpoint
`https://<workspace-hostname>/api/2.0/mcp/genie`, without a space suffix. `genie-agent` uses the
native Genie **Chat-mode** conversation API through the Databricks SDK, not the streaming
Agent-mode API or the per-space MCP endpoint.

Each native binding exposes `{id}_ask`, `{id}_poll`, and `{id}_query_result`, where `{id}` is its
binding name. Ask accepts an optional `conversation_id` for follow-ups. Ask and poll share a
120-second budget per call, including client setup and submission. If the response is still
running, they return `timed_out` with the conversation and message IDs so the caller can poll
again. If submission times out before a message ID is received, ask returns
`INDETERMINATE_SUBMISSION`: the request may still complete, so do not resubmit automatically.
`NOT_SUBMITTED` means client setup timed out before sending the question. Query results include
the first 100 rows, column schema, a truncation indicator, and a deep link to the conversation.

Both framework modules, `databricks_agentkit.langgraph` and `databricks_agentkit.openai`, export
`genie_tools()`. New managed-server templates (`server = "agentbricks"`) use it automatically for native Genie Agent bindings;
Genie One uses the existing managed MCP helpers. In an existing project with `server = "agentbricks"`, import
`genie_tools` from your framework module and add `*genie_tools()` to the agent's existing tool list.
The CLI does not patch existing Python code.

Both paths use Databricks authentication and the routed workspace. Genie One requires the
Managed MCP Servers workspace preview; delegated access requires the `genie` OAuth scope.
The effective caller needs access to the data, the SQL warehouse, and the selected Genie space
where applicable. Agent Bricks CLI does not grant permissions or promise a service-principal fallback when
caller credentials lack access. An offline add succeeding does not establish runtime access.

The opt-in live tests exercise both frameworks against the configured workspace and an existing
Genie space. From `integrations/agentbricks`, with both framework extras installed:

```sh
DATABRICKS_CONFIG_PROFILE=my-workspace RUN_AGENTBRICKS_GENIE_TESTS=1 \
  AGENTBRICKS_GENIE_SPACE_ID=SPACE_ID \
  uv run pytest tests/integration_tests/genie_tools_test.py
```

By default they ask for the row count of `samples.nyctaxi.trips`. Set `AGENTBRICKS_GENIE_QUESTION` for
another dataset and `AGENTBRICKS_GENIE_EXPECTED_VALUE` to assert a known result cell.

## Initialize the chat app demo

The chat app is a LangGraph-specific init overlay, not a command that mutates an existing project.
It is included by default for `--framework langgraph`; pass `--disable-chat-app` to scaffold the
API-only backend instead.

```sh
ab init --framework langgraph \
  --profile <profile> \
  ./my-agent
cd ./my-agent
ab dev
```

The chat app includes synchronous, SSE streaming, background polling, Session Store, Memory Store,
and HITL resume UI. The framework-specific overlay adds `ui/`, `runtime/ui.py`, the UI-enabled
`runtime/main.py`, and UI tests.

For the full deployed demo, bind both managed stores, then deploy:

```sh
ab sessions bind agent-bricks-demo-sessions
ab memory bind agent-bricks-demo-memory
ab --profile <profile> deploy agent-bricks-agent-demo --source .
```

(`bind` declares the store name in `agent.toml`; `ab deploy` creates any declared-but-missing
store and grants the app's service principal access to it. The memory store id flows to the runtime
via the `AGENT_MEMORY_STORE` env var that `deploy` injects; `ab dev` runs locally with memory off
and does not inject it. The id is not persisted in `agent.toml`.)

The chat UI generates a stable application session UUID in browser local storage, places it inside
the invocation's opaque `input`, and creates a fresh invocation UUID per turn. The
`__Host-databricks-app-router` cookie remains independent: API clients may reuse it for sticky
replica routing, but it is neither authentication nor the template's application session state.

The generated `README.md` documents every request the client makes: config discovery, sync and SSE
invocations, background submission and polling, session transcript loading, HITL resume, and memory
entry operations. Capability colors are automatic from `/api/demo/config`; only the
sync/streaming/background transport selector is manual.

## Contributing

Developing Agent Bricks CLI (`ab`), AgentKit, the runtime, and templates - plus the local dev loop and how to
test unreleased changes on `ab dev` and `ab deploy`, is covered in
[CONTRIBUTING.md](CONTRIBUTING.md).
