Skip to main content
The qckfx SDK is a TypeScript/JavaScript library that lets you embed powerful AI coding agents directly into your applications. This guide will get you building with AI agents in minutes.
For senior devs who want to get started immediately:
  1. Install: npm install @qckfx/agent
  2. Set API key: LLM_API_KEY=your-key and LLM_BASE_URL=your-provider-url in .env
  3. Hello World: 
    import { Agent } from '@qckfx/agent';
const agent = new Agent({ defaultModel: 'anthropic/claude-sonnet-4', systemPrompt: 'You are a helpful coding assistant.', environment: { type: 'local' } });
const result = await agent.processQuery('Hello, world!');
  4. Real integration: See Web App Example or Node.js Service
Quick links for deeper exploration:Pro tip: Use event handlers for responsive UIs and different environments (local/docker/remote) for security.

​
Installation

Install the SDK as a dependency in your project: 
npm install @qckfx/agent

​
Quick Start

​
1. Basic Agent Setup

Create your first agent with minimal configuration: 
import { Agent } from '@qckfx/agent';
import dotenv from 'dotenv';

// Load environment variables
dotenv.config();

// Create a basic agent
const agent = new Agent({
  defaultModel: 'anthropic/claude-sonnet-4',
  systemPrompt: 'You are a helpful AI coding agent with access to tools for analyzing and modifying code.',
  environment: {
    type: 'local' // Run in the same process
  }
});

// Process a query
const result = await agent.processQuery('What does this repository do?');
console.log('Agent response:', result.response);

​
2. Environment Variables

Set up your LLM provider credentials: 
LLM_API_KEY=sk-ant-your-secret-key
LLM_BASE_URL=https://api.anthropic.com/v1/

​
3. Your First Real Integration

Here’s a more complete example showing key SDK features: 
import { Agent } from '@qckfx/agent';

const agent = new Agent(
  {
    defaultModel: 'anthropic/claude-sonnet-4',
    systemPrompt: 'You are a code review assistant. Focus on finding bugs, security issues, and suggesting improvements.',
    environment: {
      type: 'local'
    },
    logLevel: 'info'
  },
  {
    // Handle tool execution events
    onToolExecutionStarted: (execution) => {
      console.log(`🔧 Starting tool: ${execution.toolName} (${execution.toolId})`);
    },
    
    onToolExecutionCompleted: (execution) => {
      console.log(`✅ Tool completed: ${execution.toolName} in ${execution.executionTime}ms`);
    },
    
    // Handle processing lifecycle
    onProcessingCompleted: (data) => {
      console.log('✅ Processing completed');
      console.log('Response:', data.response);
    },
    
    // Handle errors
    onProcessingError: (data) => {
      console.error('❌ Processing error:', data.error.message);
    },
    
    onToolExecutionError: (execution) => {
      console.error('❌ Tool error:', execution.error?.message);
    }
  }
);

// Process multiple queries in sequence
async function analyzeCode() {
  try {
    // First query
    const overview = await agent.processQuery(
      'Give me an overview of this codebase structure'
    );
    
    // Second query (maintains context)
    const issues = await agent.processQuery(
      'Now analyze the code for potential security issues'
    );
    
    return {
      overview: overview.response,
      securityAnalysis: issues.response
    };
  } catch (error) {
    console.error('Analysis failed:', error);
  }
}

analyzeCode();

​
Core Concepts

​
Agent Configuration

The Agent constructor takes a configuration object with these key properties: 
interface AgentConfig {
  defaultModel: string;           // Model to use (e.g., 'anthropic/claude-sonnet-4')
  systemPrompt: string;           // Instructions for the agent
  environment: {                  // Where tools execute
    type: 'local' | 'docker' | 'remote';
  };
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
  cachingEnabled?: boolean;       // Tool execution caching (default: true)
}

​
Execution Environments

Choose where your agent’s tools will execute:

Local

Best for: Development and trusted environmentsExecutes tools in the same process as your application.
environment: { type: 'local' }

Docker

Best for: Sandboxed executionRuns tools inside a Docker container for isolation.
environment: { type: 'docker' }

Remote

Best for: Production and scalabilityExecutes tools in remote sandboxed environments.
environment: { type: 'remote' }

​
Event Handling

