Agent Utilities
The in-run agent harness. agent-utilities holds only the mechanism inside one agent run. It applies the decisions it is given; it does not store, decide, serve or connect on its own.
Version: 3.1.0
What it contains
| Module | What it does inside one run |
|---|---|
agent_utilities.graph |
Applies a received ordered plan or dependency DAG. It enforces task slots and shared budgets, and emits ordered execution events. |
agent_utilities.rlm |
Runs recursive model queries with shared request and tool limits and bounded concurrent model requests. |
agent_utilities.harness.edit_engine |
Parses model-proposed edits (search/replace blocks, unified diffs), applies them with graduated matching, and re-prompts on malformed or unmatched edits. |
agent_utilities.harness.contract_validator |
Checks a tool call's pre-conditions and its output's schema and verifier. |
agent_utilities.harness.constraint_engine |
Enforces hierarchical constraints on tool calls (prompt, tool description, middleware, implementation) and escalates repeated violations. |
agent_utilities.harness.quality_gates |
The pre-emit gate: antipattern detection, a preflight checklist and a multi-dimensional critique, in warn or block mode. |
agent_utilities.runtime |
The developer workspace: typed actions and observations, a stateful shell, local and container backends, a policy gate it is given, and the browser and computer-use tier ports. |
agent_utilities.host_ports |
The protocols the host fills: native and remote toolsets, tool clients, outbound credentials, delegated identity, the fleet catalog and the session keepalive. Without a host every binding port fails closed. |
agent_utilities.core.paths |
Resolves the platform config, data, cache and log directories (ARBORA_CONFIG_DIR, XDG). |
Where everything else lives
- epistemic-graph: facts, records, vocabulary, storage and queries, ingest, retrieval, reasoning, memory, decisions, and learning (evaluation, harness evolution, reward and trace records).
- arbora: admission, auth, served
operations (MCP, REST, A2A), messaging front-ends, the registry and the multiplexer.
arbora hosts this harness and registers the
host_portsproviders. - agent-connector-sdk: connector contracts, transports, the A2A protocol library and connector helpers.
Install and use
pip install agent-utilities
from agent_utilities.runtime import create_workspace
from agent_utilities.runtime.events import CmdRunAction, TestRunAction
async with create_workspace(run_id="r1", prefer_docker=False) as ws:
await ws.act(CmdRunAction(command="git status"))
result = await ws.act(TestRunAction(selector="tests"))
Run measurements
The graph run result and terminal event include metrics from a monotonic
client clock: run_elapsed_ms and ordered model_requests with
client_request_elapsed_ms, outcome, model/provider attribution and validated
per-response token counts. The sample list is bounded; coverage: "partial"
means some observed requests were omitted. Failed requests have no invented
token counts. These measurements are emitted through the host event sink for
shared backend consumption; AU stores no session totals.
Run time includes planning, tools and retries. Client request time includes transport and provider waiting. Neither is provider generation time, and neither is used to derive generation TPS. Provider queue wait, generation duration and TTFT are absent unless a future adapter measures and identifies them explicitly.
Received dependency plans
A host can pass RunPlan(dependency_plan=DependencyPlan(...)) to the same
run or iterate_run entry point. Do not also set serial steps.
DependencyPlan contains ordered RunTask(task_id, prompt, depends_on) values,
an output_task_id, a max_concurrency task cap and an optional plan_id.
The host gets the plan from EG and admits it through Arbora. AU does not turn
free text into a plan or authorize a task.
A completed task frees a slot at once. A dependent task can start while an unrelated task still runs. Every prerequisite must succeed. Each task gets a fresh history with only its direct dependency outputs. The output task must be the sole sink. Failed or stopped plans never return a partial child answer as a completed parent result.
The trusted host can pass prior measured consumption as RunPlan.initial_usage
(a pydantic_ai.usage.RunUsage) and initial_elapsed_seconds. Both default to
zero. Keep RunBudget at its original bounds; do not subtract this usage in
the host or add it to AU's result again. AU snapshots the reported request,
tool and token counters. It includes them once in terminal aggregate usage.
It subtracts the elapsed time once from the execution deadline. Exhausted initial
model bounds stop before model binding or child dispatch. Prior tool usage above
the tool limit also stops. At the exact tool limit, model-only answers remain
allowed, but additional tools do not. Invalid counters or time
fail closed. Model proposals, request metadata and scaffold updates cannot
set this host-only input. Unreported token usage remains zero, not an estimate.
If measured host work fails before a plan can return, the decision provider can
raise RunPlanFailure(error, initial_usage=usage, initial_elapsed_seconds=elapsed).
AU validates the same inputs and includes the counters once in the terminal
event and result. It preserves the original failure or cancellation, without
dispatching work or replacing a budget. Do not wrap a provider failure without
a reported usage ledger or add these counters again in the host.
run() returns a failed RunResult. AgentRunExecutor.execute_agent() raises
RunFailed, a RuntimeError subclass with the same error message. Its immutable
result snapshot retains that aggregate receipt, with run_id and usage
properties. The allowed host facade agent_utilities.runtime lazily re-exports
the same run executor, plans, tasks, bounds, stop rule and failure types.
Hosts must check the exception type and expected run identity
before copying these counters. Keep the outcome failed; do not publish a
partial answer or add the counters again. Successful and stopped returns,
cancellation, and empty unreported ledgers keep their existing behavior.
Request and tool reservations are shared across tasks and validation retries.
An unspecified parallel tool limit uses a finite fallback of fifty calls.
Token limits use reported usage, including fallback attempts. In-flight token
use is not known in advance. RunBudget.max_concurrent_requests also caps
model requests (fallback: four); the task cap can be lower. On cancellation,
AU drains child coroutines before invoking host-scope exit. Hosts own the
cancellation safety of their asynchronous scope exits; repeated cancellation
can interrupt that host cleanup. Host tools also own external work that cannot
stop with their coroutine. No elapsed cleanup bound is promised for handlers
that do not cooperate.
RLMConfig.max_concurrent_requests and tool_calls_limit bound recursive
model calls and tool fan-out (fallbacks: four and fifty). A parent releases its
model-request slot before waiting for a child, including at capacity one.
The parent model still chooses its next tool batch after the current batch
returns. That model-choice boundary is not a declared dependency DAG.
Public lifecycle events have a per-run sequence and stable event_id.
Task events carry task_id, parent_run_id, plan_id and depends_on.
They report execution state, not private model reasoning. Arbora owns their
safe replay projection and access checks.
A DAG driver owns the deadline after setup, using the same absolute deadline. A paused event reader cannot delay task dispatch or timeout cleanup. Consumers must finish or close the iterator. Pausing can delay the parent terminal event and host-scope release, even after all task work has stopped. Request handlers finish asynchronous cleanup before cancellation returns, including nested runs.
Develop
uv sync --group dev
uv run ruff check . && uv run ruff format --check .
uv run mypy agent_utilities
uv run pytest -q
License
MIT, see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for agent-utilities 3.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| agent_utilities-3.1.0.tar.gz | 119.3 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agent_utilities-3.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 209.3 kB
Release files / agent_utilities-3.1.0.tar.gz
| Download URL | agent_utilities-3.1.0.tar.gz |
|---|---|
| Size | 119.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1539cbd00bbb34c24aa6e300d72749f98fdd258684ba5de70ad2b3d999bdf4b7
|
|
BLAKE2b-256 checksum How to use checksums |
0142c856d3973b3155a41ca184a55fb72fea7d90535954c2bb7b0c18d4f98470
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / agent_utilities-3.1.0-py3-none-any.whl
| Download URL | agent_utilities-3.1.0-py3-none-any.whl |
|---|---|
| Size | 90.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b8969b4c7ff5260ef498f32a16945e4d2a033a181e9a82347cb5cbf335429fd7
|
|
BLAKE2b-256 checksum How to use checksums |
dfb8129fe9a03496cead1106f07f25e6d59efe593ca5a506f6c34f613f24c518
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for agent-utilities 3.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
