Usage

Structure

tools:
  - id: string # Unique identifier for the tool
    use: string | object # Tool reference (shorthand or detailed)
    config: object # Tool-specific configuration
    env: object # Tool-specific environment variables
    import: string # Path to external tool definition file

    # Inline tool definition
    execute: string # TypeScript or Python code to run
    schema: object # Schema for the tool's input and output
      config: object # Tool-specific configuration
      input: object # Schema for the tool's input parameters
      output: object # Schema for the tool's output format

Basic Usage

Tools can be used in three main ways:

tools:
  - id: crypto_price
    use: compozy/tools:crypto-price@1.0.0

tools:
  - id: blockchain_scanner
    use:
      repo: compozy/tools
      package: blockchain-scanner
      version: 0.2.1

tools:
  - id: custom_tool
    use: ./tools/custom.yaml

Each tool can be configured using the config property and environment variables:

tools:
  - id: crypto_price
    use: compozy/tools:crypto-price
    config:
      api_key: "{{ env.API_KEY }}"
      currency: "USD"
    env:
      API_KEY: "your-api-key"

Inline Definitions

Tools can be defined inline using either TypeScript or Python code directly in your workflow. Each tool must export a run() function that contains the tool’s logic.

TypeScript
Python

tools:
  - id: double
    execute: |
      export function run(input: { value: number }) {
        return {
          result: input.value * 2
        };
      }
    schema:
      input:
        type: object
        properties:
          value:
            type: number
            description: "Value to double"
        required: [value]
      output:
        type: object
        properties:
          result:
            type: number
            description: "The doubled value"
        required: [result]

Deno Modules

You can use Deno modules in your tool’s TypeScript code:

import { crypto } from "jsr:@std/crypto";
import lodash from "npm:lodash";

tools:
  - id: double
    execute: |
      from typing import TypedDict

      class Input(TypedDict):
          value: float

      class Output(TypedDict):
          result: float

      def run(input: Input) -> Output:
          return {
              "result": input["value"] * 2
          }
    schema:
      input:
        type: object
        properties:
          value:
            type: number
            description: "Value to double"
        required: [value]
      output:
        type: object
        properties:
          result:
            type: number
            description: "The doubled value"
        required: [result]

Python Packages

You can use Python packages in your tool by specifying them in your tool’s requirements:

import numpy as np
from pandas import DataFrame

Schema Definition

When creating a tool, you define three types of schemas:

Configuration Schema

Defines the structure of the config object

Input Schema

Defines the structure of runtime parameters (used with with)

Output Schema

Defines the structure of the tool’s output

Here’s an example of a tool definition:

tools:
  - id: crypto_price
    execute: |
      type Input = {
        symbol: string
      }

      type Config = {
        api_key: string
        currency?: string
      }

      export function run(input: Input, config: Config) {
        return {
          price: 0,
          currency: config.currency || 'USD'
        };
      }
    schema:
      config:
        type: object
        properties:
          api_key:
            type: string
            description: "API key for the cryptocurrency data provider"
          currency:
            type: string
            description: "Default currency for price conversion"
            default: "USD"
        required: [api_key]

      input:
        type: object
        properties:
          symbol:
            type: string
            description: "Cryptocurrency symbol (e.g., BTC, ETH)"
        required: [symbol]

      output:
        type: object
        properties:
          price:
            type: number
            description: "Current price of the cryptocurrency"
          currency:
            type: string
            description: "Currency of the price"
        required: [price, currency]

tools:
  - id: crypto_price
    execute: |
      from typing import TypedDict
      from typing import Optional

      class Input(TypedDict):
          symbol: str

      class Config(TypedDict):
          api_key: str
          currency: Optional[str]

      def run(input: Input, config: Config):
          return {
              "price": 0,
              "currency": config.get("currency", "USD")
          }
    schema:
      config:
        type: object
        properties:
          api_key:
            type: string
            description: "API key for the cryptocurrency data provider"
          currency:
            type: string
            description: "Default currency for price conversion"
            default: "USD"
        required: [api_key]

      input:
        type: object
        properties:
          symbol:
            type: string
            description: "Cryptocurrency symbol (e.g., BTC, ETH)"
        required: [symbol]

      output:
        type: object
        properties:
          price:
            type: number
            description: "Current price of the cryptocurrency"
          currency:
            type: string
            description: "Currency of the price"
        required: [price, currency]

This tool can then be used like this:

tools:
  - id: price_checker
    use: ./crypto_price
    config:
      api_key: {{ env.API_KEY }}    # Matches config schema
      currency: "EUR"            # Optional config parameter

tasks:
  - id: check_price
    use: tool(price_checker)
    with:
      symbol: "BTC"             # Matches input schema

Key Points

Configuration Schema

The config schema defines persistent configuration options that are set when the tool is initialized.

Input & Output Schema

The input and output schemas define runtime parameters and the tool’s output.

Schema Format

Both configuration and input schemas use JSON Schema for validation and documentation.

Run Function Parameters

The run() function receives both input and config parameters during execution.

Required Fields

Required fields must be specified in the respective required arrays within each schema definition.

Best Practices

Tool Organization

Use clear, descriptive tool IDs
Group related tools together
Document tool-specific configuration

Configuration Management

Use environment variables for sensitive data
Set sensible defaults in tool definitions
Override only necessary config at usage points

Error Handling

Always check tool error outputs
Provide fallback behavior where appropriate
Log tool execution metadata for debugging

Security

Never expose sensitive credentials in tool code
Validate and sanitize all inputs
Follow security best practices for external services

References

Deno Runtime - The JavaScript/TypeScript runtime used by Compozy
Python Documentation - Official Python documentation
JSON Schema - The schema format used for tool configuration and input/output
Deno Standard Library - Built-in modules available for TypeScript tools
Python Standard Library - Built-in modules available for Python tools
JSR (JavaScript Registry) - Package registry for Deno modules
PyPI - Python Package Index for Python modules

Getting Started

Core Concepts

Structure

Basic Usage

Inline Definitions

Deno Modules

Python Packages

Schema Definition

Key Points

Best Practices

References

​Structure

​Basic Usage

​Inline Definitions

​Deno Modules

​Python Packages

​Schema Definition

​Key Points

​Best Practices

​References

Structure

Basic Usage

Inline Definitions

Deno Modules

Python Packages

Schema Definition

Key Points

Best Practices

References