Skip to content

Commit 391f881

Browse files
Cirilla-zmhCirilla-zmh
committed
Add json schema of gen ai tool definitions
1 parent cb69cab commit 391f881

File tree

11 files changed

+251
-50
lines changed

11 files changed

+251
-50
lines changed

‎docs/gen-ai/aws-bedrock.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -194,13 +194,22 @@ section for more details.
194194

195195
**[14] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
196196

197-
It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
198-
to the instrumentation, the instrumentation SHOULD do the best effort to
199-
deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
197+
It's expected to be an array of objects, each representing a tool definition,
198+
and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
199+
In case a serialized string is available to the instrumentation, the instrumentation
200+
SHOULD do the best effort to deserialize it to an array.
200201

201-
Since this attribute could be large, it's NOT RECOMMENDED to populate
202-
it by default. Instrumentations MAY provide a way to enable
203-
populating this attribute.
202+
When the attribute is recorded on events, it MUST be recorded in structured
203+
form. When recorded on spans, it MAY be recorded as a JSON string if structured
204+
format is not supported and SHOULD be recorded in structured form otherwise.
205+
206+
If instrumentations can reliably deserialize and extract the tool definitions,
207+
it's RECOMMENDED to only populate required fields of the definition objects
208+
by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
209+
Instrumentations MAY provide a way to enable populating this attribute.
210+
211+
> [!Warning]
212+
> This attribute is likely to contain sensitive information including user/PII data.
204213
205214
---
206215

‎docs/gen-ai/azure-ai-inference.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -195,13 +195,22 @@ section for more details.
195195

196196
**[14] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
197197

198-
It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
199-
to the instrumentation, the instrumentation SHOULD do the best effort to
200-
deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
198+
It's expected to be an array of objects, each representing a tool definition,
199+
and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
200+
In case a serialized string is available to the instrumentation, the instrumentation
201+
SHOULD do the best effort to deserialize it to an array.
201202

202-
Since this attribute could be large, it's NOT RECOMMENDED to populate
203-
it by default. Instrumentations MAY provide a way to enable
204-
populating this attribute.
203+
When the attribute is recorded on events, it MUST be recorded in structured
204+
form. When recorded on spans, it MAY be recorded as a JSON string if structured
205+
format is not supported and SHOULD be recorded in structured form otherwise.
206+
207+
If instrumentations can reliably deserialize and extract the tool definitions,
208+
it's RECOMMENDED to only populate required fields of the definition objects
209+
by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
210+
Instrumentations MAY provide a way to enable populating this attribute.
211+
212+
> [!Warning]
213+
> This attribute is likely to contain sensitive information including user/PII data.
205214
206215
---
207216

‎docs/gen-ai/gen-ai-agent-spans.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -334,13 +334,22 @@ section for more details.
334334

335335
**[15] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
336336

337-
It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
338-
to the instrumentation, the instrumentation SHOULD do the best effort to
339-
deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
337+
It's expected to be an array of objects, each representing a tool definition,
338+
and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
339+
In case a serialized string is available to the instrumentation, the instrumentation
340+
SHOULD do the best effort to deserialize it to an array.
340341

341-
Since this attribute could be large, it's NOT RECOMMENDED to populate
342-
it by default. Instrumentations MAY provide a way to enable
343-
populating this attribute.
342+
When the attribute is recorded on events, it MUST be recorded in structured
343+
form. When recorded on spans, it MAY be recorded as a JSON string if structured
344+
format is not supported and SHOULD be recorded in structured form otherwise.
345+
346+
If instrumentations can reliably deserialize and extract the tool definitions,
347+
it's RECOMMENDED to only populate required fields of the definition objects
348+
by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
349+
Instrumentations MAY provide a way to enable populating this attribute.
350+
351+
> [!Warning]
352+
> This attribute is likely to contain sensitive information including user/PII data.
344353
345354
---
346355

‎docs/gen-ai/gen-ai-events.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -175,13 +175,22 @@ section for more details.
175175

176176
**[13] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
177177

178-
It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
179-
to the instrumentation, the instrumentation SHOULD do the best effort to
180-
deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
178+
It's expected to be an array of objects, each representing a tool definition,
179+
and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
180+
In case a serialized string is available to the instrumentation, the instrumentation
181+
SHOULD do the best effort to deserialize it to an array.
181182

182-
Since this attribute could be large, it's NOT RECOMMENDED to populate
183-
it by default. Instrumentations MAY provide a way to enable
184-
populating this attribute.
183+
When the attribute is recorded on events, it MUST be recorded in structured
184+
form. When recorded on spans, it MAY be recorded as a JSON string if structured
185+
format is not supported and SHOULD be recorded in structured form otherwise.
186+
187+
If instrumentations can reliably deserialize and extract the tool definitions,
188+
it's RECOMMENDED to only populate required fields of the definition objects
189+
by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
190+
Instrumentations MAY provide a way to enable populating this attribute.
191+
192+
> [!Warning]
193+
> This attribute is likely to contain sensitive information including user/PII data.
185194
186195
---
187196

