@sisu-ai/mw-tool-calling

v10.0.0

Published

6 days ago

Execute provider-native tool call loops with robust iteration, validation, and tool result handling.

0High
0Medium
0Low

lejahmie

sisu ai ai-agent agentic middleware tool-calling

@sisu-ai/mw-tool-calling

Execute provider-native tool call loops with robust iteration, validation, and tool result handling.

Setup

npm i @sisu-ai/mw-tool-calling

Behavior

toolCalling: single-round tool calling.
- First turn: calls ctx.model.generate(messages, { tools, toolChoice:'auto' }).
- If assistant returns tool_calls, appends the assistant message and executes each tool.
  - Executes each unique (name, args) once and responds to every tool_call_id.
  - Handles provider quirks by reusing last args for identical tool names with missing args.
- Second turn: asks for a pure completion (toolChoice:'none').

sequenceDiagram
  autonumber
  participant A as Agent toolCalling
  participant M as Model Adapter
  participant R as Tools Registry
  participant H as Tool Handler

  A->>R: list
  R-->>A: tools
  A->>M: generate with tools auto
  alt tool calls
    M-->>A: assistant with tool calls
    loop each unique name args
      A->>R: resolve and validate
      R-->>A: handler
      A->>H: execute
      H-->>A: append tool message
    end
    A->>M: generate finalize none
    M-->>A: assistant completion
  else no tool calls
    M-->>A: assistant completion
  end

iterativeToolCalling: multi-round tool calling.
- Repeats calls with toolChoice:'auto' until the model returns a message with no tool_calls (max 12 iters).

sequenceDiagram
  autonumber
  participant A as Agent iterativeToolCalling
  participant M as Model Adapter
  participant R as Tools Registry
  participant H as Tool Handler

  A->>R: list
  R-->>A: tools
  loop max twelve iterations until no tool calls
    A->>M: generate with tools auto
    alt tool calls present
      M-->>A: assistant with tool calls
      loop each unique name args
        A->>R: resolve and validate
        R-->>A: handler
        A->>H: execute
        H-->>A: append tool message
      end
    else no tool calls
      M-->>A: assistant no tools
    end
  end
  A->>M: generate finalize none
  M-->>A: assistant completion

Usage

import { toolCalling, iterativeToolCalling } from '@sisu-ai/mw-tool-calling';

// Single-round
agent.use(toolCalling);

// OR multi-round
agent.use(iterativeToolCalling);

Tool Execution Records

Each executed tool call is appended to ctx.state.toolExecutions:

type ToolExecutionRecord = {
  aliasName: string;
  canonicalName: string;
  callId?: string;
  args: unknown;
  result: unknown;
};

This is useful for diagnostics and post-run inspection without manually parsing tool messages.

Community & Support

Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu. Example projects live under examples/ in the repo.