roboto.ai.agent_session.client_tool#

Module Contents#

class roboto.ai.agent_session.client_tool.ClientTool(fn, *, name, description, input_schema)#

A client-side tool with an execution callback.

Wraps a Python callable as a tool that the Roboto agent can request the client to execute. The tool’s JSON schema is inferred from the callable’s type hints; the tool description and per-parameter descriptions are taken from the function’s Google-style docstring unless passed explicitly.

Most callers build ClientTools via the client_tool() decorator or ClientTool.from_function() rather than instantiating this class directly.

Examples

Using the decorator — descriptions come from the docstring:

>>> @client_tool
... def remember(fact: str, tags: Optional[list[str]] = None) -> str:
...     """Store a fact in long-term memory.
...
...     Args:
...         fact: A standalone sentence worth remembering.
...         tags: Optional tags for later retrieval.
...     """
...     ...

Using Annotated[T, Field(...)] instead (takes precedence over the docstring):

>>> from typing import Annotated
>>> from pydantic import Field
>>> @client_tool
... def recall(
...     query: Annotated[str, Field(description="Substring to search for.")],
... ) -> str:
...     """Search long-term memory."""
...     ...

Using the factory with explicit overrides:

>>> tool = ClientTool.from_function(
...     my_fn,
...     name="store_fact",
...     description="Store a fact in long-term memory.",
... )
Parameters:

  • fn (collections.abc.Callable[Ellipsis, Any])

  • name (str)

  • description (str)

  • input_schema (dict[str, Any])

classmethod from_function(fn, *, name=None, description=None, input_schema=None)#

Build a ClientTool from a Python callable.

The tool’s name defaults to fn.__name__. The tool description defaults to the summary-and-body of fn’s docstring (everything before the first Google-style section header like Args: or Returns:). Per-parameter descriptions are pulled from the docstring’s Args: section, and can be overridden with typing.Annotated[T, pydantic.Field(description="...")] or param: T = pydantic.Field(description="...").

Parameters:

  • fn (collections.abc.Callable[Ellipsis, Any]) – The callable to invoke when the tool is dispatched.

  • name (Optional[str]) – Override for the tool name (default: fn.__name__).

  • description (Optional[str]) – Override for the tool description (default: the docstring’s summary-and-body). Required if fn has no docstring.

  • input_schema (Optional[dict[str, Any]]) – Override for the input JSON Schema (default: inferred from fn’s type hints and docstring).

Returns:

A ClientTool wrapping the given callable.

Raises:

ValueError – If the description cannot be resolved, or if input_schema is not provided and the signature cannot be automatically converted (e.g. uses *args or **kwargs).

Return type:

ClientTool

property name: str#

Tool name surfaced to the LLM.

Return type:

str

property spec: roboto.ai.agent_session.record.ClientToolSpec#

Declarative spec sent to the Roboto backend.

Return type:

roboto.ai.agent_session.record.ClientToolSpec

roboto.ai.agent_session.client_tool.client_tool(fn: collections.abc.Callable[Ellipsis, Any], /) → ClientTool#
roboto.ai.agent_session.client_tool.client_tool(*, name: str | None = None, description: str | None = None, input_schema: dict[str, Any] | None = None) → collections.abc.Callable[[collections.abc.Callable[Ellipsis, Any]], ClientTool]

Decorator that converts a function into a ClientTool.

Usable bare (@client_tool) or with keyword overrides (@client_tool(description="...")). See ClientTool.from_function() for how descriptions are resolved.

Note

This function is declared with two typing.overload() stubs above so that type checkers see the decorated name as a ClientTool regardless of call form. The overloads carry no runtime behavior; the implementation below handles both shapes.

Examples

Bare — infers everything from the function, including per-parameter descriptions from the docstring’s Args: section:

>>> @client_tool
... def remember(fact: str) -> str:
...     """Store a fact in long-term memory.
...
...     Args:
...         fact: A standalone sentence worth remembering.
...     """
...     ...

With overrides:

>>> @client_tool(name="store_fact", description="Persist a fact.")
... def _store(fact: str) -> str: ...
On this page