Implemented by the interpreter: the single binary agentica, a C VM (vm/) that runs every program, with a front end written in Agentica (compiler/) inside it that compiles to bytecode. This document describes what the interpreter accepts; planned work lives in GitHub issues.

1. What we want to validate #

Agentica is a small statically typed language that AI agents can write, read and fix. This specification fixes its syntax, its rules and its diagnostics.

2. Design decisions #

Each rule is stated once, in the section for its topic: lexical rules in §4, syntax and modules in §5, meaning and builtins in §6, and diagnostics in §7.

Agentica is “Ruby with types” for LLM agents. A form is accepted when it is real Ruby (or a typed version of it) or makes Agentica consistent with itself, keeping static checking and immutable values. A form from another language is not accepted: its help names the Agentica form. Two limits do not move: no OOP (no classes, inheritance or user methods on user types) and immutable values.

One way to do each thing. Strictness wins, so agents are precise. A Ruby form is added only when it does not create a second way to write something the language already has; otherwise the parser or the checker gives a diagnostic whose help shows the canonical form.

No warnings. A diagnostic is an error or it does not exist (§7): a warning means “wrong, but allowed”, a second accepted way, and agents ignore warnings. A new check is an error with a stable code, and only when the case is almost always a mistake and the fix is local and mechanical. Nothing turns a check off: the discard _ and a name that starts with _ are the one way to drop a value or keep a name on purpose. Deprecation warnings may be considered only after 1.0.

The method test. A method or form fails when it only renames or negates an existing call, its callback, or a statement (an alias, reject for filter with !, unless for if !), or re-spells one call or statement. A method passes when the composition it replaces needs a loop, several calls, or a seed value or typed accumulator the caller would otherwise choose. So sum, find, each_with_index, flat_map and Map.each pass; reject and the Range Enumerable methods (each is to_a and then one List call) fail.

3. A core program #

struct User
  name: String
  age: Int
end

def is_adult(user: User) -> Bool = user.age >= 18

def main() -> Void
  users = [
    User(name: "Ana", age: 25),
    User(name: "Luis", age: 16)
  ]

  for user in users
    if is_adult(user)
      puts(user.name)
    end
  end
end

The executable starts by calling main(). The top level holds only declarations; there are no executable statements there.