kubiya_agent

The kubiya_agent resource allows you to create and manage AI agents in the Kubiya platform. Agents are intelligent assistants that can perform various tasks, integrate with external systems, and execute workflows.

Agents are the core building blocks of your Kubiya automation. They can be configured with specific tools, integrations, and access controls to match your organization’s needs.

Prerequisites

Before using this resource, ensure you have:

A Kubiya account with API access
An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
At least one runner configured (or use “kubiya-hosted” for cloud execution)

Quick Start

resource "kubiya_agent" "basic_agent" {
  name         = "my-basic-agent"
  runner       = "kubiya-hosted"
  description  = "A basic AI assistant for general tasks"
  instructions = "You are a helpful AI assistant. Provide clear and concise responses to user queries."
}

Configuration Examples

Configure an agent with predefined tasks that users can execute:

resource "kubiya_agent" "ops_agent" {
  name         = "operations-agent"
  runner       = "kubiya-hosted"
  description  = "Operations management agent"
  instructions = "You are an operations agent that helps with infrastructure management tasks."
  
  tasks = [
    {
      name        = "check-cluster-health"
      prompt      = "Check the health status of all Kubernetes clusters and report any issues"
      description = "Performs comprehensive health checks on K8s clusters"
    },
    {
      name        = "scale-deployment"
      prompt      = "Scale the specified deployment to the requested number of replicas"
      description = "Scales Kubernetes deployments"
    },
    {
      name        = "backup-database"
      prompt      = "Create a backup of the specified database and store it in S3"
      description = "Performs database backup operations"
    }
  ]
  
  integrations = ["kubernetes", "aws"]
}

Advanced Configurations

Agent with Inline Tools

Create an agent with custom tools defined directly in the configuration:

resource "kubiya_source" "inline_tools" {
  name = "custom-tools"
  
  tools = jsonencode([
    {
      name        = "disk-usage-checker"
      description = "Check disk usage on servers"
      type        = "docker"
      image       = "alpine:latest"
      content     = "df -h"
    },
    {
      name        = "log-analyzer"
      description = "Analyze application logs"
      type        = "docker"
      image       = "python:3.11-slim"
      with_files = [
        {
          destination = "/analyze.py"
          content     = <<-PYTHON
            import sys
            import json
            
            def analyze_logs(log_file):
                errors = []
                warnings = []
                with open(log_file, 'r') as f:
                    for line in f:
                        if 'ERROR' in line:
                            errors.append(line.strip())
                        elif 'WARNING' in line:
                            warnings.append(line.strip())
                
                return {
                    'total_errors': len(errors),
                    'total_warnings': len(warnings),
                    'errors': errors[:10],
                    'warnings': warnings[:10]
                }
            
            if __name__ == "__main__":
                result = analyze_logs('/var/log/app.log')
                print(json.dumps(result, indent=2))
          PYTHON
        }
      ]
      content = "python /analyze.py"
    }
  ])
  
  runner = "kubiya-hosted"
}

resource "kubiya_agent" "agent_with_tools" {
  name         = "monitoring-agent"
  runner       = "kubiya-hosted"
  description  = "System monitoring agent with custom tools"
  instructions = "You are a monitoring agent with access to custom tools for system analysis."
  
  tool_sources = [kubiya_source.inline_tools.id]
}

Agent with Workflow Execution

Configure an agent that can execute complex, multi-step workflows:

resource "kubiya_source" "deployment_workflow" {
  name = "deployment-workflows"
  
  workflows = jsonencode([
    {
      name        = "blue-green-deployment"
      description = "Perform blue-green deployment"
      steps = [
        {
          name        = "prepare-green-env"
          description = "Prepare green environment"
          executor = {
            type = "command"
            config = {
              command = "kubectl apply -f green-deployment.yaml"
            }
          }
        },
        {
          name        = "health-check"
          description = "Check green environment health"
          depends     = ["prepare-green-env"]
          executor = {
            type = "command"
            config = {
              command = "kubectl wait --for=condition=ready pod -l version=green --timeout=300s"
            }
          }
        },
        {
          name        = "switch-traffic"
          description = "Switch traffic to green environment"
          depends     = ["health-check"]
          executor = {
            type = "command"
            config = {
              command = "kubectl patch service myapp -p '{\"spec\":{\"selector\":{\"version\":\"green\"}}}'"
            }
          }
        }
      ]
    }
  ])
  
  runner = "kubiya-hosted"
}

