databricks-agentbricks 0.2.0__py3-none-any.whl

databricks_agentbricks/templates/agent-openai/AGENTKIT_CONTRACT.md

@@ -0,0 +1,107 @@
+# Managed runtime integration contract for OpenAI Agents
+
+This document owns the requirements shared by generated projects and existing agents adopting
+the managed runtime. The [README](README.md) owns commands and HTTP examples; adapter docstrings own API details.
+The adjacent template is an example, not a required agent architecture. Runtime internals live in
+the installed package's runtime guide.
+
+## Command requirements
+
+Agent Bricks CLI commands operate on an application directory; they do not rewrite its agent. Each capability
+needs runtime wiring as well as manifest configuration.
+
+| Command | Required integration |
+| --- | --- |
+| `dev`, `deploy` | Installable dependencies and an `app.yaml` command starting the application |
+| `tools add mcp`, `uc-function`, `genie`, `sandbox` | Load bindings into agent tool lists and tool execution |
+| `sessions bind` | Select the bound session store and supply session/actor identity |
+| `memory bind` | Include bound, actor-scoped memory tools in the agent tool list |
+| `tracing bind`, `tracing unbind` | Initialize tracing and open a root span from resolved config |
+| `endpoint invoke` | An HTTP endpoint; the caller supplies its path and complete request body |
+
+### Project and startup
+
+Use `agent.toml` for framework, tool/store bindings, and tracing. The existing `.agentbricks/project.toml`
+file records framework and template provenance; keep it when working with projects that have it.
+Metadata alone does not integrate adapters. Install a compatible `databricks-agentbricks[openai]`
+distribution, supply the real command in `app.yaml`, load configuration before adapters, and listen
+on the app port. The Agent Bricks CLI and runtime find `agent.toml` from the working directory or
+`AGENTBRICKS_PROJECT_ROOT`. Keep credentials out of `app.yaml`.
+
+Store binding commands declare intent. `dev` and `deploy` resolve or provision declared stores and
+supply runtime config; deploy grants app access. The resolved Memory Store ID reaches the runtime
+as `AGENT_MEMORY_STORE`, rather than being stored as an ID in the manifest. Do not hardcode values
+that make later bindings ineffective.
+
+The model provider is a choice, not a requirement. The template's [agent/agent.py](agent/agent.py)
+wires the Databricks Unity Catalog AI Gateway (`AsyncDatabricksOpenAI(..., use_ai_gateway=True)`
+plus a `system.ai.*` model), but an agent may keep its existing provider instead, e.g. direct
+OpenAI via `OPENAI_API_KEY` and a model string like `gpt-4o-mini`. Whichever is chosen,
+`configure()` sets it up at startup, and deployment must ensure the chosen model is reachable
+from the app.
+
+### Tools
+
+Use `databricks_agentkit.openai.mcp_servers()` for MCP, UC function, and sandbox bindings, combining
+them with agent-owned servers without duplicates. It applies sandbox downscoping. Genie Agent
+bindings arrive as tools from `genie_tools()`. Local Python tools belong in source; the template
+discovers `@function_tool` functions through [agent/tools/__init__.py](agent/tools/__init__.py).
+
+Feed selected tools into the agent's tool list while preserving approval policy. Tools that gate on
+approval declare `needs_approval=True` and appear in the template's `REQUIRE_APPROVAL` set so
+pending calls surface as interrupts. New bindings must become effective on the next agent
+construction or restart without another source edit.
+
+### Sessions and memory
+
+Pass `session_store(session_id)` as the `session` argument of `Runner.run(agent, messages,
+session=...)` for managed conversation state. The helper selects the bound Session Store or
+an in-process session; explicit arguments and environment overrides take precedence. Supply the
+actor so the durable store partitions transcripts per user. It caches the in-process session per
+process, so restart after a binding change.
+
+Include `memory_tools(actor)` in the agent's tool list. It returns no tools when unconfigured.
+Its closures capture actor identity, so never reuse them across users. The application owns
+trusted actor/tenant authentication; a payload field alone does not establish identity.
+
+### Tracing
+
+Call `configure_tracing()` after loading config; it binds `mlflow.openai.autolog`. Then wrap agent
+execution, including streams, in `start_trace(..., session_id=session_id)`. The root span lets
+framework autologging record children. The helper enables tracing when destination and experiment
+settings are present and disables it otherwise. Preserve existing tracing semantics when composing
+it.
+
+## Managed server adapter
+
+For the managed invocation protocol, construct `DurableAgentServer` in [runtime/main.py](runtime/main.py)
+and register [runtime/adapter.py](runtime/adapter.py) hooks. Keep framework-native execution in
+[agent/agent.py](agent/agent.py), independent of runtime request/context types.
+
+The invoke hook translates opaque application input, runs the agent through the framework `Runner`,
+translates native events, calls `await context.emit(event)`, and returns JSON output. DurableAgentServer owns
+foreground/background transport, polling, and replay. Invocation UUIDs differ from stable
+application session IDs; the routing cookie is not the application session.
+
+The example assumes `messages` input and message, delta, and interrupt events. Custom inputs,
+outputs, and interruptions require explicit mappings and must not be discarded to fit the example.
+
+### Recovery and durability
+
+Runtime Store persistence covers invocations and emitted events. Session Store persistence covers
+the conversation transcript, not in-flight run state. The Agents SDK has no node-level checkpoint
+continuation: OpenAI HITL `RunState` is process-local and does not survive worker loss even with a
+Session Store bound. `dev` uses process-local invocation storage; deployment attaches a
+Lakebase-backed Runtime Store.
+
+Register recovery when intended. The recover hook replays the persisted application input against
+the same session and prepends a developer instruction warning that the prior attempt may have
+partially completed. Recovery is at least once, so side effects must be idempotent and tools must
+tolerate replay.
+
+## Optional chat app
+
+No CLI command requires the chat UI. The default overlay supplies it; `--disable-chat-app` omits
+it. When adopting it, inspect `CHAT_APP.md`, `runtime/ui.py`, and browser code. Adapt model choice,
+history, approval interrupts, and authentication to the actual agent. Its message-oriented
+assumptions must not silently change custom application behavior.

