README

Panteão is a framework that envelops the Jason interpreter, that decouples BDI cognitive logic. The big difference of this framework is the always native support to JaCaMo, we are not recreating the wheel, we are just exposing this World to everyone. This framework just envelops, solve envelop problems and create enviromet solutions. The BDI cognitive cycle runs in a dedicated engine process while applications communicate with the agents using the Panteao SDK for their language.

Running the Engine

The engine can be executed either programmatically using the package library of your language or as a standalone process from the terminal.

Standalone Executable

The core BDI interpreter can be started from the command line using the compiled executable binary:

bin/panteao-engine <project.jcm> --port <port>

Parameters:

• Path to the JaCaMo project file (.jcm).
• Port number to listen for incoming application connections.

Programmatic Integration

For applications that embed the BDI interpreter directly inside their codebase, the library wrappers spawn and manage the background engine process lifecycle automatically when the engine instance is initialized. This enables programmatic control of the engine startup, shutdown, and event mapping.

Writing Agent Code

The BDI architecture is configured through JaCaMo files and AgentSpeak plans.

JaCaMo Project File

With this framework, I separated Cartago from Jason and Moise, the environment is your system!

Define the Multi-Agent System configuration (ex: project.jcm):

mas operacao_diluvio {
    agent orquestrador : orquestrador.asl
    
    // Moise organization configuration
    org rescue_org : organization.xml
}

AgentSpeak File

Define beliefs, plans, and actions for your agents (ex: orquestrador.asl):

{ include("$moise/asl/org-rules.asl") }

+temperature(Local, T) : T > 30 <-
    .print("Critical temperature in ", Local, ": ", T);
    .send(room_controller, achieve, turn_on_ac(Local)).

When an agent schedules an action, the engine dispatches the request to the connected application.

Moise Organizational Support

Panteão provides native support for the Moise organizational model by including Moise and CArtAgO dependencies in the engine classpath. While CArtAgO is used internally to instantiate standard Moise organizational artifacts (such as GroupBoard, SchemeBoard, and OrgBoard) in memory, all other system actions are routed to your application clients. This guarantees that agents can adopt roles, execute group missions, and comply with norms using standard Moise directives and XML configurations out-of-the-box.

+obligation(Ag, Norm, Goal, DeadLine) : true <-
    .adopt_role(rescue_team);
    .print("Commiting to goal: ", Goal).

Speech Acts and ILF

Panteao supports the full range of KQML-inspired speech acts and illocutionary forces (ILF) native to the Jason interpreter. This enables sophisticated communication between the engine, external application clients, and other agents. When a message is sent or received, the SDK routes the speech act directly to registered handlers or event listeners.

The supported ILFs are:

• tell: The sender intends the receiver to believe that the content is true.
• untell: The sender intends the receiver to drop the belief that the content is true.
• achieve: The sender requests the receiver to try to achieve a state where the content is true.
• unachieve: The sender requests the receiver to drop the intention of achieving the state where the content is true.
• tellHow: The sender shares a plan with the receiver.
• untellHow: The sender requests the receiver to delete a plan from its plan library.
• askIf: The sender wants to know if the content is currently true for the receiver.
• askAll: The sender wants all answers to a query from the receiver.
• askHow: The sender wants all plans matching a triggering event from the receiver.

Important Q&A and Architectural Decisions

How is the engine packaged and what is its footprint?

The BDI engine is compiled into a standalone native binary using GraalVM. This native binary is self-contained and does not require a Java Runtime Environment (JRE) to be installed on the host system. The binary is around 68MB in size because it bundles the substrate VM, the Jason interpreter, the Moise parser, the CArtAgO runtime backend, and the TCP socket interface. If your corporate compliance policies prohibit running native binaries, the engine can be executed as a standard Java JAR file using any enterprise-certified JDK.

What is the size of the SDK dependency?

The client SDK packages (available for all 18 supported languages) are extremely small, typically under 50KB. They contain zero Java libraries, zero JAR files, and have no external dependencies. The SDK acts as a lightweight client that manages connection parameters, background threads, socket reconnection, and message parsing over a fast local TCP loopback.

How is WebAssembly browser support structured?

