The Developer's Guide to CEO.ai

sk_live_a1b2c3d4e5f6g7h8i9j0...

// Multi-agent setup  
const supportAgent = new CeoAI({ apiKey: process.env.SUPPORT_AGENT_KEY });  
const salesAgent = new CeoAI({ apiKey: process.env.SALES_AGENT_KEY });  
const analysisAgent = new CeoAI({ apiKey: process.env.ANALYSIS_AGENT_KEY });

npm install -g @ceo-ai/cli

# Interactive setup  
ceo configure  
  
# Inline (skip prompts)  
ceo configure --key sk_live_abc123  
  
# Verify  
ceo config:show

ceo configure \  
  --key sk_live_abc123 \  
  --endpoint https://ingestion.api.ceo.ai \  
  --name jules \  
  --conversation-dir ~/my-chats

# Synchronous (wait for results)  
ceo prompt "What was our Q4 revenue?" --poll  
  
# Async (get presigned URL, poll later)  
ceo prompt "Generate a detailed analysis"  
  
# Save to file  
ceo prompt "Generate report" --poll -o report.json  
  
# JSON output (for piping)  
ceo prompt "List customers" --poll --json | jq '.response'  
  
# Disable RAG  
ceo prompt "What is 2+2?" --no-rag --poll  
  
# Custom polling settings  
ceo prompt "Complex analysis" --poll --poll-interval 5000 --poll-timeout 300000

# Start a conversation  
ceo chat "What was our Q4 revenue?"  
  
# Continue it (full history sent for context)  
ceo chat "How does that compare to Q3?" -c conversation.json  
  
# Named conversations  
ceo chat "Analyze marketing spend" -c marketing.json  
ceo chat "Break it down by channel" -c marketing.json

{  
  "metadata": {  
    "agentId": "agent-abc-123",  
    "agentName": "Financial Analyst",  
    "model": "claude-sonnet-4-5",  
    "tenantId": "tenant-456",  
    "startedAt": "2025-02-14T18:30:00.000Z",  
    "lastUpdatedAt": "2025-02-14T18:35:00.000Z",  
    "totalCreditsUsed": 4500,  
    "exchangeCount": 3  
  },  
  "messages": [  
    { "role": "user", "content": "...", "timestamp": "..." },  
    { "role": "assistant", "content": "...", "timestamp": "...", "credits": 1500 }  
  ]  
}

ceo conversations  
ceo conversations --dir ~/my-chats

ceo poll "https://ceo-ai-api-output-results.s3.amazonaws.com/..." -o result.json

ceo configure --name jules  
ceo alias:setup  
# Follow the printed instructions to add the shell alias  
# Then:  
jules chat "What's the status?"

npm install @ceo-ai/sdk

const { CeoAI } = require('@ceo-ai/sdk');  
  
const ceo = new CeoAI({  
    apiKey: process.env.CEO_API_KEY,  // Required  
    endpoint: 'https://ingest.api.ceo.ai',  // Optional  
    timeout: 30000,       // HTTP request timeout (ms)  
    pollInterval: 2000,   // Default polling interval (ms)  
    pollTimeout: 120000   // Default polling timeout (ms)  
});

const result = await ceo.prompt('What was our Q4 revenue?');  
  
// result:  
// {  
//   presignedUrl: 'https://ceo-ai-api-output-results.s3.amazonaws.com/...',  
//   message: 'Processing request',  
//   estimatedCredits: 10,  
//   agentId: 'abc-123',  
//   agentName: 'Financial Analyst',  
//   model: 'claude-sonnet-4-5',  
//   tenantId: 'tenant-456'  
// }

const { response, metadata } = await ceo.promptAndWait(  
    'Summarize our sales this quarter',  
    {  
        pollInterval: 3000,  
        pollTimeout: 60000,  
        onPoll: (attempt, elapsed) => {  
            console.log(`Waiting... attempt ${attempt} (${elapsed}ms)`);  
        }  
    }  
);

// From a previously stored presigned URL  
const result = await ceo.pollForResult(storedUrl, {  
    interval: 3000,  
    timeout: 60000,  
    onPoll: (attempt, elapsed) => console.log(`Attempt ${attempt}`)  
});

ceo addRag ./docs/pricing-guide.md

# Recursive ingestion of all supported files  
ceo addRagDir ./docs --recursive  
  
