[pvlsirotkin]

Handoff note: I (@pvlsirotkin) am OOO. @RKest will be driving this PR forward — he has push access to the branch on my fork. Please direct further review feedback to him.

Description

Adds a new GenAI semantic convention metric for the number of steps a GenAI
agent takes during a single invocation, modeled on the recently-merged
gen_ai.workflow.duration metric
(#126):

• gen_ai.agent.steps (Histogram, {step}): number of discrete steps a
  GenAI agent takes during a single invocation.

The metric counts only steps the agent itself authored (e.g. in ADK, events
whose event.author equals the agent name). Tool results are not counted
(authored by the tool, not the agent). Sub-agent steps are not counted (each
step is recorded exactly once across the full call tree). Failed and partial
steps still count — they consumed the agent's execution.

Step counts MUST NOT be compared across different frameworks; instrumentations
MUST document what counts as a step for their framework.

Motivation

The existing GenAI conventions describe agents and tools but offer no
standardized way to answer "how many steps did this agent take to produce
its response?" Operators today derive that figure ad-hoc from span counts,
which is fragile and depends on sampling configuration.

User journey: capacity planning, regression detection across agent versions,
and diagnosing pathological tool loops (an agent stuck calling tools without
making progress).

Checklist

• Motivation section filled in above
• Reference instrumentation and scenarios updated for affected libraries
• Changelog entry added under changelog.d/ (Towncrier fragment)

See CONTRIBUTING.md.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: pvlsirotkin / name: Pavel Sirotkin (aefc0d6)

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a new GenAI workflow metric (gen_ai.workflow.steps) to measure discrete step counts within a workflow execution, with corresponding schema snapshot, registry entry, and documentation updates.

Changes:

• Introduce gen_ai.workflow.steps histogram metric with agent/workflow dimensions.
• Update generated schema snapshot to include the new metric.
• Extend GenAI metrics documentation and changelog to describe the new metric.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
schema-snapshot/registry.yaml	Adds the generated registry + refinements entries for gen_ai.workflow.steps.
model/gen-ai/metrics.yaml	Defines the new gen_ai.workflow.steps metric and its attributes.
docs/gen-ai/gen-ai-metrics.md	Documents gen_ai.workflow.steps and adds it to the TOC.
CHANGELOG.md	Notes addition of the new workflow steps metric.

[MikeGoldsmith]

Do we only count completed steps, or also include partial / failed steps too?

[pvlsirotkin]

New answer: tbc
Old answer: Both. The note now says: 'Steps are counted regardless of outcome: a step that errored or partially completed still consumed the agent's execution and SHOULD be counted.'

[lmolkova]

assuming we were able to stamp workflow name on all nested spans and metrics emitted in the context of this workflow, we'd had

• count of agent invocations per workflow name
• count of tool calls per workflow name
• .. (any other metrics, e.g. if we instrumented transfers, we'd had a count of transfers)

Would this metric be still necessary?

In the current shape this metric seems to be an aggregation of multiple independent things which maybe also queried and sumed up individually, but then would provide better observability.

[pvlsirotkin]

With the refocus to per-agent scope (see summary) this is no longer a workflow-level aggregation. It's a per-invocation count of an agent's own steps — distinct from summing child signals because (a) not every event is independently traced, and (b) operators get a single histogram they can directly compute percentiles on rather than needing to sum multiple counters and join by attribute.

[pvlsirotkin]

Big update on this PR after re-reading the original RFC and the production ADK implementation: the metric was always meant to count steps a specific agent takes during a single invocation, not steps in some larger workflow. An earlier revision of this PR pushed it into the gen_ai.workflow.* namespace, which turned out to be the source of most of the confusion in this review round (per-invocation vs cumulative, whether to count sub-agents, whether workflow.name should be required, whether this is just an aggregation of child counts, etc.).

Just pushed a commit that:

• Renames the metric to gen_ai.agent.steps (out of the workflow namespace).
• Drops gen_ai.workflow.name and gen_ai.agent.version from the dimensions. The only dimension is gen_ai.agent.name (at recommended level, matching Add gen_ai.invoke_agent.duration and gen_ai.execute_tool.duration metrics #201/Add gen_ai.agent.input.content.size and gen_ai.agent.output.content.size metrics #202).
• Adds attributes.gen_ai.error (per @MikeGoldsmith).
• Rewrites the metric note to spell out the per-agent semantics:
  • Counts only events the agent itself authored.
  • Tool results are not counted (authored by the tool, not the agent).
  • Sub-agent steps are not counted; each step recorded exactly once across the call tree (@aabmass' invariant).
  • Failed and partial steps still count (they consumed agent execution time).
  • Step counts MUST NOT be compared across frameworks (@MikeGoldsmith's ask for stronger wording).
  • Concrete framework definitions for ADK, LangGraph, LangChain, CrewAI, with a link to https://adk.dev/runtime/event-loop/#event (@aabmass' suggestion).
  • Histogram bucket recommendation included in the note (@MikeGoldsmith's ask).

The MD page got a new ## Generative AI agent metrics section so the metric no longer lives under "Generative AI workflow metrics". MD body is kept thin; the full semantics live in the YAML note and are rendered into the autogen block.

Replying inline on each open thread.

[trask]

Hi! As part of #275, this repository switched to Towncrier changelog fragments to reduce merge conflicts in CHANGELOG.md.

Please move this PR's changelog entry out of CHANGELOG.md and into this Towncrier fragment:

Create changelog.d/203.enhancement.md containing the change log entry, e.g.:

Add `gen_ai.agent.steps` metric to track the number of steps a GenAI agent takes during a single invocation.

After adding the fragment, please remove this PR's direct edit to CHANGELOG.md. Towncrier will add the PR link from the fragment filename when release notes are generated.

Thanks!

[lmolkova]

I did a bit of a research and I think this generalization would be confusing, it does not make sense to merge these things into one metric unless they are comparable:

1. For ADK it would count LLM and tool calls, handoffs
2. Langgraph has a notion of super-step which is "considered a single iteration over the graph nodes" (active ones). So by definition it's more than one node and step used in the metric name would be misleading. Langgraph also has configurable recursion_limit for number of super-steps and remaining_steps in the step that provides number of remaining ones until limit is reached. This is a signal that these things could be meaningful to LangGraph users.
3. I can't find a term 'turn' in crewai, my AI found iterations in agent executor - https://github.com/crewAIInc/crewAI/blob/b6e5d632c111e098d883274f0a26f02836a2172e/lib/crewai/src/crewai/agents/crew_agent_executor.py#L218 and there is a corresponding config for max_interations, but iteration is a full ReAct loop. It has something called step_callback but does not clearly document when it's called.

I think this metric tries to capture something that's a proxy to number of loops / iterations within one agent, but tries to express it through internal frameowrk implementation details.

Some alternative approaches:

0. Stamp agent name on the underlying llm and tool calls and derive average number of calls per agent from gen_ai.inference | execute_tool.duration and invoke agent duration. This won't give outliers or percentiles, but arguably many loops / events also leads to long invoke_agent duration.
1. Measure gen_ai.agent.inference_calls_per_invocation, gen_ai.agent.tool_calls_per_invocations, gen_ai.agent.transfers_per_invocation - these are understandable and generically applicable. The list can probably grow with retrievals and memory calls
2. Have specialized metrics for frameworks. [gcp.]adk.event_loop.event.count with attributes for author and type or [gcp].adk.event_loop.events_per_invocation would be specific and understandable. Langgraph and crewai would have specialized metrics too

Approaches 1 and 2 can exist together: gen_ai.agent.inference_calls_per_invocation could be a common 'give me a sense of how long this agent invocation was' that shows up on common dashboards and [gcp].adk.event_loop.events_per_invocation can be a detailed breakdown. This would align with t-shaped signals approach.

[pvlsirotkin]

Heads up — I'm OOO from today. @RKest will be taking this PR forward (he has push access to the branch on my fork).

State of the PR:

• The metric was renamed and refocused: gen_ai.workflow.steps → gen_ai.agent.steps, scoped to counting steps a specific agent itself authored during one invocation (per the underlying RFC and the production ADK implementation). The earlier "workflow" framing caused most of the confusion in prior review rounds.
• 3 review threads remain open:
  1. Generalization concern — @lmolkova thinks the metric as currently defined isn't comparable across frameworks because what counts as a "step" varies. Needs follow-up.
  2. Workflow-level aggregation alternative — @lmolkova suggested an alternative: if workflow.name could be stamped on all nested signals, this metric might be derivable by query rather than emitted directly. My response defended the per-agent metric as still useful — awaiting her take.
  3. Completed vs partial/failed steps — my reply has a New answer: tbc / Old answer:... artifact from an edit conflict; @RKest should clean this up and confirm the answer.

Background context I'm leaving behind for @RKest:

• The metric counts events the agent itself authored (e.g. ADK events where event.author == agent_name). Tool results are NOT counted (authored by tool). Sub-agent steps are NOT counted (each step once across the call tree).
• Step counts MUST NOT be compared across frameworks; instrumentations MUST document what they count.
• This was the source of a lot of cross-talk between @trask, @MikeGoldsmith, @lmolkova, @aabmass — recommend reading the top-level summary comment first for context.

Thanks everyone for the feedback so far.

[RKest]

Some alternative approaches:
...

1. Measure gen_ai.agent.inference_calls_per_invocation, gen_ai.agent.tool_calls_per_invocations, gen_ai.agent.transfers_per_invocation - these are understandable and generically applicable. The list can probably grow with retrievals and memory calls
   ...

I went ahead and implemented this alternative in #336

[lmolkova]

I'm going to close this PR since it's continued in #336, feel free to reopen if necessary