Web browser execution is enabled by Leaning Technologies' CheerpJ, which runs the compiled JVM bytecode directly inside the browser using WebAssembly. The CheerpJ runtime is lazily loaded via dynamic ES module imports, ensuring it does not bloat the initial application download size. The engine shadow JAR (~7MB) is downloaded on-demand and cached in the browser's IndexedDB for instant subsequent boots. Interaction between the BDI engine and the browser DOM is handled by a JNI bridge with sub-millisecond latency. Browser execution is recommended for admin panels, simulation tools, and developer playgrounds running on desktop environments, like videogames with complex NPCs, whereas mobile or consumer-facing apps should connect to a remote engine instance using the lightweight socket SDK.

How does the engine scale and handle failures?

By decoupling the cognitive cycle from the application logic, the reasoning engine and the web API processes run independently. If the web server experiences a CPU spike or database lock, the BDI reasoning loop remains active. Under Kubernetes, the engine can be deployed as a sidecar container alongside the API pod. With a native binary memory footprint of 12MB, running multiple sidecar instances introduces negligible memory overhead. The client SDKs include automatic reconnection routines with exponential backoff and local perception queues to ensure message delivery during engine restarts.

Performance & Corporate Impact

Comparing JVM-based deployment against GraalVM native binary deployment.

Evaluation Metrics

Metric	"GraalVM Native Binary"	JVM Execution (JAR)	Corporate Impact
Startup Time	1.5ms - 3ms	1.8s - 2.5s	Instant BDI boot for serverless and scaling environments.
RAM Usage	12MB - 18MB	120MB - 250MB	Over 90% reduction in cloud server cost and operational overhead.
Disk Footprint	~35MB (All-in-one)	~7MB (JAR only)	Lightweight deployment, removing the need to manage JRE installation.
IPC Latency	<0.5ms (Local socket)	<0.5ms (Local socket)	Negligible communication overhead for reactive systems.
Native Bridge	Yes (Static linkage)	Yes (TCP Loopback)	Fully compatible with containerized environments and microservices.

Important

Custom and Community Libraries Support: The compiled GraalVM native binary (panteao-engine) runs in a closed-world environment under GraalVM, meaning it cannot load arbitrary/custom classes at runtime. If your project uses custom agent architectures, custom environments, or third-party community libraries (e.g., libraries not pre-compiled into panteao-engine), you must run the engine using the JAR version (JVM mode) which supports dynamic classloading in the classpath.

Integration SDKs

To communicate with the BDI engine, applications use the official SDK package for their respective language. The SDK handles connection parameters, background threads, and action routing.

Python

Install the package:

pip install panteao-py

Boilerplate code:

from panteao import Panteao

# Spawns the native binary automatically
engine = Panteao(host="127.0.0.1", port=0, project="./project.jcm")
engine.connect()

def turn_on_ac(args, respond):
    print("Action received! Turning on AC.")
    engine.send_msg("tell", "sensor", "bob", "ac_status(on)")
    respond(True) # Action successful

engine.register_action("turn_on_ac", turn_on_ac)
engine.send_msg("tell", "sensor", "bob", "temperature(room_1, 35)")

# Block until the process is interrupted
engine.wait()

Go

Install the package:

go get github.com/kkphoenixgx/panteao/sdk/go

Boilerplate code:

package main

import "github.com/kkphoenixgx/panteao/sdk/go"

func main() {
	engine := panteao.New("127.0.0.1:0")
	engine.Connect()

	engine.registerAction("turn_on_ac", func(sender, receiver, content string) {
		print("Action received! Turning on AC.");
		engine.SendMsg("tell", "sensor", sender, "ac_status(on)")
	})

	engine.SendMsg("tell", "sensor", "bob", "temperature(room_1, 35)")
	select {}
}

JavaScript / Node.js

Install the package:

npm install panteao-js

Connection Client

const { Panteao } = require('panteao-js');

// Spawns the native binary automatically
const engine = new Panteao({ project: './project.jcm' });
engine.connect();

engine.registerAction('turn_on_ac', (args, respond) => {
    console.log("Action received! Turning on AC.");
    engine.sendMsg('tell', 'sensor', 'bob', 'ac_status(on)');
    respond(true); // Action successful
});

engine.sendMsg('tell', 'sensor', 'bob', 'temperature(room_1, 35)');

TypeScript

Install the package:

npm install panteao-ts

The package ships with full TypeScript types built-in — no need to install a separate @types/ package.

Exported Types

Type / Interface	Description
BdiClientOptions	Constructor options (host, port, project, binPath, autoReconnect, reconnectInterval)
ActionCallback	(args: string[], respond: (success: boolean) => void) => void
Panteao / Panteão	Main client class alias (also exported as BdiClient)

