How are systems designed and developed?

Focus on operations (e.g., microservices). But now systems are data-driven (i.e., the data-dichotomy).

How are systems maintained at deployment?

Autonomous systems that self-adapt. But their decisions are hard to interpret (i.e., intellectual debt).

The Data Dichotomy: “While data-driven systems are about exposing data, service-oriented architectures and object-oriented programming are about hiding data.” (Stopford, 2016).

Intellectual Debt: Practitioners deploy data-driven systems that work in practice, but do not fully understand their inner workings. This threatens transparency, safety, and trust, increasing risks of AI's negative social impact (Zittrain, 2022).

Two complementary projects that aim to address the dichotomy and mitigate the debt:

• DOCS: Data-Oriented Computing Systems: Aims to develop the Data-Oriented Architectures (DOAs) style for desining systems that prioritise data instead of operations.
• S4: Self-Sustaining Software Systems: Aims to define the building blocks for the next generation of autonomous systems that self-sustain while keeping humans in control.

The debugger is designed around the data-first systems principle. It makes the relevant system state and traces explicit, queryable, and reusable for analysis. Such a data substrate is used for fault localisation and repair. LLMs operate as interfaces to interpret the recorded data.

• Training telemetry: model metrics and dashboards over time.
• Fault localisation: sensitivity analysis on where the pipeline fails (statistics / diagnostics, not only final accuracy).
• Data influence: identifying the data points that generate a given behaviour.
• Model interpretability: statistical methods to improve our understanding of the model.

Related Work

• Multi-Agent Systems (MAS): rich work on coordination, communication, and decentralised decision-making
• Agent engineering frameworks: useful abstractions for environments, policies, and orchestration
• Observability / tracing ecosystems: strong tools for logs and telemetry, often external to the agent data model
• Gap: limited support for a unified, first-class record structure that jointly captures decisions, outcomes, traces, provenance, and accountability across policy types

DOAgent contributes a data-oriented substrate for MAS where analysis is not an afterthought but a built-in property of the multi-agent system.

• Policy-agnostic records (heuristic, RL, LLM) under a common schema
• Built-in traceability, provenance, accountability, and interpretability from shared records
• Explicit support for policy factorisation and observable abstention behaviours (e.g., "I don't know")

!pip install -q git+https://github.com/cabrerac/doagent.git

from doagent import Session

session = Session.from_config({
    "shared_data": {"type": "file"},
    "scenario_name": "push",
    "output_base": "./output",
    "run_config": {"logging_level": 2},
    "policies": {
        "goal_seek": heuristic_goal_seek,
        "push_block": heuristic_push_block,
    },
})

Data-first Principle

Agents communicate through a shared data substrate.

• Config-driven Session API: one entry point for env, agents, and policies
• Shared data adapters: InMemory, File (JSONL), MongoDB
• Logging levels control what is recorded (traces, provenance, reasoning)

{
  "id": "au-abc123",
  "timestamp": "2026-03-28T10:00:00Z",
  "actor": "agent_0",
  "kind": "agent_update",
  "payload": {
    "decision": {
      "request": {"inputs": {"observation": {...}}},
      "response": {
        "choice": {"status": "act", "action": 2},
        "reasoning": {"steps": [...]}
      },
      "explanation": "Moved toward landmark."
    }
  },
  "provenance": {"agent": "agent_0", "sources": [...]},
  "accountability": {"owner": "team-a", "policy_id": "pol-1"}
}

Data Model

• agent_update: decision envelope with request, response (choice + reasoning), and explanation
• outcome: environment state after each step
• trace: cause-effect links between outcomes via agent_updates

Logging levels:

• Level 0: agent_update + outcome
• Level 1: + trace + provenance + accountability
• Level 2: + explanation + reasoning

from doagent import Session

session = Session.from_config({
    ...
    "topology": {
        "mode": "peer_to_peer",
        "visibility": {
            "agent_0": ["agent_1"],
            "agent_1": ["agent_2"],
        }
    },
})
records = session.visible_records("agent_0",
    kind="agent_update")

Decentralisation Principle

Support for heterogeneous communication schemas.

• Topology: centralised, federated, peer-to-peer
• Visibility filters which records each agent sees
• Same agent code runs under any topology — configuration, not code change

session.register_participant("agent_0",
    capabilities=["map_discovery"])

if energy <= 0:
    session.deregister_participant("agent_0")

participants = session.participation_registry

Openness Principle

Agents can join and leave at any time.

• ParticipationRegistry: register and query which agents are present
• Capabilities and resources per agent
• Session-level API for join/leave

What users provide

• Environments: Use built-in (e.g. PettingZoo) or custom. The library wraps them so outcomes and traces are recorded
• Agents: Define via config. The library creates them and connects them to shared data
• Policies: Plug in any decision logic (heuristic, RL, LLM, or custom). The library records decisions and optional reasoning
• Tools (optional): Per-agent callables. The library wraps them for transparent tool-use tracing

from doagent import Session, make_env

session = Session.from_config(config)
env = make_env(create_push_env, max_cycles=100)
wrapped = session.wrap_env(env, env_actor="push_env")
agents = session.create_agents(configs,
    goal="push_towards_landmark")
observations = wrapped.reset(seed=42)

