Evalgent
Back to Blog
Voice AI Testing

Tracing Voice Agent Handoffs and Transfers Across Agents and Humans

Deepesh Jayal
15 min read
Tracing Voice Agent Handoffs and Transfers Across Agents and Humans
On this page

A caller reaches a billing agent, gets passed to a retention agent, then asks for a person. Three minutes later your dashboard shows three short calls, or two calls and an orphan. Nothing looks broken. The caller had to repeat their account number twice.

This post is voice agent handoff tracing: how one conversation stays one trace across agent swaps and across cold and warm transfers to humans or other systems. It is vendor-neutral. The examples are illustrative, not measured.

Other posts cover the neighbouring ground. For loops and guardrails, read how to test for handoff loops. For scoring a handoff, see escalation accuracy and escalation rate. For routing tests, see multi-agent orchestration. For the telephony mechanics, see ending and transferring calls in LiveKit and Pipecat. We link to them instead of repeating them.

What counts as a handoff in a trace

A handoff is any moment where the party in control of the caller changes. In a trace, that means one span ends or pauses and a different actor begins. Five kinds matter.

Handoff typeExampleWhat your trace can see
Agent to agent, same sessionBilling agent swaps to retention agentEverything, in one process
Agent to another serviceAgent calls a scheduling service over HTTP or a queueYour side, plus theirs if they continue the trace
Cold transferAgent sends the caller to a phone number or SIP addressYour side up to the transfer request and its result
Warm transferAgent briefs a human first, then connects themYour side, including the briefing
Handoff to a desk systemCase created in a ticket or contact centre toolOnly what that system reports back

The pattern is simple. The further control moves from your code, the less the trace can see. Good voice agent handoff tracing is mostly about what you record at the edge. Past the edge, you record nothing.

How context propagation carries one call across a handoff

OpenTelemetry defines context as the information a sender and receiver need to correlate signals. Propagation is the mechanism that moves that context between services and processes. The default propagator uses the headers from the W3C Trace Context specification.

That specification defines a traceparent header with four fields: version, trace ID, parent ID and trace flags. The W3C Recommendation, dated November 23, 2021, gives the trace ID as 32 lowercase hex digits and the parent ID as 16. A receiver that continues the trace must set the parent ID to the ID of its own current operation. It must not change the header in any other way.

Two consequences follow for voice.

  • The trace ID is the thread. If every actor in the call keeps the same trace ID, one query returns the whole journey.
  • The parent ID is the join point. Each new actor's first span names the handoff span as its parent.

The OpenTelemetry trace API specification calls a span a remote child when its parent was created in another process. A span context received from elsewhere reports IsRemote as true. That flag is how you tell, later, which spans crossed a boundary.

Here is a simplified Python sketch of the sender and the receiver, using the propagator classes from the OpenTelemetry Python propagation guide.

from opentelemetry import trace
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

tracer = trace.get_tracer("voice.handoff")
prop = TraceContextTextMapPropagator()

def hand_off(payload):
    with tracer.start_as_current_span("handoff") as span:
        carrier = {}
        prop.inject(carrier)          # writes traceparent for this span
        payload["traceparent"] = carrier["traceparent"]
        return send_to_next_actor(payload)

def receive(payload):
    ctx = prop.extract(carrier={"traceparent": payload["traceparent"]})
    with tracer.start_as_current_span("agent.receive", context=ctx):
        run_agent(payload)

The carrier can be an HTTP header, a queue field or a ticket column. Your handoff payload just needs a place for it.

Baggage is not a free pass for caller data

OpenTelemetry baggage travels beside the trace context. It is a separate key-value store. It is not copied to span attributes unless you do that yourself. The documentation warns that sensitive baggage can reach unintended resources, such as third-party APIs.

Keep caller names, numbers and account data out of baggage. Carry the call ID, and look details up on the side you trust. See PII redaction in logs and traces.

The rule comes from what the two spans are to each other.

OpenTelemetry links associate one span with others, implying a causal relationship. The trace API says a link can point to a span in the same trace or a different one. It also says links added at span creation are preferred, because samplers may not consider links added later.

Use this decision order.

