Overview

AgentML is the universal language for AI agents, built on the battle-tested W3C SCXML standard.

Just as HTML lets you write content once and have it render in any browser, AgentML lets you define your agent's behavior once and run it anywhere. By building on SCXML—a formal model for state machines proven for over 20 years in complex industrial systems—AgentML provides deterministic, auditable agent behavior that outlives framework trends.

The Problem

The AI agent landscape is fragmented and accelerating, with new frameworks appearing weekly. This creates:

• Vendor Lock-in: Tied to frameworks that may become limiting or unmaintained
• Costly Rewrites: Forced to rebuild when switching frameworks
• Token Waste: Sending entire conversation histories on every request
• Non-Deterministic Behavior: Unpredictable agent responses
• Poor Auditability: Difficult to trace and verify agent decisions

The AgentML Solution

AgentML solves these problems by separating agent behavior from runtime execution:

AgentML : Agent Frameworks  =  HTML : Web Browsers

Write Once, Run Anywhere

1. Native Execution (Recommended): Run agents with agentmlx, the reference runtime built in Go/WASM for high performance and portability.
2. Transformation (Planned): Convert AgentML into other popular frameworks like LangGraph, CrewAI, n8n, and more.

Core Philosophy

Deterministic Behavior via State Machines

AgentML uses W3C SCXML state machines to define deterministic behavior, moving beyond prompt-only approaches where behavior is emergent and unpredictable.

<agentml xmlns="github.com/agentflare-ai/agentml"
       datamodel="ecmascript">
 
  <state id="idle">
    <transition event="user.message" target="processing">
      <assign location="userInput" expr="_event.data.message" />
    </transition>
  </state>
 
  <state id="processing">
    <!-- Agent logic here -->
    <transition event="task.complete" target="idle" />
  </state>
</agentml>

Schema-Guided Events

LLM outputs are constrained to structured JSON events validated against schemas using the event:schema attribute. This ensures reliability and type safety.

<transition event="intent.flight"
            event:schema='{"type": "object", "properties": {"action": {"type": "string", "enum": ["search", "book", "cancel"]}}}'
            target="handle_flight" />

Token Efficiency

The runtime provides the LLM with a "snapshot" of the current state, datamodel, and available events. This context allows prompts to be minimal, and the static parts (the agent's definition) can be cached by the LLM provider, reducing token consumption dramatically.

Key Features

• 🎯 Deterministic Execution: Same inputs always produce same outputs
• 📝 Schema-Guided Events: event:schema attributes validate LLM-generated events
• 🔄 Runtime Snapshots: Efficiently provide LLM context, minimizing token usage
• 📦 Modular Design: Decompose complex agents with <invoke>
• 🔌 Extensible Namespaces: Plug in custom functionality (LLMs, memory, I/O)
• 📊 Observable: OpenTelemetry tracing and logging built-in
• 🌐 Universal Standard: Write once, deploy anywhere
• 🔗 Remote Communication: Built-in distributed agent communication via IOProcessors
• ✅ W3C Conformant: 185/193 conformance tests passing (95.9%)
• 🛡️ Compiler-Inspired Validation: Detailed, actionable error messages

Quick Example

Here's a simple customer support agent:

<agentml xmlns="github.com/agentflare-ai/agentml"
       datamodel="ecmascript"
       xmlns:gemini="github.com/agentflare-ai/agentml-go/gemini">
 
  <datamodel>
    <data id="user_input" expr="''" />
    <data id="response" expr="''" />
  </datamodel>
 
  <state id="awaiting_input">
    <transition event="user.message" target="processing">
      <assign location="user_input" expr="_event.data.message" />
    </transition>
  </state>
 
  <state id="processing">
    <onentry>
      <gemini:generate
        model="gemini-2.0-flash-exp"
        location="_event"
        promptexpr="'Help the user: ' + user_input" />
    </onentry>
 
    <transition event="action.response" target="responding" />
  </state>
 
  <state id="responding">
    <onentry>
      <assign location="response" expr="_event.data.message" />
      <log expr="'Response: ' + response" />
    </onentry>
    <transition target="awaiting_input" />
  </state>
</agentml>

Architecture Overview

AgentML consists of four main components:

1. Document Structure: AgentML files (.aml) use an <agentml> root element, which extends SCXML's <scxml> element.
2. Namespace System: Functionality is extended through namespaces declared with the xmlns:prefix="uri" directive.
3. Runtime (agentmlx): The Go/WASM interpreter executes AgentML files with full W3C SCXML conformance.
4. I/O Processors: Handle external communications via HTTP, WebSocket, and other protocols.

Getting Started

Ready to build your first AgentML agent?

1. Install agentmlx - Get the runtime installed
2. Follow the Quick Start Guide - Build your first agent
3. Learn about Core Concepts - Understand the fundamentals

Community & Support

• GitHub: github.com/agentflare-ai/agentml
• Issues: Report bugs or request features
• Discussions: Share your use cases

Next Steps: Start with Installation to set up your development environment.