Tool Configuration

Kubiya tools can be configured with various options to control their behavior, environment, and dependencies. This page documents the configuration options available for tools.

Configuration Options

When creating a tool using the @kubiya.tool() decorator or the Tool model, you can specify the following configuration options:

Option	Description
name	The name of the tool, used for registration and execution
description	A human-readable description of the tool
image	The Docker image to use for the tool
command	The command to run in the container (defaults to the function implementation)
content	The script content to execute (alternative to command)
requirements	Python package requirements to install in the container
env	Environment variables to pass to the container
secrets	Secret values to pass to the container
with_files	Files to include in the container
on_build	Commands to run during container build
on_start	Commands to run when the container starts
timeout	Maximum execution time in seconds
required_configs	List of configuration objects required by the tool

Configuration Examples

Basic Configuration

Python

from kubiya_sdk import kubiya

@kubiya.tool(
    name="text-analyzer",
    description="Analyze text for sentiment and keywords",
    image="python:3.12-slim",
    requirements=["nltk", "textblob"]
)
def analyze_text(text: str) -> dict:
    """Analyze text for sentiment and keywords"""
    from textblob import TextBlob

    blob = TextBlob(text)
    sentiment = blob.sentiment

    return {
        "polarity": sentiment.polarity,
        "subjectivity": sentiment.subjectivity,
        "keywords": [word for word, pos in blob.tags() if pos.startswith('NN')]
    }

Environment Variables and Secrets

Python

from kubiya_sdk import kubiya

@kubiya.tool(
    name="api-client",
    description="Call an external API",
    image="python:3.12-slim",
    requirements=["requests"],
    env=["API_URL"],  # Environment variable from the runtime
    secrets=["API_KEY"]  # Secret from the secret store
)
def call_api(endpoint: str, method: str = "GET", body: dict = None) -> dict:
    """Call an external API endpoint"""
    import os
    import requests

    api_url = os.environ.get("API_URL", "https://api.example.com")
    api_key = os.environ.get("API_KEY", "")

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    url = f"{api_url}/{endpoint}"

    if method == "GET":
        response = requests.get(url, headers=headers)
    elif method == "POST":
        response = requests.post(url, headers=headers, json=body)
    elif method == "PUT":
        response = requests.put(url, headers=headers, json=body)
    elif method == "DELETE":
        response = requests.delete(url, headers=headers)
    else:
        return {"error": f"Unsupported method: {method}"}

    return response.json()

Including Files in the Container

Python

from kubiya_sdk import kubiya
from kubiya_sdk.tools.models import FileSpec

@kubiya.tool(
    name="custom-script",
    description="Run a custom script in the container",
    image="python:3.12-slim",
    with_files=[
        FileSpec(
            destination="/app/utils.py",
            content="""
def analyze(data):
    return {
        "processed": True,
        "count": len(data),
        "summary": data[:100] + "..." if len(data) > 100 else data
    }
"""
        ),
        FileSpec(
            destination="/app/config.json",
            content="""
{
    "version": "1.0",
    "settings": {
        "debug": true,
        "max_length": 1000
    }
}
"""
        )
    ]
)
def run_custom_script(data: str) -> dict:
    """Run a custom script in the container"""
    import json
    import sys
    sys.path.append("/app")

    from utils import analyze

    with open("/app/config.json", "r") as f:
        config = json.load(f)

    result = analyze(data)
    result["config_version"] = config["version"]
    result["debug"] = config["settings"]["debug"]

    return result

Build and Start Commands

Python

from kubiya_sdk import kubiya

@kubiya.tool(
    name="node-app",
    description="Run a Node.js application",
    image="node:18-slim",
    on_build="""
npm init -y
npm install express uuid
""",
    on_start="""
node /app/server.js &
""",
    with_files=[
        {
            "destination": "/app/server.js",
            "content": """
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const app = express();
const port = 3000;

app.use(express.json());

let items = [];

app.get('/items', (req, res) => {
  res.json(items);
});

app.post('/items', (req, res) => {
  const item = { id: uuidv4(), ...req.body };
  items.push(item);
  res.status(201).json(item);
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});
"""
        }
    ]
)
def node_api(action: str, data: dict = None) -> dict:
    """Interact with a Node.js API server"""
    import requests
    import time

    # Wait for server to start
    time.sleep(1)

    base_url = "http://localhost:3000"

    if action == "list":
        response = requests.get(f"{base_url}/items")
        return {"items": response.json()}
    elif action == "create":
        response = requests.post(f"{base_url}/items", json=data)
        return {"created": response.json()}
    else:
        return {"error": f"Unknown action: {action}"}

Dynamic Configuration

For more advanced configuration needs, see the Dynamic Configuration guide, which explains how to use runtime configuration values with tools.