Agent Declaration - Kore.ai Docs

The agent declaration establishes the identity, metadata, goals, personality, and execution configuration of an ABL agent document. Every .agent.abl file must begin with an AGENT: declaration.

AGENT keyword

The AGENT: keyword declares the agent’s name. This name must be unique within the project and is used as the primary identifier throughout the platform.

AGENT: Wire_Transfer_Specialist

Naming rules

Use PascalCase with underscores to separate words
Must start with a letter
May contain letters, digits, and underscores
Must be unique within the system

Examples

AGENT: Hotel_Search
AGENT: Payment_Processor
AGENT: Customer_Support
AGENT: Fraud_Detection

VERSION

The VERSION: directive specifies the semantic version of the agent document. The value must be a quoted string in semver format (major.minor.patch).

VERSION: "2.0.0"

Property	Type	Required	Default	Description
`VERSION`	`string` (semver)	No	`"1.0.0"`	Document version in `major.minor.patch` format

The version is stored in the document’s metadata (meta.version) and is available for compatibility checks, deployment tracking, and audit trails.

Example

AGENT: Booking_Agent
VERSION: "3.1.0"

DESCRIPTION

The DESCRIPTION: directive provides a human-readable summary of the agent’s purpose. It supports both single-line and multi-line (pipe block) formats.

DESCRIPTION: "Handles flight booking and modifications"

DESCRIPTION: |
  Processes outbound wire transfers for retail and commercial banking
  customers. Handles domestic (Fedwire) and international (SWIFT)
  transfers with full regulatory compliance.

Property	Type	Required	Default	Description
`DESCRIPTION`	`string`	No	none	Human-readable summary of the agent’s purpose

LANGUAGE

The LANGUAGE: directive sets the primary language the agent operates in. The value is a quoted BCP 47 language tag.

LANGUAGE: "en"

LANGUAGE: "es-EC"

Property	Type	Required	Default	Description
`LANGUAGE`	`string`	No	none	BCP 47 language code (for example. `"en"`, `"es-EC"`, `"fr"`)

The language directive influences the runtime’s language-aware behavior including NLU processing, response generation, and entity recognition.

Complete declaration property reference

The following table summarizes all agent declaration properties:

Property	Type	Required	Default	Description
`AGENT`	`string`	Yes	—	Unique agent name in `PascalCase_With_Underscores`
`VERSION`	`string` (semver)	No	`"1.0.0"`	Document version
`DESCRIPTION`	`string`	No	none	Human-readable description
`LANGUAGE`	`string`	No	none	BCP 47 language code

Identity & Goals

The identity and goals sections define what an agent is trying to achieve, how it presents itself, and what boundaries it operates within. These sections feed directly into the system prompt that guides the LLM’s behavior at runtime.

GOAL

The GOAL: section defines the agent’s primary objective. It is the only required section besides AGENT:. The goal drives the LLM’s reasoning, determines completion conditions, and provides the core purpose statement included in every system prompt.

GOAL: "Process the customer's wire transfer request accurately and securely."

Multi-line goals use pipe block syntax:

GOAL: |
  Process the customer's outbound wire transfer request accurately and
  securely. Collect all required beneficiary and payment details, screen
  for sanctions and fraud, enforce daily limits and cut-off windows,
  obtain dual authorization when required, and execute the transfer
  with a complete audit trail.

Property	Type	Required	Default	Description
`GOAL`	`string`	Yes	—	The agent’s primary objective. Used in system prompt and completion detection.

Goal guidelines

State the objective from the agent’s perspective, not the user’s
Be specific about what the agent should accomplish
Include success criteria when measurable outcomes exist
When an agent includes a FLOW: section, the goal also serves as context for any steps that have REASONING: true

PERSONA

The PERSONA: section describes how the agent should present itself — its tone, communication style, expertise signaling, and behavioral characteristics. The persona is included in the system prompt to shape the LLM’s response style.

PERSONA: "Friendly and patient customer support representative."

PERSONA: |
  Senior wire operations specialist at a large commercial bank — precise
  with numbers, methodical about compliance steps, and transparent about
  processing times and fees. Never rushes a wire. Confirms every detail
  before execution because a released wire cannot be reversed, only recalled.

Property	Type	Required	Default	Description
`PERSONA`	`string`	No	`""` (empty)	Personality and communication style description

If omitted, the agent uses a neutral, professional tone determined by the LLM’s default behavior.

LIMITATIONS

The LIMITATIONS: section declares explicit boundaries on what the agent cannot or must not do. Each limitation is a quoted string in a list. Limitations are included in the system prompt as hard constraints.

LIMITATIONS:
  - "Cannot process wires to OFAC-sanctioned countries"
  - "Cannot override the daily wire transfer limit"
  - "Cannot process wires after the daily cut-off"
  - "Cannot reverse a wire after execution"

