Principle:Confident ai Deepeval Agent Entry Point Definition

Metadata

Knowledge Sources	DeepEval
Domains	LLM_Evaluation Observability Tracing
Last Updated	2026-02-14 09:00 GMT

Overview

A design principle for designating a root function as the agent entry point for trace collection in an LLM application. The agent entry point defines the top-level span that anchors the entire trace tree, providing a complete, hierarchical view of all component invocations within a single request.

Description

An LLM application typically consists of multiple components -- retrievers, generators, tool callers, rerankers -- that are orchestrated by a top-level function. When each component is individually instrumented (via decorators or other mechanisms), it produces a span. However, without a designated root span, these individual spans are disconnected fragments rather than a coherent trace.

The agent entry point solves this by designating one function as the root of the trace tree. When this function is invoked:

• A root span is created, establishing the trace boundary for the entire request.
• All child spans created by instrumented functions called within the root function are automatically nested under the root span, forming a parent-child hierarchy.
• The resulting trace tree captures the complete execution flow: which components were called, in what order, with what inputs and outputs, and how they relate to each other.

This principle is essential because:

• Trace completeness -- Without a root span, there is no way to associate related component spans into a single trace. Each component call would be an isolated event.
• Trace-level metrics -- Some metrics (e.g., end-to-end latency, overall answer quality) must be evaluated at the trace level, which requires a root span that represents the entire request.
• Trace visualization -- Tools that display trace trees (timelines, flame graphs, span hierarchies) require a root node to anchor the visualization.

Usage

Designate an agent entry point when:

• Your application has a top-level orchestrator function (e.g., a RAG pipeline, an agent loop, a multi-step workflow) that coordinates multiple instrumented components.
• You need to collect complete traces that capture the full request lifecycle from input to final output.
• You want to apply trace-level metrics that evaluate the quality of the entire pipeline output, in addition to per-component metrics.
• You are using dataset-driven evaluation that iterates over test cases and needs each iteration to produce a distinct, bounded trace.

Theoretical Basis

Distributed Tracing Root Span Concept

In distributed tracing systems (OpenTelemetry, Zipkin, Jaeger), every trace begins with a root span. The root span has no parent and serves as the anchor for all subsequent spans created during request processing. All child spans carry the root span's trace ID, which is how the tracing system groups them into a single trace.

The abstract model is:

TRACE = ROOT_SPAN(name="agent_entry", type="agent")
    |
    +-- CHILD_SPAN(name="retrieve", type="retriever")
    |       |
    |       +-- CHILD_SPAN(name="embed_query", type="tool")
    |
    +-- CHILD_SPAN(name="generate", type="llm")
    |
    +-- CHILD_SPAN(name="validate", type="tool")

The root span defines the trace's:

• Identity -- A unique trace ID that all child spans inherit.
• Boundary -- The start and end time of the entire request.
• Context -- Top-level input (the user's query) and output (the final response).

Trace Tree Construction

Trace trees are constructed implicitly through context propagation. When the root function calls a child function that is also instrumented, the tracing system:

1. Detects that there is an active parent span in the execution context.
2. Creates a new child span with a parent_id pointing to the active span.
3. Sets the child span as the new active span for the duration of its execution.
4. Restores the parent span as active when the child function returns.

This mechanism requires no explicit wiring between parent and child -- the call stack naturally establishes the hierarchy. The only requirement is that the top-level function is marked as the root, so that the tracing system knows to create a new trace rather than attaching to an existing one.

Key properties:

• Automatic nesting -- Child spans are nested under their caller's span without explicit parent references in application code.
• Scope isolation -- Each invocation of the root function creates a new, independent trace. Concurrent requests produce separate trace trees.
• Depth preservation -- Arbitrarily deep call chains are captured faithfully; the trace tree mirrors the actual call graph.

Related Pages

• Implementation:Confident_ai_Deepeval_Observe_Decorator_Agent_Type