tools by JarbasAl · Pull Request #38 · OpenVoiceOS/ovos-technical-manual

JarbasAl · 2025-10-17T15:14:45Z

companion to OpenVoiceOS/ovos-plugin-manager#340

Summary by CodeRabbit

Documentation
- Added comprehensive Agent Tools framework documentation including core concepts, consumption methods (direct Python execution and MessageBus-based interactions), and implementation guidance
- Updated navigation menu to include new Agent Tools documentation section

coderabbitai · 2025-10-17T15:14:56Z

Walkthrough

This pull request adds comprehensive documentation for the OpenVoiceOS Agent Tools framework, including core concepts (AgentTool, ToolBox), consumption methods (Direct Python and MessageBus-based), JSON Schema representations, and implementation examples. The documentation is registered in the mkdocs navigation.

Changes

Cohort / File(s)	Summary
New Agent Tools Documentation `docs/tools.md`	Introduces Agent Tools framework documentation covering AgentTool, ToolArguments, ToolOutput, and ToolBox abstractions; describes Direct Python execution and MessageBus-based interaction patterns; provides JSON Schema guidance and a complete toy file-tool implementation example with argument/output schemas.
Navigation Update `mkdocs.yml`	Adds new navigation entry "Tools for Agents" linking to `tools.md` under the AI Agents section.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A toolbox of wisdom, now written with care,
For agents who venture with tools everywhere,
From schemas to schemas, from bus calls so bright,
Documentation flows—oh what a delight!
Tools ready and waiting, all labeled just right! 🔧✨

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title Check	❓ Inconclusive	The pull request title "tools" is extremely generic and lacks descriptive specificity. While it is technically related to the changeset (which adds documentation for OpenVoiceOS Agent Tools), the title does not effectively communicate what the change accomplishes. A single-word title provides minimal information for someone scanning the project history, and it fails to distinguish this PR from many other potential changes. The title does not convey that this is documentation for the Agent Tools framework or any meaningful detail about the contribution.	Consider revising the title to be more descriptive and specific, such as "Add OpenVoiceOS Agent Tools documentation" or "Document Agent Tools framework with implementation guide". This would make the primary purpose of the PR immediately clear to reviewers and future maintainers reading the commit history.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch tools

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a5f3e50 and 5fd0fc3.

📒 Files selected for processing (2)