Connection Client

import { Panteao } from 'panteao-ts';

// Spawns the native binary automatically
const engine = new Panteao({ project: './project.jcm' });
await engine.connect();

engine.registerAction('turn_on_ac', (args: string[], respond: (success: boolean) => void) => {
    console.log("Action received! Turning on AC.");
    engine.sendMsg('tell', 'sensor', 'bob', 'ac_status(on)');
    respond(true); // Action successful
});

engine.sendMsg('tell', 'sensor', 'bob', 'temperature(room_1, 35)');

Rust

Add the dependency to Cargo.toml:

[dependencies]
panteao = "1.0"

Boilerplate code:

use panteao::Panteao;

fn main() {
    let mut engine = Panteao::new("127.0.0.1:0");
    engine.connect().unwrap();

    engine.registerAction("turn_on_ac", |sender, receiver, content| {
        print("Action received! Turning on AC.");
        engine.send_msg("tell", "sensor", sender, "ac_status(on)").unwrap();
    });

    engine.send_msg("tell", "sensor", "bob", "temperature(room_1, 35)").unwrap();
    engine.wait();
}

Java

Add the dependency:

<dependency>
    <groupId>br.com.kkphoenix.jason.ipc</groupId>
    <artifactId>panteao-sdk</artifactId>
    <version>1.0</version>
</dependency>

Boilerplate code:

import br.com.kkphoenix.jason.ipc.sdk.Panteao;

public class Main {
    public static void main(String[] args) throws Exception {
        Panteao engine = new Panteao("127.0.0.1", 0);
        engine.connect();

        engine.registerAction("turn_on_ac", (sender, receiver, content) -> {
            System.out.print("Action received! Turning on AC.");
            engine.sendMsg("tell", "sensor", sender, "ac_status(on)");
        });

        engine.sendMsg("tell", "sensor", "bob", "temperature(room_1, 35)");
    }
}

Kotlin

Add the dependency:

implementation("br.com.kkphoenix.jason.ipc:panteao-sdk:1.0")

Boilerplate code:

import br.com.kkphoenix.jason.ipc.sdk.Panteao

fun main() {
    val engine = Panteao("127.0.0.1", 0)
    engine.connect()

    engine.registerAction("turn_on_ac") { sender, receiver, content ->
        print("Action received! Turning on AC.");
        engine.sendMsg("tell", "sensor", sender, "ac_status(on)")
    }

    engine.sendMsg("tell", "sensor", "bob", "temperature(room_1, 35)")
}

Scala

Add the dependency:

libraryDependencies += "br.com.kkphoenix.jason.ipc" % "panteao-sdk" % "1.0"

Boilerplate code:

import br.com.kkphoenix.jason.ipc.sdk.Panteao

object Main extends App {
  val engine = new Panteao("127.0.0.1", 0)
  engine.connect()

  engine.registerAction("turn_on_ac", (sender, receiver, content) => {
    print("Action received! Turning on AC.");
    engine.sendMsg("tell", "sensor", sender, "ac_status(on)")
  })

  engine.sendMsg("tell", "sensor", "bob", "temperature(room_1, 35)")
}

C

Link the library:

gcc main.c -lpanteao -o main

Boilerplate code:

#include <panteao.h>
#include <stdio.h>

void turn_on_ac(const char* sender, const char* receiver, const char* content) {
    print("Action received! Turning on AC.");
    panteao_send_msg(engine, "tell", "sensor", sender, "ac_status(on)");
}

int main() {
    panteao_t* engine = panteao_create("127.0.0.1", 0);
    panteao_connect(engine);

    panteao_registerAction(engine, "turn_on_ac", turn_on_ac);
    panteao_send_msg(engine, "tell", "sensor", "bob", "temperature(room_1, 35)");
    panteao_wait(engine);
    return 0;
}

C++

Download the SDK tarball from GitHub Releases or include the repository in your project.

Link the library in your CMakeLists.txt:

add_subdirectory(panteao-sdk)
target_link_libraries(your_app panteao_client_cpp)

Boilerplate code:

#include "panteao_client.h"
#include <iostream>
#include <vector>
#include <functional>

