Skip to main content

Quick Start

This guide will get you up and running with the Droid SDK in just a few minutes.

Prerequisites​

  • Node.js 18+ or Bun 1.0+
  • Factory Droid CLI installed (or let the SDK install it for you)

Installation​

npm install @activade/droid-sdk

Basic Usage​

1. Create a Droid Instance​

import { Droid, MODELS } from '@activade/droid-sdk';

const droid = new Droid({
  model: MODELS.CLAUDE_SONNET,
  cwd: process.cwd()
});

2. Execute a Prompt​

// One-shot execution
const result = await droid.exec('Create a TypeScript function that validates email addresses');

console.log(result.finalResponse);
console.log(`Completed in ${result.durationMs}ms`);

3. Multi-turn Conversation​

// Start a conversation thread
const thread = droid.startThread();

// First prompt - establish context
await thread.run('Create a REST API for a todo list');

// Follow-up - the AI remembers the previous context
await thread.run('Add authentication using JWT');

// Another follow-up
await thread.run('Write tests for the authentication');

// Save session for later
console.log('Session ID:', thread.id);

4. Resume a Conversation​

// Resume a previous conversation
const thread = droid.resumeThread('session_abc123...');

await thread.run('What did we work on last time?');

Streaming Example​

For real-time progress updates:

const thread = droid.startThread();
const { events, result } = await thread.runStreamed('Build a React component');

// Process events as they arrive
for await (const event of events) {
  switch (event.type) {
    case 'tool_call':
      console.log(`Calling: ${event.toolName}`);
      break;
    case 'tool_result':
      console.log(`Result: ${event.isError ? 'ERROR' : 'OK'}`);
      break;
    case 'message':
      console.log(`[${event.role}] ${event.text.slice(0, 100)}...`);
      break;
  }
}

// Get final result
const finalResult = await result;
console.log('Done:', finalResult.finalResponse);

Structured Output​

Parse AI responses with Zod schemas:

import { z } from 'zod';

const TaskSchema = z.object({
  title: z.string(),
  priority: z.enum(['low', 'medium', 'high']),
  completed: z.boolean()
});

const result = await thread.run('Create a task object as JSON');
const task = result.parse(TaskSchema);

console.log(task.title);    // TypeScript knows this is a string
console.log(task.priority); // TypeScript knows this is 'low' | 'medium' | 'high'

Next Steps​