tools/ — What Agents Can Do¶

Source: kernel/tools/tools.py · kernel/tools/chain.py · kernel/tools/approval.py · kernel/tools/skills.py

Defines the complete tool taxonomy: three execution modes across two axes, wire declarations for LLM providers, sandboxed code chaining, human-in-the-loop approval, and prompt skills.

The Tool Taxonomy¶

Three Protocols govern all tools. The right one depends on who executes and who declares:

Core Data & Specs¶

• ToolExecutionResult: Represents execution outputs. Fields:
  • content: list[ContentBlock]: The multimodal output blocks.
  • is_error: bool: Flag indicating execution failure.
  • structured_content: dict: Parsed dictionary response.
• FunctionSpec: Local schema specification: name, description, parameters: dict, lazy_schema: bool.
• ProviderSpec: Provider-specific spec: name, provider: str, spec: dict.

Dispatch pattern at runtime¶

flowchart TD
    LLM["LLM returns tool call"] --> CHECK1{"is_provider_defined_tool(tool)?"}
    CHECK1 -->|"yes"| PROV_RUN["await tool.handle_call(call, ctx)<br/>&rarr; ToolExecutionResult"]
    CHECK1 -->|"no"| CHECK2{"is_hosted_tool(tool)?"}
    CHECK2 -->|"yes"| SKIP["Skip local execution<br/>(Result arrives in next LLM turn)"]
    CHECK2 -->|"no — plain Tool"| LOCAL_RUN["await tool.execute(ctx, **args)<br/>&rarr; ToolExecutionResult"]

Always check is_provider_defined_tool before is_hosted_tool — both have provider_specs, but only ProviderDefinedTool has handle_call.

ToolRisk and Approval¶

Tools declare a risk level. High and critical risk tools pause execution and ask a human before proceeding.

sequenceDiagram
    autonumber
    participant Agent
    participant Invoker as ToolInvoker (L1)
    participant Handler as ApprovalHandler
    participant Human

    Agent->>Invoker: execute tool "send_email" (ToolRisk.HIGH)
    Invoker->>Invoker: check tool.risk

    alt risk == SAFE
        Invoker->>Invoker: execute immediately
    else risk == HIGH or CRITICAL
        Invoker->>Handler: request(ApprovalRequest)
        Handler->>Human: "send_email wants to run. Approve?"
        Human-->>Handler: decision
        Handler-->>Invoker: ApprovalDecision

        alt APPROVED
            Invoker->>Invoker: execute tool
        else DENIED
            Invoker-->>Agent: ToolExecutionResult(is_error=True, "denied by user")
        end
    end

    Invoker-->>Agent: ToolExecutionResult

ApprovalRequest is immutable and fully serializable — it can be stored in Postgres and resumed after a restart. ApprovalHandler implementations: WebApprovalHandler (the ravi-ui HITL card), AutoApprovalHandler (tests), CliApprovalHandler (terminal).

Sandboxed Code-Mode Chaining¶

Tool chaining lets the LLM write a Python script that calls multiple tools and pipes results between them. The script runs in a Firecracker/K8s sandbox; each tool call crosses the bridge back to the framework-side ToolInvoker.

sequenceDiagram
    autonumber
    participant LLM
    participant Chain as ToolChainTool (L2)
    participant Sandbox as Firecracker Sandbox
    participant Invoker as ToolInvoker (L1)
    participant Tool

    LLM->>Chain: execute(code="...")
    Chain->>Sandbox: run(code, prelude_with_bridge)

    loop Each tool call in script (max 50)
        Sandbox->>Invoker: bridge call: {tool, args}
        Invoker->>Tool: execute(ctx, **args)
        Tool-->>Invoker: ToolExecutionResult

        alt result <= 4096 bytes
            Invoker-->>Sandbox: InvocationResult(text, structured)
        else large result
            Invoker->>Invoker: store in ArtifactStore
            Invoker-->>Sandbox: InvocationResult(artifact_ref, preview)
        end
    end

    Sandbox-->>Chain: ChainRunResult(output_text, call_trace)
    Chain-->>LLM: ToolExecutionResult(content)

    Note over Chain: call_trace lists every tool that ran<br/>even on crash — LLM avoids re-sending emails

Key types from chain.py:

Skills — Prompt Packages¶

A Skill behaves as a prompt package attached to an agent to inject custom instructions and constrain available tools:

A Skill extends an agent's behaviour without modifying its code. When attached to an agent, instructions are appended to the effective system prompt and allowed_tools limits which tools the skill can use.