‎docs/gen-ai/gen-ai-spans.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -207,13 +207,22 @@ section for more details.
207207

208208
**[14] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
209209

210-
It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
211-
to the instrumentation, the instrumentation SHOULD do the best effort to
212-
deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
210+
It's expected to be an array of objects, each representing a tool definition,
211+
and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
212+
In case a serialized string is available to the instrumentation, the instrumentation
213+
SHOULD do the best effort to deserialize it to an array.
214+
215+
When the attribute is recorded on events, it MUST be recorded in structured
216+
form. When recorded on spans, it MAY be recorded as a JSON string if structured
217+
format is not supported and SHOULD be recorded in structured form otherwise.
218+
219+
If instrumentations can reliably deserialize and extract the tool definitions,
220+
it's RECOMMENDED to only populate required fields of the definition objects
221+
by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
222+
Instrumentations MAY provide a way to enable populating this attribute.
213223

214-
Since this attribute could be large, it's NOT RECOMMENDED to populate
215-
it by default. Instrumentations MAY provide a way to enable
216-
populating this attribute.
224+
> [!Warning]
225+
> This attribute is likely to contain sensitive information including user/PII data.
217226
218227
---
219228

‎docs/gen-ai/gen-ai-tool-definitions.json‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
{
2+
"$defs": {
3+
"ToolDefinition": {
4+
"additionalProperties": true,
5+
"properties": {
6+
"type": {
7+
"anyOf": [
8+
{
9+
"$ref": "#/$defs/ToolType"
10+
},
11+
{
12+
"type": "string"
13+
}
14+
],
15+
"description": "Type of the tool.",
16+
"title": "ToolType"
17+
},
18+
"name": {
19+
"description": "Name of the tool.",
20+
"title": "Name",
21+
"type": "string"
22+
},
23+
"description": {
24+
"description": "Description of the tool.",
25+
"title": "Description",
26+
"type": "string"
27+
},
28+
"parameters": {
29+
"description": "Format of the tool parameters. Maybe it is a JSON schema.",
30+
"title": "Parameters"
31+
},
32+
"response": {
33+
"description": "Format of the tool response. Maybe it is a JSON schema.",
34+
"title": "Response"
35+
}
36+
},
37+
"required": [
38+
"type",
39+
"name"
40+
],
41+
"title": "ToolDefinition",
42+
"type": "object"
43+
},
44+
"ToolType": {
45+
"enum": [
46+
"function",
47+
"custom"
48+
],
49+
"title": "ToolType",
50+
"type": "string"
51+
}
52+
},
53+
"description": "Represents the list of tool definitions sent to the model.",
54+
"items": {
55+
"$ref": "#/$defs/ToolDefinition"
56+
},
57+
"title": "ToolDefinitions",
58+
"type": "array"
59+
}