Property	Type	Required	Default	Description
`LIMITATIONS`	`string[]`	No	`[]` (empty list)	List of explicit boundaries the agent must not cross

Limitation guidelines

State what the agent cannot do, not what it can do
Be specific — vague limitations are difficult for the LLM to enforce
Include the reason or consequence when it helps clarity
Limitations complement CONSTRAINTS: (which are machine-enforced); limitations are LLM-enforced behavioral rules

INSTRUCTIONS

The INSTRUCTIONS: section provides operational guidance that supplements the goal. Instructions are appended to the goal in the system prompt. Use instructions for procedural guidance that does not fit naturally in the goal or persona.

INSTRUCTIONS: |
  Always verify the customer's identity before collecting wire details.
  For international wires, confirm the purpose code. If the customer
  seems uncertain about the SWIFT/BIC code, recommend they verify
  with the beneficiary before proceeding.

Property	Type	Required	Default	Description
`INSTRUCTIONS`	`string`	No	none	Operational guidance appended to the agent’s goal

Instructions and the goal are combined at parse time: the instructions text is appended under an Instructions: heading within the goal’s description.

IDENTITY

The IDENTITY: section is an alternative, structured format that combines role, persona, expertise, and limitations into a single block. When used, its fields are mapped to the equivalent top-level sections.

IDENTITY:
  role: "Senior wire operations specialist"
  persona: "Methodical, precise, and transparent about compliance"
  expertise: [wire transfers, compliance screening, FX conversion]
  limitations: ["Cannot override daily limits", "Cannot reverse executed wires"]

IDENTITY field reference

Field	Type	Required	Default	Maps to
`role`	`string`	No	`""`	`GOAL:` (sets the goal description)
`persona`	`string`	No	`""`	`PERSONA:` (sets persona description)
`expertise`	`string[]`	No	`[]`	Appended to `PERSONA:` as “Expertise: …”
`limitations`	`string[]`	No	`[]`	`LIMITATIONS:`

Mapping behavior

When the parser encounters an IDENTITY: block:

The role value becomes the GOAL: description
The persona value becomes the PERSONA: description
The expertise list is appended to the persona as a comma-separated string
The limitations list populates LIMITATIONS:

You can use either the IDENTITY: block or the individual GOAL:, PERSONA:, LIMITATIONS: sections, but if both are present, the individual sections take the values set last in document order.

Combining identity sections

The recommended approach is to use the individual sections (GOAL:, PERSONA:, LIMITATIONS:) for clarity. The IDENTITY: block is available as a compact alternative.

Recommended style

AGENT: Hotel_Search

GOAL: |
  Help the customer find and book a hotel that matches their preferences,
  budget, and travel dates.

PERSONA: |
  Enthusiastic travel advisor who knows every major hotel chain and
  boutique property. Provides honest comparisons and highlights
  trade-offs between price, location, and amenities.

LIMITATIONS:
  - "Cannot guarantee room availability — availability changes in real time"
  - "Cannot process payments directly — redirects to the booking system"
  - "Cannot access loyalty program accounts for other hotel chains"

Compact style (using IDENTITY)

AGENT: Hotel_Search

IDENTITY:
  role: "Help the customer find and book a hotel matching their preferences"
  persona: "Enthusiastic travel advisor with deep hotel industry knowledge"
  expertise: [hotel chains, boutique properties, price comparison]
  limitations:
    - "Cannot guarantee room availability"
    - "Cannot process payments directly"

SYSTEM_PROMPT

The SYSTEM_PROMPT: section is an advanced escape hatch that supplies a complete, custom system prompt, replacing the prompt the platform would otherwise generate from GOAL:, PERSONA:, and LIMITATIONS:.

SYSTEM_PROMPT: |
  You are a wire operations specialist. Follow the bank's compliance
  procedures exactly. Never release a wire without dual authorization.

When SYSTEM_PROMPT: is present, the auto-generated prompt is not used — the goal, persona, and limitations are no longer automatically composed into the system prompt. Prefer the structured GOAL:/PERSONA:/LIMITATIONS: sections unless you specifically need full control of the prompt text.

Execution Configuration

The EXECUTION: section configures runtime behavior for the agent, including LLM model selection, temperature, token limits, timeouts, extended thinking, and per-operation model routing.

Syntax

EXECUTION:
  model: "claude-sonnet-4-5-20250929"
  temperature: 0.3
  max_tokens: 4096
  tool_timeout: 30000
  fallback_model: "claude-haiku-4-5-20251001"

All properties are optional. When omitted, the platform applies its built-in defaults.

Configuration properties

