Skip to content

Added invoke workflow operation name to agent span #3249

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wrisa wants to merge 14 commits into
base: main
Choose a base branch
from
Open

Added invoke workflow operation name to agent span #3249

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
0fab1d9
Added invoke workflow operation name to agent span
wrisa Jan 6, 2026
2d18644
Added PR number
wrisa Jan 6, 2026
8ab0313
Added invoke workflow operation name
wrisa Jan 6, 2026
98ad936
Added invoke workflow operation name to other spans
wrisa Jan 6, 2026
e92eb27
added extends
wrisa Jan 12, 2026
0b45e67
resolved conflicts with main branch
wrisa Jan 12, 2026
88c356c
fixed typo and removed framework
wrisa Jan 13, 2026
333ac6f
addressed comments
wrisa Jan 20, 2026
af63c87
corrected note
wrisa Jan 20, 2026
a033559
fixed typo
wrisa Jan 20, 2026
6fccb88
addressed comments
wrisa Jan 21, 2026
8196239
fixed conflict, added merged retrieval
wrisa Jan 21, 2026
e185d1b
fixed errors
wrisa Jan 26, 2026
5aa45c4
addressed comments
wrisa Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .chloggen/genai-invoke-workflow-operation-name.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Use this changelog template to create an entry for release notes.
#
# If your change doesn't affect end users you should instead start
# your pull request title with [chore] or use the "Skip Changelog" label.

# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: 'new_component'

# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: gen-ai

# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Add invoke workflow operation name support to the gen-ai agent span semantic conventions.

# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
# The values here must be integers.
PR: [3249]

# (Optional) One or more lines of additional information to render under the primary note.
# These lines will be padded with 2 spaces and then inserted directly into the document.
# Use pipe (|) for multiline entries.
subtext:
1 change: 1 addition & 0 deletions docs/gen-ai/aws-bedrock.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,7 @@ populating this attribute.
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down
3 changes: 2 additions & 1 deletion docs/gen-ai/azure-ai-inference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!--- Hugo front matter used to generate the website version of this page:
<!--- Hugo front matter used to generate the website version of this page:
linkTitle: Azure AI Inference
--->

Expand Down Expand Up @@ -224,6 +224,7 @@ populating this attribute.
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down
136 changes: 127 additions & 9 deletions docs/gen-ai/gen-ai-agent-spans.md
View file
Open in desktop

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions docs/gen-ai/gen-ai-events.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,7 @@ populating this attribute.
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down
5 changes: 5 additions & 0 deletions docs/gen-ai/gen-ai-metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down Expand Up @@ -245,6 +246,7 @@ Instrumentations SHOULD document the list of errors they report.
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down Expand Up @@ -362,6 +364,7 @@ Instrumentations SHOULD document the list of errors they report.
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down Expand Up @@ -466,6 +469,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down Expand Up @@ -569,6 +573,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down
3 changes: 3 additions & 0 deletions docs/gen-ai/gen-ai-spans.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,7 @@ populating this attribute.
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down Expand Up @@ -344,6 +345,7 @@ Instrumentations SHOULD document the list of errors they report.
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
Expand Down Expand Up @@ -437,6 +439,7 @@ deserialize it to an object. When recorded on spans, it MAY be recorded as a JSO
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
Expand Down
1 change: 1 addition & 0 deletions docs/gen-ai/openai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,7 @@ populating this attribute.
| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_agent` | Invoke GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) | ![Development](https://img.shields.io/badge/-development-blue) |
| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) |

---

Expand Down
2 changes: 2 additions & 0 deletions docs/registry/attributes/gen-ai.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ This document defines the attributes used to describe telemetry in the context o
| <a id="gen-ai-tool-type" href="#gen-ai-tool-type">`gen_ai.tool.type`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Type of the tool utilized by the agent [13] | `function`; `extension`; `datastore` |
| <a id="gen-ai-usage-input-tokens" href="#gen-ai-usage-input-tokens">`gen_ai.usage.input_tokens`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI input (prompt). | `100` |
| <a id="gen-ai-usage-output-tokens" href="#gen-ai-usage-output-tokens">`gen_ai.usage.output_tokens`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of tokens used in the GenAI response (completion). | `180` |
| <a id="gen-ai-workflow-name" href="#gen-ai-workflow-name">`gen_ai.workflow.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable name of the GenAI workflow provided by the application. | `Multi Agent Rag Workflow`; `customer support pipeline workflow` |
| <a id="gen-ai-framework" href="#gen-ai-framework">`gen_ai.framework`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Framework implementing the workflow. | `LangGraph`; `CrewAI`; `OpenAI agents` |

**[1] `gen_ai.data_source.id`:** Data sources are used by AI agents and RAG applications to store grounding data. A data source may be an external database, object store, document collection, website, or any other storage system used by the GenAI agent or application. The `gen_ai.data_source.id` SHOULD match the identifier used by the GenAI system rather than a name specific to the external storage, such as a database or object store. Semantic conventions referencing `gen_ai.data_source.id` MAY also leverage additional attributes, such as `db.*`, to further identify and describe the data source.

Expand Down
14 changes: 14 additions & 0 deletions model/gen-ai/registry.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -382,6 +382,10 @@ groups:
value: "execute_tool"
brief: 'Execute a tool'
stability: development
- id: invoke_workflow
value: "invoke_workflow"
brief: 'Invoke GenAI workflow'
stability: development
brief: The name of the operation being performed.
note: >
If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic
Expand Down Expand Up @@ -591,3 +595,13 @@ groups:
type: string
brief: A free-form explanation for the assigned score provided by the evaluator.
examples: ["The response is factually accurate but lacks sufficient detail to fully address the question."]
- id: gen_ai.workflow.name
stability: development
type: string
brief: Human-readable name of the GenAI workflow provided by the application.
examples: [ "multi_agent_rag", "customer_support_pipeline" ]
- id: gen_ai.framework
stability: development
type: string
brief: Framework implementing the workflow.
examples: [ "LangGraph", "CrewAI", "OpenAI agents" ]
23 changes: 23 additions & 0 deletions model/gen-ai/spans.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,3 +349,26 @@ groups:
requirement_level: required
- ref: aws.bedrock.knowledge_base.id
requirement_level: recommended

- id: span.gen_ai.invoke_workflow.client
type: span
span_kind: client
stability: development
brief: >
Represents a workflow orchestrating multiple agents with predefined code paths.
note: |
The `gen_ai.operation.name` SHOULD be `invoke_agent`.
**Span name** SHOULD be `invoke_workflow {gen_ai.workflow.name}`.
attributes:
- ref: gen_ai.workflow.name
requirement_level:
conditionally_required: when available
- ref: gen_ai.framework
requirement_level:
conditionally_required: when available
- ref: gen_ai.input.messages
requirement_level: opt_in
- ref: gen_ai.output.messages
requirement_level: opt_in
- ref: gen_ai.system_instructions
Copy link
Member

@lmolkova lmolkova Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this common for workflows to have system instructions along with input messages?

Copy link
Author

@wrisa wrisa Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Workflow will not have its own but it could be combined from agents->llm's system messages.

Copy link
Member

@aabmass aabmass Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have the same concern. Does a workflow ever actually invoke a model or is it **staticly defined ** control flow?

requirement_level: opt_in