a2e-lang

Overview

a2e-lang is a domain-specific language (DSL) compiler designed for the A2E (Agent-to-Execution) Protocol. It effectively transforms human-readable DSL into A2E JSONL format, allowing AI agents to effortlessly generate workflows without the need to deal with complex JSON structures.

What is A2E?

A2E is a declarative protocol that empowers AI agents to safely create and execute workflows without direct arbitrary code execution. It defines a set of 8 core operations:

• ApiCall: Execute HTTP API calls.
• FilterData: Filter data arrays based on specified conditions.
• TransformData: Modify and transform data, including sorting and mapping.
• Conditional: Implement branching logic in workflows.
• Loop: Iterate over arrays.
• StoreData: Save data to persistent storage.
• Wait: Introduce timed pauses in execution.
• MergeData: Consolidate data from various sources.

For a comprehensive overview, refer to the full A2E specification.

Benefits of a2e-lang

Creating A2E workflows directly in raw JSONL can be tedious and prone to errors. The a2e-lang DSL provides a more compact and readable syntax that compiles seamlessly into valid A2E JSONL format:

a2e-lang DSL (human-readable)  →  A2E JSONL (machine-readable)

This approach is particularly advantageous when AI agents generate workflows from natural language input, as the DSL is more concise than raw JSON, thereby reducing token consumption and minimizing generation errors.

Example Usage

To create a workflow, define a file named pipeline.a2e:

workflow "user-pipeline"

fetch_users = ApiCall {
  method: "GET"
  url: "https://api.example.com/users"
  headers: { Authorization: credential("api-token") }
  -> /workflow/users
}

filter_active = FilterData {
  from /workflow/users
  where status == "active", points > 100
  -> /workflow/filtered
}

store = StoreData {
  from /workflow/filtered
  storage: "localStorage"
  key: "active-users"
}

run: fetch_users -> filter_active -> store

To compile the pipeline.a2e, use:

# Official A2E spec format (recommended)
a2e-lang compile pipeline.a2e --spec

# Pretty-printed version
a2e-lang compile pipeline.a2e --spec --pretty

# Legacy format
a2e-lang compile pipeline.a2e

Output Formats

a2e-lang offers two output formats for compiled code:

1. Official A2E Protocol Format (--spec): Each operation is represented in a single line JSONL format, following the A2E specification.
2. Legacy Bundled Format: All operations are combined into a single operation update message.

Command Line Interface (CLI) Features

The CLI provides multiple commands for efficient workflow management:

a2e-lang compile <file> [--spec] [--pretty]  # Compile .a2e to JSONL
a2e-lang validate <file>                     # Validate without compiling
a2e-lang ast <file>                          # Show parsed AST (for debugging)
a2e-lang simulate <file> [--input data.json] # Simulation of workflow execution
a2e-lang decompile <file>                    # Reverse compile JSONL back to .a2e DSL

Python API Examples

Integrating with a2e-lang is straightforward using its Python API:

from a2e_lang import parse, Validator, Compiler, SpecCompiler

# Parse the DSL file
workflow = parse(open("pipeline.a2e").read())

# Validate the parsed workflow
errors = Validator().validate(workflow)

# Compile the workflow
jsonl_spec = SpecCompiler().compile(workflow)  # A2E JSONL format

Project Structure

a2e-lang is organized into several components, including:

• grammar.lark: Defines the EBNF grammar for the DSL.
• parser.py: Implements the Lark-based parser to convert DSL to AST.
• compiler.py: Facilitates the transformation of AST into JSONL formats.
• simulator.py: Provides functionality for dry-running workflow simulations.
• lsp.py: Enables features for diagnostics and autocompletion.

For advanced use cases, additional functionalities and operations are available as outlined in the A2E operations section and further detailed in the LANGUAGE.md document.

Roadmap and Future Enhancements

For insights into future development plans, refer to the ROADMAP.md. This will include potential enhancements and new features aimed at improving user experience and expanding capabilities.