1. Same process, same call. Make the next agent's span a child of the handoff span. One tree, one trace.

2. Another service you control. Inject and extract the context. The remote span becomes a child of your handoff span.

3. A system you cannot parent. Start a new trace there and add span links in both directions. Your handoff span links to the first span they report. Theirs links back to yours.

4. Work that outlives the call. A follow-up case, a callback or a summary job started after hang-up gets a span link to the call. It is not a child. The call has ended; the work has not.

Decision grid for handoff tracing: same-process agents use a child span, controlled services a remote parent, desk systems new traces with links, and carrier legs record an outcome only.

A child span says "this happened inside that." A link says "this happened because of that." A warm transfer's consult room is inside the call, so it is a child. A ticket handled tomorrow happened because of the call, so it is a link.

The wider span model is in our post on the OpenTelemetry trace and span model for voice agents. It lists links for causal relations outside the parent tree. This post applies that rule to handoffs.

What to record on a handoff span

The handoff span is the one record that explains a transfer. If a caller says "I was passed around," this span is where you look first. Put a small, bounded set of fields on it.

The OpenTelemetry GenAI conventions define an invoke_agent span, plus gen_ai.agent.name, gen_ai.agent.id and gen_ai.conversation.id. As of November 19, 2026, the agent span page marks all of them as Development. It defines the conversation ID as the identifier for a conversation, session or thread, used to correlate messages within it. The same page advises against recording transient in-memory agent instance IDs.

There is no standard handoff attribute set. The names below are suggestions with our own voice.handoff. prefix. Rename them to fit your stack. Our post on voice agent span attributes explains the naming rules.

FieldExample valueWhy it earns its place
voice.call.idcall_8f2aJoins the trace to logs and telephony records
voice.handoff.index2Counts handoffs in order, so loops show up
voice.handoff.typeagent, cold, warm, deskPicks the right reading of the trace
voice.handoff.from and .tobilling, retentionNames both sides, using stable agent names
voice.handoff.reasoncaller_requested_humanSeparates intent from failure
voice.handoff.context_sent5Fields placed in the payload
voice.handoff.context_received2Fields the next actor reported using
voice.handoff.outcomeconnected, no_answer, failedCloses the span with a result

Use stable agent names, not process IDs. Record the reason as a category from a short list. Keep transcripts out of attributes.

The two context counts are the most useful pair. They turn "the human knew nothing" into a number on a span. The fields to count are the same ones that escalation accuracy scores: caller identity and verification, reason for the call, what the agent already tried, the escalation reason and any data collected. Here we only count whether each one arrived. That scoring post covers how to judge them.

Tracing a cold transfer to a human

In a cold transfer the agent sends the caller on and leaves. For the SIP REFER version, RFC 3515 defines the method. REFER asks the other side to act on a target given in a Refer-To header. It also sets up an implicit subscription, so the sender hears the outcome through NOTIFY messages whose body is a message/sipfrag. The RFC's examples show 100 Trying while the action is pending, 200 OK on success and 503 Service Unavailable on failure. The final NOTIFY ends the subscription.

For tracing, that means the transfer has a start, a pending phase and an end, and your span should capture all three.

LiveKit's cold transfer page describes TransferSIPParticipant. It sends a SIP REFER through your trunk. A completed cold transfer closes the caller's LiveKit session. If the destination does not answer within ringing_timeout, which defaults to 30 seconds, the request returns an error and the caller stays in the room. The SDKs raise a SipCallError carrying a SIP status code and message.

So the cold transfer span should look like this.

  • Start when the agent decides to transfer. Record the reason.
  • Event when the request is sent, with the target type, not the number.
  • End with the result: connected, no answer or failed, plus the SIP status code if your platform gives you one.
  • Status set to Error on failure, so the span is findable. An Unset status only means no error was recorded.

Past this point you are blind. Once the caller is connected, your agent is out of the call. Set voice.handoff.outcome to connected and end the trace on purpose. A trace that simply stops looks like a crash. Our post on ending and transferring calls shows which legs stay in your media path.

Twilio's call resource defines parent_call_sid as the SID of the call that created a leg. Store each leg's SID on the handoff span so telephony records and the trace line up. The call ID correlation post covers the mapping table.