int main() {
    panteao::Panteao engine;
    
    // Spawns the native binary automatically
    engine.connect("127.0.0.1", 0, "./project.jcm");

    engine.registerAction("turn_on_ac", [&engine](const std::vector<std::string>& args, std::function<void(bool)> respond) {
        std::cout << "Action received! Turning on AC." << std::endl;
        
        engine.sendMsg("tell", "sensor", "bob", "ac_status(on)");

        respond(true); // Action successful
    });

    engine.sendMsg("tell", "sensor", "bob", "temperature(room_1, 35)");
    
    engine.wait();
    return 0;
}

C#

Add the package:

dotnet add package Panteao

Boilerplate code:

using System;
using Panteao.Sdk;

class Program {
    static void Main() {
        // Spawns the native binary automatically
        using var engine = new Panteao.Sdk.Panteao("127.0.0.1", 0, "./project.jcm");

        engine.RegisterAction("turn_on_ac", (args, respond) => {
            Console.WriteLine("Action received! Turning on AC.");
            engine.SendMsg("tell", "sensor", "bob", "ac_status(on)");
            respond(true); // Action successful
        });

        engine.SendMsg("tell", "sensor", "bob", "temperature(room_1, 35)");
        
        // Block until the process is interrupted
        engine.Wait();
    }
}

Dart

Add the package:

dart pub add panteao

Boilerplate code:

import 'package:panteao/panteao.dart';

void main() async {
  final engine = Panteao(host: '127.0.0.1', port: 0, project: './project.jcm');
  await engine.connect();

  engine.registerAction('turn_on_ac', (args, respond) {
    print("Action received! Turning on AC.");
    engine.sendMsg('tell', 'sensor', 'bob', 'ac_status(on)');
    respond(true);
  });

  await engine.wait();
}

PHP

Install the package:

composer require kkphoenix/panteao

Boilerplate code:

<?php
use Panteao\Panteao;

$engine = new Panteao("127.0.0.1", 0);
$engine->connect();

$engine->registerAction("turn_on_ac", function($sender, $receiver, $content) use ($engine) {
    echo "Action received! Turning on AC.";
    $engine->sendMsg("tell", "sensor", $sender, "ac_status(on)");
});

$engine->sendMsg("tell", "sensor", "bob", "temperature(room_1, 35)");
$engine->loop();

Ruby

Install the gem:

gem install panteao

Boilerplate code:

require 'panteao'

engine = Panteao::Panteao.new('127.0.0.1', 0)
engine.connect

engine.registerAction("turn_on_ac") do |sender, receiver, content|
  puts "Action received! Turning on AC.";
  engine.send_msg('tell', 'sensor', sender, 'ac_status(on)')
end

engine.send_msg('tell', 'sensor', 'bob', 'temperature(room_1, 35)')
engine.loop

Swift

Add Swift Package Manager dependency:

dependency: Panteao

Boilerplate code:

import Panteao

let engine = Panteao(host: "127.0.0.1", port: 0)
engine.connect()

engine.registerAction("turn_on_ac") { sender, receiver, content in
    print("Action received! Turning on AC.");
    engine.sendMsg("tell", sender: "sensor", receiver: sender, content: "ac_status(on)")
}

engine.sendMsg("tell", sender: "sensor", receiver: "bob", content: "temperature(room_1, 35)")

Objective-C

Add the pod:

pod 'Panteao'

Boilerplate code:

#import <Panteao/Panteao.h>

int main() {
    @autoreleasepool {
        Panteao *engine = [[Panteao alloc] initWithHost:@"127.0.0.1" port:0];
        [client connect];

        [engine registerAction:@"turn_on_ac" withBlock:^(NSString *sender, NSString *receiver, NSString *content) {
            NSLog(@"Action received! Turning on AC.");
            [engine sendMsg:@"tell" sender:@"sensor" receiver:sender content:@"ac_status(on)"];
        }];

        [engine sendMsg:@"tell" sender:@"sensor" receiver:@"bob" content:@"temperature(room_1, 35)"];
    }
    return 0;
}

R

Install the package:

install.packages("panteao")

Boilerplate code:

library(panteao)

engine <- Panteao$new(host = "127.0.0.1", port = 0)
engine$connect()

engine$registerAction("turn_on_ac", function(sender, receiver, content) {
  cat("Action received! Turning on AC.");
  engine$send_msg("tell", "sensor", sender, "ac_status(on)")
})

engine$send_msg("tell", "sensor", "bob", "temperature(room_1, 35)")
engine$loop()

Bash / Shell

Install the helper:

