Configure Span Types

Overview

Span types are optional but allow you to classify the most common types of components in AI apps, which includes:

• LLMs: Track the model used, prompt version, token usage, and cost per token.
• Retrievers: Track the embedding model, chunk size, and top-k retrieval settings.
• Tools: Track tool descriptions and function calling behavior.
• Agents: Track available tools and agent handoffs for multi-agent orchestration.

This is set via the type parameter when observing a function. By classifying span types you can create more tailored UIs on Confident AI, view online evals specific to each span type, and set type-specific attributes instead of using generalized metadata.

Confident AI has tailored displays for different span types on the UI, such as displaying prompts for LLMs and chunk sizes for retrievers.

LLM Spans

An LLM span represents a call to a language model. It tracks the input, output, and token usage of the model.

1
from deepeval.tracing import observe
2
3
@observe(type="llm", model="gpt-4")
4
def generate_response(prompt: str) -> str:
5
    pass

Retriever Spans

A Retriever span represents a component that fetches relevant information from a vector store or knowledge base. It’s a crucial part of RAG (Retrieval-Augmented Generation) pipelines, handling the embedding and retrieval process.

1
from deepeval.tracing import observe
2
from typing import List
3
4
@observe(type="retriever", embedder="text-embedding-ada-002")
5
def retrieve_documents(query: str) -> List[str]:
6
    pass

Tool Spans

A Tool span represents a function that an agent can call to perform a specific task. It’s commonly used for function calling in LLM applications.

1
from deepeval.tracing import observe
2
3
@observe(type="tool")
4
def web_search(query: str) -> str:
5
    pass

There is ONE mandatory and THREE optional parameters for the tool span type:

• type: The type of span. Must be "tool" for tool spans.
• [Optional] description: A string that describes what the tool does. Defaulted to an empty string.
• [Optional] name: A string specifying the display name on Confident AI. Defaulted to the name of the observed function.
• [Optional] metrics A list of strings specifying the names of the online metrics you wish to run upon tracing to Confident AI. Learn more about using online metrics here.

Agent Spans

An Agent span represents an autonomous entity that can make decisions and interact with other components. It’s particularly useful for implementing thinking agents or multi-agent systems.

1
from deepeval.tracing import observe
2
3
@observe(
4
    type="agent",
5
    available_tools=["search", "calculator"],
6
    handoff_agents=["research_agent", "math_agent"],
7
)
8
def supervisor_agent(query: str) -> str:
9
    pass

Agents can be nested within other agents, which is useful for implementing hierarchical agent architectures. For instance, a “supervisor” agent might coordinate communication between specialized agents.

Custom Spans

The most flexible type out of all (and the default type if type is not provided), custom spans are essential for creating hierarchical structures or grouping related spans together. They provide flexibility in organizing your tracing data.

1
from deepeval.tracing import observe
2
3
@observe(name="RAG Pipeline")
4
def rag_pipeline(query: str) -> str:
5
    pass

There is ONE mandatory and TWO optional parameters for the Custom span type:

• type: The type of span. Anything other than "llm", "retriever", "tool", and "agent" is a custom span type. Defaulted to the name.
• [Optional] name: A string specifying how this custom span is displayed on Confident AI. Defaulted to the name of the observed function.
• [Optional] metrics A list of strings specifying the names of the online metrics you wish to run upon tracing to Confident AI. Learn more about using online metrics here.

The input and output of a custom span default to the function’s input arguments and return value, but you can also set them dynamically.

Next Steps

Now that your spans are typed, enrich them further with prompt tracking and custom I/O.