Recorded multi-agent coordination¶
Read-only Harbor and Omnigent imports now export coordination.json and
coordination.html alongside their existing traces, receipts and inventories.
These reports join supplied evidence without running an agent or merging
separate documents into a session trace. They are included in
agentloop-profiler==0.1.0.
Offline workflow¶
Use Python 3.10+ and the installed checkout. Harbor, Omnigent, vendor clients, credentials, a database and a dashboard are unnecessary:
uv sync --locked --dev
uv run --frozen agentloop harbor import-atif tests/fixtures/external/harbor/atif_embedded_subagents.json --synthetic --out runs/coordination-harbor
uv run --frozen agentloop omnigent import-otel tests/fixtures/external/omnigent/parent_child_multi_trace.otlp.json --synthetic --out runs/coordination-omni
uv run --frozen python examples/multiagent_coordination.py --out runs/coordination-example
The Harbor fixture retains three distinct trajectory documents in one shared session, two referenced children and three reported model calls. Recorded model blocks report 36 input tokens; the parent/child inclusive final aggregates total 60 if blindly added. The report preserves those aggregates separately and uses 36 for attribution to the recorded model leaves. Cached tokens remain a subset. The fixture has no complete root timing: wait, overlap and critical path are unavailable.
The Omnigent fixture retains two native trace IDs. Its span link correlates the records but establishes no causal parent, handoff or cross-trace critical path. The example adds owned implementer/reviewer/responder spans with actual synthetic intervals. It reports the observed overlap and child failures without claiming a review quality effect or provider benefit.
For completed Harbor jobs, agentloop harbor import JOB --out OUT also writes
coordination reports. Trial agent-context usage remains separate from trajectory
usage. The reported parent task/verifier outcome can be attached to a child
observation, explicitly scoped to the parent trial; it does not establish that
child's independent contribution or correctness.
Evidence and metric boundaries¶
| Field | Evidence and meaning |
|---|---|
actors |
Each ATIF trajectory document or recorded Omnigent AGENT span; native run/event and receipt identities remain distinct |
handoffs / handoff_count |
Recorded ATIF delegation references or explicit source span parents for AGENT operations; no network dispatch count inferred from names |
observed_child_count |
Distinct supplied children resolved by scoped document/span identity |
unknown_child_count |
Referenced children lacking a supplied projection; no invented duration/status |
child_failure_count |
Explicit recorded failed, timed-out or cancelled child status; unknown child statuses counted separately |
handoff_wait_ms |
Unavailable without a dispatch/blocking-join interval; child runtime is reported separately and never substituted |
parallel_overlap_ms |
Union of time with at least two recorded leaf actors; enclosing parents are excluded; incomplete timing or declared missing children prevents a complete total |
known_parallel_overlap_ms |
Overlap among supplied timed leaves, with its denominator; not independence, a synchronization guarantee, or a missing-child estimate |
critical_path_by_trace |
Existing execution graph calculation only for a connected, acyclic, fully timed explicit source span tree; no order-based edges |
critical_path_ms |
Available only for one such trace without unresolved/correlation relationships or missing children; never a guessed cross-process task path |
model_call_count |
Source-reported multiplicity for recorded blocks; complete executor coverage is not established |
usage |
Known and complete-for-recorded-leaves input/output/cache counts; nested model parents and source inclusive aggregates excluded from leaf sums |
retry_count |
Unavailable because these source contracts do not establish all retry attempts |
possible_duplicate_work |
Same named tool with identical explicitly captured arguments in the same source scope; investigation evidence, not safe reuse or saved spend |
review_overhead_ms / review_quality_delta |
Unavailable without controlled reviewed-vs-unreviewed task pairs |
agent.role and omnigent.agent.role are bounded observational aliases; ATIF
agent.extra.role preserves the explicit reviewer, implementer and responder
labels. A role label never changes a verifier outcome. Parent agent/session aliases
may resolve to one actor, multiple actors or no actor. Those references remain
noncausal and create no dispatch or dependency edge. Native OTel parents remain
scoped to their original source trace.
Source clocks are not independently synchronized or authenticated. Converter- inferred timing and conflicting source segments cannot establish measured actor latency or a critical path. Actual source intervals may describe overlap even when full execution coverage is unknown; the report states that scope.
Python API and duplicate-work investigation¶
from agentloop.integrations.harbor.atif import import_atif
from agentloop.interoperability.coordination import summarize_coordination
result = import_atif("trajectory.json")
report = summarize_coordination(result.traces, result.source_receipts)
result.write("runs/imported") # Includes the JSON and HTML coordination reports.
The API checks each projection against the byte hash in its immutable receipt. It rejects mutated traces, multiple receipts claiming one run and ambiguous trajectory identities. Job/trial namespaces keep repeated trajectory IDs distinct. Original traces, receipts and outcomes remain unchanged.
Default input capture omits tool arguments, so equal tool names or argument sizes
cannot support duplication. AtifOptions(capture_content=True) is an existing
explicit privacy opt-in. With complete captured argument dictionaries, the report
compares canonical hashes and exports only hashes/span references, never argument
values. Omitted/redacted arguments remain unsupported. Changing tool state,
side effects and required independent checks still prevent a reuse conclusion.
Use the existing semantic investigations and
paired interventions to validate a proposed removal; no new
finding estimator, model judge or savings claim is added by coordination import.
Privacy, failures and compatibility¶
Default imports omit raw prompts, outputs, reasoning, tool arguments and arbitrary exception text. Report text is escaped and HTML uses the existing offline exporter styles and restrictive content policy. Explicit content capture affects the underlying imported artifacts; treat them according to the existing import guide.
Unresolved children, missing intervals, invalid/cyclic parent graphs, unrecorded roles, unknown usage and noncausal links stay visible. Export is idempotent for identical supplied bytes and refuses conflicting files or indirect output paths. No source scripts, verifiers, providers or external URLs execute. Native trace, study, storage and database schemas and core dependencies remain unchanged.
The frozen Harbor ATIF contracts are described in HARBOR_ATIF.md,
and Omnigent aliases in OMNIGENT_OTEL.md. Their pinned source
revisions are d5ac1be17f575852eaf4fffc4072fd18481c209b and
a2956be0e97bb175a60b274053d836f07d494c6c, respectively. These owned fixtures
exercise format behavior, not live vendor compatibility. Artifact hashes establish
consistency with supplied bytes, not source authenticity, verified provider
billing, or a causal harness effect.