resource "kubiya_agent" "deployment_agent" {
  name         = "deployment-automation"
  runner       = "kubiya-hosted"
  description  = "Automated deployment agent"
  instructions = <<-EOT
    You are a deployment automation agent. You can:
    1. Execute blue-green deployments
    2. Perform rollbacks if needed
    3. Monitor deployment status
    
    Always verify the target environment before deploying.
  EOT
  
  sources = [kubiya_source.deployment_workflow.id]
  integrations = ["kubernetes", "slack_integration"]
}

Arguments Reference

Required Arguments

name

string

required

The name of the agent. Must be unique within your organization.

runner

string

required

The runner to use for agent execution. Use “kubiya-hosted” for cloud execution or specify your own runner name.

description

string

required

A detailed description of the agent’s purpose and capabilities.

instructions

string

required

System instructions that define the agent’s behavior and capabilities. These instructions guide how the agent responds to user queries and executes tasks.

Optional Arguments

model

string

default:"gpt-4o"

The LLM model to use for the agent. Available options:

gpt-4o - GPT-4 Optimized (recommended)
gpt-4 - GPT-4
gpt-3.5-turbo - GPT-3.5 Turbo
azure/gpt-4 - Azure OpenAI GPT-4

image

string

default:"ghcr.io/kubiyabot/kubiya-agent:stable"

Docker image for the agent runtime environment. Use custom images for specialized functionality.

is_debug_mode

boolean

default:"false"

Enable debug mode for detailed logging and troubleshooting.

integrations

array

List of integration names the agent can access. Must match exactly with configured integrations in your Kubiya account.

users

array

List of user emails who can access the agent. If not specified, the agent is accessible to all organization members.

groups

array

List of group names that can access the agent. Use for team-based access control.

sources

array

List of source IDs for knowledge bases and workflows that the agent can utilize.

tool_sources

array

List of tool source URLs or IDs. These provide the agent with additional capabilities and tools.

secrets

array

List of secret names the agent can access for secure operations.

environment_variables

object

Map of environment variables available to the agent during execution.

tasks

array

List of predefined tasks that users can execute. Each task object contains:

tasks.name

string

required

Task identifier used for execution.

tasks.prompt

string

required

The prompt that will be executed when the task is triggered.

tasks.description

string

required

Human-readable description of what the task does.

starters

array

List of conversation starters for improved user experience. Each starter object contains:

starters.name

string

required

Display name for the conversation starter.

starters.command

string

required

Command that will be executed when the starter is selected.

links

array

List of reference links that provide additional context or documentation for the agent.

Attributes Reference

In addition to all arguments above, the following attributes are exported:

string

The unique identifier of the agent.

owner

string

The email of the user who created the agent.

created_at

string

The timestamp when the agent was created.

Import

Agents can be imported using their ID:

terraform import kubiya_agent.example <agent-id>

Best Practices

Security

Store sensitive information in secrets, not in environment variables
Use specific access controls with users and groups
Regularly audit agent permissions and access patterns

Performance

Choose the appropriate model for your use case (balance cost vs capability)
Use custom Docker images for specialized environments
Enable debug mode only when troubleshooting

Maintenance

Use descriptive names that indicate the agent’s purpose
Include comprehensive instructions to ensure consistent behavior
Store Terraform configurations in version control
Test agents in non-production runners first

User Experience

Provide clear conversation starters for common tasks
Use groups for team-based access rather than individual users
Include helpful links and documentation references

Compatibility

Requirements:

Kubiya Terraform Provider version >= 1.0.0
Terraform >= 1.0
Some features may require specific Kubiya platform tier (Enterprise features)

Important Considerations:

Custom Docker images must be accessible from the runner environment
Integration names must match exactly with configured integrations in your Kubiya account
Debug mode should not be used in production environments

Troubleshooting

Agent Not Responding

Integration Access Issues

Custom Docker Image Issues

Getting Started

Resources

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Optional Arguments

Attributes Reference

Import

Best Practices

Security

Performance

Maintenance

User Experience

Compatibility

Troubleshooting

Getting Started

Resources

​Prerequisites

​Quick Start

​Configuration Examples

​Advanced Configurations

​Arguments Reference

​Required Arguments

​Optional Arguments

​Attributes Reference

​Import

​Best Practices

Security

Performance

Maintenance

User Experience

​Compatibility

​Troubleshooting

Prerequisites

Quick Start

Configuration Examples

Advanced Configurations

Arguments Reference

Required Arguments

Optional Arguments

Attributes Reference

Import

Best Practices

Compatibility

Troubleshooting