@devteam/sdk

Orchestrate AI agent swarms with Temporal in 10 lines of code.

@devteam/sdk is the official TypeScript SDK for the DevTeam platform. It provides a high-level client for creating tasks, building execution plans (DAGs), running fan-out parallel workloads, managing human-in-the-loop approvals, deploying workflow templates, and monitoring worker nodes -- all backed by Temporal for durability and exactly-once execution guarantees.

Installation

npm install @devteam/sdk

Quick Start

import { DevTeamClient } from '@devteam/sdk';

const client = new DevTeamClient({
  serverUrl: 'https://devteam.marsala.dev',
  apiKey: 'dt_...',
});

// Simple task
const result = await client.createTask({
  prompt: 'Review this contract for risks',
  model: 'opus',
  queue: 'general-queue',
});

console.log(result.output);

Features

• Single tasks -- Send a prompt to any AI model and get a result
• Fan-out parallel -- Run N tasks concurrently with a configurable concurrency limit
• DAG execution -- Create plans with dependencies and execute them as a directed acyclic graph
• Human-in-the-loop -- Require approval before tasks execute; review and approve/reject from code
• Templates -- Deploy pre-built industry workflows with custom inputs
• Monitoring -- Track task status, view worker health, subscribe to completion events
• Type safety -- Full TypeScript types and Zod runtime validation
• Durability -- Built on Temporal: retries, timeouts, and exactly-once semantics

API Reference

Constructor

const client = new DevTeamClient({
  serverUrl: 'https://devteam.marsala.dev', // Required
  apiKey: 'dt_...',                          // Required
  namespace: 'default',                      // Optional, default: 'default'
  timeoutMs: 30000,                          // Optional, default: 30000
  debug: false,                              // Optional, default: false
});

Create a Single Task

const result = await client.createTask({
  prompt: 'Summarize this quarterly earnings report',
  model: 'sonnet',                   // 'opus' | 'sonnet' | 'haiku' | 'gpt-4o' | ...
  queue: 'general-queue',            // Temporal task queue
  priority: 'high',                  // 'critical' | 'high' | 'normal' | 'low'
  timeoutSeconds: 120,               // Per-task timeout
  requireApproval: false,            // Require HITL approval
  metadata: { source: 'earnings' },  // Arbitrary metadata
  attachments: ['./report.pdf'],     // Files to include as context
  retry: {                           // Custom retry policy
    maxAttempts: 3,
    initialIntervalMs: 1000,
    backoffCoefficient: 2,
  },
});

console.log(result.taskId);     // 'task-abc123'
console.log(result.output);     // The AI-generated response
console.log(result.usage);      // { inputTokens, outputTokens, totalTokens, costUsd }

Fan-Out Parallel Execution

Run multiple independent tasks concurrently. The second argument controls how many tasks run at the same time.

const results = await client.executeFanOut([
  { prompt: 'Analyze liability clauses', model: 'sonnet' },
  { prompt: 'Check IP provisions', model: 'sonnet' },
  { prompt: 'Review termination terms', model: 'sonnet' },
  { prompt: 'Assess indemnification risks', model: 'sonnet' },
  { prompt: 'Evaluate non-compete scope', model: 'sonnet' },
], 3); // max 3 concurrent

for (const result of results) {
  console.log(`${result.taskId}: ${result.status}`);
}

Plan and Execute a DAG

The planner decomposes a high-level goal into an ordered set of subtasks with dependencies. executeDAG then runs them layer by layer, passing results from completed tasks as context to downstream tasks.

// Step 1: Generate a plan
const plan = await client.createPlan(
  'Full due diligence on Series A investment',
  {
    strategy: 'dag',         // 'sequential' | 'parallel' | 'dag' | 'auto'
    maxSubtasks: 10,
    defaultModel: 'sonnet',
    requireApproval: true,   // Review plan before execution
  },
);

console.log(`Plan: ${plan.subtasks.length} steps`);
console.log(`Est. cost: $${plan.estimatedCostUsd}`);
console.log(`Est. time: ${plan.estimatedDurationSeconds}s`);

// Step 2: Approve the plan (if requireApproval was set)
const approvals = await client.getPendingApprovals();
for (const approval of approvals) {
  await client.approveTask(approval.taskId, 'approve');
}

// Step 3: Execute the DAG
const dagResult = await client.executeDAG(plan);

console.log(`Success: ${dagResult.success}`);
console.log(`Duration: ${dagResult.totalDurationMs}ms`);
console.log(`Total tokens: ${dagResult.totalUsage?.totalTokens}`);
console.log(`Total cost: $${dagResult.totalUsage?.costUsd}`);

// Access individual subtask results
for (const [subtaskId, result] of Object.entries(dagResult.results)) {
  console.log(`  ${subtaskId}: ${result.status}`);
}

Human-in-the-Loop Approvals

Tasks created with requireApproval: true pause before execution and wait for human review.

// Create a task that requires approval
await client.createTask({
  prompt: 'Send investor update email to all LPs',
  model: 'opus',
  requireApproval: true,
});

// Review pending approvals
const approvals = await client.getPendingApprovals();

for (const approval of approvals) {
  console.log(`Task: ${approval.taskId}`);
  console.log(`Description: ${approval.description}`);
  console.log(`Model: ${approval.model}`);
  console.log(`Priority: ${approval.priority}`);
  console.log(`Requested at: ${approval.requestedAt}`);
}