# Filter by extension  
ceo addRagDir ./src --recursive --extensions js,ts,json  
  
# Override category for all files  
ceo addRagDir ./code-samples --category code  
  
# Custom chunk size  
ceo addRagDir ./docs --chunk-size 4000 --recursive

Found 5 files to add:  
  
  README.md  
  guide/getting-started.md  
  guide/advanced.md  
  api/endpoints.md  
  api/authentication.md  
  
✓ README.md (3 chunks, 450 credits)  
✓ guide/getting-started.md (5 chunks, 780 credits)  
✓ guide/advanced.md (8 chunks, 1200 credits)  
✓ api/endpoints.md (4 chunks, 620 credits)  
✓ api/authentication.md (2 chunks, 310 credits)  
  
--- Summary ---  
  
  Succeeded: 5  
  Credits:   3360

const fs = require('fs');  
const { CeoAI } = require('@ceo-ai/sdk');  
  
const ceo = new CeoAI({ apiKey: process.env.CEO_API_KEY });  
  
// Single file  
const content = fs.readFileSync('./docs/product-guide.md', 'utf8');  
const result = await ceo.addRag(content, 'product-guide.md');  
  
console.log(result);  
// {  
//   success: true,  
//   filename: 'product-guide.md',  
//   category: 'documentation',  
//   totalChunks: 5,  
//   contentLength: 8420,  
//   memoriesAdded: 5,  
//   creditsDeducted: 2150,  
//   agentId: 'agent-123',  
//   tenantId: 'tenant-456'  
// }

# .github/workflows/train-agent.yml  
name: Update Agent Knowledge  
  
on:  
  push:  
    branches: [main]  
    paths:  
      - 'docs/**'  
      - 'knowledge-base/**'  
  
jobs:  
  train:  
    runs-on: ubuntu-latest  
    steps:  
      - uses: actions/checkout@v4  
  
      - uses: actions/setup-node@v4  
        with:  
          node-version: '20'  
  
      - run: npm install -g @ceo-ai/cli  
  
      - name: Train agent on updated docs  
        env:  
          CEO_API_KEY: ${{ secrets.CEO_SUPPORT_AGENT_KEY }}  
        run: |  
          ceo addRagDir ./docs --recursive --extensions md,txt  
          ceo addRagDir ./knowledge-base --recursive

#!/bin/bash  
# update-agent-knowledge.sh  
  
echo "Updating support agent knowledge..."  
CEO_API_KEY=$SUPPORT_AGENT_KEY ceo addRagDir ./docs --recursive --extensions md,txt  
echo "Support agent updated."  
  
echo "Updating sales agent knowledge..."  
CEO_API_KEY=$SALES_AGENT_KEY ceo addRagDir ./sales-docs --recursive  
echo "Sales agent updated."  
  
echo "All agents updated."

const { CeoAI } = require('@ceo-ai/sdk');  
const fs = require('fs');  
const path = require('path');  
  
const ceo = new CeoAI({ apiKey: process.env.CEO_API_KEY });  
  
const SUPPORTED_EXTENSIONS = new Set([  
    'md', 'txt', 'js', 'ts', 'py', 'json', 'yaml', 'yml',  
    'html', 'css', 'sql', 'sh', 'go', 'rs', 'rb', 'java',  
    'php', 'c', 'cpp', 'h'  
]);  
  
const SKIP_DIRS = new Set(['node_modules', '.git', '.env', '__pycache__']);  
const MAX_FILE_SIZE = 4 * 1024 * 1024; // 4MB  
  
