semantic-conventions icon indicating copy to clipboard operation
semantic-conventions copied to clipboard

feat(gen-ai): add agent.node.* attributes for agent‑graph spans

Open nadeemc2 opened this issue 6 months ago • 1 comments

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.yaml using type.members enum syntax.
  • Documentation
    • Regenerated docs/attributes-registry/gen-ai.md.
    • Added new explanatory page docs/gen-ai/agent-node-spans.md.
  • 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.yaml NOT changed (new attributes only).

nadeemc2 avatar May 11 '25 22:05 nadeemc2