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
You do not need to annotate every span. Only annotate those components you want represented in the graph.
Example: Selective Node Visualization
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
Last updated
Was this helpful?