ABL Overview

Agent Blueprint Language (ABL) is the enterprise control plane for agentic AI — a schema-driven language purpose-built for multi-agent orchestration where deterministic governance meets autonomous reasoning. ABL spans the full control spectrum: delegate autonomously, supervise selectively, or lock down as a deterministic state machine. Agent definitions compile into immutable artifacts, and AI can author blueprints just as humans do.

Design principles

ABL agents are goal-driven rather than script-driven. Rather than encoding an explicit numbered state machine, you declare the outcome the agent should achieve and the rules it must respect, and the runtime reasons toward that goal — falling back to deterministic execution wherever you need it.

1. Goal-oriented — agents work toward a declared GOAL:, not through hard-coded scripts.
2. Constraint-guarded — business rules are enforced by CONSTRAINTS: and GUARDRAILS:, independent of step order.
3. Memory-enabled — agents can remember user and session state across turns and sessions.
4. Composable — agents can DELEGATE: to sub-agents or HANDOFF: to peers and supervisors.
5. Human-in-the-loop — ESCALATE: provides explicit paths to human operators.

Reasoning and determinism are not either/or. An agent reasons by default; adding a FLOW: section lets you make any part of the conversation deterministic, step by step (see Auto-detection).

File structure

An ABL document is a plain-text file composed of top-level sections, each introduced by an uppercase keyword followed by a colon. Sections can appear in any order, but by convention the AGENT: declaration comes first.

AGENT: Customer_Support

GOAL: |
  Help customers resolve billing questions.

PERSONA: |
  Friendly, patient support representative.

TOOLS:
  lookup_account(account_id: string) -> {name: string, balance: number}
    description: "Retrieve account details"
    type: http
    endpoint: "/api/accounts/lookup"
    method: POST

GATHER:
  account_id:
    prompt: "What is your account number?"
    type: string
    required: true

File extensions

Extension	Contents
.agent.abl	Agent definition (most common)
.tools.abl	Reusable tool library (see Tool file imports)
.agent.yaml	Agent definition in YAML format

Required sections

Every agent document must contain:

• AGENT: — the agent name
• GOAL: — the agent’s objective

All other sections are optional. If a section is omitted, its value defaults to empty (empty list, empty object, or platform defaults as specified in each section’s reference).

Recognized top-level sections

Section	Purpose	Reference
AGENT:	Agent name declaration	Agent declaration
VERSION:	Semantic version	Agent declaration
DESCRIPTION:	Human-readable description	Agent declaration
LANGUAGE:	Agent language code	Agent declaration
GOAL:	Agent objective	Agent declaration
PERSONA:	Agent personality description	Agent declaration
LIMITATIONS:	Explicit boundaries	Agent declaration
IDENTITY:	Combined identity block	Agent declaration
INSTRUCTIONS:	Operational instructions	Agent declaration
EXECUTION:	Model and runtime configuration	Agent declaration
TOOLS:	Tool definitions	Tools
GATHER:	Information collection fields	GATHER
FLOW:	Structured execution steps	FLOW
MEMORY:	Session and persistent state	Memory & Constraints
CONSTRAINTS:	Business rule enforcement	Memory & Constraints
GUARDRAILS:	Input/output safety checks	Guardrails
DELEGATE:	Sub-agent delegation	Multi-Agent & Supervisor
HANDOFF:	Agent transfer	Multi-Agent & Supervisor
ESCALATE:	Human escalation	Multi-Agent & Supervisor
COMPLETE:	Completion conditions	Multi-Agent & Supervisor
ON_ERROR:	Error handlers	Lifecycle & Hooks
ON_START:	Session initialization	Lifecycle & Hooks
MESSAGES:	Customizable system messages	—
TEMPLATES:	Reusable response templates	Rich Content & Expressions
HOOKS:	Lifecycle event handlers	Lifecycle & Hooks
NLU:	Natural language understanding	NLU
MULTI_INTENT:	Multi-intent configuration	NLU
INTENTS:	Intent categories (routing)	NLU
ENTITIES:	Reusable named entities	NLU
LOOKUP_TABLES:	Reference data for validation	Data Types & Utilities
SYSTEM_PROMPT:	Custom system prompt template	Agent declaration
ATTACHMENTS:	File/media collection	Data Types & Utilities
DESTINATIONS:	Outbound HTTP delivery targets	—
TRANSFER_FLOW_POLICIES:	Named policies referenced by escalation routing	—
RETURN_HANDLERS:	Named parent-resume handlers for returnable handoffs	Multi-Agent & Supervisor
ACTION_HANDLERS:	Reusable interactive-action handlers	—
CONVERSATION:	Conversation-behavior configuration	—