Tracing a warm transfer

A warm transfer has more moving parts, and so more places to fail. LiveKit's warm transfer page describes the sequence. The caller is placed on hold by disabling their audio input and output. A transfer agent talks to the human in a private consult room and gets the conversation history to summarise. The human is then moved into the caller's room with MoveParticipant. If the human is unavailable, the agent can return to the caller and explain.

Every step is a place to put a span.

  • Hold as a child span. Its duration is the time the caller waited in silence.
  • Consult as a child span, even though it runs in another room. It is inside the call.
  • Briefing as an event or child span, carrying context_sent.
  • Merge as an event, when the human joins the caller's room.
  • Fallback as a child span if the agent returns to the caller.

Keep the same trace ID across the consult room and the caller's room. The rooms are different, but the call is the same. This is the practical answer to how to keep one trace ID across a warm transfer: the call ID and traceparent are yours, not the room's.

RFC 3891 defines a Replaces header that logically replaces one SIP dialog with another. It names attended transfer as an example use. If your stack uses it, record both dialog identifiers on the handoff span.

Illustrative time axis of a warm transfer: hold, consult room and briefing run as child spans under the handoff span, then a merge event and the human joins.

Tracing agent-to-agent handoffs

Inside one session the mechanics are easier, but the failure is quieter. LiveKit's handoff documentation says each new agent starts with a fresh conversation history unless you pass prior history. You pass it with chat_ctx. A handoff also adds an AgentHandoff item to the chat context with the old and new agent IDs. The full history stays in the session, even when the next agent's context is trimmed.

In a multi-agent handoff, that default makes lost context a quiet defect. The code works. The agent answers. It answers without what the caller already said.

So record on the handoff span how much history moved: the number of turns passed, and whether a summary replaced them. If you truncate or summarise, say which. The next agent's first LLM span then has an honest explanation attached.

For provoking these failures before launch, see testing multi-agent orchestration. Here the job is to find them afterwards.

Finding the four handoff failures in a trace

Four failures account for most of what goes wrong. Each has a shape in the trace that you can query. The example below is illustrative.

Four handoff failure signatures in a trace: lost context, a repeated from-to pair, a handoff span with no receiver, and two handoff spans seconds apart.

Lost context

Look for context_received lower than context_sent on the same handoff span. Then look at the next actor's first spans. If it asks for something already in the payload, such as the account number, you have the cause. Group these by handoff pair. A single pair that always loses context points at one payload builder, not at callers.

Handoff loops

Look at voice.handoff.index and the from-to pairs. A loop shows as an index that keeps rising with the same pair repeating, for example billing to retention, then retention to billing. Query for traces where the same pair appears twice. Our handoff loop post covers the cap. The trace is how you find the loops that got past it. To detect a handoff loop in a trace, count the handoff spans per trace and flag any repeated pair.

Dropped calls

To trace a dropped transfer, look for a handoff span that never closes with an outcome, or closes with one but has no receiving span. Three checks help.

  • Handoff span ended, no child or linked span from the receiver within your expected window.
  • Caller disconnect event during the hold or consult span.
  • Cold transfer span ended in no_answer or failed, but the call continued with no fallback span.

A handoff with no receiver is an orphan: one half exists. Mark it undetermined, not failed, until you can see the other side. Data from a system you do not control may simply be missing.

Double handoffs

A double handoff is two handoff spans, close in time, for one decision. The usual cause is a retry or a duplicate tool call. Look for two handoff spans from the same actor with the same target within a few seconds, or two TransferSIPParticipant-style requests for one call. The caller hears two rings, or a human finds the caller already moved.

A worked example

This is a made-up call. Times are seconds from the start of the call.

SpanStartLengthKey fields
call0214voice.call.id=call_8f2a
agent.billing071
handoff 1712type=agent, to=retention, sent=5, received=2
agent.retention7358asks for account number again
handoff 21311type=agent, to=billing, index=2
agent.billing13220second visit
handoff 31523type=warm, to=human
hold15547caller waits
human.join20212received=0

