AWA TypeScript SDK

The official TypeScript SDK for the Agentic Workflow Architecture (AWA).

Installation

Global Installation (Recommended for CLI)

npm install -g agentic-workflow-architecture

After installation, the awa command will be available globally:

awa --version

Project Installation

npm install agentic-workflow-architecture

Development from Source

cd sdk/typescript
npm install
npm run build
npm link

Quick Start

Using the CLI

Create a workflow file hello.awa.json:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Hello World",
  "version": "1.0.0",
  "activities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Greet",
      "actor_type": "application",
      "role_id": "550e8400-e29b-41d4-a716-446655440003",
      "inputs": [],
      "outputs": []
    }
  ],
  "edges": [],
  "roles": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "System",
      "actor_type": "application"
    }
  ],
  "contexts": []
}

Run it:

awa run hello.awa.json

Using Programmatically

import { WorkflowEngine, parse_workflow } from 'agentic-workflow-architecture';
import fs from 'fs/promises';

// Load and parse workflow
const content = await fs.readFile('workflow.awa.json', 'utf-8');
const workflow = parse_workflow(JSON.parse(content));

// Initialize engine
const engine = new WorkflowEngine(workflow, {
  geminiApiKey: process.env.GEMINI_API_KEY
});

// Execute workflow
await engine.start();
while (engine.getStatus() === 'running') {
  await engine.runStep();
}

console.log('Workflow completed!');

Features

• Workflow Runtime: Execute AWA workflows with a robust engine
• Workflow Builder: Fluent API to construct workflows programmatically
• Validation: Validate workflow schemas against the AWA specification
• CLI Tool: Command-line interface for running workflows
• REST API: HTTP server for triggering workflows remotely
• VSM & Analytics: Real-time tracking of DOWNTIME waste and process metrics
• Cost Tracking: Track execution costs for AI tokens, human time, and robot operations

CLI Commands

Run a Workflow

# Basic execution
awa run workflow.awa.json

# With verbose output
awa run workflow.awa.json --verbose

# With API key for AI agents
awa run workflow.awa.json --key YOUR_GEMINI_API_KEY

Start API Server

# Default port (3000)
awa serve

# Custom port
awa serve --port 8080

Then trigger workflows via HTTP:

curl -X POST http://localhost:3000/api/v1/workflows/run \
  -H "Content-Type: application/json" \
  -d '{"filePath": "./workflow.awa.json"}'

Documentation

• CLI Guide - Complete installation and usage guide with examples
• Operational API - REST API documentation
• AWA Specification - Full schema definitions

Examples

Check out the examples folder for sample workflows:

# Simple sequential workflow
awa run ../../examples/bank-account-opening/workflow.awa.json

# AI-powered workflow
awa run ../../examples/skills-demonstration/scenario.awa.json --verbose

Environment Variables

• GEMINI_API_KEY - Required for workflows using AI agents

License

Apache-2.0