A5.5 · LESSON 5 OF 6

Orchestration and tracing

Choose when to delegate independent work and define handoffs, shared-state rules and evaluation.

THE IDEA

Orchestration and tracing

The orchestrator coordinates the workers: it assigns tasks, respects dependencies and integrates results. To diagnose a slow or failed run, record each worker and tool call as a span with the trace id, its own id and its parent's id. Then latency, cost and failures can be attributed to the part of the workflow that caused them: here worker-2 took 85 of the workflow's 100 ms, and the search tool inside it took 50.

s1 workflow parent=- s2 worker-1 parent=s1 s3 worker-2 parent=s1 s4 tool: search parent=s3

Every worker and tool call is a span carrying the trace id, its own id and its parent's id. That is how latency, cost and failures are traced back to the parent workflow. Without the parent ids, the spans are just an unordered list.

Add a span whose parent is missing.

Predict first. What links an agent tool span to its parent workflow?

Chapter context

Delegation can divide a task into focused work units, but coordination creates costs and new failure paths. Add helpers when their independent contributions can be integrated and checked more clearly than one agent can do the work alone.

TRY IT YOURSELF

Part 1. Do it hands-on

Read a trace by hand, then rebuild its tree and find orphans.

s1 workflow parent=- s2 worker-1 parent=s1 s3 worker-2 parent=s1 s4 tool: search parent=s3

duration of worker-2 (ms) spans in the trace orphan spans when parent "zz" is missing trace id alone rebuilds the tree? (yes/no)

To do: Spans of one trace (ms): workflow 0–100; worker-1 5–60; worker-2 5–90; tool: search 30–80 (child of worker-2). Duration of worker-2?
To do: How many spans does the trace contain?
To do: A fifth span names parent "zz", which is not in the trace. How many orphan spans are there?
To do: Is a trace id alone enough to rebuild the parent-child structure of the spans? Type yes or no

Part 2. Do it in code

spans is a list of {"id", "parent" (id or None), "name", "start", "end"} sharing one trace.
duration(span): end − start.
orphans(spans): the sorted ids of spans whose parent id is not None and not present in the trace.
build_tree(spans): the root spans (parent None) as nested dicts {"name", "duration", "children": [...]}, children ordered by start time then id. Orphans are not included.
slowest_child(spans, parent_id): the id of the child of parent_id with the longest duration (ties: smaller id), or None if it has no children.
tool_spans_under(spans, root_id): the sorted ids of all descendants of root_id.

def duration(span):
    pass

def orphans(spans):
    pass

def build_tree(spans):
    pass

def slowest_child(spans, parent_id):
    pass

def tool_spans_under(spans, root_id):
    pass

Ctrl/⌘ + Enter runs it

Stuck, or something not working? You can come back to it any time.

CHECK YOUR UNDERSTANDING

What links an agent tool span to its parent workflow?

AThe trace id plus parent-span identifiers recorded under the tracing system, not the order of log lines.BThe span's name and its start time.CThe position of the span in the log file.

Chapter reference: math, worked example & code

This section belongs to the whole chapter, so it is the same on every lesson in it and may cover a different lesson's topic. The code for the experiment you just ran is inside the experiment itself.

Math and notation

With independent parallel task durations $t_1,\ldots,t_n$ and merge time m, an ideal lower-bound schedule is $\max_i t_i+m$ , excluding orchestration overhead. If independent tasks each succeed with probability p, all n succeed with probability $p^n$ ; correlated failures invalidate that simple model.

Worked example

Three tasks take 2,5 and 3 minutes; integration takes 1. Ideal sequential duration is 11 minutes, while fully independent parallel duration is 6. Separately, three independent 90%-reliable components all succeed with probability 0.9^3=0.729. The latency gain does not itself establish a reliability gain.

Reference code

The following example uses the Python standard library and does not call a remote service.

from math import isclose
times,merge=[2,5,3],1
assert sum(times)+merge == 11
assert max(times)+merge == 6
assert isclose(.9**3,.729)

Python examples are provided for study and local execution; this page does not execute Python.

Common mistakes

Parallel workers need explicit ownership of shared artifacts. Agreement can reflect correlated failure. More agents can increase token usage and integration work even when wall-clock time falls.