databricks_agentbricks/templates/agent-openai/AGENTS.md

@@ -0,0 +1,76 @@
+# Agent Development Guide
+
+This project is an OpenAI Agents SDK workload hosted by `databricks_agentkit.DurableAgentServer`.
+
+Read [AGENTKIT_CONTRACT.md](AGENTKIT_CONTRACT.md) before changing integration points. It owns command
+requirements, tool/state/tracing wiring, and recovery. [README.md](README.md) owns setup and client
+examples. Keep this file as a development map rather than repeating those rules.
+
+## Commands
+
+```bash
+ab dev
+uv run pytest
+ab --profile <profile> deploy <name> --source .
+```
+
+## Request contract
+
+Use only `/api/invocations`. The transport body is:
+
+```json
+{
+  "id": "<uuid>",
+  "input": {
+    "session_id": "<stable-application-session>",
+    "messages": [{"role": "user", "content": "hello"}],
+    "resume": null,
+    "model": "optional-serving-endpoint"
+  },
+  "background": false,
+  "stream": false
+}
+```
+
+`id` is the invocation identifier and idempotency key. `background` and `stream` are transport
+fields. Everything framework-specific belongs inside `input`. The browser generates a stable
+session ID in local storage; API clients should do the same. The Apps router cookie is only for
+sticky routing and is not authentication or application session state.
+
+## Code map
+
+| Change | File |
+| --- | --- |
+| Framework-native agent and `run_agent` | `agent/agent.py` |
+| Local tools | `agent/tools/` |
+| MCP servers | `agent/mcps.py` |
+| Managed runtime `invoke`/`recover` hooks and input/output translation | `runtime/adapter.py` |
+| `DurableAgentServer` construction and hook registration | `runtime/main.py` |
+| Browser and managed-state routes | `runtime/ui.py` |
+| Browser behavior | `ui/app.js` |
+
+Keep `agent/agent.py` runnable without runtime request or context types. If you bring an existing agent,
+put its framework-native execution in `run_agent`. The small `runtime/adapter.py` is the agent-author
+integration point: it translates the application payload, calls `run_agent`, emits runtime events, and
+shapes the response. Its `recover` hook calls the same `run_agent` with the original application input
+plus a developer instruction warning that the prior attempt may have partially completed because the
+Agents SDK does not expose checkpoint continuation.
+
+## State and recovery
+
+- Invocation state/events: in-memory in `ab dev`; Lakebase when `ab deploy` attaches a Runtime
+  Store.
+- Conversation transcript: in-process in `ab dev`; managed Session Store when bound, on `ab deploy`.
+- Long-term memory: off in `ab dev`; managed Memory Store when bound, on `ab deploy`.
+- OpenAI HITL `RunState`: process-local even with Session Store; it does not survive worker loss.
+- Recovery: replay the persisted application input against the same session.
+
+The adapter sends every translated framework event through `context.emit()` before delivery. OpenAI
+Agents SDK does not expose node-level checkpoint continuation, so side effects remain at-least-once
+and tools must be idempotent.
+
+## Tools
+
+`agent/tools/all_tools()` auto-imports tool modules. Add a decorated tool file rather than manually
+editing a registry. Approval tools must declare `needs_approval=True` and appear in
+`REQUIRE_APPROVAL`.

