Agents

Overview

Agents are intelligent, autonomous units in Agentlang that combine high-level declarative modeling (entities, workflows, events) with reasoning and decision-making capabilities. Agents can plan, infer, and act using the same schema used to define an application’s logic — making them deeply integrated with the data and business layer.

Agents are defined using the agent construct, and they can be composed into flows and decisions, allowing for deterministic and explainable automation of business processes.

1. Agent Definition

Syntax


agent <name> {
    role "text describing the agent’s responsibility",
    instruction "text guiding what the agent must do",
    tools [<entity_or_event_refs>],
    type <"planner" | "chat"> @optional,
    directives [<directive_object>],
    scenarios [<scenario_object>],
    glossary [<glossary_object>]
}

Example


agent employeeIncrement {
    role "Decide on the increment to be given to employees",
    instruction "Based on total sales {{totalSales}} of employee {{employeeEmail}}, decide an appropriate increment",
    tools [acme.core/giveIncrementToEmployee],
    directives [
        {"if": "Employee sales exceeded 5000", "then": "Give a salary increment of .5"},
        {"if": "Sales is between 2000 and 5000", "then": "Hike salary by .2"}
    ],
    scenarios [
        {"user": "Total sales is 5600 for employee jake@acme.com", "ai": "[{acme.core/giveIncrementToEmployee {email 'jake@acme.com', increment .5}}]"}
    ]
}

2. Agent Attributes

Attribute	Type	Description
role	String	High-level description of what the agent does. Serves as its “system prompt.”
instruction	String	A templated instruction containing dynamic placeholders (e.g., `{{employeeEmail}}`) that are filled from the runtime scratchpad.
tools	Array	List of workflows or events that the agent can invoke. Agents with tools are considered planner agents.
type	Enum(`"chat"`, `"planner"`)	Type of the agent. Planner agents can execute workflows; chat agents focus on reasoning and dialog. Default is `"chat"`.
directives	Array	Conditional hints guiding the agent’s decision-making (`if` / `then` rules).
scenarios	Array	Example user inputs and expected AI responses (few-shot guidance).
glossary	Array	Domain-specific vocabulary aiding contextual understanding.

3. Agent Types

Type	Description
chat	Default type. Engages in conversations, performs reasoning, and produces responses without executing workflows.
planner	Can directly invoke workflows and events (listed in `tools`). Used for automation and execution tasks.

4. Scenarios, Directives, and Glossary

Scenarios

Used to provide examples of expected behavior.


scenario employeeIncrement.scn01 {
  "user": "Employee sales is 5600 for jake@acme.com",
  "ai": "[{acme.erp/giveIncrementToEmployee {employeeEmail 'jake@acme.com', increment .5}}]"
}

Directives

Simple if–then rules that bias the agent’s reasoning:


directive employeeIncrement.dir01 {
  "if": "Sales > 5000",
  "then": "Increase salary by .5"
}

Glossary

Provides a domain-specific dictionary of terms:


glossaryEntry testAgent.gloss01 {
  "name": "jackpot",
  "meaning": "sales of 5000 or above",
  "synonyms": "high sales, blockbuster"
}

5. Flows

Flows define execution graphs that connect agents and workflows.

Syntax


flow <flowName> {
   <node1> --> <node2>
   <node2> --> <node3>
}

Example


flow incrementProcess {
   findEmployeeSales --> employeeIncrement
}
 
@public agent incrementProcess {
   role "You manage the employee salary increment process."
}

Flows can include agents or events as nodes. Data produced by one node becomes context for the next — this in-memory state is called the Scratchpad.

6. Scratchpad

The Scratchpad is the runtime memory where outputs of previous flow nodes are stored. Placeholders in agent instructions ({{variable}}) are dynamically replaced with these context values — allowing context-specific reasoning.

Example:


instruction "Based on {{totalSales}} of employee {{employeeEmail}}, decide the increment"

Here, totalSales and employeeEmail come from the scratchpad after the findEmployeeSales agent runs.

7. Decisions