‎docs/gen-ai/non-normative/examples-llm-calls.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,7 @@ They are likely to be siblings if there is an encompassing span.
298298
| `gen_ai.response.finish_reasons`| `["tool_calls"]` |
299299
| `gen_ai.input.messages` | [`gen_ai.input.messages`](#gen-ai-input-messages-tool-call-span-1) |
300300
| `gen_ai.output.messages` | [`gen_ai.output.messages`](#gen-ai-output-messages-tool-call-span-1) |
301+
| `gen_ai.tool.definitions` | [`gen_ai.tool.definitions`](#gen-ai-tool-definitions-tool-call-span-1) |
301302

302303
<span id="gen-ai-input-messages-tool-call-span-1">`gen_ai.input.messages` value</span>
303304

@@ -336,6 +337,30 @@ They are likely to be siblings if there is an encompassing span.
336337
]
337338
```
338339

340+
<span id="gen-ai-tool-definitions-tool-call-span-1">`gen_ai.tool.definitions` value</span>
341+
342+
```json
343+
[
344+
{
345+
"type": "function",
346+
"name": "get_weather",
347+
"description": "Get the weather in a given location",
348+
"parameters": {
349+
"type": "object",
350+
"properties": {
351+
"location": {
352+
"type": "string",
353+
"description": "The city and state, e.g. San Francisco, CA"
354+
},
355+
"required": [
356+
"location"
357+
]
358+
}
359+
}
360+
}
361+
]
362+
```
363+
339364
**Tool call:**
340365

341366
If tool call is [instrumented according to execute-tool span definition](../gen-ai-spans.md#execute-tool-span), it may look like this:

‎docs/gen-ai/non-normative/models.ipynb‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@
4141
},
4242
{
4343
"cell_type": "code",
44-
"execution_count": 1,
44+
"execution_count": null,
4545
"id": "5124fe15",
4646
"metadata": {},
4747
"outputs": [],
@@ -117,7 +117,24 @@
117117
" description=\"List of message parts that make up the message content.\")\n",
118118
"\n",
119119
" class Config:\n",
120-
" extra = \"allow\""
120+
" extra = \"allow\"\n",
121+
"\n",
122+
"class ToolType(str, Enum):\n",
123+
" FUNCTION = \"function\"\n",
124+
" CUSTOM = \"custom\"\n",
125+
"\n",
126+
"class ToolDefinition(BaseModel):\n",
127+
" \"\"\"\n",
128+
" Represents a tool definition.\n",
129+
" \"\"\"\n",
130+
" type: Union[ToolType, str] = Field(description=\"Type of the tool.\")\n",
131+
" name: str = Field(description=\"Name of the tool.\")\n",
132+
" description: str = Field(description=\"Description of the tool.\")\n",
133+
" parameters: Any = Field(description=\"Format of the tool parameters. Maybe it is a JSON schema.\")\n",
134+
" response: Any = Field(description=\"Format of the tool response. Maybe it is a JSON schema.\")\n",
135+
"\n",
136+
" class Config:\n",
137+
" extra = \"allow\"\n"
121138
]
122139
},
123140
{
@@ -222,6 +239,34 @@
222239
"# Print the JSON schema for the SystemInstructions model\n",
223240
"print(json.dumps(SystemInstructions.model_json_schema(), indent=4))"
224241
]
242+
},
243+
{
244+
"cell_type": "markdown",
245+
"id": "f019c33a",
246+
"metadata": {},
247+
"source": [
248+
"## `gen_ai.tool.definitions` model\n",
249+
"\n",
250+
"Corresponding attribute: [`gen_ai.tool.definitions`](/docs/registry/attributes/gen-ai.md#gen-ai-tool-definitions).\n",
251+
"JSON schema: [`gen_ai-tool-definitions.json`](../gen-ai-tool-definitions.json)"
252+
]
253+
},
254+
{
255+
"cell_type": "code",
256+
"execution_count": null,
257+
"id": "a9e84726",
258+
"metadata": {},
259+
"outputs": [],
260+
"source": [
261+
"class ToolDefinitions(RootModel[List[ToolDefinition]]):\n",
262+
" \"\"\"\n",
263+
" Represents the list of tool definitions available to the GenAI agent or model.\n",
264+
" \"\"\"\n",
265+
" pass\n",
266+
"\n",
267+
"# Print the JSON schema for the ToolDefinitions model\n",
268+
"print(json.dumps(ToolDefinitions.model_json_schema(), indent=4))"
269+
]
225270
}
226271
],
227272
"metadata": {

‎docs/gen-ai/openai.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -200,13 +200,22 @@ section for more details.
200200

201201
**[15] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
202202

203-
It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
204-
to the instrumentation, the instrumentation SHOULD do the best effort to
205-
deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
203+
It's expected to be an array of objects, each representing a tool definition,
204+
and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
205+
In case a serialized string is available to the instrumentation, the instrumentation
206+
SHOULD do the best effort to deserialize it to an array.
206207

207-
Since this attribute could be large, it's NOT RECOMMENDED to populate
208-
it by default. Instrumentations MAY provide a way to enable
209-
populating this attribute.
208+
When the attribute is recorded on events, it MUST be recorded in structured
209+
form. When recorded on spans, it MAY be recorded as a JSON string if structured
210+
format is not supported and SHOULD be recorded in structured form otherwise.
211+
212+
If instrumentations can reliably deserialize and extract the tool definitions,
213+
it's RECOMMENDED to only populate required fields of the definition objects
214+
by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
215+
Instrumentations MAY provide a way to enable populating this attribute.
216+
217+
> [!Warning]
218+
> This attribute is likely to contain sensitive information including user/PII data.
210219
211220
---
212221

‎docs/registry/attributes/gen-ai.md‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -157,13 +157,22 @@ deserialize it to an object. When recorded on spans, it MAY be recorded as a JSO
157157

158158
**[12] `gen_ai.tool.definitions`:** The value of this attribute matches source system tool definition format.
159159

160-
It's expected to be an array of objects where each object represents a tool definition. In case a serialized string is available
161-
to the instrumentation, the instrumentation SHOULD do the best effort to
162-
deserialize it to an array. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise.
160+
It's expected to be an array of objects, each representing a tool definition,
161+
and the structure of the array is expected to match the [Tool Definitions JSON Schema](/docs/gen-ai/gen-ai-tool-definitions.json).
162+
In case a serialized string is available to the instrumentation, the instrumentation
163+
SHOULD do the best effort to deserialize it to an array.
164+
165+
When the attribute is recorded on events, it MUST be recorded in structured
166+
form. When recorded on spans, it MAY be recorded as a JSON string if structured
167+
format is not supported and SHOULD be recorded in structured form otherwise.
168+
169+
If instrumentations can reliably deserialize and extract the tool definitions,
170+
it's RECOMMENDED to only populate required fields of the definition objects
171+
by default. Otherwise, it's NOT RECOMMENDED to populate it by default.
172+
Instrumentations MAY provide a way to enable populating this attribute.
163173

164-
Since this attribute could be large, it's NOT RECOMMENDED to populate
165-
it by default. Instrumentations MAY provide a way to enable
166-
populating this attribute.
174+
> [!Warning]
175+
> This attribute is likely to contain sensitive information including user/PII data.
167176
168177
**[13] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems.
169178
Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment.

0 commit comments

Comments
 (0)