Implementing Agent Metadata for Arize
Frameworks with Built-In Support
The following frameworks have built-in support for agent metadata through their auto-instrumentors:
LangGraph
Automatically tracks agent nodes and graph transitions
Uses native
metadata.langgraph_node
andmetadata.langgraph_step
Handles agent metadata and state transitions
No additional implementation needed
AutoGen
Automatically tracks
graph.node.id
andgraph.node.parent_id
Handles agent handoffs through
_handoffs
trackingNo additional implementation needed
CrewAI
Automatically tracks agent roles and task relationships
Includes agent metadata in spans
No additional implementation needed
OpenAI Agents
Handles agent metadata via
OpenInferenceTracingProcessor
Tracks handoffs between agents
No additional implementation needed
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:
Using frameworks without built-in support:
Vanilla OpenAI / Anthropic calls
Custom agent implementations
LangChain without agent components
Other unsupported frameworks
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:
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
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:
Traces with hierarchical structure - Navigate to the Traces section
Filter by graph attributes - Use
graph.node.id
orgraph.node.parent_id
in filtersVisual trace tree - See the parent-child relationships in the trace view
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
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
andgraph.node.parent_id
are setVerify 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
Last updated
Was this helpful?