Align gen_ai.tool_definitions with JSON Schema and add it to completion hook by wikaaaaa · Pull Request #4181 · open-telemetry/opentelemetry-python-contrib

wikaaaaa · 2026-02-09T11:42:17Z

Description

This PR aligns gen_ai.tool_definitions with JSON Schema proposed in open-telemetry/semantic-conventions#3378.

This PR also adds gen_ai.tool_definitions to completion hook and configures exporting the attribute to GCS. Its configured the same way as system instructions, it's being hashed, since it might be large and often doesn't differ.

Its a continuation of #4142, which added gen_ai.tool_definitions to gen_ai.client.inference.operation.details.

Type of change

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Manual tests: run adk web and inspected the traces and data send to the storage bucket
Unit tests

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

…onhook

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py

… the flag

DylanRussell · 2026-02-17T20:12:32Z

instrumentation-genai/opentelemetry-instrumentation-google-genai/CHANGELOG.md

 ## Unreleased
 - Fix bug in how tokens are counted when using the streaming `generateContent` method.  ([#4152](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4152)).
 - Add `gen_ai.tool.definitions` attribute to `gen_ai.client.inference.operation.details` log event ([#4142](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4142)).
+- Add `gen_ai.tool_definitions` to completion hook ([#4181](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4181))


I think we have to bump the util-genai dependency in pyproject.toml: https://github.com/open-telemetry/opentelemetry-python-contrib/blob/main/instrumentation-genai/opentelemetry-instrumentation-google-genai/pyproject.toml#L43 -- but I guess we have to do a release of the util gen AI library first ? I'm a bit confused about what the process is supposed to be here @aabmass

DylanRussell · 2026-02-18T14:01:26Z

...trumentation-google-genai/src/opentelemetry/instrumentation/google_genai/generate_content.py

+        if isinstance(td, FunctionToolDefinition):
+            result.append(
+                FunctionToolDefinition(
+                    name=td.name,


nit: this could just be 1 long dict/list comprehension

DylanRussell · 2026-02-18T14:03:47Z

...trumentation-google-genai/src/opentelemetry/instrumentation/google_genai/generate_content.py

+                **completion_details_attributes,
+            }
+        else:
+            tool_def_without_params_attr = _tool_def_without_parameters_attr(


nit: just inline this below instead of storing in a variable for 1 line (here and below)

DylanRussell · 2026-02-18T16:40:41Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/types.py

+
+    name: str
+    description: str | None
+    parameters: Any | None  # or dict[str, Any]


I'm pretty sure Any includes None ?

DylanRussell · 2026-02-18T16:42:31Z

util/opentelemetry-util-genai/CHANGELOG.md


 ## Unreleased

+- Add `gen_ai.tool_definitions` to completion hook ([#4181](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4181))


This is duplicated here and below

DylanRussell · 2026-02-18T16:47:48Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py

                usedforsecurity=False,
            ).hexdigest()
+
+        tool_definitions_hash = None


nit: update hash_tool_definitions to accept an empty list and return None in that case in order to make this code a little cleaner..

DylanRussell · 2026-02-18T16:48:49Z

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py

                self._base_path,
                f"{system_instruction_hash or uuid_str}_system_instruction.{self._format}",
            ),
+            tool_definitions_ref=posixpath.join(


do we still want to stamp the ref / do an upload if tool definitions is None ?

DylanRussell · 2026-02-18T16:52:44Z

...trumentation-google-genai/src/opentelemetry/instrumentation/google_genai/generate_content.py

-            return None
+            return []

        tool_definitions = []


nit I think it could be a list comprehension ? return [de for de in _to_tool_definition(tool) for tool in _config_to_tools(config) if de (maybe also below, but not sure with the await call..)

DylanRussell · 2026-02-18T16:55:45Z

...trumentation-google-genai/src/opentelemetry/instrumentation/google_genai/generate_content.py



+def _tool_def_without_parameters_attr(
+    tool_def: list[ToolDefinition],


Do we just want to use FunctionToolDefinitiondirectly Instead of using ToolDefinition everywhere ? I don't think we want to use the GenericToolDefinition at all ?

DylanRussell · 2026-02-18T16:58:07Z

...trumentation-google-genai/src/opentelemetry/instrumentation/google_genai/generate_content.py

-        return {
-            "error": f"failed to serialize tool definition, tool type={type(tool).__name__}"
-        }
+    return [


Ah I see we have a Generic tool definition here.. So do we really want to add something to the telemetry in case of a tool or params that we fail to serialize ? I feel like it makes more sense to leave it out and log an error/warning instead. Maybe worth bringing up that question in the sem conv PR. Maybe @aabmass has thoughts on this

wikaaaaa added 3 commits February 6, 2026 11:13

add gen_ai.tool_definitions to completion hook

0d21d4a

hash tool defintions

4b16d13

Merge remote-tracking branch 'upstream' into tooldefinitions-completi…

d3b1c88

…onhook

wikaaaaa requested a review from a team as a code owner February 9, 2026 11:42

github-actions bot assigned codefromthecrypt, DylanRussell, karthikscale3, lmolkova, lzchen and nirga Feb 9, 2026

wikaaaaa added 3 commits February 9, 2026 11:46

Update CHANGELOG

2bbda1f

make tool.defintions optional in on_completion

de8533d

fix lint errors

405b235

DylanRussell approved these changes Feb 9, 2026

View reviewed changes

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py Outdated Show resolved Hide resolved

RKest approved these changes Feb 9, 2026

View reviewed changes

wikaaaaa and others added 5 commits February 11, 2026 10:07

Merge branch 'main' into tooldefinitions-completionhook

6b8558a

add gen_ai.tool_definitions to completion hook

faadf17

hash tool defintions

680852d

fix CompetionHook docstring

9d4e0e3

fix lint test

18a3ff0

aabmass reviewed Feb 12, 2026

View reviewed changes

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_upload/completion_hook.py Outdated Show resolved Hide resolved

wikaaaaa changed the title ~~Add gen_ai.tool_definitions to completion hook~~ Align gen_ai.tool_definitions with JSON Schema and add it to completion hook Feb 17, 2026

wikaaaaa force-pushed the tooldefinitions-completionhook branch from c79def6 to c6531c5 Compare February 17, 2026 14:03

wikaaaaa added 7 commits February 17, 2026 14:06

add gen_ai.tool_definitions to completion hook

3aa2739

hash tool defintions

9eb3631

Update CHANGELOG

1bbd3fa

align tool.defintions with JSON schema

c688df0

fix tests

2b267ff

fix ruff

2dc28f2

fix unexpected indent

81c2124

wikaaaaa added 3 commits February 17, 2026 14:06

use local changes from util/opentelemetry-util-genai

a16c38a

fix ruff

53ec626

add gen_ai.tool_definitions to completion hook

a7bc9de

wikaaaaa force-pushed the tooldefinitions-completionhook branch from c6531c5 to a7bc9de Compare February 17, 2026 14:06

wikaaaaa and others added 4 commits February 17, 2026 14:51

re-add changes lost during merge

98f23e0

Merge branch 'main' into tooldefinitions-completionhook

1c8c4f0

put tool.defintions in the telemetry by default and the params behind…

84c9ae4

… the flag

fix: Too many local variables

2412629

DylanRussell reviewed Feb 18, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Align gen_ai.tool_definitions with JSON Schema and add it to completion hook #4181

Align gen_ai.tool_definitions with JSON Schema and add it to completion hook #4181
wikaaaaa wants to merge 25 commits intoopen-telemetry:mainfrom
wikaaaaa:tooldefinitions-completionhook

wikaaaaa commented Feb 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

DylanRussell Feb 17, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

DylanRussell Feb 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

Comments


		## Unreleased

		- Add `gen_ai.tool_definitions` to completion hook ([#4181](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/4181))



		def _tool_def_without_parameters_attr(
		tool_def: list[ToolDefinition],

Conversation

wikaaaaa commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

Comments

wikaaaaa commented Feb 9, 2026 •

edited

Loading