MagicArtifact

MagicArtifact is a research proof of concept for exposing artifact logic implemented outside Java to JaCaMo agents through a generic CArtAgO artifact.

This repository contains three executable versions of the same social-media monitoring scenario. The application finds a recent post with replies, classifies up to 20 replies as positive, negative, or neutral with Gemini, and prints a sentiment summary. The three versions make it possible to compare the original TypeScript application, a conventional JaCaMo migration, and the proposed MagicArtifact architecture.

Compared implementations

Directory	Coordination	Artifact logic	Role in the comparison
withoutJacamo/	A TypeScript reflex agent	TypeScript classes called in-process	Original application and comparison baseline
jacamoANDcartago/	A Jason agent running on JaCaMo	Application-specific CArtAgO artifacts reimplemented in Java	Conventional JaCaMo migration
jacamoWithMagicArtifact/	A Jason agent running on JaCaMo	Generic Java MagicArtifact instances connected to TypeScript artifacts	Proposed architecture

The second version gains the JaCaMo reasoning and environment layers but ports the external integrations and artifact state to Java. The third version keeps the Jason coordination while moving the concrete Twitter and sentiment logic back to TypeScript; no application-specific Java artifact is required.

Repository structure

magicArtifactProof/
├── withoutJacamo/                 # TypeScript baseline
├── jacamoANDcartago/              # Jason + Java CArtAgO artifacts
└── jacamoWithMagicArtifact/
    ├── jacamo-remote-artifact-bridge/  # Jason agent and JaCaMo configuration
    ├── artifact-runtime-ts/            # WebSocket runtime and TS artifacts
    └── docs/                           # Development-stage design notes

The generic Java bridge used by the third version is maintained separately in the chon-group/MagicArtifact repository and is resolved by the JaCaMo configuration as a package dependency. The documents under jacamoWithMagicArtifact/docs/ record earlier development stages and may refer to specific proxies or the former JaCaMagic name; the current source code and .jcm file are authoritative.

Scenario workflow

All three versions implement the same high-level workflow:

1. Request up to the three latest posts for the configured Twitter/X username through TwitterAPI.io.
2. Select the first post that has usable replies.
3. Send at most 20 reply texts to the Gemini API for sentiment classification.
4. Print each classification and the positive, negative, and neutral totals.

The target username is currently set in each entry point:

• TypeScript baseline: withoutJacamo/src/index.ts
• Conventional JaCaMo version: jacamoANDcartago/src/agt/sample_agent.asl
• MagicArtifact version: jacamoWithMagicArtifact/jacamo-remote-artifact-bridge/src/agt/bob.asl

Edit the corresponding currentUser value or agent.run(...) argument to monitor another public profile.

How MagicArtifact works

The proposed version separates the JaCaMo application from the runtime that implements its artifacts:

Jason agent
    ↓ CArtAgO operations and perceptions
chon.MagicArtifact (generic Java bridge)
    ↓ JSON messages over WebSocket
TypeScript artifact runtime
    ↓
TwitterArtifact / SentimentArtifact / external APIs

Two chon.MagicArtifact instances are declared in remote_artifact_bridge.jcm, one for TwitterArtifact and one for SentimentArtifact. At runtime:

1. Each bridge connects to the TypeScript server and requests its artifact description.
2. The server returns a machine-readable interface containing the artifact name and operations. The current protocol calls this message artifact_manifest.
3. MagicArtifact registers the described operations dynamically in CArtAgO.
4. Calls made by the Jason agent become operation_request messages with a callId.
5. Runtime responses are mapped back to CArtAgO signals or observable properties. done and error messages report remote completion or failure.

The wire protocol is language-independent in principle. This repository validates one runtime implementation, written in TypeScript; supporting another language requires implementing a compatible runtime.

Requirements

The provided helper scripts target Debian or Ubuntu and assume bash, sudo, APT, and GNU sed. Manual setup is possible on other systems, but the scripts are not portable as written.

Install or provide:

• Git and an internet connection;
• Node.js 20 or newer;
• Yarn for withoutJacamo/ (the repository pins Yarn 4.2.2);
• npm for the TypeScript runtime in jacamoWithMagicArtifact/;
• Java 21 or newer;
• JaCaMo CLI for the two JaCaMo versions (tested with 1.3.0);
• setsid and lsof for the MagicArtifact helper script;
• a TwitterAPI.io API key for live post collection;
• a Google AI Studio API key for Gemini.

Clone the repository:

git clone https://github.com/LabRedesCefetRJ/magicArtifactProof.git
cd magicArtifactProof

Configuration

API credentials in the first two versions

The scripts in withoutJacamo/ and jacamoANDcartago/ ask for both API keys on the first run and cache them in local .api-key1 and .api-key2 files. These files are ignored by Git. During execution, the scripts temporarily insert the keys into source files and restore the placeholder NONE after a normal exit.

If a run is interrupted, inspect git diff before committing: a credential may still be present in a source file. The baseline script also prints credentials to the terminal, so do not share its logs unredacted.

TypeScript runtime environment

Before running the MagicArtifact version, review jacamoWithMagicArtifact/artifact-runtime-ts/.env, which is committed with placeholder credentials:

TWITTER_API_KEY=your_twitterapi_io_key
GEMINI_API_KEY=your_google_ai_studio_key
GEMINI_MODEL=gemini-2.5-flash
USE_MOCK_TWITTER_FALLBACK=false

The helper script updates the first two variables with the interactively supplied credentials and restores NONE after a normal exit. Although .gitignore contains a rule for this path, the file is already tracked, so edits are still visible to Git. Inspect git diff after an interrupted run and never commit real credentials.

Set USE_MOCK_TWITTER_FALLBACK=true to let the TypeScript runtime return a small built-in reply set when live Twitter collection fails. This fallback exercises the bridge and control flow; it does not reproduce live Twitter data. Gemini still requires its own key, and an analysis failure is converted to neutral results by the current prototype.

Running the scenarios

Run each command from the repository root. The scripts install project dependencies when needed and prompt for missing credentials.

A. TypeScript baseline

cd withoutJacamo
./run.sh

This builds the TypeScript application and runs its reflex agent once. The agent directly invokes the local tweet collector and sentiment analyzer.

B. Conventional JaCaMo and CArtAgO

cd jacamoANDcartago
./run.sh

This starts the JaCaMo application in tcc_ia_jacamo.jcm. The Jason agent uses two application-specific Java artifacts, TwitterArtifact and SentimentArtifact.

C. JaCaMo with MagicArtifact

Review the runtime .env file described above, then run:

cd jacamoWithMagicArtifact
./run.sh

The script starts the TypeScript WebSocket runtime on port 8080, launches the JaCaMo application, and stops the runtime after the multi-agent system exits. The JaCaMo application resolves the generic MagicArtifact package declared in remote_artifact_bridge.jcm.

For debugging, the two processes can be started in separate terminals:

cd jacamoWithMagicArtifact/artifact-runtime-ts
npm install
npm run dev

cd jacamoWithMagicArtifact/jacamo-remote-artifact-bridge
jacamo remote_artifact_bridge.jcm

Stop the TypeScript runtime manually when using this mode.

Expected behavior

A successful run prints the selected post, the collected replies, one sentiment label per analyzed reply, and a final count for the three sentiment categories. The wording differs between implementations, but their high-level result is the same.

Exact posts, reply counts, classifications, and execution time are not deterministic. They depend on the current public data, API availability and rate limits, network latency, and the selected Gemini model.

Contributors

• Eric Pinheiro
• Nilson Lazarin

License

This repository does not currently include a software license.