Agentarium: scripting agent simulations with checkpoints and custom actions

A simulation harness rather than an agent library

Agentarium is described as an open source framework for creating and managing simulations populated with AI-powered agents, and the distinction matters. It is not an agent implementation, and it does not bring its own model. It is the scaffolding around a set of agents that talk to each other and take actions, aimed at people who want to design complex interactive environments where agents can act, learn and evolve. The stated features are agent management with different roles and capabilities, autonomous decision making where an agent picks its next action from its context, a checkpoint system for saving and restoring states and interactions, custom actions beyond the default talk and think capabilities, memory of past interactions, and integration with AI providers through aisuite. The audience is a Python developer experimenting with multi-agent behaviour who wants the plumbing handled.

create_agent, talk_to and act

The API is small enough to read in one sitting. Agents are created through a factory on the Agent class, and they interact in two ways. The first is directed, where one agent sends a message to another:

from agentarium import Agent

# Create agents (configure an LLM provider first - see examples/1_basic_chat/config.yaml)
alice = Agent.create_agent(name="Alice")
bob = Agent.create_agent(name="Bob")

# Direct communication between agents
alice.talk_to(bob, "Hello Bob! I heard you're working on some interesting ML projects.")

# Agent autonomously decides its next action based on context
bob.act()

The distinction between talk_to and act is the interesting part. A talk_to pushes a message at a named agent, while act hands control back to the agent, which decides on its own next action given what it knows. That is the hook for emergent behaviour, and it is also where the cost of the design shows up, since every autonomous decision is a model call.

Personality is constructor data, not a prompt template

An agent's characteristics are passed at creation, which keeps the persona in the same place as the rest of the configuration rather than in a prompt string you assemble yourself:

agent = Agent.create_agent(
    name="Alice",
    age=28,
    occupation="Software Engineer",
    location="San Francisco",
    bio="A passionate developer who loves AI"
)

The examples use the same fields, with alice created as a Software Engineer and bob as a Data Scientist, so occupation is the field that most often carries the role. The repo depends on faker, which suggests the framework also has a way to generate profile data rather than requiring every field to be spelled out, though the README does not show that call directly. What is not documented is how the fields are turned into the model prompt, so if you need to control exactly what the model sees about an agent, that part of the package is a black box until you read the source in the agentarium/ directory.

Custom actions are plain functions with a parameter list

Beyond the default talk and think behaviour, you can register your own actions. An action is a Python function plus metadata describing it, and the metadata is what the model sees when it chooses what to do next:

from agentarium import Agent, Action

# Define a simple greeting action
def greet(name: str, **kwargs) -> str:
    return f"Hello, {name}!"

# Create an agent and add the greeting action
agent = Agent.create_agent(name="Alice")
agent.add_action(
    Action(
        name="GREET",
        description="Greet someone by name",
        parameters=["name"],
        function=greet
    )
)

# Use the custom action
agent.execute_action("GREET", "Bob")

The function takes keyword arguments with a kwargs catch all, so the signature has to tolerate being called with arguments you did not plan for. execute_action invokes it directly by name, which is also the path the autonomous loop uses once it has picked an action.

Checkpoints exist for reproducibility

The checkpoint system is the feature that separates Agentarium from a plain multi-agent script. It saves and restores agent states and interactions, so a run can be reproduced or picked up later. The manager is constructed with a name, and the flow shown in the README is to update the manager with a step label and then save:

from agentarium import Agent
from agentarium.CheckpointManager import CheckpointManager

# Initialize checkpoint manager
checkpoint = CheckpointManager("demo")

# Create and interact with agents
alice = Agent.create_agent(name="Alice")
bob = Agent.create_agent(name="Bob")

alice.talk_to(bob, "What a beautiful day!")
checkpoint.update(step="interaction_1")

# Save the current state
checkpoint.save()

The loading side is the gap worth flagging: the README shows update and save but never shows a matching load call, and it does not say where the checkpoint files are written. The package depends on dill, which is what makes serialising arbitrary agent objects possible, and that also means a saved checkpoint is tied to the code that produced it in ways a JSON format would not be.

The model provider comes from a YAML file

Model access is configured outside the code. The provider and model are set in a YAML file, and credentials for aisuite sit in the same file:

llm:
  provider: "openai"  # The LLM provider to use (any provider supported by aisuite)
  model: "gpt-4"      # The specific model to use from the provider

aisuite:              # (optional) Credentials for aisuite
  openai:            # Provider-specific configuration
    api_key: "sk-..."  # Your API key

The provider field is open ended, accepting any provider aisuite supports, and the model field names a model within that provider. The README does not document how the framework locates this file at runtime; the code comment in the quick start points at examples/1_basic_chat/config.yaml, so the path convention is carried by the example rather than by the documentation. Since the credentials live in the same file, a deployment needs to keep that file out of version control, and the example directories in the repository, 1_basic_chat, 2_checkpointing and 3_adding_a_custom_action, are the reference for how each feature is wired up.

A small package with a young release history

The dependency list is short and tells you what the framework leans on: openai for the client, aisuite for the provider abstraction, PyYAML for the configuration file, faker for generated profile data, dill for serialisation, and boto3, which the README does not explain. The build is a standard pyproject.toml with hatchling as the backend, version 0.3.1, and requires-python set to >=3.10. The test configuration is worth noting because it shows the project's own bar: pytest with coverage over the agentarium package and --cov-fail-under=80, so a pull request that drops coverage below 80 percent fails. On releases, v0.3.0 came out on 2025-01-04 and v0.3.1 on 2025-01-30, while the last push to the main branch was on 2026-10-09. The licence field on the repository says Apache-2.0, and the README points to the LICENSE file for details.

Editorial conclusion

Adopt Agentarium when you are prototyping multi-agent behaviour in Python and want agent personas, a registry of actions, an interaction log and saved checkpoints without writing that harness yourself, and treat the checkpoint files as tied to the code version that produced them. Do not adopt it for production agent systems, since the package is at version 0.3.1 and the README documents neither a load call for checkpoints nor how the configuration file is located at runtime. Verify first which aisuite provider and model you point it at, that your credentials stay out of the YAML file you commit, and that every autonomous act call is accounted for in your budget, because each one is a model request.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. Thytu/Agentarium on GitHub