Syntax rules

Indentation

ABL uses indentation to express nesting. Use spaces (two or more) for indentation. Tabs are accepted but spaces are preferred for consistency. Content nested under a section keyword must be indented further than the keyword line.

TOOLS:
  search(query: string) -> {results: string[]}
    description: "Search the catalog"
    type: http
    endpoint: "/api/search"
    method: GET

Keywords

Section keywords are followed by a colon (:). In the .agent.abl format, section keywords must be uppercase (AGENT:, GOAL:, TOOLS:, …). In the .agent.yaml format, they must be lowercase (agent:, goal:, …). Mixed case is not supported, and the two formats do not accept each other’s casing.

Comments

Lines beginning with # are comments and are ignored by the parser. Comments can appear anywhere in the file.

# This is a comment
AGENT: My_Agent

GOAL: "Help with orders"  # Inline comments are NOT supported in ABL format

Strings

Strings can be written in several forms:

Form	Syntax	Use case
Quoted	"value"	Single-line values
Unquoted	value	Simple values without special characters
Pipe block	| followed by indented lines	Multi-line text (preserves newlines)

GOAL: "Single line goal"

GOAL: |
  Multi-line goal that preserves
  line breaks within the block.

LANGUAGE: "en"

Lists

Lists use YAML-style - item syntax with indentation:

LIMITATIONS:
  - "Cannot access external systems"
  - "Cannot process payments directly"

Auto-detection

The parser determines the document type from the first meaningful keyword it encounters:

First keyword	Document type
AGENT:	Agent document
SUPERVISOR:	Supervisor document
BEHAVIOR_PROFILE:	Behavior profile document
TOOLS: (at root level in a .tools.abl file)	Tool file document

Within an agent document, execution mode is not declared via a global MODE: keyword. Instead, agents operate in reasoning mode by default — the LLM decides which tools to call and when, guided by the GOAL: and PERSONA:.

Any agent can optionally include a FLOW: section to add structured execution steps. Adding a FLOW: section gives the agent a step-by-step execution graph. Each step within the flow declares REASONING: true or REASONING: false to control whether that individual step uses LLM reasoning or deterministic execution.

Note: The MODE: keyword is deprecated and produces a parser error if used. Remove it and use per-step REASONING: declarations within FLOW: instead.

YAML format

ABL supports an alternative YAML format for agent definitions. YAML files use .agent.yaml as their extension. The parser auto-detects YAML format by checking whether the first non-comment, non-empty lines use lowercase keys matching known ABL sections (agent, goal, persona, tools, etc.).

agent: Customer_Support

goal: |
  Help customers resolve billing questions.

persona: |
  Friendly, patient support representative.

tools:
  - name: lookup_account
    parameters:
      - name: account_id
        type: string
    returns:
      type: object
      fields:
        name: string
        balance: number
    description: Retrieve account details
    type: http
    endpoint: /api/accounts/lookup
    method: POST

Both formats produce the same intermediate representation (AST) and compile to identical runtime artifacts.

Version declaration

The optional VERSION: directive specifies the document version in semver format:

VERSION: "2.0.0"

When omitted, the version defaults to "1.0.0". The version is stored in the document metadata and can be used for compatibility tracking.

Compilation

ABL source files are compiled to a typed intermediate representation (AgentIR) at deploy time. The runtime loads and executes the IR directly — there is no code-generation step.

ABL source (.agent.abl / .agent.yaml)
        │
        ▼
   Parser        → parses the document into an AST
        │
        ▼
   Compiler      → produces a CompilationOutput: a map of AgentIR
        │           instances (one per agent, including supervisors)
        │           plus the entry agent
        ▼
   Runtime       → loads the IR and executes it (reasoning loop,
                   flow steps, routing, constraint checking)

Each agent (and supervisor) compiles to a single AgentIR that gathers the document’s sections into typed configuration — identity (from GOAL/PERSONA/LIMITATIONS, including a generated system prompt), tools, gather, constraints and guardrails, coordination (handoffs/delegates/escalation), completion, and memory. Supervisors are ordinary agents with routing populated, so a project’s agents and supervisors all live in one registry and can compose hierarchically.

Template interpolation

Throughout ABL, string values support template interpolation using double-brace syntax:

"Hello, {{customer_name}}. Your balance is {{balance}}."

Conditional blocks use Handlebars-style helpers:

"{{#if exchange_rate}}Rate: {{exchange_rate}}{{/if}}"

Template expressions are resolved at runtime against session variables and tool results.