ARK

Runtime supervision and observability for AI agents.

Keep your model. Keep your agent. Keep your tools. Add ARK around the runtime.

ARK sits between an agent's proposed consequential tool action and its execution. Before the action runs, ARK validates it against the runtime constraint that applies and the trusted evidence you provide, then returns one of ALLOW, REJECT, REQUIRE_EVIDENCE, or RECOVERY_EXHAUSTED. Only an allowed action runs. ARK does not author the replacement action. The agent remains the author.

pip install ark-agent-runtime

from ark import ARK

Alpha software, version 0.1.0a2. Supervision is experimental and off by default.

Why ARK

An agent can know a rule and still propose the wrong tool call. Once that call runs, explaining it correctly afterward does not undo the side effect. The booking already happened. The row was already written.

ARK sits at that point, just before the call runs. It gives the runtime a place to look at the proposed action, the constraint that applies, and the trusted evidence, and then decide whether the call goes through.

agent proposes an action
        |
        v
     ARK check
      |     \
   ALLOW     not ALLOW
      |          \
   it runs     feedback goes back, the agent proposes again

Install

pip install ark-agent-runtime

from ark import ARK

The core SDK has zero runtime Python dependencies and is tested in CI on Python 3.9 through 3.14. The wheel ships with the Go runtime bridge for your platform, so you do not need Go installed, the source repo, PYTHONPATH, or ARK_BRIDGE_BIN. The import stays from ark import ARK.

Two ways to use ARK

1. Run a task through ARK

from ark import ARK

ark = ARK()
result = ark.run("hello from ARK", mode="mock")

print(result.success, result.total_cost)
for d in result.decisions:
    print(d.id, d.action, d.model, d.cost.total_cost)

Mock mode works with no API key, so you can try it right away. mode="live" runs a real provider and needs a configured model, meaning an API key and an agent.yaml.

2. Put ARK around your own agent

You do not replace your agent to use ARK. You keep your framework, your model, and your tools, and you report what the agent did. ARK builds the same result.

from ark import ARK

ark = ARK()
with ark.trace("book the second cheapest flight") as run:
    # your loop, your model, your tools
    run.record(action="tool_call", tool="search", model="gpt-4o-mini",
               input_tokens=449, output_tokens=16, outcome="success")

result = run.result
print(result.total_cost, [d.model for d in result.decisions])

This is the mode that matters if you already have an agent. ARK never runs your model. You do.

Runtime supervision (experimental)

Supervision is experimental and off by default. Turn it on with ARK(supervision="experimental").

The flow:

1. your agent proposes an action
2. ARK checks the constraint that applies
3. ARK checks the trusted evidence you provide
4. ARK returns a verdict
5. on a verdict other than ALLOW, the agent gets feedback and decides again
6. your integration runs the action only after ALLOW

from ark import ARK

with ARK(supervision="experimental").trace("book a flight") as run:
    verdict = run.check(
        proposed_action={"option": "A"},
        constraint="rank",
        evidence={
            "requested_rank": 2,
            "evidence_complete": True,
            "options": [{"id": "A", "price": 163}, {"id": "B", "price": 290}],
        },
        tool="book",
    )
    if verdict.allowed:
        ...  # run the tool
    else:
        # the agent reads the verdict and feedback, then proposes the next action itself
        ...

The agent stays the author. ARK returns a verdict and feedback grounded in the evidence. It does not write the next action. The agent reads that feedback and decides what to do next.

Supervision is not a correctness guarantee. It does not make an agent safe, and it does not catch every bad action. It gives the runtime one place to check a proposed consequential action against a constraint and trusted evidence before the action runs.

LangGraph

There is a real integration with LangGraph. You keep your LangGraph agent, your model, and your tools.

pip install "ark-agent-runtime[langgraph]"

from ark.integrations.langgraph import ArkCallbackHandler, ark_supervise_tool

The extra requires Python >=3.10 (LangChain and LangGraph 1.x declare requires-python >=3.10) and is tested in CI on Python 3.10 through 3.14. Core ARK on 3.9 is unaffected; only the LangGraph extra needs 3.10+.

To observe, pass ArkCallbackHandler(run) in the callbacks and ARK records the model and tool decisions from LangChain's callback events. To supervise, wrap a tool with ark_supervise_tool(run, tool, constraint=..., evidence=...): before the real tool runs, ARK checks the proposed action, and on a verdict other than ALLOW the tool does not run and ARK returns evidence-grounded feedback as the tool result, which LangGraph feeds back to the model.

