cleveragents-core/docs/reference/tool_bindings.md

Tool Resource Bindings

Tools in CleverAgents declare resource slots that describe which resources they operate on. At activation time the binding resolution service maps each slot to a concrete resource from the registry.

Binding Modes

Contextual Binding (default)

The slot declares only a resource_type requirement. The system searches the plan's project for linked resources that match at activation time.

Resolution rules:

1. Collect all linked resources whose type matches the slot's resource_type (including sub-types via parent_types).
2. If exactly one resource matches, it is automatically bound.
3. If multiple resources match, the slot name is used as a hint: the resource whose alias (or short name) equals the slot name is selected. If no alias matches, a ValidationError is raised.
4. If no resource matches and the slot is required, a ValidationError is raised.

resource_slots:
  - name: repo
    resource_type: git-checkout
    access: read_write
    binding: contextual       # default -- can be omitted

Static Binding

The slot is hardcoded to a specific registered resource by name via the static_resource field. Validated at registration time.

resource_slots:
  - name: config_dir
    resource_type: fs-directory
    access: read_only
    binding: static
    static_resource: local/shared-config

Parameter Binding

The resource reference is passed as a tool argument at invocation time. Resolution is deferred until the tool is actually called.

resource_slots:
  - name: target
    resource_type: fs-directory
    access: read_write
    binding: parameter

At invocation the caller supplies target=<resource-name-or-id>.

Resolution Order

For each resource slot on the tool:

1. Determine the binding mode (static, parameter, or contextual).
2. Static -- look up the named resource in the registry; verify type compatibility.
3. Parameter -- if invocation params include the slot name, resolve eagerly; otherwise mark as deferred.
4. Contextual -- search the project's linked resources for type-compatible matches and apply disambiguation rules.

Type Compatibility

A resource is type-compatible with a slot when:

• The resource's type exactly matches the slot's resource_type, or
• The resource's type declares the slot's resource_type in its parent_types list (sub-type relationship).

For example, fs-directory lists git-checkout in its parent_types, so an fs-directory resource satisfies a slot requiring git-checkout.

Examples

Single Contextual Resource

from cleveragents.application.services.binding_resolution_service import (
    BindingResolutionService,
)

service = BindingResolutionService(resource_registry)
results = service.resolve(tool, project)
# results[0].binding_mode == "contextual"
# results[0].resource_id == "01HGZ..."

Mixed Bindings

A tool may combine all three modes:

resource_slots:
  - name: repo
    resource_type: git-checkout
    access: read_write
    binding: contextual
  - name: config
    resource_type: fs-directory
    access: read_only
    binding: static
    static_resource: local/shared-config
  - name: output
    resource_type: fs-directory
    access: write_only
    binding: parameter

API Reference

See:

• BindingResolutionService
• BindingResult
• ResourceSlot