Software systems are the interfaces between AI technologies and our socio-technical systems.

Socio-technical systems include people, institutions, infrastructure, and digital technologies that cooperate to serve our society

• Government agencies
• Hospitals
• Industries
• Universities
• Research institutes
• ...

AI-based software systems are data-driven. Unlike in traditional systems, developers cannot fully predefine their behaviour. ML components learn such behaviour from data, operating as black boxes that propagate uncertainty into complex software.

AI-based software systems are data-driven. Unlike in traditional systems, developers cannot fully predefine their behaviour. ML components learn such behaviour from data, operating as black boxes that propagate uncertainty into complex software.

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).

Threat to AI applications and promises

• Mundane applications for problems we did not know we had
• Disregard for social and environmental implications
• Unrealistic expectations and hype
• Exclusion of diverse perspectives and voices
• Unsustainable technologies
• Increased inequality and digital divide
• Security and privacy concerns
• ...

AI as a Service (AIaaS) enables us to access and expose AI capabilities over the internet. We can integrate AI tools such as machine learning models, natural language processing, and computer vision into our applications leveraging SOA and microservices features.

Focus on Operations:

• Separation of concerns
• High availability
• Scalability
• Low latency

Data is secondary and hidden behind services' interfaces.

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

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

Data-First Systems

• Data is available by design
• Traceability and monitoring
• Interpretability

Prioritise Decentralisation

• Super-low latency requirements
• Privacy by design

Openness

• Sustainable solutions
• Data ownership

Most of the surveyed works partially adopt the DOA principles to handle data-intensive requirements. The survey results also show that diverse tools can support adopting DOA principles: Apache Kafka, Spark Streaming, Hadoop Distributed File System, MQTT, and RabbitMQ.

Data-Orientated Architectures make data available by design facilitating monitoring and maintenance. Decentralisation supports local data processing, reducing latency and improving privacy by respecting data ownership. Openness enables managing resource-constrained environments by exploiting the computing power of everyday devices (Cabrera et al., 2025).

How can we exploit these properties to address the intellectual debt problem in AI-based systems?

Positioning of the DOA Debugger

The debugger is designed around DOA principles: make the relevant system state and traces explicit, queryable, and reusable for analysis.

• Input: structured artefacts from training/inference/runtime logs
• Core: data-first representation + retrieval pipeline to support diagnostic reasoning
• Output: interpretable, context-grounded debugging assistance for ML-based systems

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

Positioning of DOAgent

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

• 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.

• AI Software Systems are the interface between socio-technical systems and AI technologies.
• We do not always understand how the inners of these novel systems work, generating Intellectual Debt.
• One cause of Intellectual Debt is the Data Dichotomy generated by current software architecture paradigms.
• Data-Oriented Architectures (DOAs) offer and alternative to avoid the dichotomy and address Intellectual Debt by facilitating traceability and interpretability.