databricks_agentbricks/templates/agent-openai/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

databricks_agentbricks/templates/agent-openai/README.md

@@ -0,0 +1,143 @@
+# OpenAI Agents template
+
+An OpenAI Agents SDK agent served by `databricks_agentkit.DurableAgentServer`. The managed runtime keeps invocation state and
+events in memory during `ab dev`. Deployment attaches a persistent Runtime Store, so invocation
+state and events survive process loss and interrupted work can be recovered.
+
+The generated project separates portable agent execution from the managed HTTP protocol:
+
+```text
+client -> runtime/main.py -> runtime/adapter.py -> agent/agent.py:run_agent
+```
+
+- `agent/agent.py` owns the framework-native agent, sessions, tools, MCP lifetime, HITL state, and
+  `run_agent`.
+- `runtime/adapter.py` owns the agent-author integration hooks: runtime input/output translation plus
+  `invoke` and `recover`.
+- `runtime/main.py` constructs the server and registers those hooks.
+
+To bring an existing Agents SDK agent, keep its normal execution code in `agent/agent.py`, expose a
+`run_agent` function that returns the native streaming result, and make only the small payload/event
+mapping changes needed in `runtime/adapter.py`.
+
+## Run locally
+
+```bash
+ab dev
+```
+
+The API is available at `http://localhost:8000/api/invocations`. Every request supplies a UUID `id`.
+That ID is the invocation identifier and idempotency key. Agent-specific values live inside the
+opaque `input` object:
+
+```bash
+SESSION_ID=$(uuidgen)
+INVOCATION_ID=$(uuidgen)
+
+curl -sS http://localhost:8000/api/invocations \
+  -H 'Content-Type: application/json' \
+  -d "{\"id\":\"$INVOCATION_ID\",\"input\":{\"session_id\":\"$SESSION_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"What time is it? Use your tool.\"}]}}"
+```
+
+Reuse `SESSION_ID` for multi-turn conversation history. Generate a new `INVOCATION_ID` for each
+turn. Retrying the same request with the same invocation ID returns the persisted result; changing
+the request while reusing the ID returns `409`.
+
+## Invocation modes
+
+- Foreground: omit `background` and `stream`; the response contains the agent result under `output`.
+- Foreground streaming: set `stream: true`; the response is SSE backed by persisted events.
+- Background: set `background: true`; poll the returned `status_url`.
+- Background streaming: set both flags; the `202` response includes `status_url` and `events_url`.
+
+```bash
+INVOCATION_ID=$(uuidgen)
+curl -sN http://localhost:8000/api/invocations \
+  -H 'Content-Type: application/json' \
+  -d "{\"id\":\"$INVOCATION_ID\",\"input\":{\"session_id\":\"$SESSION_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Count to three.\"}]},\"stream\":true}"
+
+INVOCATION_ID=$(uuidgen)
+curl -sS http://localhost:8000/api/invocations \
+  -H 'Content-Type: application/json' \
+  -d "{\"id\":\"$INVOCATION_ID\",\"input\":{\"session_id\":\"$SESSION_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize durable agents.\"}]},\"background\":true}" | jq
+curl -sS "http://localhost:8000/api/invocations/$INVOCATION_ID" | jq
+```
+
+SSE records contain events translated by `runtime/adapter.py`: token `delta`s, completed `message`s,
+and HITL `interrupt`s. Replay from a cursor with
+`GET /api/invocations/{id}/events?after={sequence}`.
+
+## Human approval
+
+`send_message` requires approval. When output or the event stream contains an `interrupt`, submit a
+new invocation with the same application session:
+
+```json
+{
+  "id": "<new-uuid>",
+  "input": {
+    "session_id": "<same-session-id>",
+    "resume": {"decisions": [{"type": "approve"}]}
+  }
+}
+```
+
+The paused Agents SDK `RunState` is process-local. A managed Session Store preserves transcript
+history, but not a pending approval across restarts or replicas.
+
+## Crash recovery
+
+`runtime/main.py` always registers the adapter's `invoke` and `recover` hooks. Both call the same
+`agent.agent.run_agent` function. OpenAI Agents SDK does not currently expose LangGraph-style node
+checkpoints, so `recover` replays the original application input against the same session. The
+adapter prepends a developer instruction telling the agent that this is a recovery attempt and that
+some tool calls or external side effects may already have completed or may still be in progress.
+When deployment attaches a Runtime Store, invocation state and emitted events survive process loss
+and the runtime can call `recover` on a replacement worker. Without a Runtime Store, invocation state
+remains process-local and interrupted work is not automatically recovered. External side effects
+remain at-least-once and must be idempotent.
+
+## Chat app
+
+The browser UI is included by default. It generates a stable application session ID in local
+storage, places it inside each invocation's `input`, and generates a fresh invocation UUID per turn.
+Use `ab init --framework openai --disable-chat-app` for API-only output.
+
+## Configure and deploy
+
+- Change the model, instructions, tools, and framework-native execution in `agent/agent.py`.
+- Change `runtime/adapter.py` only to map a different application input/output contract.
+- Add local tools under `agent/tools/`; modules are auto-discovered.
+- Add MCP servers in `agent/mcps.py` or with `ab tools add mcp`.
+- Bind long-term memory with `ab memory bind <store>`.
+- Bind durable transcript history with `ab sessions bind <store>`.
+
+```bash
+ab --profile <profile> deploy agent-openai --source .
+```
+
+When deployment provisions a dedicated Runtime Store, only the app-owned
+`databricks_agentkit_runtime_<hash>` schema and runtime tables are added. Managed Runtime Store
+deployments use their own default schema.
+
+The `__Host-databricks-app-router` cookie may be supplied independently for sticky replica routing.
+It is not authentication and is not used as the template's application session ID.
+
+# Request-user authorization
+
+Declared tools in `agent.toml` select `auth = "user"` or `auth = "app"`; legacy missing auth
+continues to use the application/default identity. Deployed user tools require the request resolver
+and never fall back to application credentials. Model, memory-service, session-service, and custom
+MCP server credentials are unchanged.
+
+`runtime/main.py` derives the invocation policy after `configure()`. The runtime adapter namespaces
+public session IDs and actor values for the request owner, then passes only `workspace_client_for`
+to the framework-native agent. Internal session keys are never returned to clients.
+
+User-policy invocations use the existing Runtime for synchronous, streaming, and background calls,
+including status polling, event replay, and invocation-ID idempotency. The Runtime Store persists no
+credential; request-user authentication remains process-local for the active first attempt. A
+replacement attempt fails with `MCP_USER_AUTH_RECOVERY_UNSUPPORTED` before agent code runs. Approval
+interruptions remain unsupported and fail with `MCP_USER_AUTH_HITL_UNSUPPORTED`, without storing a
+credential-bearing `RunState`. Existing namespaced memory and conversation-store behavior is
+unchanged; OBO does not add another saver.

