English | 简体中文
This document describes the goals, direction, and boundaries of the tinyagent Tool Runtime.
The Tool Runtime establishes a consistent, validated, and auditable call boundary between the model and concrete capabilities. Built-in tools, application-registered tools, the Skill reader, and MCP tools all run through the same Registry and execution loop.
The module aims to:
- register tools through an explicit Registry, without implicit package scanning;
- validate tool names, JSON arguments, and JSON Schemas before execution;
- return expected tool failures to the model as structured results;
- enforce explicit limits on iterations, output size, concurrency, and cancellation behavior;
- expose one lifecycle to the CLI, SDK, Session audit trail, and streaming events.
Tools implement a narrow protocol owned by tinyagent. Its core fields are a name, description, parameter Schema, and async execution method. Execution receives a ToolContext and returns a ToolResult. Third-party SDK objects and raw provider tool-call structures are not part of the public tool interface.
The parameter Schema must be a JSON Schema object. Unknown tools, malformed JSON, Schema errors, and internal tool exceptions all produce an error-marked ToolResult instead of corrupting the Session or causing the Runtime to lose the current Run state.
The Runtime requests a provider response, executes any returned tool calls, and returns the results to the provider as Tool messages. This continues until the model produces a final response or an explicit termination condition is met.
Each call emits tool.started, followed by either tool.completed or tool.failed. Calls and results are persisted using the Session's existing Assistant/Tool message boundaries rather than a second call log that could diverge from conversation state.
Tool results are subject to a character limit before being sent to the model or written to the audit trail. Tool-call batches are constrained by the maximum iteration count. Reaching the limit ends the Run with the stable tool_iteration_limit error and does not misinterpret ordinary model text as a tool call.
Multiple tool calls execute serially by default. A batch may run concurrently only when every tool explicitly declares both read_only = True and concurrency_safe = True. Concurrency is an exception jointly determined by tool capability declarations and Runtime validation, not the default.
Cancellation must propagate to running tools. Individual tools must also implement their own timeouts, process-group cleanup, or transport shutdown. The Runtime does not swallow cancellation and fabricate a successful result.
Application code can register custom tools only by explicitly calling agent.tools.register(...). Built-in, custom, and MCP tools share a namespace. Duplicate names and invalid definitions must be rejected or isolated at the registration boundary; a later tool cannot silently override a security-sensitive capability.
The Tool Runtime does not implement filesystem security policy, the Shell sandbox, MCP transports, or Skill parsing. It provides a consistent call protocol and lifecycle; each capability module makes its own trust decisions and normalizes definitions before entering the Registry.