A decision is a specialized agent that uses explicit case logic to produce deterministic outcomes.

Syntax


decision <name> {
  case (<condition1>) {
    <output1>
  }
  case (<condition2>) {
    <output2>
  }
  ...
}

Example


decision classifyOrder {
  case (carType == "EV" and segment == "economy") {
    EconomyEV
  }
  case (carType == "SUV" and segment == "luxury") {
    LuxurySUV
  }
}

Integration in Flow


flow carOrderRequestManager {
  analyseCarOrderRequest --> classifyOrder
  classifyOrder --> "EconomyEV" orderEconomyEV
  classifyOrder --> "LuxurySUV" orderLuxuryEV
}

Decisions act as deterministic routing mechanisms in business workflows.

8. Documents

An agent can be provided with additional information in external documents. The Agentlang runtime will select the contents from the documents, most appropriate for the user request.

Example


{agentlang.ai/doc {
    title "price list",
    url "https://cameras.com/prices.txt"}}
  
{agentlang.ai/doc {
    title "g7x user manual",
    url "./docs/g7x_manual.txt"}}
  
{agentlang.ai/doc {
    title "eosr user manual",
    url "./docs/eosr_manual.txt"}}
  
agent supportAgent {
    instruction "Analyse the user query and give an appropriate response.",
    documents ["price list", "g7x user manual", "eosr user manual"]
}

A database that supports vector-storage must be enabled for documentation support.

Example config.al


{
  "store": {
    "type": "postgres",
    "host": "#js process.env.POSTGRES_HOST || 'localhost'",
    "username": "#js process.env.POSTGRES_USER || 'postgres'",
    "password": "#js process.env.POSTGRES_PASSWORD || 'postgres'",
    "dbname": "#js process.env.POSTGRES_DB || 'postgres'",
    "port": "#js parseInt(process.env.POSTGRES_PORT || '5432')"
  },
  "service": {
    "port": "#js parseInt(process.env.SERVICE_PORT || '8080')"
  }
}

Also set the AL_DB_TYPE environment variable to postgres.

9. Public Agents

An agent can be made publicly accessible (via HTTP API) using the @public decorator:


@public agent carOrderRequestManager {
  instruction "You are an agent who analyses car orders and triggers manufacturing workflows."
}

This will expose the agent as:


POST /<module>/<agentName>

10. Reliability Features (Agent Reliability Modelling)

Agentlang introduces Agent Reliability Modelling to make AI agents deterministic and trustworthy:

Feature	Description
Flows	Define explicit process sequences → predictable outcomes.
Directives	Encode decision guidance as data-driven rules.
Scenarios	Ground agent responses using curated examples.
Glossary	Reduce ambiguity via domain vocabulary.
Decisions	Represent logical, rule-based branching behavior.
Scratchpad	Provides full data transparency and context propagation.
Documents	Enable agent to access context specific external information.

11. Example: Complete Agent Flow


module acme.erp
  
entity Employee {
   email Email @id,
   name String,
   salary Decimal
}
  
entity EmployeeSales {
   id UUID @default(uuid()),
   employee Email,
   totalSales Decimal
}
  
event giveIncrementToEmployee {
   employeeEmail Email,
   increment Decimal
}
  
workflow giveIncrementToEmployee {
   {Employee {email? giveIncrementToEmployee.employeeEmail,
              salary salary + salary * giveIncrementToEmployee.increment}}
}
  
agent findEmployeeSales {
   instruction "Find the sales for the given employee email",
   tools [acme.erp/EmployeeSales]
}
  
agent employeeIncrement {
   role "Decide salary increment for employees",
   instruction "Based on total sales {{totalSales}} of employee {{employeeEmail}}",
   tools [acme.core/giveIncrementToEmployee],
   directives [
       {"if": "Sales > 5000", "then": "Increment .5"},
       {"if": "Sales between 2000 and 5000", "then": "Increment .2"}
   ]
}
  
flow incrementProcess {
   findEmployeeSales --> employeeIncrement
}
  
@public agent incrementProcess {
   role "You manage the salary increment process"
}