Three signatures sit in one trace. Handoff 1 sent five fields and the receiver used two, so the retention agent re-asked for the account number. Handoff 2 reversed the first pair, a loop of length two. In handoff 3 the human received nothing, because the briefing span is missing.

No single span is red. The call completed. The failure only shows when you read the handoff spans together. That is the argument for root cause analysis beyond the trace and for a debugging routine for a bad call.

How to do voice agent handoff tracing in six steps

1. Fix the call ID first - Create one call ID at call start and put it on every span and log line. See the correlation post for the mapping of telephony and room IDs.

2. Wrap every handoff in a span - Open a handoff span before control moves. Set the type, from, to and reason at creation, since attributes and links set at creation are preferred.

3. Propagate the context - Inject traceparent into the payload, header or queue message. Extract it on the receiving side and use it as the parent.

4. Choose child or link - Child spans inside systems you own. A new trace with links both ways for systems you cannot parent.

5. Record what moved - Set context_sent on the sender and context_received on the receiver. Add the history size for agent swaps.

6. Close the span with an outcome - Set connected, no answer or failed, with the status code. Then add queries for loops, orphans and doubles.

Where Evalgent fits

Evalgent Observe, which is launching, ingests OpenTelemetry-format data from any stack, plus call details you upload. It traces each failure to the step or handoff that caused it, and it groups failures into root causes. It is never in the media path. Where the data you send cannot show what happened on the far side of a transfer, it says undetermined and shows the coverage gap. It does not guess. For the bigger picture, read what voice agent observability is.

Evalgent Monitor, which is live, flags problems in production calls with fix recommendations. A handoff that never reached a person is the kind of call it is meant to surface. That is voice agent handoff tracing applied to live traffic.

On the testing side, Evalgent test calls can force a handoff scenario before release, and Reviews replay the call with audio and transcript together and show the exact tool payloads. If you want to check your handoffs before they reach live callers, you can book a demo.

Frequently asked questions

How do you trace a transfer to a human agent?

For voice agent handoff tracing of a human transfer, wrap the transfer in a handoff span that records the reason, target type and outcome. Close it with connected, no answer or failed, plus the SIP status code if your platform exposes it. Your trace ends where the human begins. Link any ticket or desk-tool record back to the call ID.

Use a child span when the next actor runs inside the call and you can pass the context. Use a span link when the work happens because of the call but in a separate trace, such as a ticket handled later. A child says "inside this," while a link says "caused by this."

How do you keep one trace ID across a warm transfer?

Create the call ID and trace context at call start, then pass the traceparent into the consult room and any briefing step. The consult room is a separate room but the same call. Make the consult span a child of the handoff span, so both rooms sit in one trace.

What should the handoff span record?

Record the call ID, handoff index, type, from, to, reason category, context fields sent and received, and the outcome. Add the history size for agent swaps. Use stable agent names. Keep transcripts and caller details out of attributes. There is no standard handoff attribute set, so these names are suggestions.

How do you find lost context in a voice agent handoff?

Compare the fields sent with the fields the receiver used on the same handoff span. Then check whether the next actor asked for something already in the payload. Group by handoff pair. If one pair keeps losing context, the payload builder for that pair is the cause.

How do you detect a handoff loop in a trace?

In voice agent handoff tracing, count handoff spans per trace and flag any from-to pair that repeats. A rising handoff index with the same two agents alternating is the signature. Add a query that lists traces above your own ceiling. Guardrails and tests for the cap are in the handoff loop post.

How do you detect a double handoff?

Look for two handoff spans from the same actor to the same target within a few seconds. The usual causes are a retried request or a duplicate tool call. Check the tool spans just before each handoff. Two identical calls with one decision between them confirm it.

Should baggage carry caller details across a handoff?

No. Baggage travels in headers and can reach third parties, and it is not copied into attributes automatically. Carry the call ID and look caller details up on the side you trust. If a field must travel, mask it first and check your redaction rules.

The bottom line

Voice agent handoff tracing means one trace ID for the whole call, a handoff span at every change of control, and a stated outcome on each. Record what context was sent and what arrived, because the failures that matter are quiet ones that no single span marks as an error.

Related Articles