Agent Development

Agents are the core components of the Codebolt ecosystem. They are intelligent assistants that can perform specific tasks, manage software development lifecycle (SDLC) steps, and provide specialized functionality. This guide covers how to create, manage, and deploy agents using the Codebolt CLI.

What are Codebolt Agents?

Codebolt Agents are configurable AI assistants that:

• Handle SDLC Steps: Manage specific phases of software development
• Provide Actions: Offer shortcuts and functionality via \ commands
• Support Multiple Languages: Work with various programming languages and frameworks
• Integrate Seamlessly: Connect with the Codebolt platform and other agents
• Customize Behavior: Adapt to specific project needs and workflows

Agent Architecture

Core Components

# codeboltagent.yaml
title: "My Agent"
description: "Agent description"
unique_id: "my-unique-agent-id"
tags: ["tag1", "tag2"]

metadata:
  agent_routing:
    worksonblankcode: true
    worksonexistingcode: true
    supportedlanguages: ["javascript", "python"]
    supportedframeworks: ["react", "express"]
  
  sdlc_steps_managed:
    - name: "Code Generation"
      example_instructions:
        - "Generate a new React component"
        - "Create API endpoints"

actions:
  - name: "Quick Setup"
    description: "Set up project structure"
    detailDescription: "Creates initial project files and configuration"
    actionPrompt: "Initialize the project with best practices"

Directory Structure

my-agent/
├── codeboltagent.yaml    # Agent configuration
├── package.json          # Node.js dependencies
├── index.js             # Main agent logic
├── README.md            # Agent documentation
├── .gitignore           # Git ignore rules
└── src/                 # Source code
    ├── actions/         # Action implementations
    ├── utils/           # Utility functions
    └── templates/       # Code templates

Creating Agents

Interactive Creation

Create a new agent with the interactive wizard:

codebolt-cli createagent

The wizard will guide you through:

1. Basic Information

   • Agent name and description
   • Unique identifier
   • Tags for categorization

2. Agent Routing Configuration

   • Supported languages and frameworks
   • Blank vs existing code compatibility
   • Target use cases

3. SDLC Steps Management

   • Development phases the agent handles
   • Example instructions for each step

4. Actions Definition

   • Shortcut commands the agent provides
   • Action descriptions and prompts

Quick Creation

For rapid development, use the quick mode:

codebolt-cli createagent --name "My Agent" --quick

This creates an agent with default settings that you can customize later.

Command Options

codebolt-cli createagent [options]

Options:
  -n, --name <name>    Name of the agent
  --quick             Create with default settings
  -h, --help          Display help information

Agent Configuration

Basic Metadata

title: "React Component Generator"
description: "Generates React components with TypeScript support"
unique_id: "react-component-generator"
tags: ["react", "typescript", "components"]
version: "1.0.0"

Agent Routing

Configure how the Universal Agent Router selects your agent:

metadata:
  agent_routing:
    worksonblankcode: true        # Works on new projects
    worksonexistingcode: true     # Works on existing codebases
    supportedlanguages:           # Programming languages
      - "javascript"
      - "typescript"
    supportedframeworks:          # Frameworks and libraries
      - "react"
      - "next.js"
      - "vite"

SDLC Steps

Define which development phases your agent manages:

metadata:
  sdlc_steps_managed:
    - name: "Code Generation"
      example_instructions:
        - "Create a new React component with props interface"
        - "Generate a custom hook for data fetching"
        - "Build a form component with validation"
    
    - name: "Testing"
      example_instructions:
        - "Write unit tests for the component"
        - "Create integration tests"
        - "Add snapshot tests"

Actions

Define shortcut commands users can invoke:

actions:
  - name: "component"
    description: "Generate React component"
    detailDescription: "Creates a new React component with TypeScript interfaces"
    actionPrompt: "Generate a React component with the specified props and styling"
  
  - name: "hook"
    description: "Create custom hook"
    detailDescription: "Generates a reusable React hook"
    actionPrompt: "Create a custom React hook for the specified functionality"

Agent Lifecycle Management

Publishing Agents

Publish your agent to the Codebolt platform:

# Publish from current directory
codebolt-cli publishagent

# Publish specific folder
codebolt-cli publishagent ./my-agent

The publish process:

1. Validates agent configuration
2. Packages agent files
3. Uploads to the platform
4. Makes agent available for use

Listing Your Agents

View all your published agents:

codebolt-cli listagents

Output includes:

• Agent names and descriptions
• Unique identifiers
• Publication status
• Last update timestamps

Pulling Agent Updates

