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)

State	Description
`Task`	Execute an agent with parameters
`Choice`	Conditional branching
`Map`	Iterate over arrays
`Parallel`	Execute branches concurrently
`Pass`	Transform data
`Wait`	Pause execution
`Succeed`	End successfully
`Fail`	End with failure

Agent-Native States (ASL Extensions)

State	Description
`Approval`	Human-in-the-loop gate
`Debate`	Multi-agent deliberation
`Checkpoint`	Save/resume point

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

Example	Description
Task Breakdown	Recursive task decomposition
Code Review	Multi-agent review with approval
Research Assistant	Web search and synthesis
Customer Support	Intent routing and escalation
Content Pipeline	Generation and moderation

Tutorial Path

Core Tutorials

Hello World - Your first workflow
Simple Workflow - Sequential states
Conditional Logic - Choice states
Parallel Execution - Concurrent branches
Recursive Workflows - Map iterations
Memory & Context - State persistence
Tool Orchestration - Tool permissions
Human Approval - Human-in-the-loop
Multi-Agent Debate - Agent collaboration
Cost Management - Budget controls
Error Handling - Retry and catch
Building Skills - Composition patterns

claude-php-agent Integration

Integrating Claude PHP Agent - Wrapper pattern for ASL
Tool-Enabled Agent Workflows - Tools in workflows
Multi-Agent Orchestration - Parallel agent execution
Loop Strategies in Workflows - ReAct, Reflection, Plan-Execute
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.

agent-state-language / asl

Maintainers

Details