diff --git a/.chloggen/genai-invoke-workflow-operation-name.yaml b/.chloggen/genai-invoke-workflow-operation-name.yaml
new file mode 100644
index 0000000000..dd0e7ef072
--- /dev/null
+++ b/.chloggen/genai-invoke-workflow-operation-name.yaml
@@ -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: 'enhancement'
+
+# 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 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:
diff --git a/docs/gen-ai/aws-bedrock.md b/docs/gen-ai/aws-bedrock.md
index e26f7a655a..77c7b9d5ca 100644
--- a/docs/gen-ai/aws-bedrock.md
+++ b/docs/gen-ai/aws-bedrock.md
@@ -243,6 +243,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md
index 8d1fa1acbc..df2041d8c4 100644
--- a/docs/gen-ai/azure-ai-inference.md
+++ b/docs/gen-ai/azure-ai-inference.md
@@ -1,4 +1,4 @@
-
@@ -244,6 +244,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
diff --git a/docs/gen-ai/gen-ai-agent-spans.md b/docs/gen-ai/gen-ai-agent-spans.md
index b1e323833e..1b148ead98 100644
--- a/docs/gen-ai/gen-ai-agent-spans.md
+++ b/docs/gen-ai/gen-ai-agent-spans.md
@@ -11,6 +11,7 @@ linkTitle: Agent spans
- [Spans](#spans)
- [Create agent span](#create-agent-span)
- [Invoke agent span](#invoke-agent-span)
+ - [Invoke workflow span](#invoke-workflow-span)
- [Execute tool span](#execute-tool-span)
@@ -135,14 +136,15 @@ and SHOULD be provided **at span creation time** (if provided at all):
| Value | Description | Stability |
| --- | --- | --- |
-| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
-| `create_agent` | Create GenAI agent |  |
-| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
-| `execute_tool` | Execute a tool |  |
-| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) |  |
-| `invoke_agent` | Invoke GenAI agent |  |
+| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `create_agent` | Create GenAI agent |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
+| `execute_tool` | Execute a tool |  |
+| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) |  |
+| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
@@ -402,6 +404,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
@@ -446,6 +449,99 @@ and SHOULD be provided **at span creation time** (if provided at all):
+### Invoke workflow span
+
+
+
+
+
+
+**Status:** 
+
+Represents a workflow orchestrating multiple agents and steps through predefined code paths.
+
+The `gen_ai.operation.name` SHOULD be `invoke_workflow`.
+
+**Span name** SHOULD be `invoke_workflow {gen_ai.workflow.name}`.
+Semantic conventions for individual GenAI systems and frameworks MAY specify different span name format.
+
+**Span kind** SHOULD be `CLIENT`.
+
+**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document.
+
+**Attributes:**
+
+| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
+| --- | --- | --- | --- |------------------------------------------------------------------------| --- |
+| [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `invoke_workflow` |
+| [`error.type`](/docs/registry/attributes/error.md) |  | `Conditionally Required` if the operation ended in an error | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500`|
+| [`gen_ai.workflow.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If provided by the application. | string | Human-readable name of the GenAI workflow provided by the application. | `Multi Agent Rag Workflow`; `Customer support pipeline workflow` |
+| [`gen_ai.input.messages`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | The input provided to the workflow. [3] | [
{
"role": "user",
"parts": [
{
"type": "text",
"content": "Weather in Paris?"
}
]
} |
+| [`gen_ai.output.messages`](/docs/registry/attributes/gen-ai.md) |  | `Opt-In` | any | Messages returned by the workflow. [4] | [
{
"role": "assistant",
"parts": [
{
"type": "text",
"content": "The weather in Paris is currently rainy with a temperature of 57°F."
}
],
"finish_reason": "stop"
}
] |
+
+**[1] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value.
+
+**[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library,
+the canonical name of exception that occurred, or another low-cardinality error identifier.
+Instrumentations SHOULD document the list of errors they report.
+
+**[3] `gen_ai.input.messages`:** Instrumentations MUST follow [Input messages JSON schema](/docs/gen-ai/gen-ai-input-messages.json).
+When the attribute is recorded on events, it MUST be recorded in structured
+form. 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.
+
+Instrumentations MAY provide a way for users to filter or truncate
+input messages.
+
+> [!Warning]
+> This attribute is likely to contain sensitive information including user/PII data.
+See [Recording content on attributes](/docs/gen-ai/gen-ai-spans.md#recording-content-on-attributes)
+section for more details.
+
+**[4] `gen_ai.output.messages`:** Instrumentations MUST follow [Output messages JSON schema](/docs/gen-ai/gen-ai-output-messages.json)
+
+When the attribute is recorded on events, it MUST be recorded in structured
+form. 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.
+
+Instrumentations MAY provide a way for users to filter or truncate
+output messages.
+
+> [!Warning]
+> This attribute is likely to contain sensitive information including user/PII data.
+See [Recording content on attributes](/docs/gen-ai/gen-ai-spans.md#recording-content-on-attributes)
+section for more details.
+
+---
+
+`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value | Description | Stability |
+| --- | --- | --- |
+| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  |
+
+---
+
+`gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value | Description | Stability |
+| --- | --- | --- |
+| `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  |
+| `create_agent` | Create GenAI agent |  |
+| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  |
+| `execute_tool` | Execute a tool |  |
+| `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) |  |
+| `invoke_agent` | Invoke GenAI agent |  |
+| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
+| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
+
+---
+
+
+
+
+
## Execute tool span
If you are using some tools in your agent, refer to [Execute Tool Span](./gen-ai-spans.md#execute-tool-span).
diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md
index 6b0f99cec0..b139bb8627 100644
--- a/docs/gen-ai/gen-ai-events.md
+++ b/docs/gen-ai/gen-ai-events.md
@@ -215,6 +215,7 @@ populating this attribute.
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md
index 7add2c3839..328c04c0fb 100644
--- a/docs/gen-ai/gen-ai-metrics.md
+++ b/docs/gen-ai/gen-ai-metrics.md
@@ -127,6 +127,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
@@ -247,6 +248,7 @@ Instrumentations SHOULD document the list of errors they report.
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
@@ -365,6 +367,7 @@ Instrumentations SHOULD document the list of errors they report.
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
@@ -470,6 +473,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
@@ -574,6 +578,7 @@ applicable `aws.bedrock.*` attributes and are not expected to include
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md
index 3cc6b9ea06..f18a1494a1 100644
--- a/docs/gen-ai/gen-ai-spans.md
+++ b/docs/gen-ai/gen-ai-spans.md
@@ -257,6 +257,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
@@ -401,6 +402,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
@@ -666,6 +668,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md
index 608b73062a..1f382236cc 100644
--- a/docs/gen-ai/openai.md
+++ b/docs/gen-ai/openai.md
@@ -246,6 +246,7 @@ and SHOULD be provided **at span creation time** (if provided at all):
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
diff --git a/docs/registry/attributes/gen-ai.md b/docs/registry/attributes/gen-ai.md
index 2ce8dc46f9..319d66e6fe 100644
--- a/docs/registry/attributes/gen-ai.md
+++ b/docs/registry/attributes/gen-ai.md
@@ -60,6 +60,7 @@ This document defines the attributes used to describe telemetry in the context o
| `gen_ai.usage.cache_read.input_tokens` |  | int | The number of input tokens served from a provider-managed cache. [17] | `50` |
| `gen_ai.usage.input_tokens` |  | int | The number of tokens used in the GenAI input (prompt). [18] | `100` |
| `gen_ai.usage.output_tokens` |  | int | The number of tokens used in the GenAI response (completion). | `180` |
+| `gen_ai.workflow.name` |  | string | Human-readable name of the GenAI workflow provided by the application. | `Multi Agent Rag Workflow`; `customer support pipeline workflow` |
**[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.
@@ -218,6 +219,7 @@ by summing different token types parsed from the provider output.
| `invoke_agent` | Invoke GenAI agent |  |
| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  |
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
+| `invoke_workflow` | Invoke GenAI workflow |  |
---
diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml
index d64574f6f7..5bcb0c5685 100644
--- a/model/gen-ai/registry.yaml
+++ b/model/gen-ai/registry.yaml
@@ -405,6 +405,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
@@ -655,3 +659,10 @@ groups:
brief: The name of the prompt that uniquely identifies it.
stability: development
examples: ["analyze-code"]
+ - 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" ]
+ note: |
+ This attribute can be populated in different frameworks eg: name of the trace in OpenAI agents OR name of the first chain in LangChain OR name of the crew in CrewAI.
diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml
index b9b256ed57..08012e2cb9 100644
--- a/model/gen-ai/spans.yaml
+++ b/model/gen-ai/spans.yaml
@@ -468,3 +468,27 @@ groups:
note: >
Anthropic reports this separately from `input_tokens`.
This value MUST be added to the Anthropic `input_tokens` to compute `gen_ai.usage.input_tokens`.
+
+ - id: span.gen_ai.invoke_workflow.internal
+ type: span
+ span_kind: internal
+ stability: development
+ brief: >
+ Represents a workflow orchestrating one or more agents.
+ note: |
+ The `gen_ai.operation.name` SHOULD be `invoke_workflow`.
+ **Span name** SHOULD be `invoke_workflow {gen_ai.workflow.name}`.
+
+ This span SHOULD be reported by the instrumentations when they can
+ reliably determine that invocation is a workflow (i.e. groups several agent
+ invocations) and SHOULD NOT be reported by instrumentations that
+ can't distinguish it `invoke_workflow` from `invoke_agent`.
+ extends: attributes.gen_ai.common.client
+ attributes:
+ - ref: gen_ai.workflow.name
+ requirement_level:
+ conditionally_required: when available
+ - ref: gen_ai.input.messages
+ requirement_level: opt_in
+ - ref: gen_ai.output.messages
+ requirement_level: opt_in