databricks_agentbricks/templates/agent-openai/agent/agent.py

@@ -0,0 +1,205 @@
+import asyncio
+import logging
+import os
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager, suppress
+from typing import Any
+
+from agents import Agent, Runner, RunResultStreaming, RunState
+from agents.mcp import MCPServerManager
+from databricks.sdk import WorkspaceClient
+from databricks_openai import AsyncDatabricksOpenAI
+
+from agent.mcps import build_mcp_servers
+
+# Importing the tools package auto-registers every tool module.
+from agent.tools import all_tools
+from databricks_agentkit import workspace_client, workspace_headers
+from databricks_agentkit.openai import (
+    configure_tracing,
+    genie_tools,
+    mcp_servers,
+    memory_tools,
+    session_store,
+    start_trace,
+)
+from databricks_agentkit.runtime.auth import AuthError
+
+logger = logging.getLogger(__name__)
+
+# A Unity Catalog AI Gateway model service, served from the `system.ai` schema and queried through
+# the gateway (see `use_ai_gateway=True` in configure()). Swap for any `system.ai.*` model service
+# your workspace exposes — the demo chat app's picker lists what's available.
+MODEL = "system.ai.claude-sonnet-4-5"
+
+# Tools that require human approval before they run. Add a tool's name here and the agent pauses when
+# the model calls it, emitting an `interrupt` event; the client resumes by sending `resume` with the
+# same session id. The tools declare `needs_approval=True` themselves (see agent/tools/); this set is
+# how the runtime knows which pending calls to surface. Empty it to disable approval gating.
+REQUIRE_APPROVAL = {"send_message"}
+
+# OpenAI Sessions persist transcript history, not a paused RunState. Keep pending approvals local.
+_pending_runs: dict[str, RunState] = {}
+
+
+def configure() -> None:
+    """Wire up global state; call once at server startup (not at import)."""
+    _check_databricks_auth()
+    from agents import set_default_openai_api, set_default_openai_client
+
+    # use_ai_gateway routes to the Unity Catalog AI Gateway (`<host>/ai-gateway/mlflow/v1`), so
+    # `MODEL` is a `system.ai.*` model name rather than a serving-endpoint name.
+    set_default_openai_client(
+        AsyncDatabricksOpenAI(
+            workspace_client=workspace_client(),
+            default_headers=workspace_headers() or None,
+            use_ai_gateway=True,
+        )
+    )
+    set_default_openai_api("chat_completions")
+    configure_tracing()
+
+
+def _check_databricks_auth() -> None:
+    """Fail fast at startup with a clear message if Databricks auth isn't configured.
+
+    Without this, a missing/invalid profile only surfaces on the first model call — as a generic SDK
+    error buried in a request traceback. Resolving a WorkspaceClient here validates the same config
+    the model client uses, so the failure is immediate and actionable.
+    """
+    try:
+        workspace_client()
+    except Exception as e:
+        profile = os.getenv("DATABRICKS_CONFIG_PROFILE")
+        target = (
+            f"profile {profile!r}" if profile else "the DEFAULT profile / DATABRICKS_HOST+TOKEN"
+        )
+        raise RuntimeError(
+            f"Databricks auth is not configured — the agent can't call the model. Tried {target}.\n"
+            "Fix one of:\n"
+            "  • set DATABRICKS_CONFIG_PROFILE in .env to a profile from `databricks auth profiles`, or\n"
+            "  • run `databricks auth login --profile <name>` to create one, or\n"
+            "  • set DATABRICKS_HOST and DATABRICKS_TOKEN in .env.\n"
+            f"(underlying error: {e})"
+        ) from e
+
+
+def create_agent(
+    actor: str,
+    mcp=None,
+    model: str | None = None,
+    *,
+    workspace_client_for: Callable[[str], WorkspaceClient] | None = None,
+) -> Agent:
+    """Build the OpenAI Agents SDK agent: tools, memory, MCP servers, and model."""
+    return Agent(
+        name="Agent",
+        instructions="You are a helpful assistant.",
+        model=model or MODEL,
+        tools=[
+            *all_tools(),
+            *memory_tools(actor),
+            *genie_tools(workspace_client_for=workspace_client_for),
+        ],
+        mcp_servers=mcp or [],
+    )
+
+
+def resume_agent(session_id: str, resume: dict[str, Any]) -> RunState:
+    """Apply human decisions to a paused run and return the native RunState."""
+    state = _pending_runs.pop(session_id, None)
+    if state is None:
+        raise RuntimeError(
+            "No paused run for this session. HITL pauses are in-process only, so a restart or a "
+            "different replica loses them; retry the turn."
+        )
+    decisions = resume.get("decisions") or []
+    for decision, item in zip(decisions, state.get_interruptions(), strict=False):
+        if decision.get("type") == "approve":
+            state.approve(item)
+        else:
+            state.reject(item, rejection_message=decision.get("message"))
+    return state
+
+
+@asynccontextmanager
+async def run_agent(
+    agent_input: list[Any] | RunState,
+    *,
+    session_id: str,
+    actor: str | None = None,
+    model: str | None = None,
+    workspace_client_for: Callable[[str], WorkspaceClient] | None = None,
+) -> AsyncIterator[RunResultStreaming]:
+    """Run the agent and expose its native streaming result.
+
+    This is the framework-native entrypoint. It has no dependency on Agent Bricks request or context types,
+    so it can be called from another server, a notebook, or a test harness.
+    """
+    actor = actor or session_id
+    auth_kwargs = {"workspace_client_for": workspace_client_for} if workspace_client_for else {}
+    servers = await mcp_servers(build_mcp_servers(), **auth_kwargs)
+    async with MCPServerManager(servers) as manager:
+        for server, error in manager.errors.items():
+            if getattr(server, "_agentbricks_request_user", False) is True or isinstance(
+                error, AuthError
+            ):
+                raise error
+        active_servers = []
+        for server in manager.active_servers:
+            tool_filter = server.tool_filter
+            try:
+                server.tool_filter = None
+                server.cache_tools_list = True
+                async with asyncio.timeout(manager.connect_timeout_seconds):
+                    await server.list_tools()
+            except Exception as error:
+                if getattr(server, "_agentbricks_request_user", False) is True or isinstance(
+                    error, AuthError
+                ):
+                    raise
+                logger.warning(
+                    "Failed to list tools from MCP server %r; continuing without it.",
+                    server.name,
+                    exc_info=True,
+                )
+            else:
+                active_servers.append(server)
+            finally:
+                server.tool_filter = tool_filter
+
+        agent = create_agent(
+            actor,
+            active_servers,
+            model=model,
+            workspace_client_for=workspace_client_for,
+        )
+        with start_trace(name="invoke", inputs=agent_input, session_id=session_id) as span:
+            if isinstance(agent_input, RunState):
+                result = Runner.run_streamed(agent, agent_input)
+            else:
+                result = Runner.run_streamed(
+                    agent,
+                    agent_input,
+                    session=session_store(session_id, actor),
+                )
+
+            try:
+                yield result
+            finally:
+                if workspace_client_for is not None and not result.is_complete:
+                    result.cancel()
+                    with suppress(asyncio.CancelledError, Exception):
+                        async for _ in result.stream_events():
+                            pass
+
+            if result.interruptions:
+                if workspace_client_for is not None:
+                    raise AuthError(
+                        "MCP_USER_AUTH_HITL_UNSUPPORTED",
+                        "Request-user invocations do not support paused approvals.",
+                        400,
+                    )
+                _pending_runs[session_id] = result.to_state()
+            if span is not None:
+                span.set_outputs({"output": result.final_output})

