Project Structure

Kodey.ai provides a comprehensive framework for building, configuring, and deploying AI agents with their associated tools and LLM integrations. Understanding the project structure is essential for effectively developing and customizing your agents.

Directory Organization

The Kodey.ai agent framework follows a modular architecture that separates concerns between agents, tools, and language models:

.
├── README.md                 # Project documentation
├── __init__.py               # Package initializer
├── agents/                   # Core agent implementations
│   ├── __init__.py
│   ├── assistant_agent.py    # Conversational assistant agent
│   ├── data_agent.py         # Data processing agent
│   └── workflow_agent.py     # Workflow automation agent
├── tools/                    # Tool integrations for agents
│   ├── __init__.py
│   ├── data_connectors/      # Data source connectors
│   │   ├── __init__.py
│   │   ├── database.py       # Database connection tools
│   │   └── api_client.py     # API integration tools
│   ├── file_operations/      # File handling tools
│   │   ├── __init__.py
│   │   └── file_tools.py     # File read/write utilities
│   └── web_tools/            # Web interaction tools
│       ├── __init__.py
│       ├── browser.py        # Web browsing capabilities
│       └── scraper.py        # Content extraction tools
├── models/                   # LLM configurations and adapters
│   ├── __init__.py
│   ├── model_manager.py      # Central model management
│   └── model_adapters/       # Model-specific adapters
│       ├── __init__.py
│       ├── anthropic.py      # Anthropic Claude adapter
│       ├── openai.py         # OpenAI GPT adapter
│       └── local.py          # Local model adapter
├── config/                   # Configuration files
│   ├── __init__.py
│   ├── agent_config.yaml     # Agent configuration
│   └── platform_config.yaml  # Platform settings
├── supervisor.py             # Agent orchestration system
└── .env                      # Environment variables and secrets

Core Components

Agents

The agents/ directory contains different agent implementations that serve various purposes:

• Assistant Agent: Handles conversational interactions and user requests
• Data Agent: Specializes in data analysis and processing tasks
• Workflow Agent: Manages complex workflow automation sequences

Each agent can be customized or extended to fit specific use cases.

Tools

The tools/ directory houses modular capabilities that agents can leverage:

• Data Connectors: Integrations with databases, APIs, and data sources
• File Operations: Utilities for reading, writing, and managing files
• Web Tools: Capabilities for web browsing, scraping, and interaction

Adding custom tools is as simple as creating a new module in the appropriate subdirectory.

Models

The models/ directory manages language model integrations:

• Model Manager: Handles model selection, fallbacks, and optimization
• Model Adapters: Provides standardized interfaces to different LLM providers

This abstraction allows you to easily switch between different model providers or use multiple models simultaneously.

Configuration

The config/ directory contains YAML files for configuring the behavior of:

• Agent Configuration: Defines agent capabilities, permissions, and defaults
• Platform Configuration: Controls deployment settings and platform integration

Supervisor

The supervisor.py file orchestrates the interaction between agents, handling:

• Command routing and delegation
• Tool access management
• Error handling and recovery
• Multi-agent coordination

Customization Points

When developing with Kodey.ai, you'll typically modify these key areas:

1. Adding Custom Tools:

   • Create a new file in the appropriate tools subdirectory
   • Implement the BaseTool interface
   • Register your tool with the agent configuration

2. Extending Agents:

   • Subclass one of the base agent types
   • Override methods to customize behavior
   • Configure tool access and permissions

3. Configuring Models:

   • Update model settings in configuration files
   • Create custom model adapters for specialized providers
   • Set up model fallback chains

4. Environment Variables:

   • Store API keys and credentials in the .env file
   • Reference sensitive information via environment variables

Example: Custom Tool Implementation

Here's how to implement a custom tool for Kodey.ai:

# tools/custom_category/my_tool.py
from kodey.tools import BaseTool

class MyCustomTool(BaseTool):
    """A custom tool that performs a specific function."""
    
    name = "my_custom_tool"
    description = "Performs a specialized operation for specific use cases"
    
    def _run(self, input_data: str) -> str:
        """Execute the tool functionality."""
        # Implement your custom logic here
        result = process_input(input_data)
        return result
        
    async def _arun(self, input_data: str) -> str:
        """Execute the tool asynchronously."""
        # Implement async version if needed
        result = await async_process_input(input_data)
        return result

Agent Configuration Example

# config/agent_config.yaml
agent:
  name: "customer_support_agent"
  description: "Handles customer inquiries and support requests"
  type: "assistant"
  
  tools:
    - name: "knowledge_base_search"
      enabled: true
      config:
        database_url: "${KB_DATABASE_URL}"
        max_results: 5
        
    - name: "ticket_creator"
      enabled: true
      config:
        system: "zendesk"
        priority_levels: ["low", "medium", "high", "urgent"]
        
  model:
    provider: "anthropic"
    model_name: "claude-3-sonnet"
    fallback_provider: "openai"
    fallback_model: "gpt-4"
    
  memory:
    type: "conversation_buffer"
    max_tokens: 4000

Best Practices

When working with the Kodey.ai project structure:

1. Keep Tools Modular: Design tools to perform specific, focused tasks
2. Leverage Config Files: Use configuration rather than hardcoding settings
3. Separate Concerns: Maintain separation between agents, tools, and models
4. Test Independently: Write tests for each component in isolation
5. Document Thoroughly: Provide clear documentation for custom components

Following these practices ensures your Kodey.ai implementation remains maintainable and scalable as your agent ecosystem grows.