Background
Currently, the entire ToolMixin surface — define_tool, define_tools, register_swaig_function, on_function_call — is documented only under AgentBase in the Python SDK reference, to which the SWMLService index page points. That convention exists because ToolMixin was originally factored out of AgentBase (its docstring still reads "all tool/function-related methods for AgentBase"), and was only later composed into the lower-level SWMLService.
This topic came up while merging the ai_sidecar docs (#352). That branch had originally added a Python swml-service/define-tool page; at that time, we removed that page because it was an exact duplicate of the agent-base page, and followed the existing convention of placing ToolMixin methods under AgentBase.
The problem
In the SDK source these methods live on ToolMixin, which is composed into SWMLService (class SWMLService(ToolMixin)); AgentBase inherits them transitively through SWMLService and does not override them. Both SWMLService and AgentBase are concrete, top-level public classes, and the SDK ships standalone examples that use define_tool on SWMLService with no AgentBase involved (swmlservice_swaig_standalone.py, swmlservice_ai_sidecar.py). This means that SWMLService is a first-class entry point for the SDK.
Sidenote: By contrast, the TypeScript version has two real, separately-declared methods (SWMLService.defineTool and an AgentBase.defineTool override) with distinct signatures.
Proposed changes
I see two reasonable approaches:
-
Document ToolMixin methods once, only on SWMLService, and cross-link from agent-base. This is a sensible convention because it documents the feature on the lower-level class where the capability is introduced. If we take this route, we'd need to lightly edit the method docstrings to read correctly in the SWMLService context, as they currently include agent-specific language.
-
Document in both places using the Markdown partial component, so SWMLService and AgentBase each render the same canonical reference without drift. That way, ToolMixin methods are equally discoverable from both core API classes.
Either way the decision should apply to the whole ToolMixin surface, not just define_tool, so the four methods stay consistent.
Background
Currently, the entire
ToolMixinsurface —define_tool,define_tools,register_swaig_function,on_function_call— is documented only under AgentBase in the Python SDK reference, to which the SWMLService index page points. That convention exists becauseToolMixinwas originally factored out ofAgentBase(its docstring still reads "all tool/function-related methods for AgentBase"), and was only later composed into the lower-levelSWMLService.This topic came up while merging the
ai_sidecardocs (#352). That branch had originally added a Pythonswml-service/define-toolpage; at that time, we removed that page because it was an exact duplicate of theagent-basepage, and followed the existing convention of placing ToolMixin methods under AgentBase.The problem
In the SDK source these methods live on
ToolMixin, which is composed intoSWMLService(class SWMLService(ToolMixin));AgentBaseinherits them transitively throughSWMLServiceand does not override them. BothSWMLServiceandAgentBaseare concrete, top-level public classes, and the SDK ships standalone examples that usedefine_toolonSWMLServicewith noAgentBaseinvolved (swmlservice_swaig_standalone.py,swmlservice_ai_sidecar.py). This means thatSWMLServiceis a first-class entry point for the SDK.Sidenote: By contrast, the TypeScript version has two real, separately-declared methods (
SWMLService.defineTooland anAgentBase.defineTooloverride) with distinct signatures.Proposed changes
I see two reasonable approaches:
Document
ToolMixinmethods once, only onSWMLService, and cross-link fromagent-base. This is a sensible convention because it documents the feature on the lower-level class where the capability is introduced. If we take this route, we'd need to lightly edit the method docstrings to read correctly in the SWMLService context, as they currently include agent-specific language.Document in both places using the
Markdownpartial component, soSWMLServiceandAgentBaseeach render the same canonical reference without drift. That way,ToolMixinmethods are equally discoverable from both core API classes.Either way the decision should apply to the whole
ToolMixinsurface, not justdefine_tool, so the four methods stay consistent.