databricks_agentbricks/templates/agent-openai/agent/mcps.py

@@ -0,0 +1,28 @@
+"""MCP servers to offer the agent — this is where you configure them.
+
+Empty by default: the agent runs with only the MCP servers declared in ``agent.toml``. Add servers
+to ``build_mcp_servers`` to offer more; ``agent.py`` joins them with the ``agent.toml`` servers and
+omits any that fail to connect or list tools.
+"""
+
+from databricks_openai.agents import McpServer
+
+
+def build_mcp_servers() -> list[McpServer]:
+    """Return the MCP servers to offer the agent. Empty by default — add your own.
+
+    Example (a Databricks-managed MCP, authed as the app service principal)::
+
+        from databricks.sdk import WorkspaceClient
+
+        client = WorkspaceClient()
+        host = client.config.host.rstrip("/")
+        return [
+            McpServer(
+                url=f"{host}/api/2.0/mcp/functions/system/ai",
+                name="system-ai",
+                workspace_client=client,
+            ),
+        ]
+    """
+    return []

databricks_agentbricks/templates/agent-openai/agent/tools/__init__.py

@@ -0,0 +1,24 @@
+"""Agent tools package.
+
+Every module here is auto-imported, and every OpenAI Agents SDK ``FunctionTool`` it defines (via the
+``@function_tool`` decorator) is collected by ``all_tools()``. Drop a new ``*.py`` into this folder
+with a ``@function_tool``-decorated function and it's picked up automatically — no wiring to edit.
+``create_agent`` uses ``all_tools()``.
+"""
+
+import importlib
+import inspect
+import pkgutil
+
+from agents import FunctionTool
+
+
+def all_tools() -> list[FunctionTool]:
+    """Every FunctionTool defined across the modules in this package."""
+    tools: list[FunctionTool] = []
+    for module in pkgutil.iter_modules(__path__):
+        mod = importlib.import_module(f"{__name__}.{module.name}")
+        for _, obj in inspect.getmembers(mod, lambda o: isinstance(o, FunctionTool)):
+            if obj not in tools:  # a tool imported into several modules is collected once
+                tools.append(obj)
+    return tools

