# Kodey.ai Documentation

> Kodey.ai is an agentic AI platform for building, deploying, and managing AI agents without coding. This document contains comprehensive documentation for customers and developers.

## What is Kodey.ai?

Kodey.ai is a comprehensive agentic AI platform designed primarily for non-developers to easily build, run, and deploy powerful AI agents without coding experience. It also provides advanced APIs and SDKs for developers who want to create custom solutions.

### Core Value Proposition

- Build AI agents through intuitive visual interfaces (no code required)
- Deploy production-ready agents with enterprise-grade reliability
- Scale your AI capabilities without infrastructure hassles
- Multi-channel deployment: API, WebSocket, and embeddable HTML widgets

### Key Features

| Feature | Description |
|---------|-------------|
| Visual Agent Builder | Drag-and-drop interface for non-technical users |
| Multi-Agent Systems | Supervisor agent coordinates specialized sub-agents |
| Knowledge Base | Upload documents (PDF, Word, TXT, CSV) to train agents |
| Enterprise Security | Containerized deployment with access controls |
| Auto-Scaling | Automatically scales based on demand |
| Version Control | Track changes and rollback agent configurations |
| Real-Time Chat | WebSocket support for interactive experiences |
| HTML Widget | Embed agents directly in websites |

---

## Getting Started

### Step 1: Create Account
1. Go to https://dashboard.kodey.ai/signup
2. Create account and enter payment information

### Step 2: Set Up Your Team
1. Navigate to Team section in dashboard
2. Use Add/Invite Member to add team members
3. Optionally rename your team in Settings

### Step 3: Configure LLM API Key
1. Go to Settings > Supervisor Settings
2. Select your model (e.g., GPT-4.0)
3. Enter your OpenAI or Anthropic API key
4. Click Save Settings

### Step 4: Create Your First Agent
1. Navigate to Agents menu
2. Click Create Agent
3. Name your agent (e.g., "Customer Support Bot")
4. Select the model and configure settings

### Step 5: Configure the Agent
1. Open agent and click Agent Settings
2. Upload relevant files under Files tab
3. Write a prompt describing the agent's role
4. Click Update Agent

### Step 6: Test the Agent
1. Use the chat window to test
2. Ask the agent to perform relevant tasks
3. Refine prompts based on responses

---

## Multi-Agent Architecture

Kodey.ai uses a multi-agent system where a supervisor agent coordinates with specialized sub-agents.

### System Components

1. **Supervisor Agent**: Routes user messages to appropriate sub-agents
2. **Sub-Agents**: Specialized agents for specific tasks or domains
3. **Routing Logic**: Rules determining which agent handles each message

### Benefits

- Specialized expertise per agent
- Cleaner, more maintainable prompts
- Better performance on specific tasks
- Easier updates and maintenance

### Default Supervisor Prompt

```
You are a supervisor being tasked to route/choose one worker among all options.
Respond with the worker to act next followed by its reasoning.
When everything is done, respond with finish.
```

**Important**: Always keep this default text as the foundation. Add customizations around it, never remove the core instructions.

### Customizing Routing

Add XML tags to organize routing conditions:

```xml
<normal_flow>
For normal conversations, use the COACH agent.
</normal_flow>

<special_flow>
For detailed analysis requests, use the ANALYST agent.
</special_flow>
```

---

## Prompting Guide

### Agent Prompt Structure

Follow the three-part structure:

1. **Description**: Agent's identity and purpose
2. **Notes**: Guidelines and constraints
3. **Actions**: Specific behaviors expected

### Example Agent Prompt

```xml
<description>
You are [Name], an expert in [domain]. You help users with [specific tasks].
</description>

<notes>
- Always be helpful and professional
- Ask clarifying questions when needed
- Never provide medical/legal advice
</notes>

<actions>
1. Greet the user warmly
2. Understand their request
3. Provide helpful guidance
4. Ask if they need anything else
</actions>
```

### XML Tags Best Practices

- Use descriptive tag names (e.g., `<identity>`, `<tone>`, `<actions>`)
- Keep naming consistent across prompts
- Close all tags properly
- Don't overuse tags - only for meaningful separations

### Prompting Best Practices

1. **Be Specific**: Clear instructions produce better results
2. **Include Examples**: Show ideal responses
3. **Define Tone**: Specify formality level and style
4. **Set Boundaries**: Define what agent should NOT do
5. **Test Thoroughly**: Try various inputs and edge cases
6. **Iterate**: Refine prompts based on real usage

