semantic-conventions
semantic-conventions copied to clipboard
feat(gen-ai): add agent.node.* attributes for agent‑graph spans
Changes
This PR adds node‑level attributes to the Gen AI semantic conventions so agent frameworks (CrewAI, LangGraph, AutoGen v2, OpenAI Agents SDK, etc.) can emit spans for each step in an execution graph.
- New attributes
gen_ai.agent.node.type– enum:llm_call,tool_call,decision,vector_search.gen_ai.agent.node.id– stable identifier for each node.gen_ai.agent.parent_id– direct parent node ID (blank for roots).
- Registry updates
- Added definitions to
model/gen-ai/registry.yamlusingtype.membersenum syntax.
- Added definitions to
- Documentation
- Regenerated
docs/attributes-registry/gen-ai.md. - Added new explanatory page
docs/gen-ai/agent-node-spans.md.
- Regenerated
- Ran
make fix; all markdown is autogenerated.
Rationale
Current Gen AI spans capture model calls but cannot express the topology of multi‑step agents (decisions, tool calls, RAG look‑ups).
Standardising agent.node.* unlocks:
- Per‑step latency and cost analysis.
- Prompt‑injection/guard‑rail tracing at the node level.
- Vendor‑neutral graph visualisation across frameworks.
Impact
- Backwards‑compatible – additive only.
- Language generators will expose new constants; no existing code breaks.
- Instrumentations can start emitting the fields immediately.
Merge requirement checklist
- [X] CONTRIBUTING.md guidelines followed.
- [X] Changelog fragment added in
.chloggen/unreleased/. - [X]
schema-next.yamlNOT changed (new attributes only).