for round_id in range(1, 101):
    actions = {
        aid: agents[aid].decide(
            observations[aid], round_id
        )["action"]
        for aid in agents
    }
    step = wrapped.step(actions)
    observations = step["observations"]

Run loop

• session.wrap_env records outcomes and traces automatically
• session.create_agents binds policies from config
• agent.decide() records the agent_update, wraps tools, merges reasoning

GridWorld example

• Dependency-free grid-world mapping scenario: agents discover cells and landmarks under partial observations
• Each round agents publish an agent_update. They read the shared map (from visible records) and choose a move
• Configurable topology and visibility. Optional energy-based participation (join/leave)
• Run from config. Session records outcomes, traces, and agent_updates transparently

{"id":"out-1","kind":"outcome",
"actor":"env","payload":{...}}
{"id":"au-1","kind":"agent_update",
"actor":"agent_0","payload":{
  "decision":{"response":{"choice":{"status":"act","action":2}}}
}}
{"id":"tr-1","kind":"trace",
"payload":{"from_id":"out-0","to_id":"out-1",
"enabled_by_id":"au-1","round":1}}

Stored records

• outcome: env state after each step (observations per agent, done flags)
• agent_update: per-agent decision envelope with choice, optional reasoning, explanation
• trace: from_id, to_id, enabled_by_id — links outcome-to-outcome via the agent_update that caused the transition
• Collection-per-kind (e.g. outcome.jsonl, agent_update.jsonl, trace.jsonl)

from doagent.analysis import (
    provenance, traceability,
    accountability, interpretability,
)

# DOAgent Analysis Module
provenance.render_chain_tree("last", run_id,
    output_base="output", write_output=True)
traceability.build_trace_graph(run_id,
    output_base="output", write_output=True)
accountability.causal_attribution(run_id,
    output_base="output", write_output=True)
interpretability.build_atomic_explanations(
    "last", run_id, output_base="output",
    write_output=True)

Analysis from records alone

• Traceability: cause-effect graph across the run
• Provenance: chain of records leading to an outcome
• Accountability: causal attribution — which agent caused which state transitions
• Interpretability: atomic explanation units from traces and decisions

All analysis uses only shared records. No access to policy or env internals. Same tools for any policy type.

Causal attribution results: Left: per-agent cumulative discovery over rounds. Centre: total cells discovered per agent. Right: decision effectiveness (productive vs redundant transitions). All derived from shared records.

def heuristic_goal_seek(params):
    def decide(request):
        obs = request["inputs"]["observation"]
        action = compute_best_move(obs)
        return {
            "choice": {"status": "act", "action": action}
        }
    return decide

Policies in MAS are functions that map an agent's observations to actions:

Agents have always had policies: rules, heuristics, RL, symbolic planners. A policy receives a observations and returns an action

DOAgent is model-agnostic: the library coordinates decisions, not how they are made.

Policy Factorisation decomposes the agent's policy into reasoning and action (Wei et al., 2026).

: history at step ; : internal reasoning; : external action.

• z (reasoning): chain-of-thought, tool-use traces, confidence scores
• a (action): the environment-specific primitive

LLM-based policies produce z in natural language. Is that a particular feature of Agentic AI?

{
  "actor": "agent_3",
  "kind": "agent_update",
  "payload": {
    "decision": {
      "response": {
        "choice": {"status": "act", "action": 1},
        "reasoning": {
          "confidence": 0.8,
          "source": "llm",
          "text": "Moving left is the least
            explored direction...",
          "tool_steps": [{"kind": "tool",
            "name": "llm", "elapsed_s": 1.24}]
        }
      },
      "explanation": "Moving left — least explored."
    }
  }
}

LLM record: action + observable reasoning (z).

{
  "actor": "agent_3",
  "kind": "agent_update",
  "payload": {
    "decision": {
      "response": {
        "choice": {
          "status": "abstain",
          "action": null
        },
        "reasoning": {
          "confidence": 0.0,
          "source": "llm",
          "text": "All surrounding cells explored.
            Cannot determine best move."
        }
      },
      "explanation": "Abstained: low confidence."
    }
  }
}

Let's imagine the hypothetical case where the agent says "I Don't Know".

If we factorise the policy, DOAgent offers and engineering approach to observe the reasoning trace that explains why the agent abstained.

• Traceability: Traceable multi-agent coordination and sensitivity analysis.
• Event analytics: over agent records: causal attribution, abstention rates, policy comparison.
• Interpretability: understanding why agents made a give decision.

Deploying ML in the Intensive Care Unit to support practitioners in collaboration with clinicians at the Karolinska Institute.

Uniform access to harmonised ICU data across heterogeneous sources (aICU, MIMIC, eICU, HiRID, …).

• Federated deployment: same library locally and on hospital servers.
• Harmonisation layer: clinical concepts mapped to per-source extraction rules.
• Query engine: DuckDB with delta_scan on versioned Delta Lake tables.
• Privacy by design: least-privilege reads, auditable lineage, no unnecessary export.

from aicu_access import load_concept
df = load_concept("hr", source="miiv")

• Data architecture: heterogeneous datasets, privacy and anonimisation approaches, generation of synthetic datasets.
• ML models: reproducing and benchmarking ML models for a given problem on top of our dataset.
• Interpretability: interpretability and explainability approaches for health care models.
• Sensitivity Analysis: determine how models influence each other when we connect more than one..