---

## Knowledge Base

### Supported File Formats

- Text files (.txt)
- Word documents (.doc, .docx)
- PDF documents (.pdf)
- CSV files (.csv)

### Not Supported

- Video files (.mp4, .mov)
- PowerPoint (.ppt, .pptx)
- Excel spreadsheets (.xls, .xlsx)
- Image files (.jpg, .png)

### Best Practices

1. Use clear headings and structured formatting
2. Ensure PDFs have selectable text (not images)
3. Include clear column headers in CSVs
4. Organize files with descriptive names

### Using Knowledge in Prompts

Add this rule to ensure agents access the knowledge base:

```
RULE: You MUST call the AgentKnowledgeTool to answer questions. Never output 'Final Answer:' until after a tool has been used.
```

---

## Kodey API

**Base URL**: `https://pooled.api.kodey.ai`

### Authentication

All requests require the `x-api-key` header:

```http
x-api-key: <your_api_key>
```

### API Key Types

| Key Type | Prefix | Use Case |
|----------|--------|----------|
| Publishable Key | `pk_live_` | Client-side chat integrations |
| Team Secret Key | `sk_live_` | Server-side team operations |
| User Secret Key | `usk_live_` | Multi-team management & admin |

### Access Matrix

| Endpoint | `pk_live_` | `sk_live_` | `usk_live_` |
|----------|:----------:|:----------:|:-----------:|
| Chat Operations | Yes | Yes | Yes |
| Agent Operations | No | Yes | Yes |
| Workflow Operations | No | Yes | Yes |
| File Operations | No | Yes | Yes |
| Team Management | No | No | Yes |

### Chat API

**Create Chat Session**
```http
POST /chat
Content-Type: application/json

{
  "agentId": "string",
  "userId": "string (optional)",
  "metadata": {}
}
```

**Send Message**
```http
POST /chat/:chatId/message
Content-Type: application/json

{
  "content": "string",
  "role": "user"
}
```

**List Chats**
```http
GET /chat
```

**Get Chat by ID**
```http
GET /chat/:chatId
```

**Delete Chat**
```http
DELETE /chat/:chatId
```

### Agent API

**Create Agent**
```http
POST /agent
Content-Type: application/json

{
  "name": "string",
  "description": "string",
  "systemPrompt": "string",
  "model": "string",
  "temperature": 0.7,
  "tools": []
}
```

**List Agents**
```http
GET /agent
```

**Get Agent**
```http
GET /agent/:id
```

**Update Agent**
```http
PUT /agent/:id
```

**Delete Agent**
```http
DELETE /agent/:id
```

**Rollback Agent**
```http
PUT /agent/:id/rollback
```

### Security Best Practices

- **Publishable Keys**: Safe for frontend, limited to chat endpoints
- **Secret Keys**: Never expose in frontend code
- **User Secret Keys**: Highest privilege - use only server-side

---

## HTML Chat Widget

Embed Kodey agents directly in your website.

### Standard Installation

```html
<!-- Container -->
<div id="kodey-chat-container"></div>

<!-- Load widget -->
<script src="https://cdn.kodey.ai/chat-widget.bundle.js"></script>

<!-- Initialize -->
<script>
  ChatWidgetLibrary.initChatWidget('kodey-chat-container', {
    connectionUrl: "wss://pooled.ws.kodey.ai",
    apiKey: "your-api-key",
    serverUrl: 'https://pooled.api.kodey.ai',
    userId: 'user-id',
    theme: 'dark',
    size: 'compact'
  });
</script>
```

### Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| connectionUrl | string | WebSocket URL for real-time chat |
| apiKey | string | Your Kodey API key |
| serverUrl | string | API server URL |
| userId | string | Unique user identifier |
| theme | string | `light` or `dark` |
| size | string | `full`, `compact`, or `floating` |

### WordPress Installation

WordPress sites can auto-detect logged-in users. Add this PHP function:

```php
function kodey_chat_localize_script() {
  wp_enqueue_script('jquery');
  wp_localize_script('jquery', 'wpApiSettings', array(
    'root' => esc_url_raw(rest_url()),
    'nonce' => wp_create_nonce('wp_rest'),
    'isLoggedIn' => is_user_logged_in(),
    'userId' => is_user_logged_in() ? get_current_user_id() : 0
  ));
}
add_action('wp_enqueue_scripts', 'kodey_chat_localize_script');
```