databricks_agentbricks/templates/agent-openai/agent/tools/sample_tool.py

@@ -0,0 +1,15 @@
+"""Sample tool. A working example — add your own tools as new files in this package.
+
+Decorate a function with ``@function_tool`` (OpenAI Agents SDK) and it becomes an agent tool; the
+package auto-collects it via ``all_tools()``, which ``create_agent`` uses.
+"""
+
+from datetime import datetime
+
+from agents import function_tool
+
+
+@function_tool
+def get_current_time() -> str:
+    """Get the current date and time."""
+    return datetime.now().isoformat()

databricks_agentbricks/templates/agent-openai/agent/tools/send_message.py

@@ -0,0 +1,18 @@
+"""A side-effecting sample tool, gated by human approval.
+
+Unlike ``get_current_time`` (a harmless read), this tool stands in for an action with real
+consequences — sending a message. ``needs_approval=True`` makes the Agents SDK pause before it runs
+and surface a pending approval; the runtime relays that as an ``interrupt`` event and resumes on an
+approve/reject decision (its name is also listed in ``REQUIRE_APPROVAL`` in ``agent/agent.py``). Swap
+the body for a real send; the approval gate is what the template is demonstrating.
+"""
+
+from agents import function_tool
+
+
+@function_tool(needs_approval=True)
+def send_message(recipient: str, body: str) -> str:
+    """Send a message to a recipient. Use when the user asks to notify or message someone."""
+    # A real implementation would call an email/Slack/SMS API here. The point of this template is the
+    # human-approval gate in front of it (needs_approval=True), not the delivery.
+    return f"Message sent to {recipient}: {body}"

databricks_agentbricks/templates/agent-openai/app.yaml

@@ -0,0 +1,15 @@
+command: ["uv", "run", "start-server"]
+# databricks apps listen by default on port 8000
+#
+# Agent Bricks injects the deployed Runtime Store endpoint. The Agents SDK session remains
+# in-process unless a managed Session Store is bound. Tracing is bound with `ab tracing bind
+# --experiment-name <path>` (ab deploy then wires the env below; `ab dev` traces to a local
+# MLflow server). To set a deployment's tracing env by hand instead:
+#
+# env:
+#   # Tracing (set a destination + an experiment). Destination: MLFLOW_TRACKING_URI or
+#   # MLFLOW_TRACING_DESTINATION. Experiment: MLFLOW_EXPERIMENT_ID or MLFLOW_EXPERIMENT_NAME.
+#   - name: MLFLOW_TRACKING_URI
+#     value: "databricks"
+#   - name: MLFLOW_EXPERIMENT_ID
+#     value: "<experiment-id>"