> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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.

```yaml expandable=true theme={null}
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](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md#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](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md) |
| `VERSION:` | Semantic version | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#version) |
| `DESCRIPTION:` | Human-readable description | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#description) |
| `LANGUAGE:` | Agent language code | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#language) |
| `GOAL:` | Agent objective | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#goal) |
| `PERSONA:` | Agent personality description | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#persona) |
| `LIMITATIONS:` | Explicit boundaries | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#limitations) |
| `IDENTITY:` | Combined identity block | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#identity) |
| `INSTRUCTIONS:` | Operational instructions | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#instructions) |
| `EXECUTION:` | Model and runtime configuration | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#execution-configuration) |
| `TOOLS:` | Tool definitions | [Tools](https://koreai.mintlify.site/agent-platform/abl/reference/tools.md) |
| `GATHER:` | Information collection fields | [GATHER](https://koreai.mintlify.site/agent-platform/abl/reference/gather.md) |
| `FLOW:` | Structured execution steps | [FLOW](https://koreai.mintlify.site/agent-platform/abl/reference/flow.md) |
| `MEMORY:` | Session and persistent state | [Memory & Constraints](https://koreai.mintlify.site/agent-platform/abl/reference/memory-and-constraints.md) |
| `CONSTRAINTS:` | Business rule enforcement | [Memory & Constraints](https://koreai.mintlify.site/agent-platform/abl/reference/memory-and-constraints.md#constraints) |
| `GUARDRAILS:` | Input/output safety checks | [Guardrails](https://koreai.mintlify.site/agent-platform/abl/reference/guardrails.md) |
| `DELEGATE:` | Sub-agent delegation | [Multi-Agent & Supervisor](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#delegate) |
| `HANDOFF:` | Agent transfer | [Multi-Agent & Supervisor](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#handoff) |
| `ESCALATE:` | Human escalation | [Multi-Agent & Supervisor](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#escalate) |
| `COMPLETE:` | Completion conditions | [Multi-Agent & Supervisor](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#complete) |
| `ON_ERROR:` | Error handlers | [Lifecycle & Hooks](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks.md#on_error-handlers) |
| `ON_START:` | Session initialization | [Lifecycle & Hooks](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks.md#on_start-handler) |
| `MESSAGES:` | Customizable system messages | [Lifecycle & Hooks](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks.md#messages) |
| `TEMPLATES:` | Reusable response templates | [Rich content](https://koreai.mintlify.site/agent-platform/abl/reference/rich-content.md) |
| `HOOKS:` | Lifecycle event handlers | [Lifecycle & Hooks](https://koreai.mintlify.site/agent-platform/abl/reference/lifecycle-and-hooks.md#hooks) |
| `NLU:` | Natural language understanding | [NLU](https://koreai.mintlify.site/agent-platform/abl/reference/nlu.md) |
| `MULTI_INTENT:` | Multi-intent configuration | [NLU](https://koreai.mintlify.site/agent-platform/abl/reference/nlu.md#multi-intent-handling-multi_intent) |
| `INTENTS:` | Intent categories (routing) | [NLU](https://koreai.mintlify.site/agent-platform/abl/reference/nlu.md#intent-categories-intents-section) |
| `ENTITIES:` | Reusable named entities | [NLU](https://koreai.mintlify.site/agent-platform/abl/reference/nlu.md#named-entities-entities-section) |
| `LOOKUP_TABLES:` | Reference data for validation | [Data Types & Utilities](https://koreai.mintlify.site/agent-platform/abl/reference/data-types-and-utilities.md#lookup-tables) |
| `SYSTEM_PROMPT:` | Custom system prompt template | [Agent declaration](https://koreai.mintlify.site/agent-platform/abl/reference/agent-declaration.md#system_prompt) |
| `ATTACHMENTS:` | File/media collection | [Data Types & Utilities](https://koreai.mintlify.site/agent-platform/abl/reference/data-types-and-utilities.md#attachments) |
| `DESTINATIONS:` | Outbound HTTP delivery targets | [Data Types & Utilities](https://koreai.mintlify.site/agent-platform/abl/reference/data-types-and-utilities.md#destinations) |
| `TRANSFER_FLOW_POLICIES:` | Named policies referenced by escalation routing | [Multi-Agent & Supervisor](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#transfer-flow-policies) |
| `RETURN_HANDLERS:` | Named parent-resume handlers for returnable handoffs | [Multi-Agent & Supervisor](https://koreai.mintlify.site/agent-platform/abl/reference/multi-agent-and-supervisor.md#return-handlers) |
| `ACTION_HANDLERS:` | Reusable interactive-action handlers | [Rich Content & Expressions](https://koreai.mintlify.site/agent-platform/abl/reference/rich-content.md#reusable-handlers-action_handlers) |
| `CONVERSATION:` | Conversation-behavior configuration | [Behavior profiles](https://koreai.mintlify.site/agent-platform/abl/reference/behavior-profiles.md#conversation) |

> [!NOTE]
>
> `TESTS:` is a reserved section name the parser accepts but currently **ignores** — content under
> it is parsed and discarded with no effect. It exists to avoid "unknown section" errors; do not
> rely on it for behavior.

## 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.

```yaml theme={null}
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.

```yaml theme={null}
# 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) |

```yaml theme={null}
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:

```yaml theme={null}
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.).

```yaml expandable=true theme={null}
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:

```yaml theme={null}
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.

```yaml theme={null}
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:

```text theme={null}
"Hello, {{customer_name}}. Your balance is {{balance}}."
```

Conditional blocks use Handlebars-style helpers:

```text theme={null}
"{{#if exchange_rate}}Rate: {{exchange_rate}}{{/if}}"
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.