SDK Integration

SDK Integration

Quick Reference

• Who: Developer
• Where: Any Node.js/Bun application
• Time: ~15 minutes to integrate
• Prerequisites: Node.js ≥18, npm, API key

Prerequisites

• Node.js ≥18 or Bun installed
• Codebuff API key (from codebuff.com/profile)
• A project to integrate with

Step-by-Step Guide

Step 1: Install the SDK

npm install @codebuff/sdk

Step 2: Initialize the Client

import { CodebuffClient } from '@codebuff/sdk'

const client = new CodebuffClient({
  apiKey: 'your-api-key',
  cwd: '/path/to/your/project',
  onError: (error) => console.error('Codebuff error:', error.message),
})

(sdk/src/client.ts)

Step 3: Run a Built-in Agent

const result = await client.run({
  agent: 'base',
  prompt: 'Add error handling to all API endpoints',
  handleEvent: (event) => {
    console.log('Progress:', event)
  },
})

Step 4: Run a Custom Agent

import type { AgentDefinition } from '@codebuff/sdk'

const myAgent: AgentDefinition = {
  id: 'code-reviewer',
  displayName: 'Code Reviewer',
  model: 'openai/gpt-5.1',
  instructionsPrompt: 'Review code for best practices and potential issues.',
}

const result = await client.run({
  agent: 'code-reviewer',
  agentDefinitions: [myAgent],
  prompt: 'Review the authentication module',
  customToolDefinitions: [],
  handleEvent: (event) => {
    console.log('Review progress:', event)
  },
})

(sdk/src/run.ts)

Step 5: Add Custom Tools

const customTool = {
  name: 'check_deployment',
  description: 'Check the deployment status of the application',
  parameters: {
    type: 'object',
    properties: {
      environment: { type: 'string', enum: ['staging', 'production'] }
    }
  },
  handler: async (params) => {
    // Your custom logic
    return { status: 'deployed', version: '1.2.3' }
  }
}

const result = await client.run({
  agent: 'base',
  prompt: 'Check if staging is deployed',
  customToolDefinitions: [customTool],
})

(sdk/src/custom-tool.ts)

Expected Results

• ✅ SDK connects to Codebuff API
• ✅ Agents execute and return structured results
• ✅ Progress events stream in real-time
• ✅ File changes applied to the specified directory

Troubleshooting

🔴 Error: Invalid API key

Cause: The API key is incorrect or expired.

Solution:

1. Verify your API key at codebuff.com/profile
2. Ensure you’re using the correct key format
3. Check that your account is active

FAQ

Q: What's the difference between the CLI and SDK?

A: The CLI provides an interactive terminal UI for direct developer use. The SDK is a programmatic API for embedding agent workflows in applications, CI/CD pipelines, or custom tools. Both use the same underlying agent runtime.

Related

• Custom Agents — Create agent definitions
• API Reference — Full API documentation
• CLI Interactive Chat — Interactive usage