async function trainOnDirectory(dirPath, options = {}) {  
    const { recursive = true } = options;  
    const results = { succeeded: 0, failed: 0, totalCredits: 0 };  
  
    async function processDir(dir) {  
        const entries = fs.readdirSync(dir, { withFileTypes: true });  
  
        for (const entry of entries) {  
            const fullPath = path.join(dir, entry.name);  
  
            if (entry.isDirectory()) {  
                if (recursive && !SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {  
                    await processDir(fullPath);  
                }  
                continue;  
            }  
  
            if (!entry.isFile()) continue;  
  
            const ext = path.extname(entry.name).slice(1).toLowerCase();  
            if (!SUPPORTED_EXTENSIONS.has(ext)) continue;  
  
            const stat = fs.statSync(fullPath);  
            if (stat.size === 0 || stat.size > MAX_FILE_SIZE) continue;  
  
            try {  
                const content = fs.readFileSync(fullPath, 'utf8');  
                const result = await ceo.addRag(content, entry.name);  
                console.log(`✓ ${entry.name} (${result.totalChunks} chunks, ${result.creditsDeducted} credits)`);  
                results.succeeded++;  
                results.totalCredits += result.creditsDeducted;  
            } catch (err) {  
                console.error(`✗ ${entry.name}: ${err.message}`);  
                results.failed++;  
            }  
        }  
    }  
  
    await processDir(dirPath);  
    return results;  
}  
  
// Usage  
const results = await trainOnDirectory('./docs');  
console.log(`Done: ${results.succeeded} succeeded, ${results.failed} failed, ${results.totalCredits} credits`);

const questions = [  
    'What was Q1 revenue?',  
    'What was Q2 revenue?',  
    'What was Q3 revenue?',  
    'What was Q4 revenue?'  
];  
  
// Submit all concurrently  
const submissions = await Promise.all(  
    questions.map(q => ceo.prompt(q))  
);  
  
console.log(`Submitted ${submissions.length} prompts`);  
  
// Allow processing time  
await new Promise(r => setTimeout(r, 15000));  
  
// Collect all results  
const results = await Promise.all(  
    submissions.map(s => ceo.pollForResult(s.presignedUrl, { timeout: 60000 }))  
);  
  
results.forEach((result, i) => {  
    console.log(`\n--- ${questions[i]} ---`);  
    console.log(result);  
});

# Start  
ceo chat "What was our Q4 revenue?"  
# Creates conversation.json with the full exchange  
  
# Continue (sends full history for context)  
ceo chat "How does that compare to Q3?" -c conversation.json  
  
# Named conversations for different topics  
ceo chat "Analyze marketing spend" -c marketing.json  
ceo chat "What about the Google Ads budget?" -c marketing.json

const history = [];  
  
// First exchange  
const first = await ceo.promptAndWait('What was our Q4 revenue?');  
history.push(  
    { role: 'user', content: 'What was our Q4 revenue?' },  
    { role: 'assistant', content: JSON.stringify(first.response) }  
);  
  
// Follow-up with context  
const second = await ceo.promptAndWait('How does that compare to Q3?', {  
    conversationHistory: history  
});  
history.push(  
    { role: 'user', content: 'How does that compare to Q3?' },  
    { role: 'assistant', content: JSON.stringify(second.response) }  
);  
  
// Third turn — full context maintained  
const third = await ceo.promptAndWait('What drove the change?', {  
    conversationHistory: history  
});

const express = require('express');  
const { CeoAI, CeoAPIError } = require('@ceo-ai/sdk');  
  
const app = express();  
app.use(express.json());  
  
const ceo = new CeoAI({ apiKey: process.env.CEO_API_KEY });  
  
// Async — returns immediately with a presigned URL  
app.post('/api/ask', async (req, res) => {  
    try {  
        const result = await ceo.prompt(req.body.question);  
        res.json({  
            presignedUrl: result.presignedUrl,  
            estimatedCredits: result.estimatedCredits  
        });  
    } catch (error) {  
        if (error instanceof CeoAPIError) {  
            res.status(error.statusCode).json({ error: error.message });  
        } else {  
            res.status(500).json({ error: 'Internal server error' });  
        }  
    }  
});  
  
// Sync — waits for the result (holds the connection open)  
app.post('/api/ask/sync', async (req, res) => {  
    try {  
        const { response, metadata } = await ceo.promptAndWait(  
            req.body.question,  
            { pollTimeout: 60000 }  
        );  
        res.json({ response, metadata });  
    } catch (error) {  
        if (error instanceof CeoAPIError) {  
            res.status(error.statusCode).json({  
                error: error.message,  
                details: error.details  
            });  
        } else {  
            res.status(500).json({ error: 'Internal server error' });  
        }  
    }  
});  
  
app.listen(3000);

// Initialize agents with different roles  
const agents = {  
    support: new CeoAI({ apiKey: process.env.SUPPORT_KEY }),  
    sales: new CeoAI({ apiKey: process.env.SALES_KEY }),  
    analysis: new CeoAI({ apiKey: process.env.ANALYSIS_KEY }),  
    content: new CeoAI({ apiKey: process.env.CONTENT_KEY })  
};  
  
// Route requests to the appropriate agent  
app.post('/api/support', async (req, res) => {  
    const { response } = await agents.support.promptAndWait(req.body.question);  
    res.json(response);  
});  
  
app.post('/api/proposal', async (req, res) => {  
    const { response } = await agents.sales.promptAndWait(  
        `Generate a proposal for: ${JSON.stringify(req.body.clientDetails)}`  
    );  
    res.json(response);  
});

const { CeoAI, CeoAPIError } = require('@ceo-ai/sdk');  
  
const ceo = new CeoAI({ apiKey: process.env.CEO_API_KEY });  
  
exports.handler = async (event) => {  
    const body = JSON.parse(event.body);  
  
    try {  
        const { response, metadata } = await ceo.promptAndWait(  
            body.question,  
            { pollTimeout: 25000 } // Lambda timeout considerations  
        );  
  
        return {  
            statusCode: 200,  
            headers: { 'Content-Type': 'application/json' },  
            body: JSON.stringify({ response, metadata })  
        };  
    } catch (error) {  
        if (error instanceof CeoAPIError) {  
            return {  
                statusCode: error.statusCode,  
                body: JSON.stringify({ error: error.message })  
            };  
        }  
        return {  
            statusCode: 500,  
            body: JSON.stringify({ error: 'Internal server error' })  
        };  
    }  
};

const { CeoAI, CeoAPIError } = require('@ceo-ai/sdk');  
  
try {  
    const { response } = await ceo.promptAndWait('Hello');  
} catch (error) {  
    if (error instanceof CeoAPIError) {  
        console.log(error.message);      // Human-readable error  
        console.log(error.statusCode);   // HTTP status code  
        console.log(error.details);      // Additional context (if any)  
  
        // Convenience getters  
        if (error.isAuthError) { /* 401 — invalid/expired key */ }  
        if (error.isInsufficientCredits) { /* 402 — not enough credits */ }  
        if (error.isRateLimited) { /* 429 — slow down */ }  
        if (error.isTimeout) { /* 408 — polling timed out */ }  
    }  
}

async function queryAgent(question) {  
    try {  
        const { response, metadata } = await ceo.promptAndWait(question, {  
            pollTimeout: 60000  
        });  
        return { success: true, response, metadata };  
  
    } catch (error) {  
        if (!(error instanceof CeoAPIError)) {  
            // Network error, DNS failure, etc.  
            return { success: false, error: 'connection_error', message: error.message };  
        }  
  
        switch (true) {  
            case error.isAuthError:  
                // Key invalid or revoked. Don't retry.  
                return { success: false, error: 'auth', message: 'API key invalid' };  
  
            case error.isInsufficientCredits:  
                // Out of credits. Surface to user or trigger credit purchase.  
                return {  
                    success: false,  
                    error: 'credits',  
                    required: error.details?.requiredCredits,  
                    available: error.details?.availableCredits  
                };  
  
            case error.isRateLimited:  
                // Back off and retry.  
                await new Promise(r => setTimeout(r, 5000));  
                return queryAgent(question); // Simple retry — add max attempts in production  
  
            case error.isTimeout:  
                // Agent took too long. Increase timeout or use async pattern.  
                return { success: false, error: 'timeout', message: 'Agent processing exceeded timeout' };  
  
            default:  
                return { success: false, error: 'api_error', statusCode: error.statusCode, message: error.message };  
        }  
    }  
}

# No key  
$ ceo prompt "Hello"  
Error: No API key configured. Run: ceo configure  
  
# Bad key  
$ ceo prompt "Hello" --key invalid  
Error: Invalid API key format  
  
# Insufficient credits  
$ ceo prompt "Hello" --poll  
✗ Request failed  
  Error: You need 50 credits but only have 20 available.  
  Details: {"requiredCredits":50,"availableCredits":20,"deficit":30}  
  
# Timeout  
$ ceo prompt "Hello" --poll --poll-timeout 5000  
✗ Polling failed  
  Error: Polling timed out after 5000ms (3 attempts)  
  
# File too large (RAG)  
$ ceo addRag ./massive-file.pdf  
Error: File too large (max 4MB)