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

```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 | <code>\|</code> 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 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.

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