Verified authorship, live with a real OpenAI model

model proposes A
   -> ARK REJECT
   -> A does not execute
   -> feedback returns to the model
   -> model proposes B
   -> ARK ALLOW
   -> only B executes

B was authored by the model, not generated by ARK. This shows the mechanism can supervise a real external agent framework while the agent keeps authorship. It does not show that ARK improves every LangGraph agent.

Reporting and observability

Every run returns a canonical RunResult. A decision can carry the model and provider, input and output tokens, cost (which ARK derives from tokens and model when you do not pass one), the tool or proposed action and its outcome, a supervision verdict, executed state, retry number, latency, and a stable id that links a proposed action to the action that ran. Run totals include total cost, total tokens, and cost grouped by model, by tool, and by action. Missing fields stay empty; ARK does not fill them in.

run.report()               # readable summary of the run
run.report(verbose=True)   # adds per-decision evidence and reported-vs-derived provenance
result = run.result
result.to_dict()           # the canonical RunResult as a dict
result.to_json()           # the canonical RunResult as JSON

report() prints run status, the model and tool decisions in order, costs and tokens, supervision verdicts, executed state, and retries. verbose=True adds the evidence behind each verdict and, from the trace session, the provenance of each fact (what your runtime reported versus what ARK derived). result.report() prints the same summary when you only have the RunResult.

cost_by_supervision is the cost of decisions that carry a supervision verdict. It is not necessarily ARK's causal incremental overhead.

Concurrency and transport

The runtime session transport is serialized per session, so concurrent callers cannot interleave on the single line protocol. This is tested with parallel LangGraph tool fan-out. A verified six-way parallel fan-out produced six concurrent tool decisions with unique decision ids, a successful run, and no JSON corruption.

A deliberately hung bridge is subject to a bounded timeout: the process is terminated, and the dead session then refuses further calls rather than consuming a stale or late response as the answer to a later command.

Platforms and fresh install

All five platform wheels are built and fresh-installed in CI, each carrying the bundled Go runtime bridge:

• macOS arm64
• macOS x86_64
• Linux x86_64
• Linux arm64
• Windows x86_64

The release candidate was installed into a clean environment outside the source repo, with PYTHONPATH and ARK_BRIDGE_BIN unset. There ARK imported from site-packages, the bundled bridge was discovered automatically and executed ARK().run(), the canonical RunResult telemetry came back, cost reconciliation passed, ark.trace() worked, and supervision stayed off by default.

Python compatibility

Evidence

Two separate results, held to their own scope.

A scoped benchmark: tau-bench airline, K=16

Paired evaluation on one constrained recovery failure class.

That is +75 percentage points, with nine directly attributable recoveries and zero observed regressions. Rank was satisfied on all 16 of 16 trials, with zero false rejects and zero evidence leakage.

Scope: this is one constrained recovery failure class in the tau-bench airline research environment. tau-bench airline is a research benchmark, not an airline. It is not evidence that ARK improves every agent or every workload, and it does not solve hallucinations.

A small local paired evaluation

A small local paired mechanism and regression check over five action-validation cases. OFF passed 0 of 5 and ON passed 5 of 5.

Every one of the five ON successes contained an actual non-ALLOW intervention followed by a later ALLOW, so all five are attributable and none are unattributed. Case 4, for example, went REJECT, REJECT, REJECT, then ALLOW. This is a small local mechanism and regression check, not the headline benchmark, and not a general 100% reliability claim.

How recoveries are attributed

An OFF-fail with an ON-pass is counted as an ARK recovery only when a non-ALLOW ARK intervention precedes a later successful ALLOW. An ON win with no intervention is classified as unattributed, not credited to ARK.

Safety of claims

• Supervision is experimental and off by default.
• ARK is not a correctness guarantee.
• ARK does not solve hallucinations in general.
• The evidence here applies to scoped action-validation workloads, not to arbitrary agents or tasks.

Also in ARK

When ARK runs the workload itself with ark.run, it also routes each step to a model and can run structural checks on code output, such as compile and lint. These appear in the same telemetry and are secondary to the supervision and observability story above.

License

The ark-agent-runtime package, meaning the Python SDK and the bundled Go bridge, is licensed Apache-2.0. The license ships inside the wheel.

Feedback

Issues and ideas: https://github.com/atripati/ark/issues