Add agent call count metrics on AgentInvocation (#597)

[dlowzzxx]

Description

Tracks and records agent call count metrics on \AgentInvocation\ (\LocalAgentInvocation\ and \RemoteAgentInvocation) in \opentelemetry-util-genai\ per OpenTelemetry Generative AI Semantic Conventions (\semantic-conventions-genai).

Per issue #597, semantic conventions define two call count histogram metrics for agent invocations:

• \gen_ai.invoke_agent.inference_calls: Number of inference calls made during the agent invocation (unit: {inference_call}).
• \gen_ai.invoke_agent.tool_calls: Number of tool calls executed during the agent invocation (unit: {tool_call}).

This PR addresses the foundational sub-task of #597:

- [ ] Add utils support to track and record counter metrics on AgentInvocation\

Key Changes:

1. **_instruments.py**:
   • Added \invoke_agent_inference_calls\ and \invoke_agent_tool_calls\ histogram instruments to _Instruments.
2. **_agent_invocation.py**:
   • Added instance attributes \inference_calls: int | None = None\ and \ ool_calls: int | None = None\ on \AgentInvocation.
   • Added _record_call_metrics()\ helper to record both count metrics if set.
   • Updated \LocalAgentInvocation._record_metrics()\ to record call metrics alongside \invoke_agent_duration.
   • Updated \RemoteAgentInvocation._record_metrics()\ to record call metrics (attaching \gen_ai.agent.name\ when specified) alongside client operation metrics.
3. **\ ests/test_handler_agent.py**:
   • Added unit tests to \TestAgentInvocationMetrics:
     • \ est_agent_records_inference_and_tool_calls\
     • \ est_agent_without_calls_does_not_record_call_metrics\
     • \ est_agent_records_zero_calls\
     • \ est_remote_agent_records_calls_with_server_attrs\
     • \ est_failed_agent_records_calls_with_error_type\
     • \ est_agent_name_omitted_from_metrics_when_none\
4. Changelog:
   • Added Towncrier news fragment \util/opentelemetry-util-genai/.changelog/634.added.

Related to #597.

Type of change

• New feature (non-breaking change which adds functionality)

How has this been tested?

• Ran unit test suite in \util/opentelemetry-util-genai/tests/test_handler_agent.py: 44/44 passed.
• Ran full package test suite in \util/opentelemetry-util-genai/tests: 424/424 passed.
• Ran
  uff check util/opentelemetry-util-genai: passed cleanly.
• Ran
  uff format --check util/opentelemetry-util-genai: passed cleanly across 72 files.
• Verified towncrier check passes with fragment \634.added.

Checklist

• Followed the style guidelines of this project
• Changelog updated if the change requires an entry
• Unit tests added
• Documentation updated

[Copilot]

🟡 Changes recommended

The Towncrier changelog fragment filename does not match the PR/issue number referenced in the PR description, reducing traceability and conflicting with expected fragment naming.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds opentelemetry-util-genai support for recording agent invocation call-count metrics aligned with the GenAI semconv, so downstream instrumentations can report how many model/tool calls happened during invoke_agent.

Changes:

• Added two new metric instruments for agent call counts (gen_ai.invoke_agent.inference_calls, gen_ai.invoke_agent.tool_calls).
• Extended AgentInvocation and the metrics recorder to carry/emit inference_calls and tool_calls (including agent name in metric attributes).
• Added unit tests covering presence/absence/zero counts, error cases, and remote-agent server attributes.

File summaries

File	Description
util/opentelemetry-util-genai/src/opentelemetry/util/genai/instruments.py	Defines new histogram instruments for agent inference/tool call counts and exports them.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/metrics.py	Registers the new instruments and records call-count metrics when present on an invocation.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_agent_invocation.py	Adds inference_calls / tool_calls, includes agent name in metric attributes, and records via record_agent().
util/opentelemetry-util-genai/tests/test_handler_agent.py	Adds test coverage for agent call-count metric recording behavior.
util/opentelemetry-util-genai/.changelog/634.added	Adds a Towncrier fragment describing the new agent call-count metric support.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[dlowzzxx]

Renamed the Towncrier fragment to 597.added in commit 92c520b to match the referenced issue number.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-09-11 22:31 UTC

Resolve merge conflicts.

Respond to 3 review items (e.g. link a commit, explain why not, ask a follow-up):

• Inline threads: 1
• Top-level threads: 2, 3

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
• Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

[dlowzzxx]

/dashboard route:reviewers

[opentelemetry-pr-dashboard]

@dlowzzxx, this pull request was routed to reviewers.

[lmolkova]

I believe it's blocked on https://github.com/open-telemetry/opentelemetry-python-genai/pull/616/changes, please give it a review

[dlowzzxx]

Thanks for pointing this out, @lmolkova!

I have completed a thorough review of #616 (#616) and submitted an approving review. Splitting AgentInvocation into LocalAgentInvocation (SpanKind.INTERNAL) and RemoteAgentInvocation (SpanKind.CLIENT), as well as isolating gen_ai.invoke_agent.duration to local agent runs while keeping client duration/token metrics on remote invocations, aligns cleanly with the GenAI Semantic Conventions (gen-ai-agent-spans.md).

Once #616 is merged, I will rebase PR #634 to cleanly attach the gen_ai.invoke_agent.inference_calls and gen_ai.invoke_agent.tool_calls call-count metrics across the newly split invocation classes.

[dlowzzxx]

/dashboard route:reviewers

[lmolkova]

#616 is being merged, please rebase

[opentelemetry-pr-dashboard]

@dlowzzxx, this pull request was routed to reviewers. No top-level feedback was retired because the dashboard could not determine a safe command time; unresolved review threads remain open.

[dlowzzxx]

@lmolkova Rebased onto upstream \main\ following the merge of #616. The call-count metrics (\gen_ai.invoke_agent.inference_calls\ and \gen_ai.invoke_agent.tool_calls) are now wired across \LocalAgentInvocation\ and \RemoteAgentInvocation\ via _Instruments, and the Towncrier fragment is aligned to \634.added. Full test suite and lint checks pass cleanly.

/dashboard route:reviewers