README

A JSON-based domain-specific language for defining configurable, composable AI agent workflows.

Overview

Agent State Language extends the concepts of AWS Step Functions' Amazon States Language with agent-native primitives for:

• 🧠 Memory & Context - Persistent memory, sliding context windows
• 🔧 Tool Orchestration - Permissions, rate limits, sandboxing
• 👤 Human-in-the-Loop - Approval gates, feedback collection
• 💬 Multi-Agent Communication - Debates, delegation, consensus
• 💰 Cost Management - Token budgets, model fallbacks
• 🛡️ Guardrails - Input/output validation, content moderation
• 📊 Observability - Reasoning traces, execution logs

Quick Start

Installation

composer require agent-state-language/asl

Define a Workflow

Create workflow.asl.json:

{
  "Comment": "Simple greeting workflow",
  "StartAt": "Greet",
  "States": {
    "Greet": {
      "Type": "Task",
      "Agent": "GreeterAgent",
      "Parameters": {
        "name.$": "$.userName"
      },
      "End": true
    }
  }
}

Run It

<?php

use AgentStateLanguage\Engine\WorkflowEngine;
use AgentStateLanguage\Agents\AgentRegistry;

$registry = new AgentRegistry();
$registry->register('GreeterAgent', new MyGreeterAgent());

$engine = WorkflowEngine::fromFile('workflow.asl.json', $registry);
$result = $engine->run(['userName' => 'Alice']);

echo $result->getOutput(); // "Hello, Alice!"

State Types

Core States (AWS ASL Compatible)

Agent-Native States (ASL Extensions)

Agent-Native Extensions

Memory Block

{
  "AnalyzeCode": {
    "Type": "Task",
    "Agent": "Analyzer",
    "Memory": {
      "Read": ["project_patterns", "user_preferences"],
      "Write": { "Key": "analysis_results", "TTL": "7d" }
    }
  }
}

Context Block

{
  "GenerateResponse": {
    "Type": "Task",
    "Agent": "Responder",
    "Context": {
      "Strategy": "sliding_window",
      "MaxTokens": 8000,
      "Priority": ["$.currentTask", "$.recentHistory"]
    }
  }
}

Tools Block

{
  "Research": {
    "Type": "Task",
    "Agent": "Researcher",
    "Tools": {
      "Allowed": ["web_search", "read_file"],
      "Denied": ["write_file", "execute_shell"],
      "RateLimits": { "web_search": { "MaxPerMinute": 10 } }
    }
  }
}

Budget Block

{
  "Comment": "Workflow with cost controls",
  "Budget": {
    "MaxTokens": 100000,
    "MaxCost": "$5.00",
    "OnExceed": "PauseAndNotify"
  }
}

Approval State

{
  "ReviewChanges": {
    "Type": "Approval",
    "Prompt": "Review the proposed changes",
    "Options": ["approve", "reject", "modify"],
    "Timeout": "24h",
    "Next": "ApplyChanges"
  }
}

Debate State

{
  "DebateSolution": {
    "Type": "Debate",
    "Agents": ["ProAgent", "ConAgent", "JudgeAgent"],
    "Topic.$": "$.proposal",
    "Rounds": 3,
    "Consensus": { "Required": true, "Arbiter": "JudgeAgent" }
  }
}

Documentation

• 📖 Specification - Complete language specification
• 🚀 Getting Started - First steps guide
• 📚 Tutorials - Step-by-step learning path
• 📘 Guides - Best practices and patterns
• 📋 Reference - API and syntax reference

Examples

Tutorial Path

Core Tutorials

1. Hello World - Your first workflow
2. Simple Workflow - Sequential states
3. Conditional Logic - Choice states
4. Parallel Execution - Concurrent branches
5. Recursive Workflows - Map iterations
6. Memory & Context - State persistence
7. Tool Orchestration - Tool permissions
8. Human Approval - Human-in-the-loop
9. Multi-Agent Debate - Agent collaboration
10. Cost Management - Budget controls
11. Error Handling - Retry and catch
12. Building Skills - Composition patterns

claude-php-agent Integration

1. Integrating Claude PHP Agent - Wrapper pattern for ASL
2. Tool-Enabled Agent Workflows - Tools in workflows
3. Multi-Agent Orchestration - Parallel agent execution
4. Loop Strategies in Workflows - ReAct, Reflection, Plan-Execute
5. RAG-Enhanced Workflows - Knowledge-augmented agents

Requirements

• PHP 8.1 or higher
• Composer

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Related Projects

• claude-php-agent - PHP agent framework with ReAct, Reflection, and Plan-Execute loops
• Claude PHP SDK - Low-level PHP SDK for Claude API
• AWS Step Functions - Inspiration for ASL

Integration with claude-php-agent

ASL can be combined with claude-php-agent for advanced AI agent workflows:

use AgentStateLanguage\Engine\WorkflowEngine;
use AgentStateLanguage\Agents\AgentRegistry;
use ClaudeAgents\Agent;
use ClaudePhp\ClaudePhp;

// Create a claude-php-agent wrapped for ASL
$client = ClaudePhp::make(getenv('ANTHROPIC_API_KEY'));
$agent = Agent::create($client)
    ->withSystemPrompt('You are a helpful assistant.')
    ->withTools([...]);

// Register with ASL
$registry = new AgentRegistry();
$registry->register('Assistant', new ClaudeAgentAdapter('Assistant', $agent));

// Run workflow with advanced agent capabilities
$engine = WorkflowEngine::fromFile('workflow.asl.json', $registry);
$result = $engine->run(['task' => 'Analyze this code...']);

See Tutorial 13: Integrating Claude PHP Agent for complete integration guide.