@deepguide-ai/agent-sdk

Official SDK for programmatic workflow execution via the DeepGuide Agent API.

Register your account at DeepGuide.ai and obtain your API key first.

Installation

npm install @deepguide-ai/agent-sdk
# or
yarn add @deepguide-ai/agent-sdk
# or
pnpm add @deepguide-ai/agent-sdk

Quick Start

import { DeepGuideClient } from '@deepguide-ai/agent-sdk';

const client = new DeepGuideClient({
  apiKey: 'your-api-key'
});

// List available browser profiles
const profiles = await client.profiles.list();
console.log('Available profiles:', profiles.profiles);

// Execute a workflow with a specific profile
const handle = await client.workflows.execute('workflow-id', {
  params: { url: 'https://example.com' },
  browserProfileId: profiles.profiles[0].id
});

console.log('Job queued:', handle.jobId);

// Wait for completion
const result = await client.executions.waitFor(handle.jobId);
console.log('Result:', result);

Features

• Workflow Execution: Queue and monitor workflow executions
• Browser Profiles: List and use authenticated browser profiles
• Priority Queuing: Support for low, normal, high, and critical priorities
• Webhook Notifications: Receive notifications when executions complete
• Automatic Retries: Built-in retry logic with exponential backoff
• TypeScript Support: Full type definitions included

API Reference

Client Configuration

const client = new DeepGuideClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.deepguide.ai/api/agent', // optional
  timeout: 30000, // optional, default 30s
  headers: {}, // optional custom headers
  retry: {
    maxRetries: 3, // optional, default 3
    initialDelay: 1000, // optional, default 1s
    maxDelay: 30000 // optional, default 30s
  }
});

Browser Profiles

Browser profiles represent authenticated sessions for different applications. You must create and validate profiles via the DeepGuide web UI before using them in the SDK.

List Profiles

const profiles = await client.profiles.list();

profiles.profiles.forEach(profile => {
  console.log(`${profile.name} (${profile.id})`);
  console.log(`  App: ${profile.appName}`);
  console.log(`  Environment: ${profile.environment}`);
  console.log(`  Valid: ${profile.isValid}`);
  console.log(`  Last validated: ${profile.lastValidatedAt}`);
});

Get Profile Details

const profile = await client.profiles.get('profile-id');
console.log('Profile:', profile.name);
console.log('Login URL:', profile.loginUrl);
console.log('Type:', profile.profileType);

Workflows

Execute Workflow

const handle = await client.workflows.execute('workflow-id', {
  params: { username: '[email protected]' },
  priority: 'high', // 'low' | 'normal' | 'high' | 'critical'
  browserProfileId: 'profile-123', // optional
  webhookUrl: 'https://your-server.com/webhook', // optional
  metadata: { customField: 'value' } // optional
});

// Returns ExecutionHandle
console.log(handle.jobId); // Unique job identifier
console.log(handle.queuePosition); // Position in queue
console.log(handle.estimatedStartTime); // When execution will start

List Workflows

const workflows = await client.workflows.list({
  page: 1,
  pageSize: 10
});

workflows.workflows.forEach(wf => {
  console.log(`${wf.name}: ${wf.successRate}% success rate`);
});

Get Workflow Details

const workflow = await client.workflows.get('workflow-id');
console.log(workflow.steps); // Workflow step definitions
console.log(workflow.documentation); // Usage documentation

Executions

Get Execution Status

const status = await client.executions.getStatus('job-id');
console.log(status.status); // 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'
console.log(status.progress.percentComplete); // 0-100

Wait for Completion

try {
  const result = await client.executions.waitFor('job-id', {
    timeout: 600000, // 10 minutes
    pollInterval: 5000 // Poll every 5 seconds
  });

  if (result.status === 'completed') {
    console.log('Success:', result.result.outputs);
    console.log('Screenshots:', result.result.screenshots);
  } else if (result.status === 'failed') {
    console.error('Error:', result.error.message);
  }
} catch (error) {
  if (error instanceof ExecutionTimeoutError) {
    console.error('Execution timed out');
  }
}

Cancel Execution

const cancellation = await client.executions.cancel('job-id');
console.log('Cancelled at:', cancellation.cancelledAt);

List Recent Executions

const executions = await client.executions.list({
  limit: 20,
  status: 'completed' // optional filter
});

executions.executions.forEach(exec => {
  console.log(`${exec.workflowName}: ${exec.status} (${exec.executionTime}ms)`);
});

Error Handling

import {
  DeepGuideError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ExecutionTimeoutError
} from '@deepguide-ai/agent-sdk';

try {
  await client.workflows.execute('workflow-id');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limit: ${error.currentUsage}/${error.maxUsage}`);
  } else if (error instanceof NotFoundError) {
    console.error(`Not found: ${error.resourceId}`);
  } else if (error instanceof ExecutionTimeoutError) {
    console.error(`Timeout: ${error.timeoutMs}ms`);
  }
}

Webhooks

Webhook payloads include:

• X-DeepGuide-Signature: HMAC-SHA256 signature
• X-DeepGuide-Event: Event type

Events: execution.started, execution.completed, execution.failed

TypeScript Types

All types are exported:

import type {
  DeepGuideClientConfig,
  ExecuteWorkflowOptions,
  ExecutionHandle,
  ExecutionStatus,
  ExecutionResult,
  BrowserProfile,
  BrowserProfileList
} from '@deepguide-ai/agent-sdk';

License

MIT