---

## Agent Design Requirements

### Core Functional Requirements

- What is the agent's primary role and function?
- What time intervals should the agent operate on?
- What are example outputs you expect?

### Knowledge & Information Access

- What documents will the agent need (PDFs, transcripts, etc.)?
- What systems must it access (Google Drive, CRM, APIs)?
- What data needs regular updates vs. static knowledge?

### User Interaction Model

- Who are the primary users and their technical levels?
- What interfaces will be used (chat, voice, email)?
- What authentication model is needed?
- What feedback mechanisms should exist?

### Agent Capabilities & Limitations

- What tasks can be autonomous vs. requiring human oversight?
- What are decision-making boundaries?
- When must it escalate to humans?
- How should it handle uncertain information?

### Ethical & Safety Constraints

- What misuses need to be prevented?
- How should sensitive data be handled?
- What failsafes prevent harmful actions?
- What compliance requirements exist?

---

## Industry AI Recipes

### Entrepreneurs & Coaches

Create an AI coaching agent that:
- Embodies your unique coaching style and methodology
- Provides 24/7 access to your coaching approach
- Guides clients through structured processes (Hot Seats)
- Scales your impact while maintaining authenticity

**Components Needed**:
- COACH agent for regular conversations
- HOTSEAT agent for structured processes
- Supervisor to route appropriately
- Knowledge base with your methodologies

### Financial Advisors

Build AI agents for:
- Client onboarding and data gathering
- Portfolio discussion and education
- Appointment scheduling
- FAQ handling

### Personal Injury Attorneys

Create AI agents for:
- Initial case screening
- Client intake questionnaires
- Document collection guidance
- Appointment scheduling

### Concierge Medical Practices

Deploy AI agents for:
- Patient intake and history
- Appointment management
- Health education
- Follow-up coordination

---

## LLM Configuration

### OpenAI Setup

1. Visit https://platform.openai.com
2. Sign in and verify your organization
3. Navigate to API keys section
4. Click "Create new secret key"
5. Copy and store securely (shown only once)
6. Paste into Kodey.ai Settings > Supervisor Settings

### Anthropic Setup

1. Visit https://console.anthropic.com
2. Create account or sign in
3. Navigate to API keys
4. Generate new key
5. Copy and store securely
6. Paste into Kodey.ai Settings > Supervisor Settings

### Model Selection Tips

- **GPT-4**: Best for complex reasoning and nuanced responses
- **GPT-3.5-Turbo**: Faster and cheaper for simpler tasks
- **Claude**: Strong for analysis and longer contexts

---

## Best Practices Summary

### Agent Creation

1. Start simple, add complexity as needed
2. One agent per specialized function
3. Use clear, specific prompts
4. Include example responses
5. Test with various inputs
6. Iterate based on feedback

### Multi-Agent Systems

1. Keep routing logic simple
2. Create clear agent boundaries
3. Use XML tags for organization
4. Preserve default supervisor instructions
5. Test transitions between agents

### Knowledge Base

1. Upload relevant, high-quality documents
2. Use clear file names and organization
3. Update content regularly
4. Use supported formats only

### Security

1. Never expose secret keys in frontend
2. Use publishable keys for client-side
3. Store keys in secure environment variables
4. Rotate keys periodically

---

## Support & Resources

- **Dashboard**: https://dashboard.kodey.ai
- **Documentation**: https://docs.kodey.ai
- **Sign Up**: https://dashboard.kodey.ai/signup

---

## Quick Reference

### API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| /chat | POST | Create chat session |
| /chat | GET | List all chats |
| /chat/:id | GET | Get specific chat |
| /chat/:id | DELETE | Delete chat |
| /chat/:id/message | POST | Send message |
| /chat/:id/message | GET | List messages |
| /agent | POST | Create agent |
| /agent | GET | List agents |
| /agent/:id | GET | Get agent |
| /agent/:id | PUT | Update agent |
| /agent/:id | DELETE | Delete agent |

### Common Parameters

- **temperature**: Controls randomness (0.0-1.0, default 0.7)
- **model**: LLM model to use (e.g., "gpt-4")
- **systemPrompt**: Agent's base instructions
- **tools**: Array of enabled tools/integrations