Building Agentic Systems

What it is

An Agentic Graph is a directed acyclic graph. Every node is one bounded agentic loop, a unit of work an agent runs end to end. Every edge is a control-flow dependency. A node is not a prompt and not a function call. It carries:

• A precise brief, written so an agent that has seen nothing else can act on it.
• Typed inputs and outputs, so data flow is declared separately from control flow.
• Success criteria the harness evaluates rather than the model asserts. Kinds include command, file_exists, json_schema, regex, expression, llm_judge, and human.
• An intelligence tier from minimal to frontier, a normalized capability demand that describes the task without naming any model or vendor.
• Tools, permissions, and budgets, the ceiling on what a node may do and what it may spend.
• Failure handling: retries with feedback, fallbacks, escalation, and human gates.

Node types cover tasks, decisions, human gates, bounded loops, bounded fan-out maps, and subgraphs. Every loop has a max_iterations and every fan-out has a max_items, so there is no way to write an unbounded document. JSON and YAML are the same data model, and a YAML file that does not survive a lossless round trip through JSON is not a valid AGS document.

How to use it

If you are planning work: author a graph by hand, or have an agent generate one, then read it before anything runs. A node is a few lines.

ags_version: "1.0"
kind: AgenticGraph
id: myorg/add-healthcheck
title: Add a health check endpoint
objective: Expose GET /healthz returning service and dependency status.

entrypoints: [implement]