Property	Type	Required	Default	Description
`model`	`string`	No	Platform default	Primary LLM model identifier
`temperature`	`number`	No	Platform default	Sampling temperature (0.0—1.0). Lower values produce more deterministic output.
`max_tokens`	`number`	No	Platform default	Maximum tokens in LLM response
`tool_timeout`	`number`	No	Platform default	Timeout in milliseconds for tool execution
`llm_timeout`	`number`	No	Platform default	Timeout in milliseconds for LLM inference calls
`session_idle_timeout`	`number`	No	Platform default	Timeout in milliseconds before an idle session expires
`max_reasoning_iterations`	`number`	No	Platform default	Maximum reasoning loop iterations for agents without a flow
`max_flow_iterations`	`number`	No	Platform default	Maximum step transitions in a flow before forced exit
`voice_latency_target`	`number`	No	Platform default	Target latency in milliseconds for voice channel responses
`fallback_model`	`string`	No	none	Model to use when the primary model is unavailable or errors
`enable_thinking`	`boolean`	No	`false`	Enable extended thinking (Anthropic Claude models)
`thinking_budget`	`number`	No	Platform default	Token budget allocated to extended thinking
`compaction_threshold`	`number`	No	Platform default	Context-usage ratio (0.0—1.0) that triggers auto-compaction
`compaction`	`object`	No	Platform default	Fine-grained compaction policy overrides. See Compaction policy overrides.
`inline_gather`	`boolean`	No	`false`	When `true`, gather fields are collected inline during conversation rather than as a separate phase
`concurrency`	`string`	No	`serial`	Message-processing strategy: `serial`, `preemptive`, or `parallel`. See Message concurrency.
`max_queue_depth`	`number`	No	`10`	Maximum pending messages held in the per-session queue.
`max_concurrent_messages`	`number`	No	Platform default	Maximum concurrent message executions when `concurrency: parallel`.
`conversation_history_window`	`number`	No	Platform default	Number of prior conversation messages to include in the LLM context.
`voice`	`object`	No	none	Agent-level voice (TTS) configuration. See Voice configuration.
`pipeline`	`object`	No	disabled	Pre-classification / tool-filter pipeline (supervisors). See Multi-Agent & Supervisor.

Extended thinking

Extended thinking allows Claude models to perform internal reasoning before producing a response. This is useful for complex multi-step reasoning tasks where the agent needs to plan before acting.

EXECUTION:
  model: "claude-sonnet-4-5-20250929"
  enable_thinking: true
  thinking_budget: 8000

Property	Type	Required	Default	Description
`enable_thinking`	`boolean`	No	`false`	Enable the extended thinking capability
`thinking_budget`	`number`	No	Platform default	Maximum tokens the model can use for internal reasoning

When enabled, the model uses a portion of its context window for internal chain-of-thought reasoning before producing the visible response. The thinking_budget controls how many tokens are allocated to this internal reasoning.

Context compaction

As conversations grow, the context window fills with message history. Context compaction automatically summarizes older messages when the context usage exceeds a threshold, preventing context-window overflow.

EXECUTION:
  compaction_threshold: 0.75

Property	Type	Required	Default	Description
`compaction_threshold`	`number`	No	Platform default	Ratio (0.0—1.0) of context usage that triggers compaction

When the ratio of used tokens to available tokens exceeds this threshold, the runtime compacts older conversation history into a summary, freeing space for new messages while preserving essential context.

Compaction policy overrides

For fine-grained control, the compaction: sub-block overrides how three categories of context are compacted. This is advanced tuning — most agents only need compaction_threshold.

EXECUTION:
  compaction:
    tool_results:
      strategy: structured      # none | truncate | structured | summarize
      max_chars: 2000
      keep_recent: 3
    prior_turns:
      strategy: compact         # none | placeholder | compact | summarize
      assistant_preview_chars: 200
    prompt_context:
      projection_strategy: summary   # preview | summary | metadata
      value_max_chars: 500
      total_max_chars: 4000

Sub-block	Purpose	`strategy` values
`tool_results`	How historical tool-call results are compacted	`none`, `truncate`, `structured`, `summarize`
`prior_turns`	How older conversation turns are compacted	`none`, `placeholder`, `compact`, `summarize`
`prompt_context`	How injected prompt-context values are projected	`projection_strategy`: `preview`, `summary`, `metadata`

Each sub-block accepts additional character-budget and retention keys (for example. max_chars, keep_recent, assistant_preview_chars, value_max_chars, total_max_chars).

Message concurrency

The concurrency property controls how a session handles multiple inbound messages.

EXECUTION:
  concurrency: preemptive     # serial | preemptive | parallel
  max_queue_depth: 10
  max_concurrent_messages: 3

Value	Behavior
`serial`	(Default) Process one message at a time; additional messages queue.
`preemptive`	A new message can interrupt/replace in-flight processing of a superseded turn.
`parallel`	Process up to `max_concurrent_messages` messages concurrently.

max_queue_depth (default 10) bounds how many messages wait in the per-session queue.

