Tools

spec:
  tools:
    - type: filesystem
      root_path: ./src
      read_only: true
      allowed_extensions: [".py", ".md"]
    - type: http
      base_url: https://api.example.com
      allowed_methods: ["GET", "POST"]
      headers:
        Authorization: Bearer ${API_TOKEN}
    - type: mcp
      transport: stdio
      command: npx
      args: ["-y", "@anthropic/mcp-server-filesystem"]
    - type: custom
      module: my_tools
      config:
        db_url: "postgres://..."
    - type: api
      name: weather
      base_url: https://api.weather.com
      endpoints:
        - name: get_weather
          path: "/current/{city}"
          parameters:
            - name: city
              type: string
              required: true

tools:
  - type: filesystem
    root_path: ./src
    read_only: true
    allowed_extensions: [".py", ".md", ".txt"]

tools:
  - type: http
    base_url: https://api.example.com
    allowed_methods: ["GET"]
    headers:
      Authorization: Bearer ${API_TOKEN}

tools:
  # Stdio transport (local process)
  - type: mcp
    transport: stdio
    command: npx
    args: ["-y", "@anthropic/mcp-server-filesystem"]

  # SSE transport (remote server)
  - type: mcp
    transport: sse
    url: http://localhost:3001/sse

  # Streamable HTTP transport
  - type: mcp
    transport: streamable-http
    url: http://localhost:3001/mcp
    tool_filter: [search, get_document]

tools:
  # Auto-discover all public functions
  - type: custom
    module: my_tools

  # Load a single function
  - type: custom
    module: my_tools
    function: search_db

  # With config injection
  - type: custom
    module: my_tools
    config:
      api_key: ${MY_API_KEY}

initrunner init --template tool --name my_tools

"""Custom tools module for InitRunner.

All public functions are auto-discovered as agent tools. Type annotations and
docstrings are used as tool schemas and descriptions. Functions accepting a
``tool_config`` parameter receive the config dict from role.yaml (hidden from
the LLM).
"""

import hashlib
import json
import uuid


def convert_units(value: float, from_unit: str, to_unit: str) -> str:
    """Convert a numeric value between common measurement units.

    Supported conversions: km/mi, kg/lb, c/f, l/gal, m/ft, cm/in.
    """
    conversions: dict[tuple[str, str], float | None] = {
        ("km", "mi"): 0.621371,
        ("mi", "km"): 1.60934,
        ("kg", "lb"): 2.20462,
        ("lb", "kg"): 0.453592,
        ("c", "f"): None,
        ("f", "c"): None,
        ("l", "gal"): 0.264172,
        ("gal", "l"): 3.78541,
        ("m", "ft"): 3.28084,
        ("ft", "m"): 0.3048,
        ("cm", "in"): 0.393701,
        ("in", "cm"): 2.54,
    }

    key = (from_unit.lower(), to_unit.lower())
    if key == ("c", "f"):
        result = value * 9 / 5 + 32
    elif key == ("f", "c"):
        result = (value - 32) * 5 / 9
    elif key in conversions:
        result = value * conversions[key]
    else:
        return f"Unsupported conversion: {from_unit} -> {to_unit}"

    return f"{value} {from_unit} = {result:.4f} {to_unit}"


def generate_uuid() -> str:
    """Generate a random UUID v4 identifier."""
    return str(uuid.uuid4())


def format_json(text: str) -> str:
    """Pretty-print a JSON string with 2-space indentation."""
    try:
        parsed = json.loads(text)
        return json.dumps(parsed, indent=2, ensure_ascii=False)
    except json.JSONDecodeError as e:
        return f"Invalid JSON: {e}"


def word_count(text: str) -> str:
    """Count words, characters, and lines in a text string."""
    words = len(text.split())
    chars = len(text)
    lines = text.count("\n") + 1 if text else 0
    return f"Words: {words}, Characters: {chars}, Lines: {lines}"


def hash_text(text: str, algorithm: str = "sha256") -> str:
    """Hash text using the specified algorithm (md5, sha1, sha256, sha512)."""
    algo = algorithm.lower()
    if algo not in ("md5", "sha1", "sha256", "sha512"):
        return f"Unsupported algorithm: {algorithm}. Use md5, sha1, sha256, or sha512."
    h = hashlib.new(algo)
    h.update(text.encode())
    return f"{algo}:{h.hexdigest()}"


def lookup_with_config(query: str, tool_config: dict) -> str:
    """Look up a query using the configured prefix and source.

    The tool_config parameter is injected by InitRunner from the role YAML
    and is hidden from the LLM.
    """
    prefix = tool_config.get("prefix", "DEFAULT")
    source = tool_config.get("source", "unknown")
    return f"[{prefix}] Result for '{query}' from source '{source}'"

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: custom-tools-demo
  description: Demonstrates custom tool type with auto-discovered Python functions
spec:
  role: |
    You are a utility assistant with access to custom tools defined in a Python
    module. Use these tools to help the user with practical tasks.

    Available custom tools:
    - convert_units: Convert between common measurement units
    - generate_uuid: Generate a random UUID v4 identifier
    - format_json: Pretty-print a JSON string
    - word_count: Count words, characters, and lines in text
    - hash_text: Hash text with md5, sha1, sha256, or sha512
    - lookup_with_config: Look up a query using the configured prefix and source

    Always use the appropriate tool rather than trying to compute results yourself.
  model:
    provider: openai
    name: gpt-4o-mini
    temperature: 0.1
  tools:
    - type: custom
      module: my_tools
      config:
        prefix: "DEMO"
        source: "custom-tools-demo"
    - type: datetime
  guardrails:
    max_tokens_per_run: 20000
    max_tool_calls: 15
    timeout_seconds: 60

cd examples/roles/custom-tools-demo
initrunner run custom-tools-demo.yaml -i

> Convert 72 degrees Fahrenheit to Celsius
> Generate a UUID for me
> Hash "hello world" with sha256
> Look up "test query"

tools:
  - type: api
    name: github
    description: GitHub REST API
    base_url: https://api.github.com
    headers:
      Accept: application/vnd.github.v3+json
    auth:
      Authorization: "Bearer ${GITHUB_TOKEN}"
    endpoints:
      - name: get_repo
        method: GET
        path: "/repos/{owner}/{repo}"
        description: Get repository information
        parameters:
          - name: owner
            type: string
            required: true
          - name: repo
            type: string
            required: true
        response_extract: "$.full_name"
      - name: create_issue
        method: POST
        path: "/repos/{owner}/{repo}/issues"
        description: Create a new issue
        parameters:
          - name: owner
            type: string
            required: true
          - name: repo
            type: string
            required: true
          - name: title
            type: string
            required: true
          - name: body
            type: string
            required: false
            default: ""
        body_template:
          title: "{title}"
          body: "{body}"
        response_extract: "$.html_url"

initrunner init --template api --name weather-agent

tools:
  - type: delegate
    agents:
      - name: summarizer
        role_file: ./roles/summarizer.yaml
        description: "Summarizes long text"
      - name: researcher
        role_file: ./roles/researcher.yaml
        description: "Researches topics"
    mode: inline
    max_depth: 3
    timeout_seconds: 120

tools:
  - type: git
    repo_path: .
    read_only: true
    timeout_seconds: 30

tools:
  - type: shell
    allowed_commands: [kubectl, docker, curl]
    require_confirmation: false
    timeout_seconds: 30
    working_dir: .

tools:
  - type: slack
    channel: "#alerts"
    token: ${SLACK_TOKEN}