nodes:
  implement:
    title: Implement /healthz
    description: >
      Add a GET /healthz endpoint returning 200 with {"status":"ok"} when the
      database and cache are both reachable, and 503 with per-dependency detail
      when either is not.
    intelligence:
      tier: standard
    requirements:
      tools: [file_read, file_write, shell_exec]
      permissions: [fs:read:**, fs:write:src/**, shell:exec:pytest*]
    success:
      summary: The endpoint exists and behaves as specified under test.
      criteria:
        - id: tests_pass
          kind: command
          description: The health-check tests pass.
          run: pytest tests/test_healthz.py -q

Validate it against the reference implementation, then hand it to any conformant harness:

python3 -m pip install jsonschema pyyaml
python3 tools/validate_agraph.py path/to/graph.agraph.yaml
python3 tools/validate_agraph.py --strict examples/

If you build harnesses: the repository has a JSON Schema for graph documents and another for run records, five worked examples, invalid fixtures that each name the diagnostic they should produce, and an integration guide covering parsing, scheduling, model routing, criteria evaluation, and human checkpoints. You pick a conformance level and reject graphs that need more, rather than silently ignoring what you cannot do.

• 0Reader. Parse, validate, resolve dependencies, render a plan. No execution.
• 1Minimal harness. Tasks and gates, sequence edges, retries, the basic criteria kinds, tier routing.
• 2Standard harness. Decisions, conditional edges, the full expression language, budget enforcement, real parallelism, escalation.
• 3Full harness. Loops, maps, subgraphs, judged and external criteria, compensation, run records, checkpoint and resume.

Why it matters

When the decomposition lives inside a harness, four things follow. You cannot review the plan before the tokens are spent. You cannot move it to another tool. Completion is whatever the model claims it is. And every task gets the same model, which either overspends on trivia or underspends on the one architectural decision that mattered.

Making the plan a file fixes all four at once. It becomes reviewable in a pull request, diffable across revisions, portable between harnesses, and checkable against criteria a machine can run. The tier field is the quiet win: a graph states how hard each piece of work is, and the harness maps tiers to models through its own routing profile, so a plan written today still routes correctly when next year's models arrive.

What it is

Loro is the same general harness idea as MagAgent pointed at a different problem. A developer harness optimizes for speed in one person's terminal. An enterprise harness has to answer questions afterward: who ran this, under whose identity, with whose approval, against which policy, and what did it touch.

• Identity context resolved from configuration and environment, with managed required fields propagated into audit and session records.
• Identity-bound approvals with once, session, and deny prompts, plus replay protection.
• Permission policy over normalized filesystem, shell, Git, memory, catalog, provider, and MCP resources, with loro policy explain to show why a decision was made.
• Subprocess sandbox profiles with minimized environments, bounded runtime and output, and optional Bubblewrap enforcement.
• Runtime budgets covering model bytes, tokens, cost, and tool calls.
• A hash-chained audit log: versioned JSONL with process locking and a SHA-256 chain, an authenticated HTTP sink, bounded buffering with retry, and audit doctor, flush, and verify commands.
• Governed memory, local and shared, with Postgres and Apache Iceberg adapters where shared writes are explicit-only and draft-gated, plus read-only Apache Polaris catalog discovery.
• Layered configuration from system, user, project, local, and runtime sources, with enterprise-managed overlays that can be required and pinned by SHA-256.

It also generates artifacts, Markdown and DOCX documents, PPTX decks, and XLSX or CSV spreadsheets, each with a provenance sidecar recording the prompt preview, generated paths, assumptions, and generator metadata. It speaks MCP as a client and can serve a least-privilege read-only subset as a server.

Since 0.12.0 the harness has grown three things worth calling out. Channel gateways now cover Slack, Discord, Telegram, Teams, Signal bridges, and generic signed webhooks, with platform users mapped to tenant-scoped Loro identities and remote message text explicitly carrying no approval authority. A credential vault keeps provider and gateway secrets in the operating-system keyring, including multiple named accounts for the same provider. And loro get-started reads the current folder's provider, model, profile, workspace, memory, MCP, sandbox, and audit readiness, then recommends the next command.

Current release: 0.16.1 completes that loopback-first React Web UI over the same governed runtime. The parts that make Loro Loro are now in the browser: Agentic Graphs run through the same governed executor and hold human gates for an explicit decision; a read-only Governance view shows resolved identity, budgets, sandbox posture, what policy would decide for a hypothetical request, and the audit record with its hash chain verified; and Memory exposes local notes, governed shared memory, and the proposal queue, where a proposal can now be declined rather than only accepted. A chat reply and a graph run each outlive the page watching them, resuming from a cursor after a reload. Nothing about it is a second policy path: the browser sees what the CLI would allow, and no more.

How to use it

Install, configure a provider, then run the setup wizards for the governance pieces your organization needs. There is a mock provider so a first run needs no API key at all.

python -m pip install loro-agent
loro configure
loro get-started
loro doctor

loro setup identity
loro setup approvals
loro setup sandbox
loro setup audit

loro run "Inspect README.md and suggest the next three improvements."
loro audit verify

python -m pip install "loro-agent[webui]"
loro web                     # the same governed runtime, in a loopback browser

For work that needs explicit scheduling and approval, go through a graph instead of a single prompt. Loro implements AGS at conformance level 3, including durable resume, model-tier routing, harness-evaluated criteria, gates, branches, bounded loops and maps, subgraphs, parallel execution, fallbacks, and compensation. When a graph node names an OAP profile, Loro intersects the graph, profile, identity, and managed policy before it runs anything.

loro graph generate "Create a release readiness report" --out release.agraph.yaml
loro graph validate release.agraph.yaml --strict
loro graph plan release.agraph.yaml
loro graph run release.agraph.yaml --dry-run

Why it matters

Agentic coding stalls in regulated environments for a reason that has nothing to do with model quality. The blocker is evidence. A team can rarely say which identity authorized a write, what the policy was at that moment, or prove the record has not been edited since. Loro is built so those answers exist by default rather than being reconstructed later.

Worth saying plainly: shipping this in a portable, provable form is what the project covers. Identity-provider integration, production sandbox validation, retention, destination immutability, and an approved external-checker registry are deployment concerns that belong to the adopting organization. The repository documents that boundary instead of implying the box is checked.