curl -sSL https://panteao.run/install.sh | bash

Boilerplate code:

#!/bin/bash
source panteao.sh

panteao_connect "127.0.0.1" 0

panteao_registerAction "turn_on_ac" turn_on_ac
turn_on_ac() {
    local sender="$1"
    local receiver="$2"
    local content="$3"
    echo "Action received! Turning on AC.";
    panteao_send_msg "tell" "sensor" "$sender" "ac_status(on)"
}

panteao_send_msg "tell" "sensor" "bob" "temperature(room_1, 35)"
panteao_wait

Custom Language Integration

If you want to integrate the Panteão BDI framework with a programming language that does not have an official SDK wrapper, refer to the UNSUPPORTED_LANGUAGES.md guide. It outlines the raw JSON socket protocol schema, speech acts, action execution callbacks, and includes lightweight connection examples (e.g., in COBOL).

For Developers

This section is dedicated to developers working on the Panteão BDI framework core, building it from source, or implementing custom language integrations.

Minimum Requirements

To build and run the engine, you need:

• Java Development Kit (JDK) 17 (required for CheerpJ WebAssembly browser target compatibility).
• Node.js (version 18 or newer) for SDK packaging and Node CLI execution.
• Docker (optional, for running integration test containers).

Compilation and Build Instructions

You can build the Java/BDI core from source using the following commands:

• Generate the Fat JAR: Builds the standalone JAR with all dependencies:

  ./gradlew shadowJar

  The generated JAR file is located at build/libs/jason-ipc-all.jar.

• Build Everything and Copy Native Executable: Builds the JAR and compiles the optimized native image (using GraalVM native-image if configured on your host system):

  npm run build

  This command will compile and output the native binary panteao-engine directly inside the bin directory.

Global CLI Installation

Panteão provides a Node.js CLI launcher. You can link and install the CLI globally on your system to run MAS projects easily:

npm install -g .

Once installed, you can launch the BDI engine with any .jcm or .mas2j file using the panteao command:

panteao test/counter_test.jcm --port 0

The CLI launcher automatically handles classpath discovery, generates temporary MAS2J files for project configurations, and starts either the native binary (if compiled) or falls back to the Java bytecode runner.

Note: By default, the programmatic SDK wrappers will attempt to fall back to running the Java JAR engine if the native executable is not found. To enforce strict execution of the GraalVM native binary only (preventing the JAR fallback), configure the useJarFallback option to false in your client initialization (e.g. new Panteao({ useJarFallback: false })).

Docker Integration

To compile and package the Panteão BDI engine inside an isolated Docker container, run:

docker build -t panteao-engine .

To execute the engine inside a Docker container while exposing the TCP loopback port (e.g. 0):

docker run -d --name panteao-bdi -p 0:0 panteao-engine

How to Run the Test Suite

The repository contains scripts for local and containerized integration testing:

• Local JS Tests: Runs the Node.js SDK tests sequentially measuring execution latency:

  ./run_all_js_tests.sh

• Multi-Language Docker Tests (Dilúvio): Runs the integration tests across all 18 programming languages in isolated containers:

  ./test/diluvio/run_all.sh

• Complete Test Suite and Report Generation: Executes all JS and multi-language tests, generating a consolidated markdown report at metrics_report.md:

  ./run_all_tests.sh

Repository Structure

• src/main/java: Java source code for the Panteão core, socket environment, browser CheerpJ bridge, and launcher.
• bin: Shell and Node.js launcher executables and target output directory for native compilation.
• sdk: Client library implementations for all supported programming languages.
• test: Integration test suites, ASL agent behaviors, JCM projects, and the Dilúvio containerized test environment.

Communication Protocol Architecture

Decoupled messaging architecture between the BDI reasoning engine and custom application SDK clients:

graph LR
    subgraph Engine ["Panteão BDI Engine (JVM / WebAssembly)"]
        Jason["Jason Cognitive Loop"]
        IPCAgArch["IPCAgArch / BrowserAgArch"]
        IPCEnv["IPCEnvironment / BrowserEnvironment"]
        
        Jason --> IPCAgArch
        IPCAgArch --> IPCEnv
    end
    
    subgraph Application ["Client Application"]
        SDK["Panteão SDK Wrapper"]
        App["App Business Logic"]
        
        SDK <--> App
    end
    
    IPCEnv <-->| "TCP Sockets (JSON Speech Acts)" | SDK

Loading