From ce115792421735b64d15bd4d83771a2b29052f6a Mon Sep 17 00:00:00 2001 From: Kc Balusu Date: Thu, 2 Apr 2026 14:50:08 -0700 Subject: [PATCH] Add plan operation for GenAI agent spans --- .chloggen/gen-ai-plan-operation.yaml | 7 +++ docs/gen-ai/anthropic.md | 1 + docs/gen-ai/aws-bedrock.md | 1 + docs/gen-ai/azure-ai-inference.md | 1 + docs/gen-ai/gen-ai-agent-spans.md | 89 ++++++++++++++++++++++++++++ docs/gen-ai/gen-ai-events.md | 1 + docs/gen-ai/gen-ai-metrics.md | 7 +++ docs/gen-ai/gen-ai-spans.md | 4 ++ docs/gen-ai/mcp.md | 4 ++ docs/gen-ai/openai.md | 1 + docs/registry/attributes/gen-ai.md | 1 + model/gen-ai/registry.yaml | 4 ++ model/gen-ai/spans.yaml | 45 ++++++++++++++ 13 files changed, 166 insertions(+) create mode 100644 .chloggen/gen-ai-plan-operation.yaml diff --git a/.chloggen/gen-ai-plan-operation.yaml b/.chloggen/gen-ai-plan-operation.yaml new file mode 100644 index 0000000000..ca2c6e59c9 --- /dev/null +++ b/.chloggen/gen-ai-plan-operation.yaml @@ -0,0 +1,7 @@ +change_type: enhancement +component: gen_ai +note: "Add `plan` operation for GenAI agent planning/task decomposition spans" +issues: [2664] +subtext: | + Adds `plan` as a new `gen_ai.operation.name` value and a corresponding + INTERNAL span definition for agent planning or task decomposition. diff --git a/docs/gen-ai/anthropic.md b/docs/gen-ai/anthropic.md index 1083e874ba..f5915e6599 100644 --- a/docs/gen-ai/anthropic.md +++ b/docs/gen-ai/anthropic.md @@ -218,6 +218,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/gen-ai/aws-bedrock.md b/docs/gen-ai/aws-bedrock.md index 6abb4a0830..35dc3530da 100644 --- a/docs/gen-ai/aws-bedrock.md +++ b/docs/gen-ai/aws-bedrock.md @@ -242,6 +242,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/gen-ai/azure-ai-inference.md b/docs/gen-ai/azure-ai-inference.md index f7abfcce7a..761d530b1d 100644 --- a/docs/gen-ai/azure-ai-inference.md +++ b/docs/gen-ai/azure-ai-inference.md @@ -243,6 +243,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/gen-ai/gen-ai-agent-spans.md b/docs/gen-ai/gen-ai-agent-spans.md index f235d084c2..1705be741b 100644 --- a/docs/gen-ai/gen-ai-agent-spans.md +++ b/docs/gen-ai/gen-ai-agent-spans.md @@ -12,6 +12,7 @@ linkTitle: Agent spans - [Create agent span](#create-agent-span) - [Invoke agent span](#invoke-agent-span) - [Invoke workflow span](#invoke-workflow-span) + - [Plan span](#plan-span) - [Execute tool span](#execute-tool-span) @@ -144,6 +145,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -405,6 +407,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -557,6 +560,92 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | +| `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | + + + + + +### Plan span + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +Represents an agent planning or task decomposition phase. + +The `gen_ai.operation.name` SHOULD be `plan`. +**Span name** SHOULD be `plan {gen_ai.agent.name}` if `gen_ai.agent.name` is readily available. +When `gen_ai.agent.name` is not available, it SHOULD be `plan`. + +A plan span represents the decision phase where an agent formulates +a strategy before executing it. The LLM call that generates the plan is a child +of the plan span, and the tool or task spans produced from the plan are sibling +operations under the same `invoke_agent` span. + +This span SHOULD be reported by instrumentations when they can reliably determine +that the operation being instrumented is planning or task decomposition, and SHOULD +NOT be reported when the instrumentation cannot distinguish planning from generic +reasoning or normal inference. + +Grouping primitives or span links can correlate planning-related spans, but they +do not represent the planning phase itself as a timed parent span with a child +`chat` call. + +This is distinct from task execution. A task span represents execution of assigned +work, while a plan span represents strategy formulation before execution. + +**Span kind** SHOULD be `INTERNAL`. + +**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) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | +| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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.agent.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` if applicable. | string | The unique identifier of the GenAI agent. | `asst_5j66UpCpwteGg4YSxUnt7lPY` | +| [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Conditionally Required` when available | string | Human-readable name of the GenAI agent provided by the application. | `Math Tutor`; `Fiction Writer` | + +**[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. + +The following attributes can be important for making sampling decisions +and SHOULD be provided **at span creation time** (if provided at all): + +* [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) + +--- + +`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + +--- + +`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) | ![Development](https://img.shields.io/badge/-development-blue) | +| `create_agent` | Create GenAI agent | ![Development](https://img.shields.io/badge/-development-blue) | +| `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) | ![Development](https://img.shields.io/badge/-development-blue) | +| `execute_tool` | Execute a tool | ![Development](https://img.shields.io/badge/-development-blue) | +| `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) | +| `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index bb2c5c7cc1..bd79528033 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -214,6 +214,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/gen-ai/gen-ai-metrics.md b/docs/gen-ai/gen-ai-metrics.md index 706259dabb..3c7fb9705a 100644 --- a/docs/gen-ai/gen-ai-metrics.md +++ b/docs/gen-ai/gen-ai-metrics.md @@ -128,6 +128,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -249,6 +250,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -350,6 +352,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -451,6 +454,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -570,6 +574,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -676,6 +681,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -781,6 +787,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index fa67bd82a6..e581cfd06a 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -256,6 +256,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -402,6 +403,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -536,6 +538,7 @@ Each document object SHOULD contain at least the following properties: | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -669,6 +672,7 @@ and SHOULD be provided **at span creation time** (if provided at all): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/gen-ai/mcp.md b/docs/gen-ai/mcp.md index 372c903023..646a84babe 100644 --- a/docs/gen-ai/mcp.md +++ b/docs/gen-ai/mcp.md @@ -251,6 +251,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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -411,6 +412,7 @@ It SHOULD be set to `pipe` if the transport is stdio. | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -550,6 +552,7 @@ It SHOULD be set to `pipe` if the transport is stdio. | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | @@ -681,6 +684,7 @@ It SHOULD be set to `pipe` if the transport is stdio. | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/gen-ai/openai.md b/docs/gen-ai/openai.md index dc8d82df57..4dcd2227b5 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): | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/docs/registry/attributes/gen-ai.md b/docs/registry/attributes/gen-ai.md index b7b4f0926d..ae99f15df2 100644 --- a/docs/registry/attributes/gen-ai.md +++ b/docs/registry/attributes/gen-ai.md @@ -221,6 +221,7 @@ by summing different token types parsed from the provider output. | `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) | | `invoke_workflow` | Invoke GenAI workflow | ![Development](https://img.shields.io/badge/-development-blue) | +| `plan` | Agent planning or task decomposition phase | ![Development](https://img.shields.io/badge/-development-blue) | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) | ![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) | diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml index ddd2408b27..b35ee7eb30 100644 --- a/model/gen-ai/registry.yaml +++ b/model/gen-ai/registry.yaml @@ -414,6 +414,10 @@ groups: value: "invoke_workflow" brief: 'Invoke GenAI workflow' stability: development + - id: plan + value: "plan" + brief: 'Agent planning or task decomposition phase' + 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 diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 2ff5f5c639..d1ef14f38a 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -516,3 +516,48 @@ groups: requirement_level: opt_in - ref: gen_ai.output.messages requirement_level: opt_in + + - id: span.gen_ai.plan.internal + type: span + span_kind: internal + stability: development + brief: > + Represents an agent planning or task decomposition phase. + note: | + The `gen_ai.operation.name` SHOULD be `plan`. + **Span name** SHOULD be `plan {gen_ai.agent.name}` if `gen_ai.agent.name` is readily available. + When `gen_ai.agent.name` is not available, it SHOULD be `plan`. + + A plan span represents the decision phase where an agent formulates + a strategy before executing it. The LLM call that generates the plan is a child + of the plan span, and the tool or task spans produced from the plan are sibling + operations under the same `invoke_agent` span. + + This span SHOULD be reported by instrumentations when they can reliably determine + that the operation being instrumented is planning or task decomposition, and SHOULD + NOT be reported when the instrumentation cannot distinguish planning from generic + reasoning or normal inference. + + Grouping primitives or span links can correlate planning-related spans, but they + do not represent the planning phase itself as a timed parent span with a child + `chat` call. + + This is distinct from task execution. A task span represents execution of assigned + work, while a plan span represents strategy formulation before execution. + attributes: + - ref: gen_ai.operation.name + requirement_level: required + sampling_relevant: true + - ref: error.type + requirement_level: + conditionally_required: "if the operation ended in an error" + note: | + 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. + - ref: gen_ai.agent.id + requirement_level: + conditionally_required: if applicable. + - ref: gen_ai.agent.name + requirement_level: + conditionally_required: when available