concurrency, max_queue_depth, max_concurrent_messages, and the EXECUTION.voice block are supported in the .agent.abl format. The .agent.yaml format does not yet parse these keys.

Per-operation model routing

The models: sub-block within EXECUTION: allows you to route different operations to different LLM models. This enables cost optimization by using faster, cheaper models for simple tasks and more capable models for complex reasoning.

EXECUTION:
  model: "claude-sonnet-4-5-20250929"
  fallback_model: "claude-haiku-4-5-20251001"
  models:
    extraction: "claude-haiku-4-5-20251001"
    response_gen: "claude-sonnet-4-5-20250929"
    reasoning: "claude-sonnet-4-5-20250929"
    coordination: "claude-sonnet-4-5-20250929"

The models: block maps operation names to model identifiers. The model property serves as the default for any operation not explicitly listed.

Recognized operation names

Operation	Description
`extraction`	Extracting structured data from user messages (for example. gather field extraction)
`validation`	Validating extracted or gathered values
`tool_selection`	Selecting which tool to call (also used by the classification pipeline)
`response_gen`	Generating user-facing responses
`summarization`	Summarizing conversation history during compaction
`reasoning`	Complex reasoning, planning, and decision-making
`realtime_voice`	Low-latency voice-channel turns
`coordination`	Multi-agent coordination and routing decisions
`embedding`	Embedding generation
`title`	Conversation/title generation

Any other operation name is accepted by the parser but only resolved at runtime if the platform recognizes it.

EXECUTION.compaction.model is deprecated — use EXECUTION.models.summarization instead to set the model used when summarizing history.

Complete execution example

EXECUTION:
  model: "claude-sonnet-4-5-20250929"
  temperature: 0.1
  max_tokens: 4096
  max_reasoning_iterations: 8
  tool_timeout: 30000
  llm_timeout: 60000
  session_idle_timeout: 900000
  fallback_model: "claude-haiku-4-5-20251001"
  enable_thinking: true
  thinking_budget: 4000
  compaction_threshold: 0.8
  models:
    extraction: "claude-haiku-4-5-20251001"
    response_gen: "claude-sonnet-4-5-20250929"
    reasoning: "claude-sonnet-4-5-20250929"
    coordination: "claude-sonnet-4-5-20250929"

Complete example

AGENT: Wire_Transfer_Specialist
VERSION: "2.0.0"
DESCRIPTION: |
  Processes outbound wire transfers for retail and commercial banking
  customers. Handles domestic (Fedwire) and international (SWIFT)
  transfers with full regulatory compliance.
LANGUAGE: "en"

GOAL: |
  Process the customer's outbound wire transfer request accurately
  and securely.

PERSONA: |
  Senior wire operations specialist at a large commercial bank — precise
  with numbers, methodical about compliance steps, and transparent about
  processing times and fees.

LIMITATIONS:
  - "Cannot process wires to OFAC-sanctioned countries"
  - "Cannot override the daily wire transfer limit"
  - "Cannot reverse a wire after execution"

EXECUTION:
  model: "claude-sonnet-4-5-20250929"
  temperature: 0.1
  max_tokens: 4096
  tool_timeout: 30000
  fallback_model: "claude-haiku-4-5-20251001"

Language overview — file structure, syntax rules, and auto-detection
Tools — tool-level timeout configuration
FLOW — per-step GOAL overrides and MAX_TURNS for reasoning steps

​AGENT keyword

​Naming rules

​Examples

​VERSION

​Example

​DESCRIPTION

​LANGUAGE

​Complete declaration property reference

​Identity & Goals

​GOAL

​Goal guidelines

​PERSONA

​LIMITATIONS

​Limitation guidelines

​INSTRUCTIONS

​IDENTITY

​IDENTITY field reference

​Mapping behavior

​Combining identity sections

​Recommended style

​Compact style (using IDENTITY)

​SYSTEM_PROMPT

​Execution Configuration

​Syntax

​Configuration properties

​Extended thinking

​Context compaction

​Compaction policy overrides

​Message concurrency

​Per-operation model routing

​Recognized operation names

​Complete execution example

​Complete example

​Related

AGENT keyword

Naming rules

Examples

VERSION

Example

DESCRIPTION

LANGUAGE

Complete declaration property reference

Identity & Goals

GOAL

Goal guidelines

PERSONA

LIMITATIONS

Limitation guidelines

INSTRUCTIONS

IDENTITY

IDENTITY field reference

Mapping behavior

Combining identity sections

Recommended style

Compact style (using IDENTITY)

SYSTEM_PROMPT

Execution Configuration

Syntax

Configuration properties

Extended thinking

Context compaction

Compaction policy overrides

Message concurrency

Per-operation model routing

Recognized operation names

Complete execution example

Complete example

Related