Schema Definition

An Agentlang app is organized into modules that define data models, relationships, workflows, and LLM-powered agents.

1. Module

A module is the fundamental unit of organization in Agentlang. Each module defines a namespace and can contain definitions for:

• Records
• Entities
• Relationships
• Events
• Workflows
• Agents

Syntax

module <name>

Example

module school.core

The fully qualified name (FQN) of any element is constructed as:

<module-name>$<definition-name>

2. Records and Entities

Overview

record and entity definitions describe structured data types composed of attributes.

• A record defines a data structure that is not persisted by default.
• An entity defines a persisted structure, automatically managed by the Agentlang runtime.

Syntax

record <name> [extends <parent-record>] {
    <attribute-list>
}
 
entity <name> [extends <parent-record-or-entity>] {
    <attribute-list>
}

Attributes

Each attribute has:

• A name
• A type
• Optional annotations (tags)

<name> <Type> [@annotation]

Example

record Person {
    firstName String,
    lastName String,
    dateOfBirth Date,
    gender @enum("male", "female", "other")
}
  
entity Teacher extends Person {
    employeeId Int @id,
    dateOfJoining Date,
    email Email
}

Notes

• Every entity has an internal attribute called path (of type Path), automatically generated by the runtime.

• The path uniquely identifies an entity instance using the pattern:

  <fully-qualified-entity-name>/<id-value>

  Example: school.core$teacher/101

• The @id annotation marks the identifier attribute for that entity.

• An entity may inherit attributes from a parent record or entity.

3. Attribute Types

The following types are supported:

Array attributes

An attribute can be specified to be an array of a base type.

entity Student {
    id UUID @id,
    name String,
    courses String[] // array of course names
}

Attribute Properties

Agentlang allows attributes within entity and record definitions to be annotated with special decorators that control their behavior, constraints, and persistence. These decorators define schema-level metadata similar to database constraints or type-system refinements.

General Syntax

entity Example {
    id UUID @id @default(uuid()),
    name String @indexed @unique,
    createdAt DateTime @default(now()) @readonly,
    status String @enum("draft", "published", "archived") @default("draft"),
    category String @oneof(Category.name),
    description String @optional
}

List of Supported Attribute Properties

Built-in Default Functions

Example: Full Entity Definition

entity Product {
    id UUID @id @default(uuid()),
    name String @unique @indexed,
    category String @oneof(Category.name),
    price Decimal @check(isPositive),
    status String @enum("draft", "published", "archived") @default("draft"),
    createdAt DateTime @default(now()) @readonly,
    updatedAt DateTime @default(now())
}

This definition ensures:

• Each product has a unique id generated automatically.
• name is unique and searchable.
• category must refer to an existing Category.name.
• price passes a validation predicate isPositive.
• status defaults to "draft".
• createdAt is set automatically and cannot be changed later.

Meta Settings

An entity definition can have some meta settings which can be used to control certain behavior related to persistence.

See the section on configuration for more details on enabling audit. If the fullTextSearch setting in *, all attributes will be indexed.

An example of fullTextSearch:

entity Person {
    email Email @id,
    name String,
    address String,
    @meta {"fullTextSearch": [address]}
}
 
// search all persons that match a given, partial-address
{Person? "Queens, New York"}

4. Relationships

A relationship defines how two entities are connected.

Types of Relationships

Syntax

relationship <name> between(<entityA>, <entityB>)
relationship <name> contains(<parentEntity>, <childEntity>) [@one_many]

Example

entity Grade {
    name String @id,
    section String
}
 
relationship GradeTeacher between(Grade, Teacher)
relationship GradeStudent contains(Grade, Student) @one_many

Semantics

between

• Creates a many-to-many link between two entities.

• Each entity can reference multiple instances of the other.

• Example: GradeTeacher means:

  • A teacher can teach multiple grades.
  • A grade can have multiple teachers.

contains

• Creates a hierarchical containment relationship.
• By default, it represents a 1–1 relationship.
• When tagged with @one_many, it becomes 1–N.
• The child’s path reflects the hierarchy.

Example:

school.core$grade/3A/school.core$gradeStudent/school.core$student/198

Here:

• Grade is the parent
• Student is the child
• The hierarchy is encoded in the path

5. Example Module

module school.core
  
record Person {
    firstName String,
    lastName String,
    dateOfBirth Date,
    gender @enum("male", "female", "other")
}
  
entity Teacher extends Person {
    employeeId Int @id,
    dateOfJoining Date,
    email Email
}
  
entity Student extends Person {
    studentId Int @id
}
  
entity Grade {
    name String @id,
    section String
}
  
relationship GradeTeacher between(Grade, Teacher)
relationship GradeStudent contains(Grade, Student) @one_many

6. Runtime Behavior Summary