Jeff
dfb91781aa
CI / lint (pull_request) Successful in 14s
CI / typecheck (pull_request) Successful in 26s
CI / security (pull_request) Successful in 21s
CI / quality (pull_request) Successful in 15s
CI / integration_tests (pull_request) Successful in 4m10s
CI / build (pull_request) Successful in 16s
CI / unit_tests (pull_request) Successful in 8m23s
CI / docker (pull_request) Successful in 39s
CI / coverage (pull_request) Successful in 6m21s
CI / lint (push) Waiting to run
CI / typecheck (push) Waiting to run
CI / security (push) Waiting to run
CI / quality (push) Waiting to run
CI / unit_tests (push) Waiting to run
CI / integration_tests (push) Waiting to run
CI / coverage (push) Blocked by required conditions
CI / build (push) Waiting to run
CI / docker (push) Blocked by required conditions
101 lines
5.7 KiB
Markdown
101 lines
5.7 KiB
Markdown
# Tool Domain Model
|
|
|
|
The `Tool` is the atomic unit of execution in CleverAgents -- a namespaced,
|
|
independently registered callable operation.
|
|
|
|
## Tool Name
|
|
|
|
Tools use a `namespace/short_name` naming pattern:
|
|
|
|
```
|
|
local/line-counter
|
|
devops/docker-build
|
|
```
|
|
|
|
The name is the unique identifier. Tools and Validations share the same
|
|
namespace; no collisions are allowed.
|
|
|
|
## Source Types
|
|
|
|
| Source | Description | Required Fields |
|
|
|---------------|------------------------------------------------|---------------------------|
|
|
| `mcp` | Delegates to an MCP server | `mcp_server`, `mcp_tool_name` |
|
|
| `agent_skill` | Agent Skills Standard folder | `agent_skill_path` |
|
|
| `builtin` | Provided by the runtime | (none) |
|
|
| `custom` | Inline Python code | `code` |
|
|
| `wrapped` | Validation-only; wraps an existing tool | (set via Validation) |
|
|
|
|
## ToolCapability
|
|
|
|
Describes what a tool can and cannot do:
|
|
|
|
| Field | Type | Default | Description |
|
|
|--------------------------|----------------|---------|------------------------------------------|
|
|
| `read_only` | `bool` | `False` | Tool only reads, never writes |
|
|
| `writes` | `bool` | `False` | Tool can write to resources |
|
|
| `write_scope` | `str \| None` | `None` | Scope of writes |
|
|
| `checkpointable` | `bool` | `False` | Tool supports checkpoint/rollback |
|
|
| `checkpoint_scope` | `CheckpointScope \| None` | `None` | Granularity of checkpoint support |
|
|
| `side_effects` | `list[str]` | `[]` | Known side effects |
|
|
| `idempotent` | `bool` | `False` | Safe to re-run |
|
|
| `unsafe` | `bool` | `False` | Requires extra safety checks |
|
|
| `human_approval_required`| `bool` | `False` | Requires human approval |
|
|
| `cost_profile` | `str \| None` | `None` | Named cost profile |
|
|
|
|
**Constraint**: If `read_only=True`, then `writes` and `checkpointable` must be `False`.
|
|
|
|
## ResourceSlot
|
|
|
|
Declares a resource binding for a tool:
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------------------|---------------------|---------------|-------------------------------------|
|
|
| `name` | `str` | (required) | Slot name (valid Python identifier) |
|
|
| `resource_type` | `str` | (required) | Resource type name |
|
|
| `access` | `ResourceAccessMode`| (required) | `read_only` or `read_write` |
|
|
| `description` | `str` | `""` | Human-readable description |
|
|
| `binding` | `BindingMode` | `contextual` | How the resource is resolved |
|
|
| `static_resource` | `str \| None` | `None` | Resource name (required for static) |
|
|
| `required` | `bool` | `True` | Whether slot must be filled |
|
|
|
|
**Constraint**: `static_resource` required when `binding=static`; forbidden otherwise.
|
|
|
|
## ToolLifecycle
|
|
|
|
Optional lifecycle hooks:
|
|
|
|
| Field | Type | Description |
|
|
|--------------|---------------|---------------------------|
|
|
| `discover` | `str \| None` | Hook for tool discovery |
|
|
| `activate` | `str \| None` | Hook for tool activation |
|
|
| `deactivate` | `str \| None` | Hook for tool deactivation|
|
|
|
|
## Tool Fields
|
|
|
|
| Field | Type | Default | Description |
|
|
|--------------------|-------------------------|------------------|----------------------------------------|
|
|
| `name` | `str` | (required) | `namespace/short_name` format |
|
|
| `description` | `str` | (required) | Short description |
|
|
| `source` | `ToolSource` | (required) | Implementation source |
|
|
| `tool_type` | `ToolType` | `tool` | Registry discriminator |
|
|
| `code` | `str \| None` | `None` | Inline Python (custom source) |
|
|
| `mcp_server` | `str \| None` | `None` | MCP server name |
|
|
| `mcp_tool_name` | `str \| None` | `None` | MCP tool name |
|
|
| `agent_skill_path` | `str \| None` | `None` | Agent Skills path |
|
|
| `input_schema` | `dict \| None` | `None` | JSON Schema for inputs |
|
|
| `output_schema` | `dict \| None` | `None` | JSON Schema for outputs |
|
|
| `capability` | `ToolCapability` | `ToolCapability()`| Capability metadata |
|
|
| `resource_slots` | `list[ResourceSlot]` | `[]` | Resource bindings |
|
|
| `lifecycle` | `ToolLifecycle \| None` | `None` | Lifecycle hooks |
|
|
| `timeout` | `int` | `300` | Execution timeout (seconds, >= 1) |
|
|
|
|
## Class Methods
|
|
|
|
- `Tool.from_config(config: dict)` -- Create from a YAML config dict
|
|
- `tool.as_cli_dict()` -- Stable ordered dict for CLI rendering
|
|
|
|
## Properties
|
|
|
|
- `tool.namespace` -- Extracted namespace from name
|
|
- `tool.short_name` -- Extracted short name from name
|