Agentic Tools

Tools are the building blocks that empower Kubiya agents to interact with your systems and perform specific actions. By connecting agents to tools, you extend their capabilities beyond conversation to enable real operational tasks.

What Are Agentic Tools?

Agentic tools are containerized functions that agents can invoke to:

• Access external systems (cloud platforms, databases, ticketing systems)
• Execute scripts and commands
• Process data or perform calculations
• Implement business logic
• Interact with APIs

How Tools Work

When an agent determines that a tool is needed to fulfill a request:

1. The agent identifies which tool(s) to use
2. It prepares the necessary parameters based on the conversation context
3. The tool is executed in a controlled environment
4. Results are returned to the agent
5. The agent processes the results and continues the conversation

Tool Architecture

Tools in Kubiya are:

• Self-contained: Each tool runs in its own Docker container
• Stateless: Tools focus on specific operations without maintaining state
• Composable: Multiple tools can be combined for complex workflows
• Secure: Execution happens with defined permissions and boundaries
• Versioned: Tools are tracked and can be updated independently

Tool Anatomy

A typical tool definition includes:

name: aws-ec2-instance-manager
description: "Manages EC2 instances (create, start, stop, terminate)"
image: kubiya/aws-tools:latest
alias: ec2-manager
content: |
  # Tool implementation code (script, executable, etc.)
  # This can be a shell script, Python code, or other executable content
args:
  - name: action
    description: "Action to perform (create, start, stop, terminate)"
    required: true
    type: string
  - name: instance_id
    description: "ID of the EC2 instance"
    required: false
    type: string
env:
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY
  - AWS_REGION
with_volumes:
  - name: cache
    path: /cache
with_files:
  - source: $HOME/.aws/config
    destination: /root/.aws/config

Types of Tools

Kubiya supports various types of tools:

System Tools

• Execute shell commands
• Run scripts in various languages
• Access file systems

Integration Tools

• Connect to cloud providers (AWS, GCP, Azure)
• Interact with Kubernetes clusters
• Manage infrastructure

Application Tools

• Ticketing systems (Jira, ServiceNow)
• Version control (GitHub, GitLab)
• Monitoring systems (Datadog, Prometheus)

Custom Tools

• Organization-specific workflows
• Internal application APIs
• Business process automation

Building Custom Tools

You can extend Kubiya with your own custom tools:

1. Define the tool interface: Specify parameters, environment variables, and return values
2. Implement the logic: Create the code that will execute when the tool is invoked
3. Package in a container: Build a Docker image with your tool implementation
4. Register with Kubiya: Make the tool available to your agents

Managing Tools Using Tool Sources

Tool Sources provide a structured, version-controlled way to manage, distribute, and collaborate on agentic tools within the Kubiya platform. They enable DevOps principles for tool development including version control, collaboration, automation, and reusability.

How Tool Sources Work

When you connect a source to Kubiya:

1. The platform analyzes the repository contents
2. Tool definitions are discovered and validated
3. Tools are registered and made available to agents
4. Changes to the source are automatically synced on update

The Kubiya runner component continuously monitors connected sources and automatically updates tools when changes are detected.

Benefits of Tool Sources

Using Tool Sources provides several key advantages:

• Version Control: Track changes, manage releases, and maintain history
• Collaboration: Enable team development through pull requests and reviews
• Standardization: Enforce consistent tool structure and documentation
• CI/CD Integration: Automate testing and deployment workflows
• Centralized Management: Maintain tools in a single location with controlled access
• Reusability: Share tools across multiple agents and environments

Tool Source Structure

A well-organized Tool Source has a clear structure:

repository/
├── aws-tools/                     # Group related tools
│   ├── ec2-manager/               # Individual tool
│   │   ├── kubiya.yaml            # Tool definition
│   │   ├── Dockerfile             # Container definition
│   │   ├── README.md              # Documentation
│   │   └── src/                   # Implementation code
│   └── s3-manager/
│       ├── kubiya.yaml
│       └── src/
├── k8s-tools/
│   ├── deployment-manager/
│   │   ├── kubiya.yaml
│   │   └── src/
└── kubiya_bundle.json             # Generated by SDK

Discovery Methods

Kubiya supports multiple methods for tool discovery within sources:

1. Bundle-based Discovery

The Kubiya SDK's kubiya bundle command generates a kubiya_bundle.json file that indexes all tools in the repository. This is the recommended approach for complex sources.

# Generate the bundle file
kubiya bundle

2. Auto-discovery

For simpler sources, Kubiya can automatically discover tools by scanning for kubiya.yaml files or Python files with tool decorators.

Development Approaches

There are multiple approaches to creating tools for your sources:

Python SDK

The Kubiya Python SDK provides a decorator-based approach:

from kubiya import tool
 
@tool
def aws_s3_list_buckets(region: str = "us-east-1"):
    """
    Lists all S3 buckets in the specified AWS region.
    
    Args:
        region: AWS region to check (default: us-east-1)
        
    Returns:
        List of S3 bucket names
    """
    import boto3
    client = boto3.client('s3', region_name=region)
    response = client.list_buckets()
    return [bucket['Name'] for bucket in response['Buckets']]

YAML Definition

You can define tools using YAML configuration:

name: aws-s3-list-buckets
description: "Lists all S3 buckets in the specified AWS region"
image: kubiya/aws-tools:latest
content: |
  #!/usr/bin/env python3
  import boto3
  import json
  import os
  
  region = os.environ.get('REGION', 'us-east-1')
  client = boto3.client('s3', region_name=region)
  response = client.list_buckets()
  buckets = [bucket['Name'] for bucket in response['Buckets']]
  
  print(json.dumps({"buckets": buckets}))
args:
  - name: region
    description: "AWS region to check"
    required: false
    default: "us-east-1"
    type: string
env:
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY

Connecting Sources

You can connect Tool Sources to Kubiya using various methods:

CLI

# Add a source from a Git repository
kubiya source add --name "aws-tools" --url "https://github.com/org/aws-tools"
 
# Sync changes from a source
kubiya source sync aws-tools

Web UI

Sources can be added and managed through the Kubiya Web interface under the Sources section.

Terraform

For infrastructure-as-code workflows:

resource "kubiya_source" "aws_tools" {
  name        = "aws-tools"
  description = "AWS automation tools"
  url         = "https://github.com/org/aws-tools"
  branch      = "main"
  sync_interval = "30m"
  
  credentials {
    type = "ssh_key"
    key  = var.github_ssh_key
  }
}

CI/CD Integration

Tool Sources can be integrated into CI/CD pipelines for automated testing and deployment:

# Example GitHub Actions workflow
name: Kubiya Tool CI/CD
 
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install kubiya-sdk pytest
      - name: Validate tools
        run: kubiya bundle --validate
      - name: Run tests
        run: pytest tests/
  
  sync:
    needs: test
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - name: Sync Kubiya Source
        uses: kubiya/source-sync-action@v1
        with:
          source_id: ${{ secrets.KUBIYA_SOURCE_ID }}
          api_key: ${{ secrets.KUBIYA_API_KEY }}

Best Practices for Tool Sources

When working with Tool Sources, follow these best practices:

• Organize logically: Group related tools together
• Document thoroughly: Include READMEs and inline documentation
• Test rigorously: Write tests for all tools
• Version appropriately: Use semantic versioning for releases
• Minimize dependencies: Keep tools focused and lightweight
• Secure secrets: Never hardcode sensitive information

Next Steps

• Explore Knowledge Sources to improve agent context
• Learn about Agents that use tools