Sync the latest version of an agent:

# Pull to current directory
codebolt-cli pullagent

# Pull to specific directory
codebolt-cli pullagent ./my-agent

Starting Agents

Run an agent locally for development:

# Start in current directory
codebolt-cli startagent

# Start in specific directory
codebolt-cli startagent ./my-agent

Cloning Agents

Clone an existing agent for customization:

# Clone to current directory
codebolt-cli cloneagent agent-unique-id

# Clone to specific directory
codebolt-cli cloneagent agent-unique-id ./my-custom-agent

Development Best Practices

Agent Design Principles

1. Single Responsibility: Each agent should focus on specific tasks
2. Clear Documentation: Provide comprehensive README and inline comments
3. Flexible Configuration: Support customization through parameters
4. Error Handling: Implement robust error handling and user feedback
5. Testing: Include unit and integration tests

Code Organization

// index.js - Main agent entry point
const { Agent } = require('@codebolt/agent-sdk');

class MyAgent extends Agent {
  constructor(config) {
    super(config);
    this.setupActions();
  }

  setupActions() {
    this.registerAction('component', this.generateComponent.bind(this));
    this.registerAction('hook', this.generateHook.bind(this));
  }

  async generateComponent(params) {
    // Component generation logic
  }

  async generateHook(params) {
    // Hook generation logic
  }
}

module.exports = MyAgent;

Configuration Management

// config/default.js
module.exports = {
  templates: {
    component: './templates/component.template',
    hook: './templates/hook.template'
  },
  
  defaults: {
    typescript: true,
    styling: 'css-modules',
    testing: 'jest'
  }
};

Template System

// templates/component.template
import React from 'react';
{{#if typescript}}
interface {{componentName}}Props {
  {{#each props}}
  {{name}}: {{type}};
  {{/each}}
}
{{/if}}

const {{componentName}}: React.FC<{{#if typescript}}{{componentName}}Props{{/if}}> = ({{#if props}}{ {{#each props}}{{name}}{{#unless @last}}, {{/unless}}{{/each}} }{{/if}}) => {
  return (
    <div className="{{kebabCase componentName}}">
      {/* Component content */}
    </div>
  );
};

export default {{componentName}};

Testing Agents

Local Testing

Test your agent locally before publishing:

# Start agent in development mode
npm run dev

# Run agent tests
npm test

# Test specific functionality
npm run test:actions

Integration Testing

Test agent integration with the platform:

# Test agent routing
codebolt-cli test-routing ./my-agent

# Validate configuration
codebolt-cli validate ./my-agent

# Test actions
codebolt-cli test-actions ./my-agent

Advanced Features

Custom Dependencies

Add specialized dependencies to your agent:

{
  "dependencies": {
    "@codebolt/agent-sdk": "^1.0.0",
    "handlebars": "^4.7.7",
    "prettier": "^2.8.0",
    "typescript": "^4.9.0"
  }
}

Environment Configuration

Support different environments:

# codeboltagent.yaml
environments:
  development:
    debug: true
    verbose_logging: true
  
  production:
    debug: false
    performance_monitoring: true

Plugin System

Extend agent functionality with plugins:

// plugins/prettier-plugin.js
class PrettierPlugin {
  format(code, options) {
    return prettier.format(code, options);
  }
}

// Register plugin
agent.use(new PrettierPlugin());

Troubleshooting

Common Issues

Configuration Errors

Error: Invalid codeboltagent.yaml format

Solution: Validate YAML syntax and required fields.

Publishing Failures

Error: Agent validation failed

Solution: Check agent configuration and ensure all required files are present.

Runtime Errors

Error: Action 'component' not found

Solution: Verify action registration and implementation.

Debugging

Enable debug mode for detailed logging:

DEBUG=codebolt:* codebolt-cli startagent

Examples

Simple Component Generator

title: "Component Generator"
description: "Generates React components"
unique_id: "simple-component-generator"

actions:
  - name: "component"
    description: "Create React component"
    actionPrompt: "Generate a React component"

Full-Stack Agent

title: "Full-Stack Developer"
description: "Handles frontend and backend development"
unique_id: "fullstack-developer"

metadata:
  agent_routing:
    supportedlanguages: ["javascript", "typescript", "python"]
    supportedframeworks: ["react", "express", "fastapi"]
  
  sdlc_steps_managed:
    - name: "Code Generation"
    - name: "API Development"
    - name: "Database Design"
    - name: "Testing"
    - name: "Deployment"

Next Steps

• Learn about tool development
• Explore the complete command reference
• See practical examples
• Understand the agent SDK