Implementing Agent Metadata for Arize

Frameworks with Built-In Support

The following frameworks have built-in support for agent metadata through their auto-instrumentors:

1. LangGraph

   • Automatically tracks agent nodes and graph transitions

   • Uses native metadata.langgraph_node and metadata.langgraph_step

   • Handles agent metadata and state transitions

   • No additional implementation needed

2. AutoGen

   • Automatically tracks graph.node.id and graph.node.parent_id

   • Handles agent handoffs through _handoffs tracking

   • No additional implementation needed

3. CrewAI

   • Automatically tracks agent roles and task relationships

   • Includes agent metadata in spans

   • No additional implementation needed

4. OpenAI Agents

   • Handles agent metadata via OpenInferenceTracingProcessor

   • Tracks handoffs between agents

   • No additional implementation needed

5. Agno

   • Tracks agent names and team relationships

   • Includes agent metadata in spans

   • No additional implementation needed

Understanding Agent/Node Visualization Scope

Key Principle:

Agent and node visualization is designed to track high-level workflow components and their relationships, not every individual operation. Think of it as a "logical flow map" rather than a detailed trace view.

What to Track with Agent/Node Metadata:

✅ High-Level Components

• Main agent roles (e.g., "supervisor_agent", "research_agent")

• Major processing stages (e.g., "data_collection_node", "analysis_node")

• Key decision points (e.g., "review_node", "approval_node")

✅ Important Transitions

• Handoffs between major components

• Significant state changes

• Branch points in workflow

When Custom Implementation Is Needed

Custom agent metadata tracking is required when:

1. Using frameworks without built-in support:

   • Vanilla OpenAI / Anthropic calls

   • Custom agent implementations

   • LangChain without agent components

   • Other unsupported frameworks

2. Using hybrid instrumentation:

   • Mixing auto-instrumented frameworks with custom code

   • Building custom agents that interact with instrumented frameworks

Required Metadata Attributes

To enable agent and node visualization, include the following metadata:

Attribute	Description	Required
graph.node.id	Unique name for the agent/node	✅
graph.node.parent_id	ID of the parent node (if applicable)	Optional, but recommended. We will infer the graph using the relationship of the spans within the trace if this is not included

Example Hierarchy

Attribute	Example
graph.node.id	"input_parser", "research_agent"
graph.node.parent_id	"main_orchestrator"

The example creates this structure:

main_orchestrator
├── input_parser
├── content_generator
│   ├── research_agent
│   └── writer_agent
└── quality_checker

You do not need to annotate every span. Only annotate those components you want represented in the graph.

How to Use in Your Application

Basic Pattern

# 1. Add graph attributes to your spans
def add_graph_attributes(self, span, node_id: str, parent_id: str = None):
    span.set_attribute("graph.node.id", node_id)
    if parent_id:
        span.set_attribute("graph.node.parent_id", parent_id)
    span.set_attribute("graph.node.display_name", node_id.replace("_", " ").title())

# 2. Use in your tracing code
with self.tracer.start_as_current_span("my_operation") as span:
    self.add_graph_attributes(span, "my_component", "parent_component")
    # Your logic here...

Multi-Level Hierarchy

# Root level (no parent)
with tracer.start_as_current_span("main_workflow") as main_span:
    add_graph_attributes(main_span, "orchestrator")
    
    # Child level
    with tracer.start_as_current_span("parse_input") as parse_span:
        add_graph_attributes(parse_span, "parser", "orchestrator")
        
        # Grandchild level
        with tracer.start_as_current_span("validate_input") as validate_span:
            add_graph_attributes(validate_span, "validator", "parser")

What You'll See in Arize

After running the example, check your Arize dashboard for:

1. Traces with hierarchical structure - Navigate to the Traces section

2. Filter by graph attributes - Use graph.node.id or graph.node.parent_id in filters

3. Visual trace tree - See the parent-child relationships in the trace view

4. Custom display names - More readable component names in the UI

Best Practices

Naming Conventions

• Use descriptive names that reflect the component's purpose

• Keep names consistent across your application

Common Pitfalls to Avoid

Pitfall	Description
Inconsistent IDs	Use consistent naming conventions for graph.node.id and graph.node.parent_id
Over-instrumentation	Only add graph metadata to spans you want to visualize
Missing State Updates	Always mark transitions and error states explicitly

Troubleshooting

Issue: I don't see the hierarchy in Arize

• Check that both graph.node.id and graph.node.parent_id are set

• Verify your spans are being created with the correct parent-child timing

Issue: The graph looks too complex

• Consider grouping related operations under fewer parent nodes

• Use fewer hierarchy levels for simpler visualization