The SDK provides rich event handling for building responsive UIs: 
const agent = new Agent(config, {
  // Tool execution events
  onToolExecutionStarted: (execution) => updateUI(`Using ${execution.toolName}`),
  onToolExecutionCompleted: (execution) => showToolOutput(execution.result),
  
  // Processing events
  onProcessingStarted: (data) => showSpinner(),
  onProcessingCompleted: (data) => hideSpinner(),
  
  // Error handling
  onProcessingError: (data) => showErrorMessage(data.error),
  onToolExecutionError: (execution) => showErrorMessage(execution.error),
  
  // Permission requests (for interactive apps)
  onPermissionRequested: async (permission) => {
    return await askUserPermission(permission);
  }
});

​
Common Integration Patterns

​
Web Application Integration

// React component example
import { useState, useEffect } from 'react';
import { Agent } from '@qckfx/agent';

function CodeAssistant() {
  const [agent, setAgent] = useState<Agent | null>(null);
  const [response, setResponse] = useState('');
  const [isProcessing, setIsProcessing] = useState(false);

  useEffect(() => {
    const newAgent = new Agent(
      {
        defaultModel: 'anthropic/claude-sonnet-4',
        systemPrompt: 'You are a helpful coding assistant.',
        environment: { type: 'docker' } // Safer for web apps
      },
      {
        onProcessingStarted: () => setIsProcessing(true),
        onProcessingCompleted: (data) => {
          setResponse(data.response);
          setIsProcessing(false);
        }
      }
    );
    setAgent(newAgent);
  }, []);

  const handleQuery = async (query: string) => {
    if (agent) {
      await agent.processQuery(query);
    }
  };

  return (
    <div>
      <button onClick={() => handleQuery('Analyze this code')}>
        Analyze Code
      </button>
      {isProcessing && <div>Processing...</div>}
      <div>{response}</div>
    </div>
  );
}

​
Node.js Service Integration

// Express.js API endpoint
import express from 'express';
import { Agent } from '@qckfx/agent';

const app = express();
const agent = new Agent({
  defaultModel: 'anthropic/claude-sonnet-4',
  systemPrompt: 'You are an API that analyzes code and returns JSON responses.',
  environment: { type: 'docker' }
});

app.post('/analyze', async (req, res) => {
  try {
    const { query } = req.body;
    const result = await agent.processQuery(query);
    
    res.json({
      success: true,
      response: result.response,
      sessionId: result.sessionId
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error.message
    });
  }
});

app.listen(3000);

​
Advanced Features

​
Custom Tool Configurations

// Load agent configuration from JSON file
import agentConfig from './agent-config.json';

const agent = new Agent(agentConfig);
Example agent-config.json: 
{
  "$schema": "https://unpkg.com/@qckfx/sdk-schema@latest/agent-config.schema.json",
  "defaultModel": "anthropic/claude-sonnet-4",
  "systemPrompt": "You are a specialized code review agent...",
  "tools": [
    "bash",
    "file_read",
    "file_edit",
    "grep",
    "think"
  ],
  "experimentalFeatures": {
    "subAgents": true
  }
}

​
Session Management

// Continue conversations across multiple queries
let sessionState = null;

const result1 = await agent.processQuery('What files are in this project?');
sessionState = result1.sessionState;

const result2 = await agent.processQuery(
  'Now analyze the main entry point file',
  sessionState
);

​
Permission Control

const agent = new Agent(config, {
  onPermissionRequested: async (permission) => {
    // Custom permission logic
    if (permission.toolId === 'bash' && JSON.stringify(permission.args).includes('rm')) {
      return false; // Deny dangerous commands
    }
    return true; // Allow other operations
  }
});

​
Next Steps

SDK API Reference

Complete API documentation for all SDK methods and options

Agent Configuration

Learn about advanced agent configuration options

Built-in Tools

Explore all the tools available to your agents

Core Concepts

Understand the architecture behind qckfx agents

​
Troubleshooting

Make sure you have the correct types installed:
npm install --save-dev @types/node
And ensure your tsconfig.json includes:
{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}
The SDK looks for LLM_API_KEY and LLM_BASE_URL environment variables. Make sure they’re set:
// Check if variables are loaded
console.log('API Key:', process.env.LLM_API_KEY ? 'Set' : 'Missing');
console.log('Base URL:', process.env.LLM_BASE_URL);
Ensure Docker is running and accessible:
docker --version  # Should show Docker version
docker ps         # Should list running containers

​
What’s Next?

Now that you have the SDK integrated, you can:
  • Build custom UIs: Create web or desktop applications with embedded agents
  • Integrate with existing systems: Add AI capabilities to your current applications
  • Scale your solution: Use remote environments for production deployments
  • Customize behavior: Create specialized agents for specific use cases
⌘I