Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

refactor: update ToolManager to initialize in lifespans.py and use ToolBase for backend tool registration (#6375)

Joaquin Corominae70300ed1c08
diff --git a/marimo/_ai/_convert.py b/marimo/_ai/_convert.py
index 7ec1f8f5e8..95a3709ab9 100644
--- a/marimo/_ai/_convert.py
+++ b/marimo/_ai/_convert.py
@@ -17,7 +17,7 @@ from marimo._ai._types import (
TextPart,
ToolInvocationPart,
)
-from marimo._server.ai.tools.types import Tool
+from marimo._server.ai.tools.types import ToolDefinition
if TYPE_CHECKING:
from anthropic.types import ( # type: ignore[import-not-found]
@@ -557,7 +557,9 @@ def convert_to_ai_sdk_messages(
# Tool conversions
-def convert_to_openai_tools(tools: list[Tool]) -> list[dict[str, Any]]:
+def convert_to_openai_tools(
+ tools: list[ToolDefinition],
+) -> list[dict[str, Any]]:
return [
{
"type": "function",
@@ -571,7 +573,9 @@ def convert_to_openai_tools(tools: list[Tool]) -> list[dict[str, Any]]:
]
-def convert_to_anthropic_tools(tools: list[Tool]) -> list[dict[str, Any]]:
+def convert_to_anthropic_tools(
+ tools: list[ToolDefinition],
+) -> list[dict[str, Any]]:
return [
{
"name": tool.name,
@@ -582,7 +586,9 @@ def convert_to_anthropic_tools(tools: list[Tool]) -> list[dict[str, Any]]:
]
-def convert_to_google_tools(tools: list[Tool]) -> list[dict[str, Any]]:
+def convert_to_google_tools(
+ tools: list[ToolDefinition],
+) -> list[dict[str, Any]]:
return [
{
"function_declarations": [
diff --git a/marimo/_ai/_tools/base.py b/marimo/_ai/_tools/base.py
index a0e9a8d8cb..7a97352e06 100644
--- a/marimo/_ai/_tools/base.py
+++ b/marimo/_ai/_tools/base.py
@@ -22,9 +22,16 @@ from starlette.applications import (
)
from marimo._ai._tools.utils.exceptions import ToolExecutionError
+from marimo._config.config import CopilotMode
+from marimo._server.ai.tools.types import (
+ FunctionArgs,
+ ToolDefinition,
+ ValidationFunction,
+)
from marimo._server.api.deps import AppStateBase
from marimo._server.sessions import Session, SessionManager
from marimo._types.ids import SessionId
+from marimo._utils.dataclass_to_openapi import PythonTypeToOpenAPI
from marimo._utils.parse_dataclass import parse_raw
ArgsT = TypeVar("ArgsT")
@@ -85,8 +92,8 @@ class ToolBase(Generic[ArgsT, OutT], ABC):
"""
# Override in subclass, or rely on fallbacks below
- name: str | None = None
- description: str | None = None
+ name: str = ""
+ description: str = ""
Args: type[ArgsT]
Output: type[OutT]
context: ToolContext
@@ -114,11 +121,11 @@ class ToolBase(Generic[ArgsT, OutT], ABC):
self.context = context
# get name from class name
- if self.name is None:
+ if self.name == "":
self.name = self._to_snake_case(self.__class__.__name__)
# get description from class docstring
- if self.description is None:
+ if self.description == "":
self.description = (self.__class__.__doc__ or "").strip()
async def __call__(self, args: ArgsT) -> OutT:
@@ -201,13 +208,30 @@ class ToolBase(Generic[ArgsT, OutT], ABC):
return handler
- def as_backend_tool(self) -> None:
- """Convert the tool to a backend tool."""
- # TODO: implement
- ...
+ def as_backend_tool(
+ self, mode: list[CopilotMode]
+ ) -> tuple[ToolDefinition, ValidationFunction]:
+ """Convert the tool to a ToolDefinition for backend use."""
- # helpers
+ # convert the args to python dict
+ converter = PythonTypeToOpenAPI(name_overrides={}, camel_case=False)
+ converted_args = converter.convert(self.Args, processed_classes={})
+
+ # get tool_definition
+ tool_definition = ToolDefinition(
+ name=self.name,
+ description=self.description,
+ parameters=converted_args,
+ source="backend",
+ mode=mode,
+ )
+ # get validation_function
+ validation_function = self._create_validation_function(self.Args)
+
+ return tool_definition, validation_function
+
+ # helpers
def _coerce_args(self, args: Any) -> ArgsT: # type: ignore[override]
"""If Args is a dataclass and args is a dict, construct it; else pass through."""
if dataclasses.is_dataclass(args):
@@ -241,3 +265,20 @@ class ToolBase(Generic[ArgsT, OutT], ABC):
def _error_context(self, _args: Any) -> dict[str, Any]:
return {}
+
+ def _create_validation_function(
+ self, args_type: type[Any]
+ ) -> ValidationFunction:
+ """Create a validator using parse_raw against the tool's Args type."""
+
+ def validation_function(
+ arguments: FunctionArgs,
+ ) -> Optional[tuple[bool, str]]:
+ try:
+ # Will raise on bad types/required fields
+ parse_raw(arguments, args_type)
+ return True, ""
+ except Exception as e:
+ return False, f"Invalid arguments: {e}"
+
+ return validation_function
diff --git a/marimo/_server/ai/config.py b/marimo/_server/ai/config.py
index 549f0c240f..13d05fa996 100644
--- a/marimo/_server/ai/config.py
+++ b/marimo/_server/ai/config.py
@@ -20,7 +20,7 @@ from marimo._config.config import (
from marimo._server.ai.constants import DEFAULT_MAX_TOKENS, DEFAULT_MODEL
from marimo._server.ai.ids import AiModelId
from marimo._server.ai.tools.tool_manager import get_tool_manager
-from marimo._server.ai.tools.types import Tool
+from marimo._server.ai.tools.types import ToolDefinition
from marimo._server.api.status import HTTPStatus
@@ -34,7 +34,7 @@ class AnyProviderConfig:
ca_bundle_path: Optional[str] = None
client_pem: Optional[str] = None
extra_headers: Optional[dict[str, str]] = None
- tools: Optional[list[Tool]] = None
+ tools: Optional[list[ToolDefinition]] = None
def __post_init__(self) -> None:
# Only include tools if they are available
@@ -186,8 +186,12 @@ class AnyProviderConfig:
return os.environ.get(key)
-def _get_tools(mode: CopilotMode) -> list[Tool]:
- tool_manager = get_tool_manager()
+def _get_tools(mode: CopilotMode) -> list[ToolDefinition]:
+ try:
+ tool_manager = get_tool_manager()
+ except ValueError:
+ # ToolManager may not be initialized in some tests or non-server contexts
+ return []
return tool_manager.get_tools_for_mode(mode)
diff --git a/marimo/_server/ai/tools/backend_tools/sample_tool.py b/marimo/_server/ai/tools/backend_tools/sample_tool.py
deleted file mode 100644
index 7a01d4fcd1..0000000000
--- a/marimo/_server/ai/tools/backend_tools/sample_tool.py
+++ /dev/null
@@ -1,262 +0,0 @@
-# Copyright 2024 Marimo. All rights reserved.
-"""
-SAMPLE BACKEND TOOL - This file is commented out as an example.
-
-This file demonstrates how to create a backend tool for the marimo AI system.
-Backend tools are functions that run on the server and can be called by the AI
-during conversations.
-
-To create your own backend tool:
-1. Copy this file and rename it
-2. Uncomment the code
-3. Modify the tool definition and handler function
-4. Import it in tools.py
-
-Backend tools are useful for:
-- Server-side operations that require access to the filesystem
-- Database queries
-- API calls to external services
-- System information gathering
-- File operations
-
-##################################################################################
-
- To use the tools below:
- 1. Uncomment the code below
- 2. Add the tools to `tools.py`
- 3. Restart the marimo server
-
- The AI will then be able to use your tool in conversations!
-"""
-
-# from __future__ import annotations
-
-# from typing import Any, Optional, TypedDict
-
-# from marimo import _loggers
-# from marimo._server.ai.tools.types import BackendTool, Tool
-
-# LOGGER = _loggers.marimo_logger()
-
-
-# class SampleToolArgs(TypedDict):
-# message: str
-# count: int
-# uppercase: bool
-
-
-# class SampleTool(BackendTool[SampleToolArgs]):
-# """A sample backend tool that processes text messages."""
-
-# @property
-# def tool(self) -> Tool:
-# return Tool(
-# name="sample_backend_tool",
-# description="A sample backend tool that processes text messages. This demonstrates how to create backend tools.",
-# parameters={
-# "type": "object",
-# "properties": {
-# "message": {
-# "type": "string",
-# "description": "The message to process",
-# },
-# "count": {
-# "type": "integer",
-# "description": "Number of times to repeat the message",
-# "default": 1,
-# "minimum": 1,
-# "maximum": 10,
-# },
-# "uppercase": {
-# "type": "boolean",
-# "description": "Whether to convert the message to uppercase",
-# "default": False,
-# },
-# },
-# "required": ["message"],
-# },
-# source="backend", # This indicates it's a backend tool
-# mode=["ask", "chat"], # Available in both ask and chat modes
-# )
-
-# def handler(self, arguments: SampleToolArgs) -> dict[str, Any]:
-# """
-# Handle the sample tool execution.
-
-# Args:
-# arguments: The validated arguments passed to the tool
-
-# Returns:
-# Dictionary containing the tool's response
-# """
-# try:
-# # Extract parameters with defaults
-# message = arguments["message"]
-# count = arguments.get("count", 1)
-# uppercase = arguments.get("uppercase", False)
-
-# # Process the message
-# processed_message = message.upper() if uppercase else message
-# result = [processed_message] * count
-
-# # Return structured response
-# return {
-# "success": True,
-# "original_message": message,
-# "processed_messages": result,
-# "settings": {"count": count, "uppercase": uppercase},
-# "total_characters": sum(len(msg) for msg in result),
-# }
-
-# except Exception as e:
-# # Handle errors gracefully
-# LOGGER.error(f"Error in sample tool: {str(e)}")
-# return {
-# "success": False,
-# "error": f"Tool execution failed: {str(e)}",
-# }
-
-# def validator(
-# self, arguments: SampleToolArgs
-# ) -> Optional[tuple[bool, str]]:
-# """
-# Validate parameters for the sample tool.
-
-# This function is optional but recommended for robust parameter validation.
-
-# Args:
-# arguments: The arguments to validate
-
-# Returns:
-# Tuple of (is_valid, error_message). If is_valid is True, error_message is empty.
-# """
-# # Define valid parameter names and their expected types
-# valid_params = {
-# "message": str,
-# "count": int,
-# "uppercase": bool,
-# }
-
-# # Check for required parameters
-# required_params = {"message"}
-# missing_params = required_params - set(arguments.keys())
-# if missing_params:
-# error_msg = (
-# f"Missing required parameters: {', '.join(missing_params)}"
-# )
-# return False, error_msg
-
-# # Check for unknown parameters
-# unknown_params = set(arguments.keys()) - set(valid_params.keys())
-# if unknown_params:
-# error_msg = f"Unknown parameters: {', '.join(unknown_params)}. Valid parameters are: {', '.join(valid_params.keys())}"
-# return False, error_msg
-
-# # Validate parameter types
-# for param_name, param_value in arguments.items():
-# expected_type = valid_params[param_name]
-# if not isinstance(param_value, expected_type):
-# error_msg = f"Parameter '{param_name}' must be of type {expected_type.__name__}, got {type(param_value).__name__}"
-# return False, error_msg
-
-# # Custom validation logic
-# if "count" in arguments and arguments["count"] < 1:
-# return False, "Parameter 'count' must be greater than 0"
-
-# if "count" in arguments and arguments["count"] > 10:
-# return False, "Parameter 'count' must be 10 or less"
-
-# # All validation checks passed
-# return True, ""
-
-
-# # Advanced tool example
-
-
-# class FileInfoToolArgs(TypedDict):
-# pattern: str
-# include_hidden: bool
-
-
-# class FileInfoTool(BackendTool[FileInfoToolArgs]):
-# """A backend tool that gets information about files in the current working directory."""
-
-# @property
-# def tool(self) -> Tool:
-# return Tool(
-# name="get_file_info",
-# description="Get information about files in the current working directory. Only works on the server.",
-# parameters={
-# "type": "object",
-# "properties": {
-# "pattern": {
-# "type": "string",
-# "description": "File pattern to match (e.g., '*.py', '*.md')",
-# "default": "*",
-# },
-# "include_hidden": {
-# "type": "boolean",
-# "description": "Whether to include hidden files",
-# "default": False,
-# },
-# },
-# "required": [],
-# },
-# source="backend",
-# mode=["ask", "chat"],
-# )
-
-# def handler(self, arguments: FileInfoToolArgs) -> dict[str, Any]:
-# """Get file information from the server's file system."""
-# import glob
-# import os
-# from pathlib import Path
-
-# try:
-# pattern = arguments.get("pattern", "*")
-# include_hidden = arguments.get("include_hidden", False)
-
-# # Get current working directory
-# cwd = os.getcwd()
-
-# # Find matching files
-# files = glob.glob(pattern, recursive=False)
-
-# # Filter hidden files if requested
-# if not include_hidden:
-# files = [f for f in files if not f.startswith(".")]
-
-# # Get file info
-# file_info = []
-# for file_path in files[:20]: # Limit to 20 files
-# try:
-# path = Path(file_path)
-# stat = path.stat()
-# file_info.append(
-# {
-# "name": path.name,
-# "size": stat.st_size,
-# "is_file": path.is_file(),
-# "is_dir": path.is_dir(),
-# "modified": stat.st_mtime,
-# }
-# )
-# except Exception:
-# continue
-
-# return {
-# "success": True,
-# "working_directory": cwd,
-# "pattern": pattern,
-# "files_found": len(file_info),
-# "files": file_info,
-# }
-
-# except Exception as e:
-# return {"success": False, "error": str(e)}
-
-# def validator(
-# self, arguments: FileInfoToolArgs
-# ) -> Optional[tuple[bool, str]]:
-# del arguments
-# return None
diff --git a/marimo/_server/ai/tools/tool_manager.py b/marimo/_server/ai/tools/tool_manager.py
index c773f1ab2d..4adbfefa6d 100644
--- a/marimo/_server/ai/tools/tool_manager.py
+++ b/marimo/_server/ai/tools/tool_manager.py
@@ -3,14 +3,23 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any, Callable, Optional
+from starlette.applications import (
+ Starlette, # noqa: TCH002 - required at runtime
+)
+
from marimo import _loggers
+from marimo._ai._tools.base import ToolBase, ToolContext
+from marimo._ai._tools.tools.cells import (
+ GetCellRuntimeData,
+ GetLightweightCellMap,
+)
+from marimo._ai._tools.tools.notebooks import GetActiveNotebooks
from marimo._config.config import CopilotMode
from marimo._config.manager import get_default_config_manager
from marimo._server.ai.tools.types import (
- BackendTool,
FunctionArgs,
- Tool,
- ToolResult,
+ ToolCallResult,
+ ToolDefinition,
ToolSource,
ValidationFunction,
)
@@ -27,11 +36,12 @@ LOGGER = _loggers.marimo_logger()
class ToolManager:
"""Centralized manager for backend and frontend tools, with dynamic MCP tool access."""
- def __init__(self) -> None:
+ def __init__(self, app: Starlette) -> None:
"""Initialize the tool manager."""
- self._tools: dict[str, Tool] = {}
+ self._tools: dict[str, ToolDefinition] = {}
self._backend_handlers: dict[str, Callable[[FunctionArgs], Any]] = {}
self._validation_functions: dict[str, ValidationFunction] = {}
+ self.app: Starlette = app
# TODO: this may be stale if the config is updated after the tool manager is created
self._config = get_default_config_manager(
@@ -42,24 +52,31 @@ class ToolManager:
)
# Add backend tools here
- # backend_tools = [SampleTool()]
- # for tool in backend_tools:
- # self.register_backend_tool(tool)
-
- def register_backend_tool(self, tool: BackendTool[Any]) -> None:
+ # Backend tools MUST BE DEFINED in:
+ # - marimo._ai._tools.tools.*
+ tool_context = ToolContext(app=self.app)
+
+ backend_tools: list[ToolBase[Any, Any]] = [
+ GetActiveNotebooks(tool_context),
+ GetCellRuntimeData(tool_context),
+ GetLightweightCellMap(tool_context),
+ ]
+ for tool in backend_tools:
+ self.register_backend_tool(tool)
+
+ def register_backend_tool(self, tool: ToolBase[Any, Any]) -> None:
"""Register a backend tool with its handler function and optional validator."""
- tool_definition = tool.tool
- if tool_definition.source != "backend":
- raise ValueError("Tool source must be 'backend'")
-
- name = tool_definition.name
+ name = tool.name
+ tool_definition, validation_function = tool.as_backend_tool(
+ mode=["ask"]
+ )
self._tools[name] = tool_definition
- self._backend_handlers[name] = tool.handler
- self._validation_functions[name] = tool.validator
+ self._backend_handlers[name] = tool.__call__
+ self._validation_functions[name] = validation_function
LOGGER.debug(f"Registered backend tool: {name}")
- def register_frontend_tool(self, tool: Tool) -> None:
+ def register_frontend_tool(self, tool: ToolDefinition) -> None:
"""Register a frontend tool (definition only - no handler or validator needed)."""
if tool.source != "frontend":
raise ValueError("Tool source must be 'frontend'")
@@ -67,21 +84,21 @@ class ToolManager:
self._tools[tool.name] = tool
LOGGER.debug(f"Registered frontend tool: {tool.name}")
- def get_all_tools(self) -> list[Tool]:
+ def get_all_tools(self) -> list[ToolDefinition]:
"""Get all available frontend, backend, and MCP tools."""
local_tools = list(self._tools.values())
mcp_tools = self.list_mcp_tools()
all_tools = local_tools + mcp_tools
return all_tools
- def get_tools_for_mode(self, mode: CopilotMode) -> list[Tool]:
+ def get_tools_for_mode(self, mode: CopilotMode) -> list[ToolDefinition]:
"""Get all tools available for a specific mode."""
all_tools = self.get_all_tools()
return [tool for tool in all_tools if mode in tool.mode]
def get_tool(
self, name: str, source: Optional[ToolSource] = None
- ) -> Optional[Tool]:
+ ) -> Optional[ToolDefinition]:
"""Get tool definition by name."""
if source:
if source == "backend":
@@ -145,7 +162,7 @@ class ToolManager:
return True, ""
- def list_mcp_tools(self) -> list[Tool]:
+ def list_mcp_tools(self) -> list[ToolDefinition]:
"""Get all MCP tools from the MCP client."""
if not self._enable_mcp_tools:
return []
@@ -161,7 +178,7 @@ class ToolManager:
LOGGER.error(f"Failed to get MCP tools: {str(e)}")
return []
- def convert_mcp_tool(self, mcp_tool: MCPRawTool) -> Tool:
+ def convert_mcp_tool(self, mcp_tool: MCPRawTool) -> ToolDefinition:
"""Convert an MCP tool to marimo Tool format."""
# Get namespaced name from meta field (meta is dict[str, Any] | None)
meta = mcp_tool.meta or {}
@@ -170,7 +187,7 @@ class ToolManager:
)
# Convert to marimo Tool format
- return Tool(
+ return ToolDefinition(
name=namespaced_name or mcp_tool.name,
description=mcp_tool.description or "No description available",
parameters=mcp_tool.inputSchema,
@@ -181,12 +198,12 @@ class ToolManager:
async def invoke_tool(
self, tool_name: str, arguments: FunctionArgs
- ) -> ToolResult:
+ ) -> ToolCallResult:
"""Invoke a tool by name and return the result."""
tool = self.get_tool(tool_name)
if not tool:
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name,
result=None,
error=f"Internal error: Tool '{tool_name}' not found.",
@@ -195,7 +212,7 @@ class ToolManager:
if tool.source == "frontend":
system_error = f"Frontend tool '{tool_name}' cannot be invoked in the backend. Frontend tools must be executed in the client."
LOGGER.error(system_error)
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name,
result=None,
error=f"Internal error: Tool '{tool_name}' is a frontend tool and cannot be executed on the server.",
@@ -208,7 +225,7 @@ class ToolManager:
self.validate_backend_tool_arguments(tool_name, arguments)
)
if not is_valid:
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name,
result=None,
error=f"Invalid arguments for tool '{tool_name}': {validation_error}",
@@ -219,13 +236,13 @@ class ToolManager:
f"No handler found for backend tool '{tool_name}'."
)
LOGGER.error(system_error)
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name,
result=None,
error=f"Internal error: Tool '{tool_name}' cannot be invoked.",
)
result = await self._call_handler(handler, arguments)
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name, result=result, error=None
)
@@ -251,7 +268,7 @@ class ToolManager:
LOGGER.error(
f"MCP tool '{tool_name}' returned error: {error_text}"
)
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name, result=None, error=error_text
)
@@ -262,7 +279,7 @@ class ToolManager:
if success_messages
else "MCP tool completed successfully with no text output"
)
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name, result=result_text, error=None
)
@@ -270,7 +287,7 @@ class ToolManager:
# Unknown tool source
system_error = f"Unknown tool source: {tool.source} for tool {tool_name}. Supported sources are: backend, frontend, mcp."
LOGGER.error(system_error)
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name,
result=None,
error=f"Internal error: Tool configuration error for tool {tool_name}.",
@@ -279,7 +296,7 @@ class ToolManager:
except Exception as e:
error_message = f"Error invoking tool '{tool_name}': {str(e)}"
LOGGER.error(error_message)
- return ToolResult(
+ return ToolCallResult(
tool_name=tool_name, result=None, error=str(error_message)
)
@@ -322,12 +339,18 @@ class ToolManager:
_TOOL_MANAGER: Optional[ToolManager] = None
-def get_tool_manager() -> ToolManager:
- """Get the global tool manager instance, initializing it if needed."""
+def setup_tool_manager(app: Starlette) -> None:
+ """Setup the tool manager with the app."""
global _TOOL_MANAGER
if _TOOL_MANAGER is None:
- _TOOL_MANAGER = ToolManager()
+ _TOOL_MANAGER = ToolManager(app)
LOGGER.info(
f"ToolManager initialized with {len(_TOOL_MANAGER._tools)} backend/frontend tools"
)
+
+
+def get_tool_manager() -> ToolManager:
+ """Get the global tool manager instance."""
+ if _TOOL_MANAGER is None:
+ raise ValueError("ToolManager not initialized")
return _TOOL_MANAGER
diff --git a/marimo/_server/ai/tools/types.py b/marimo/_server/ai/tools/types.py
index 8902d88c9d..291b2f10e9 100644
--- a/marimo/_server/ai/tools/types.py
+++ b/marimo/_server/ai/tools/types.py
@@ -1,8 +1,7 @@
# Copyright 2025 Marimo. All rights reserved.
-from abc import ABC, abstractmethod
from dataclasses import dataclass
-from typing import Any, Callable, Generic, Literal, Optional, TypeVar
+from typing import Any, Callable, Literal, Optional, TypeVar
from marimo._config.config import CopilotMode
@@ -14,7 +13,7 @@ ToolSource = Literal["mcp", "backend", "frontend"]
@dataclass
-class Tool:
+class ToolDefinition:
"""Tool definition compatible with ai-sdk-ui format."""
name: str
@@ -28,7 +27,7 @@ class Tool:
@dataclass
-class ToolResult:
+class ToolCallResult:
"""Represents the result of a tool invocation."""
tool_name: str
@@ -37,26 +36,3 @@ class ToolResult:
T = TypeVar("T")
-
-
-class BackendTool(ABC, Generic[T]):
- """Base class for all backend tools."""
-
- @property
- @abstractmethod
- def tool(self) -> Tool:
- """The tool definition."""
-
- @abstractmethod
- def handler(self, arguments: T) -> dict[str, Any]:
- """The handler function for the tool."""
-
- @abstractmethod
- def validator(self, arguments: T) -> Optional[tuple[bool, str]]:
- """The validator function for the tool parameters.
- Strongly recommended to return a tuple of (is_valid, error_message).
-
- If None is returned, the tool will be validated against the parameters schema.
- """
- del arguments
- return None
diff --git a/marimo/_server/api/lifespans.py b/marimo/_server/api/lifespans.py
index 2d72493341..49137a7789 100644
--- a/marimo/_server/api/lifespans.py
+++ b/marimo/_server/api/lifespans.py
@@ -66,6 +66,20 @@ async def lsp(app: Starlette) -> AsyncIterator[None]:
pass
+async def tool_manager(app: Starlette) -> AsyncIterator[None]:
+ try:
+ from marimo._server.ai.tools.tool_manager import setup_tool_manager
+
+ # Initialize and attach to app state
+ setup_tool_manager(app)
+
+ except Exception as e: # pragma: no cover - defensive
+ LOGGER.warning("Failed to initialize ToolManager: %s", e)
+
+ yield
+
+
@contextlib.asynccontextmanager
async def mcp(app: Starlette) -> AsyncIterator[None]:
if TYPE_CHECKING:
diff --git a/marimo/_server/start.py b/marimo/_server/start.py
index 2d0a5c1d70..d8dc807f08 100644
--- a/marimo/_server/start.py
+++ b/marimo/_server/start.py
@@ -247,6 +247,7 @@ def start(
lifespans.signal_handler,
lifespans.logging,
lifespans.open_browser,
+ lifespans.tool_manager,
*LIFESPAN_REGISTRY.get_all(),
]
diff --git a/tests/_ai/test_chat_convert.py b/tests/_ai/test_chat_convert.py
index f22f5240f6..1a8f633bca 100644
--- a/tests/_ai/test_chat_convert.py
+++ b/tests/_ai/test_chat_convert.py
@@ -29,7 +29,7 @@ from marimo._ai._types import (
ToolInvocationPart,
)
from marimo._plugins.ui._impl.chat.utils import from_chat_message_dict
-from marimo._server.ai.tools.types import Tool
+from marimo._server.ai.tools.types import ToolDefinition
@pytest.fixture
@@ -947,7 +947,7 @@ def test_from_chat_message_dict():
@pytest.fixture
def sample_tools():
return [
- Tool(
+ ToolDefinition(
name="test_tool",
description="A test tool",
parameters={
diff --git a/tests/_server/ai/test_ai_config.py b/tests/_server/ai/test_ai_config.py
index e51111230d..3d41ce16e5 100644
--- a/tests/_server/ai/test_ai_config.py
+++ b/tests/_server/ai/test_ai_config.py
@@ -24,7 +24,7 @@ from marimo._server.ai.config import (
get_edit_model,
get_max_tokens,
)
-from marimo._server.ai.tools.types import Tool
+from marimo._server.ai.tools.types import ToolDefinition
from marimo._server.api.status import HTTPStatus
@@ -286,7 +286,7 @@ class TestAnyProviderConfig:
@patch("marimo._server.ai.config._get_tools")
def test_tools_included_when_available(self, mock_get_tools: Any) -> None:
"""Test that tools are included when available."""
- mock_tool = Tool(
+ mock_tool = ToolDefinition(
name="test_tool",
description="Test tool",
parameters={},
diff --git a/tests/_server/api/endpoints/test_ai.py b/tests/_server/api/endpoints/test_ai.py
index 47bbd28e61..c49c711e22 100644
--- a/tests/_server/api/endpoints/test_ai.py
+++ b/tests/_server/api/endpoints/test_ai.py
@@ -19,7 +19,7 @@ from marimo._server.ai.providers import (
OpenAIProvider,
without_wrapping_backticks,
)
-from marimo._server.ai.tools.types import ToolResult
+from marimo._server.ai.tools.types import ToolCallResult
from tests._server.conftest import get_session_config_manager
from tests._server.mocks import token_header, with_session
@@ -1039,8 +1039,8 @@ class TestInvokeToolEndpoint:
# Mock successful tool result as a coroutine
async def mock_invoke_tool(
_tool_name: str, _arguments: dict
- ) -> ToolResult:
- return ToolResult(
+ ) -> ToolCallResult:
+ return ToolCallResult(
tool_name="test_tool",
result={
"message": "Tool executed successfully",
@@ -1087,8 +1087,8 @@ class TestInvokeToolEndpoint:
# Mock tool result with error as a coroutine
async def mock_invoke_tool(
_tool_name: str, _arguments: dict
- ) -> ToolResult:
- return ToolResult(
+ ) -> ToolCallResult:
+ return ToolCallResult(
tool_name="failing_tool",
result=None,
error="Tool execution failed: Invalid parameter",
@@ -1132,8 +1132,8 @@ class TestInvokeToolEndpoint:
# Mock tool result for non-existent tool as a coroutine
async def mock_invoke_tool(
_tool_name: str, _arguments: dict
- ) -> ToolResult:
- return ToolResult(
+ ) -> ToolCallResult:
+ return ToolCallResult(
tool_name="nonexistent_tool",
result=None,
error="Tool 'nonexistent_tool' not found. Available tools: get_server_debug_info",
@@ -1171,8 +1171,8 @@ class TestInvokeToolEndpoint:
# Mock tool result with validation error as a coroutine
async def mock_invoke_tool(
_tool_name: str, _arguments: dict
- ) -> ToolResult:
- return ToolResult(
+ ) -> ToolCallResult:
+ return ToolCallResult(
tool_name="test_tool",
result=None,
error="Invalid arguments for tool 'test_tool': Missing required parameter 'required_param'",
@@ -1214,8 +1214,8 @@ class TestInvokeToolEndpoint:
# Mock successful tool result with complex data as a coroutine
async def mock_invoke_tool(
_tool_name: str, _arguments: dict
- ) -> ToolResult:
- return ToolResult(
+ ) -> ToolCallResult:
+ return ToolCallResult(
tool_name="complex_tool",
result={
"processed_data": [
@@ -1289,8 +1289,8 @@ class TestInvokeToolEndpoint:
# Mock successful tool result with empty arguments
async def mock_invoke_tool(
tool_name: str, _arguments: dict
- ) -> ToolResult:
- return ToolResult(
+ ) -> ToolCallResult:
+ return ToolCallResult(
tool_name=tool_name,
result={"message": "Tool executed with empty args"},
error=None,