// Approve
await client.approveTask(approvals[0].taskId, 'approve');

// Reject with feedback
await client.approveTask(approvals[1].taskId, 'reject', 'Too aggressive tone');

// Modify with instructions
await client.approveTask(approvals[2].taskId, 'modify', 'Use conservative language');

Deploy Workflow Templates

Templates are pre-built, parameterized workflows for common use cases.

// List available templates
const templates = await client.listTemplates({
  industry: 'legal',
  category: 'review',
});

for (const t of templates) {
  console.log(`${t.templateId}: ${t.name} (${t.version})`);
  console.log(`  Cost: ~$${t.estimatedCostUsd}`);
  console.log(`  Duration: ~${t.avgDurationSeconds}s`);
}

// Deploy a template
const workflowId = await client.deployTemplate('legal-contract-review-v1', {
  contract_file: './contract.pdf',
  jurisdiction: 'US-NY',
  review_depth: 'comprehensive',
  output_format: 'structured',
});

console.log(`Workflow started: ${workflowId}`);

// Track progress
const status = await client.getTaskStatus(workflowId);
console.log(`Status: ${status.status}, Progress: ${status.progress}%`);

Monitor Workers

const workers = await client.getWorkers();

for (const worker of workers) {
  console.log(`${worker.nodeName} (${worker.workerId})`);
  console.log(`  Queue: ${worker.taskQueue}`);
  console.log(`  Online: ${worker.online}`);
  console.log(`  Active: ${worker.activeTasks}/${worker.maxConcurrency}`);
  console.log(`  Models: ${worker.availableModels.join(', ')}`);
  console.log(`  CPU: ${worker.cpuPercent}% | RAM: ${worker.memoryPercent}%`);
}

Subscribe to Task Completions

const unsubscribe = client.onTaskComplete((result) => {
  console.log(`Task ${result.taskId} completed: ${result.status}`);
  if (result.error) {
    console.error(`  Error: ${result.error.message}`);
  } else {
    console.log(`  Output: ${result.output?.substring(0, 100)}...`);
  }
});

// ... later
unsubscribe();

// Or disconnect everything
client.disconnect();

Advanced Usage

Workflow Utilities

The SDK exports low-level utilities for building custom orchestration logic.

import {
  topologicalSort,
  aggregateUsage,
  parallelLimit,
  withRetry,
} from '@devteam/sdk';

// Topological sort for custom DAG execution
const layers = topologicalSort(plan.subtasks);
// layers[0] = tasks with no dependencies (can run in parallel)
// layers[1] = tasks depending only on layer 0, etc.

// Aggregate token usage across results
const totalUsage = aggregateUsage(results);

// Run async operations with concurrency control
const outputs = await parallelLimit(urls, 5, async (url) => {
  return fetch(url).then((r) => r.json());
});

// Retry with exponential backoff
const data = await withRetry(
  () => fetch('https://api.example.com/data').then((r) => r.json()),
  { maxAttempts: 3, initialIntervalMs: 500 },
);

Zod Schemas

Use the exported Zod schemas for runtime validation in your own code.

import { TaskInputSchema, PlanOptionsSchema } from '@devteam/sdk';

// Validate user input
const parsed = TaskInputSchema.safeParse(userInput);
if (!parsed.success) {
  console.error('Validation errors:', parsed.error.issues);
}

Error Handling

import { DevTeamError, DevTeamValidationError, DevTeamTimeoutError } from '@devteam/sdk';

try {
  const result = await client.createTask({ prompt: 'Hello' });
} catch (err) {
  if (err instanceof DevTeamValidationError) {
    console.error('Invalid input:', err.message);
  } else if (err instanceof DevTeamTimeoutError) {
    console.error('Request timed out:', err.message);
  } else if (err instanceof DevTeamError) {
    console.error(`API error [${err.code}]: ${err.message}`);
    console.error(`Status: ${err.statusCode}, Request ID: ${err.requestId}`);
  }
}

Type Reference

| Type | Description | |------|-------------| | DevTeamClientOptions | Constructor options (serverUrl, apiKey, namespace, etc.) | | TaskInput | Input for creating a task (prompt, model, queue, etc.) | | TaskResult | Result of a completed task (output, usage, error, etc.) | | TaskStatus | Current status with progress and logs | | Plan | Generated execution plan with subtasks | | PlanOptions | Options for plan generation (strategy, maxSubtasks, etc.) | | PlanSubtask | Individual step within a plan | | DAGResult | Result of executing a full DAG | | Approval | Pending human approval request | | Template | Workflow template metadata | | Worker | Worker node status and capabilities | | ModelId | Supported model identifiers | | TaskPriority | Priority levels: critical, high, normal, low | | TaskState | Task lifecycle states | | TokenUsage | Token count and cost breakdown | | RetryPolicy | Per-task retry configuration |

Architecture

Your Code
    |
    v
@devteam/sdk (this package)
    |
    v  HTTPS + JSON
DevTeam API Server (devteam.marsala.dev)
    |
    v  gRPC
Temporal Server
    |
    v  Task Queues
Worker Nodes (ASUS GPU, Surface, GR-14, EC2, ...)
    |
    v
AI Models (Claude, GPT, Gemini, Ollama, ...)

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (recommended)

License

MIT