AI Agent Span Semantic Convention #1657
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,185 @@ | ||
| <!--- Hugo front matter used to generate the website version of this page: | ||
| linkTitle: Generative AI traces | ||
| ---> | ||
|
|
||
| # Semantic Conventions for AI Agent Spans | ||
|
|
||
| **Status**: [Experimental][DocumentStatus] | ||
|
|
||
| <!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` --> | ||
|
|
||
| <!-- toc --> | ||
|
|
||
| - [SPAN KIND](#span-kind) | ||
| - [Name](#name) | ||
| - [AI Agent attributes](#ai-agent-attributes) | ||
| - [Workflow Attributes](#workflow-attributes) | ||
| - [Agent Attributes](#agent-attributes) | ||
| - [Tools Attributes](#tools-attributes) | ||
| - [Task Attributes](#task-attributes) | ||
| - [Interaction Attributes](#interaction-attributes) | ||
| - [Examples](#examples) | ||
| - [Workflow: Market Analysis Pipeline](#workflow-market-analysis-pipeline) | ||
| - [Agents Involved](#agents-involved) | ||
| - [DataCollectorAgent](#datacollectoragent) | ||
| - [DataAnalystAgent](#dataanalystagent) | ||
| - [Tasks and Tools](#tasks-and-tools) | ||
| - [Task: Data Collection](#task-data-collection) | ||
| - [Tool Utilized: WebScraperTool](#tool-utilized-webscrapertool) | ||
| - [Task: Data Analysis](#task-data-analysis) | ||
| - [Tool Utilized: DataAnalyzerTool](#tool-utilized-dataanalyzertool) | ||
|
|
||
| <!-- tocstop --> | ||
|
|
||
| ## SPAN KIND | ||
|
|
||
| Each step in an AI Agent workflow is treated as a span. | ||
|
|
||
| **Span kind:** SHOULD be `CLIENT`. It MAY be set to `INTERNAL` on spans representing call in an AI Agent workflow. | ||
|
|
||
| ## Name | ||
|
|
||
| AI Agent spans MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/trace/api.md#span). The **span name** SHOULD be `{ai_agent.operation.name} {ai_agent.workflow.system}`. | ||
| Semantic conventions for individual AI Agent systems and frameworks MAY specify different span name format. | ||
|
|
||
| - ai_agent.operation.name: The operation being performed (e.g., `workflow.kickoff`,`agent.execution`, `task.execution`, `agent.interaction`). | ||
| - ai_agent.workflow.system: The type of agent performing the operation (e.g., `CrewAI`, `LangGraph`, `AutoGen`). | ||
|
|
||
| ## AI Agent attributes | ||
|
|
||
| ### Workflow Attributes | ||
|
|
||
| | Attribute | Type | Description | Example | Requirement Level | Stability | | ||
| | ------------------------------ | ------ | --------------------------------------------------------- | --------------------------------- | ----------------- | --- | | ||
| | `ai_agent.workflow.name` | string | Name of the workflow. | `Data Processing Pipeline` | Required |  | | ||
| | `ai_agent.workflow.tasks` | array | List of tasks included in the workflow. | `["Data Collection", "Analysis"]` | Recommended |  | | ||
| | `ai_agent.workflow.agents` | array | List of agents participating in the workflow. | `["Agent A", "Agent B"]` | Recommended |  | | ||
| | `ai_agent.workflow.config` | object | Configuration settings for the workflow. | `{"setting1": "value1"}` | Recommended |  | | ||
| | `ai_agent.workflow.start_time` | string | Timestamp when the workflow started. | `2024-12-06T10:00:00Z` | Required |  | | ||
| | `ai_agent.workflow.end_time` | string | Timestamp when the workflow ended. | `2024-12-06T11:00:00Z` | Required |  | | ||
| | `ai_agent.workflow.end_state` | string | Final state of the workflow (e.g., `success`, `failure`). | `success` | Required |  | | ||
| | `ai_agent.workflow.end_reason` | string | Reason for the workflow's end, if applicable. | `Completed all tasks` | Recommended |  | | ||
| | `ai_agent.workflow.system` | string | System or environment where the workflow is executed. | `CrewAI`, `LangGraph`, `AutoGen` | Recommended |  | | ||
|
|
||
| ### Agent Attributes | ||
|
|
||
| | Attribute | Type | Description | Example | Requirement Level | Stability | | ||
| | ------------------------------ | ------ | ------------------------------------------ | -------------------------------- | ----------------- | --- | | ||
| | `ai_agent.agent.name` | string | Name of the agent. | `Researcher Bot` | Required |  | | ||
| | `ai_agent.agent.role` | string | Role assigned to the agent. | `Data Collector` | Required |  | | ||
| | `ai_agent.agent.backstory` | string | Background story or context for the agent. | `Specializes in web data mining` | Required |  | | ||
|
There was a problem hiding this comment. AFAICT, |
||
| | `ai_agent.agent.workflow_name` | string | Name of the workflow the agent is part of. | `Data Processing Pipeline` | Required |  | | ||
| | `ai_agent.agent.model` | string | Underlying model powering the agent. | `gpt-4` | Required |  | | ||
|
There was a problem hiding this comment. how's agent model is different from |
||
| | `ai_agent.agent.tools` | array | List of tools available to the agent. | `["Web Scraper", "Analyzer"]` | Recommended |  | | ||
|
There was a problem hiding this comment. how'd it be different from generic gen_ai tool? |
||
|
|
||
| ### Tools Attributes | ||
|
|
||
| | Attribute | Type | Description | Example | Requirement Level | Stability | | ||
| | ------------------------ | ------ | -------------------------------------------- | ----------------- | ----------------- | --- | | ||
| | `ai_agent.tool.name` | string | Name of the tool utilized by the agent. | `Web Scraper` | Required |  | | ||
| | `ai_agent.tool.function` | string | Specific function or capability of the tool. | `Data Extraction` | Recommended |  | | ||
|
There was a problem hiding this comment. do we also need a |
||
| | `ai_agent.tool.output` | object | Output produced by the tool. | `{"data": [...]}` | Required |  | | ||
|
|
||
| ### Task Attributes | ||
|
|
||
| | Attribute | Type | Description | Example | Requirement Level | Stability | | ||
| | --------------------------- | ------- | ------------------------------------------------------------------------ | ---------------------------------- | ----------------- | --- | | ||
| | `ai_agent.task.name` | string | Name of the task. | `Data Collection` | Required |  | | ||
|
There was a problem hiding this comment. do we also need a There was a problem hiding this comment. I'm curious if we can consolidate it under |
||
| | `ai_agent.task.agent_name` | string | Name of the agent responsible for the task. | `Agent A` | Required |  | | ||
| | `ai_agent.task.description` | string | Detailed description of the task. | `Collect data from specified URLs` | Required |  | | ||
| | `ai_agent.task.output` | object | Output generated from the task. | `{"collected_data": [...]}` | Required |  | | ||
| | `ai_agent.task.priority` | string | Priority level of the task (e.g., `low`, `medium`, `high`). | `high` | Recommended |  | | ||
| | `ai_agent.task.state` | string | Current state of the task (e.g., `pending`, `in_progress`, `completed`). | `in_progress` | Required |  | | ||
| | `ai_agent.task.duration` | integer | Duration taken to complete the task in milliseconds. | `120000` | Recommended |  | | ||
|
|
||
| ### Interaction Attributes | ||
|
|
||
| | Attribute | Type | Description | Example | Requirement Level | Stability | | ||
| | ----------------------------- | ------ | ------------------------------------------------------------------ | ------------------ | ----------------- | --- | | ||
| | `ai_agent.interaction.type` | string | Type of interaction (e.g., `message_exchange`, `task_delegation`). | `message_exchange` | Required |  | | ||
| | `ai_agent.interaction.source` | string | Identifier of the source agent initiating the interaction. | `Agent A` | Required |  | | ||
| | `ai_agent.interaction.target` | string | Identifier of the target agent receiving the interaction. | `Agent B` | Required |  | | ||
| | `ai_agent.interaction.status` | string | Outcome of the interaction (e.g., `success`, `failure`). | `success` | Required |  | | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Workflow: Market Analysis Pipeline | ||
|
|
||
| Description: This workflow aims to analyze market trends by collecting and analyzing data from various sources. | ||
|
|
||
| - Attributes: | ||
| - ai_agent.workflow.name: Market Analysis Pipeline | ||
| - ai_agent.workflow.tasks: ["Data Collection", "Data Analysis"] | ||
| - ai_agent.workflow.agents: ["DataCollectorAgent", "DataAnalystAgent"] | ||
| - ai_agent.workflow.config: {"schedule": "weekly", "priority": "high"} | ||
| - ai_agent.workflow.start_time: 2024-12-06T08:00:00Z | ||
| - ai_agent.workflow.end_time: 2024-12-06T10:00:00Z | ||
| - ai_agent.workflow.end_state: success | ||
| - ai_agent.workflow.end_reason: All tasks completed successfully | ||
| - ai_agent.workflow.tags: ["Market Analysis", "Automation"] | ||
| - ai_agent.workflow.system: Production | ||
|
|
||
| ### Agents Involved | ||
|
|
||
| #### DataCollectorAgent | ||
|
|
||
| - Attributes: | ||
| - ai_agent.agent.name: DataCollectorAgent | ||
| - ai_agent.agent.role: Data Collection | ||
| - ai_agent.agent.backstory: Specializes in gathering data from diverse online sources. | ||
| - ai_agent.agent.workflow_name: Market Analysis Pipeline | ||
| - ai_agent.agent.model: gpt-4 | ||
| - ai_agent.agent.tools: ["WebScraperTool"] | ||
|
|
||
| #### DataAnalystAgent | ||
|
|
||
| - Attributes: | ||
| - ai_agent.agent.name: DataAnalystAgent | ||
| - ai_agent.agent.role: Data Analysis | ||
| - ai_agent.agent.backstory: Proficient in interpreting data to extract meaningful insights. | ||
| - ai_agent.agent.workflow_name: Market Analysis Pipeline | ||
| - ai_agent.agent.model: gpt-4 | ||
| - ai_agent.agent.tools: ["DataAnalyzerTool"] | ||
|
|
||
| ### Tasks and Tools | ||
|
|
||
| #### Task: Data Collection | ||
|
|
||
| - Assigned Agent: DataCollectorAgent | ||
|
|
||
| - Attributes: | ||
| - ai_agent.task.name: Data Collection | ||
| - ai_agent.task.agent_name: DataCollectorAgent | ||
| - ai_agent.task.description: Gather market data from specified online sources. | ||
| - ai_agent.task.output: {"data_size": "500MB", "records": 10000} | ||
| - ai_agent.task.priority: high | ||
| - ai_agent.task.state: completed | ||
| - ai_agent.task.duration: 3600000 | ||
|
|
||
| #### Tool Utilized: WebScraperTool | ||
|
|
||
| - Attributes: | ||
| - ai_agent.tool.name: WebScraperTool | ||
| - ai_agent.tool.function: Data Extraction | ||
| - ai_agent.tool.output: {"records_extracted": 10000, "duration": "1h"} | ||
|
|
||
| #### Task: Data Analysis | ||
|
|
||
| - Assigned Agent: DataAnalystAgent | ||
| - Attributes: | ||
| - ai_agent.task.name: Data Analysis | ||
| - ai_agent.task.agent_name: DataAnalystAgent | ||
| - ai_agent.task.description: Analyze the collected data to identify market trends. | ||
| - ai_agent.task.output: {"insights": ["Trend A", "Trend B"]} | ||
| - ai_agent.task.priority: high | ||
| - ai_agent.task.state: completed | ||
| - ai_agent.task.duration: 5400000 | ||
|
|
||
| #### Tool Utilized: DataAnalyzerTool | ||
|
|
||
| - Attributes: | ||
| - ai_agent.tool.name: DataAnalyzerTool | ||
| - ai_agent.tool.function: Data Analysis | ||
| - ai_agent.tool.output: {"identified_trends": 2, "duration": "1.5h"} | ||
|
|
||
| This simplified workflow demonstrates how two agents collaborate to perform data collection and analysis tasks, utilizing specific tools to achieve the objectives of the Market Analysis Pipeline. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Those are still genai agents, so I think this out should be
gen_ai.agent.name