docs/tools.md (1 hunks)
mkdocs.yml (1 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/tools.md

[grammar] ~37-~37: Ensure spelling is correct
Context: ...s. * Bus Integration: Registering messagebus handlers to support dynamic discovery a...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

[grammar] ~52-~52: Ensure spelling is correct
Context: ...nefits:** * Direct Access: No messagebus latency. * Strong Validation:...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🪛 markdownlint-cli2 (0.18.1)

docs/tools.md

27-27: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

28-28: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

36-36: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

37-37: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

38-38: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

50-50: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

51-51: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

52-52: Unordered list indentation
Expected: 2; Actual: 6

(MD007, ul-indent)

53-53: Unordered list indentation
Expected: 2; Actual: 6

(MD007, ul-indent)

54-54: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

67-67: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

71-71: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

72-72: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

92-92: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

102-102: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

103-103: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

113-113: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

🔇 Additional comments (1)

mkdocs.yml (1)

48-48: Navigation entry correctly added.

The new navigation entry is properly formatted and logically placed under the AI Agents section alongside related documentation.

coderabbitai · 2025-10-17T15:18:31Z

+  * **`ToolArguments(BaseModel)`**: Tool consumers (agents) must format their input according to the concrete Pydantic model derived from this base. This ensures rigorous input validation.
+  * **`ToolOutput(BaseModel)`**: The result of a tool call is guaranteed to conform to the concrete Pydantic model derived from this base. This ensures reliable data handling by the consuming agent.


⚠️ Potential issue | 🟠 Major

Fix unordered list indentation throughout the document (MD007).

Markdown linting will fail due to inconsistent list indentation. Unordered lists should not have leading spaces; they should start at column 0.

Apply these diffs to fix the indentation:

#### 2. ToolArguments and ToolOutput These are base classes for Pydantic models that define the data contract for a tool. - * **`ToolArguments(BaseModel)`**: Tool consumers (agents) must format their input according to the concrete Pydantic model derived from this base. This ensures rigorous input validation. - * **`ToolOutput(BaseModel)`**: The result of a tool call is guaranteed to conform to the concrete Pydantic model derived from this base. This ensures reliable data handling by the consuming agent. +* **`ToolArguments(BaseModel)`**: Tool consumers (agents) must format their input according to the concrete Pydantic model derived from this base. This ensures rigorous input validation. +* **`ToolOutput(BaseModel)`**: The result of a tool call is guaranteed to conform to the concrete Pydantic model derived from this base. This ensures reliable data handling by the consuming agent.

The `ToolBox` handles: - * **Tool Discovery:** Implementing the abstract `discover_tools()` method to define the available tools. - * **Bus Integration:** Registering messagebus handlers to support dynamic discovery and remote calling (`ovos.persona.tools.discover`, `ovos.persona.tools.<toolbox_id>.call`). - * **Execution and Validation:** Providing the `call_tool(name, tool_kwargs)` method, which is the official interface for executing tools, including mandatory **input and output Pydantic validation**. +* **Tool Discovery:** Implementing the abstract `discover_tools()` method to define the available tools. +* **Bus Integration:** Registering message bus handlers to support dynamic discovery and remote calling (`ovos.persona.tools.discover`, `ovos.persona.tools.<toolbox_id>.call`). +* **Execution and Validation:** Providing the `call_tool(name, tool_kwargs)` method, which is the official interface for executing tools, including mandatory **input and output Pydantic validation**.

Note: Apply similar fixes to all remaining indentation errors throughout the file (lines 50–53, 54, 67, 71–72, 92, 102–103, 113).

Also applies to: 36-38

🧰 Tools

🪛 markdownlint-cli2 (0.18.1)

27-27: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

28-28: Unordered list indentation
Expected: 0; Actual: 2

(MD007, ul-indent)

🤖 Prompt for AI Agents

In docs/tools.md around lines 27-28 (and also apply to 36-38, 50-53, 54, 67, 71-72, 92, 102-103, 113), the unordered list items have leading spaces causing MD007 lint errors; remove the leading spaces so each unordered list marker (*) starts at column 0, and normalize indentation for nested list items to use consistent two-space indents (or none if top-level) throughout the file to fix all similar occurrences.

mikejgray

Some comments, but overall I think this documentation is very easy to read and understand. It makes it trivial to implement and I'm looking forward to trying some of these out!

mikejgray · 2025-10-18T02:05:56Z

+
+| Attribute | Type | Description |
+| :--- | :--- | :--- |
+| **`name`** | `str` | The **unique**, snake_case identifier for the tool. This name is typically used by the agent/LLM to reference the function. |


Is snake_case strictly enforced or just suggested?

just seems to be how everyone is doing it, but there's no specific checks to enforce it

mikejgray · 2025-10-18T02:06:31Z

+| Attribute | Type | Description |
+| :--- | :--- | :--- |
+| **`name`** | `str` | The **unique**, snake_case identifier for the tool. This name is typically used by the agent/LLM to reference the function. |
+| **`description`** | `str` | A detailed, natural language explanation of the tool's purpose and how it should be used. Essential for LLM reasoning. |


Guidelines around length would be helpful here. A character/word limit or suggested minimum would make it easier to determine how to fulfill this

mikejgray · 2025-10-18T02:07:14Z

+| **`argument_schema`** | `Type[ToolArguments]` | A Pydantic model defining the **required structure and types** for the input arguments. |
+| **`output_schema`** | `Type[ToolOutput]` | A Pydantic model defining the **guaranteed structure and types** for the tool's output. |


Is there a hard requirement for Pydantic? I personally prefer it for typing in Python, but I know it's not the go-to for all projects (Home Assistant comes to mind)

pydantic is being used to validate the inputs and outputs to the tools, i like it because it gives very clear errors when input/output is malformed

mikejgray · 2025-10-18T02:09:32Z

+
+These are base classes for Pydantic models that define the data contract for a tool.
+
+  * **`ToolArguments(BaseModel)`**: Tool consumers (agents) must format their input according to the concrete Pydantic model derived from this base. This ensures rigorous input validation.


Have you tested if LLMs can handle Pydantic as a contract well? I know it's not just for LLMs but it will probably be a popular use case

this will probably depend on the LLM, LLMs may output garbage or invalid data so thats why pydantic is important, it validates that the LLM followed the prompt and gave results in right format.

this is up to the agent developer to handle, all the toolbox does is throw an error then the agent needs to either retry or do somehing else

mikejgray · 2025-10-18T02:13:20Z

+      * **Strong Validation:** Enforces the `argument_schema` and `output_schema` before and after execution, ensuring data integrity.
+  * **Usage Flow (Internal to Agent):**
+    1.  Get the `ToolBox` instance (e.g., via a plugin loading utility).
+    2.  Call: `validated_output = toolbox.call_tool(name="tool_name", tool_kwargs={"arg1": value})`


It will probably make more sense when I look at code, but I thought you pass a tool a Pydantic model?

the pydantic model is part of the tool definition, not really user facing, the pydantic validation happens inside the toolbox.call_tool method

tool users should not need to worry about pydantic models, just tool developers

mikejgray · 2025-10-18T02:16:27Z

+        "type": "ovos.persona.tools.<toolbox_id>.call.response",
+        "data": {
+            "toolbox_id": "web_search_tools",
+            "error": "ValueError: Invalid input for 'tool_name'..."


ToolOutput is supposed to be the guaranteed response per the tool contract, but this would be a different format, wouldn't it? Is there going to be something like a ToolError class and a tool could return ToolOutput | ToolError?

this is not the tool output itself, this is the messagebus handler, when an exception happened using the tool, so in this case there's no tool output because it failed

mikejgray · 2025-10-18T02:18:08Z

+class FileWriteOutput(ToolOutput):
+    """Output structure for the write_file tool."""
+    path: str = Field(description="The path to the file that was written.")
+    bytes_written: int = Field(description="The number of bytes successfully written.")
+    success: bool = Field(default=True)
+    error: Optional[str] = None


Related to my question above, seems that there are several ways to go about handling valid outputs vs. errors. Might be good to standardize on one for consistency

mikejgray · 2025-10-18T02:20:50Z

+    except RuntimeError as e:
+        print(f"\nExecution Failed (Tool Logic/Output Validation): {e}")
+
+# solve_file_problem()


Is this meant to be commented out for this example?

mikejgray · 2025-10-18T02:21:43Z

      - Personas: 150-personas.md
      - AI Transformers: 151-llm-transformers.md
      - Specialized Solvers: 150-advanced_solvers.md
+      - Tools for Agents: tools.md


This should have a number to conform to the rest of the files

tools

5fd0fc3

JarbasAl requested review from NeonDaniel and mikejgray October 17, 2025 15:14

JarbasAl mentioned this pull request Oct 17, 2025

feat: tool plugins OpenVoiceOS/ovos-plugin-manager#340

Merged

coderabbitai Bot reviewed Oct 17, 2025

View reviewed changes

JarbasAl mentioned this pull request Oct 17, 2025

OpenAI function calling OpenVoiceOS/ovos-persona-server#12

Open

JarbasAl marked this pull request as draft October 17, 2025 15:53

mikejgray reviewed Oct 18, 2025

View reviewed changes

		* `ToolArguments(BaseModel)`: Tool consumers (agents) must format their input according to the concrete Pydantic model derived from this base. This ensures rigorous input validation.
		* `ToolOutput(BaseModel)`: The result of a tool call is guaranteed to conform to the concrete Pydantic model derived from this base. This ensures reliable data handling by the consuming agent.

		\| `argument_schema` \| `Type[ToolArguments]` \| A Pydantic model defining the required structure and types for the input arguments. \|
		\| `output_schema` \| `Type[ToolOutput]` \| A Pydantic model defining the guaranteed structure and types for the tool's output. \|


		These are base classes for Pydantic models that define the data contract for a tool.

		* `ToolArguments(BaseModel)`: Tool consumers (agents) must format their input according to the concrete Pydantic model derived from this base. This ensures rigorous input validation.

Uh oh!

Conversation

JarbasAl commented Oct 17, 2025 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Pre-merge checks and finishing touches

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mikejgray left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JarbasAl Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JarbasAl commented Oct 17, 2025 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Oct 17, 2025 •

edited

Loading

JarbasAl Oct 18, 2025 •

edited

Loading