[RFC] Semantic Conventions for AI Agent Observability

OpenTelemetry Semantic Conventions for AI Agents

Table of Contents

1. Introduction
2. Overview
3. Span Definitions
4. Attribute Registry
5. Event Definitions - in a comment
6. Metrics Definitions - in a comment

Introduction

This document defines semantic conventions for observability of AI agent systems built with frameworks like LangGraph, CrewAI, Autogen, Google ADK, LlamaIndex, OpenAI Agents SDK, Agno, MastraAI, Smolagents, Haystack, and AWS Bedrock AgentCore.

These conventions extend the existing OpenTelemetry Semantic Conventions for GenAI by adding specialized concepts for:

• Agent lifecycle and orchestration - Creation, execution, handoffs, termination
• Multi-agent coordination - Teams, crews, agent-to-agent communication
• Task management - Task creation, execution, delegation, hierarchies
• Memory systems - Short-term, long-term, vector-based memory operations
• Tool execution - Function calling, MCP integrations, error handling
• Workflow orchestration - Graph-based execution, state transitions, checkpointing
• Quality assurance - Guardrails, runtime evaluations, human-in-the-loop
• Session management - Conversations, context, checkpointing

Design Principles

1. Framework Agnostic - Conventions work across all major agent frameworks
2. Extend, Don't Replace - Build on existing gen_ai.* conventions

Namespace Convention

All agent-specific attributes use the gen_ai.* prefix to align with existing OpenTelemetry GenAI semantic conventions:

• gen_ai.agent.* - Agent-specific attributes
• gen_ai.team.* - Multi-agent team attributes
• gen_ai.task.* - Task-specific attributes
• gen_ai.tool.* - Tool execution attributes (extends existing)
• gen_ai.memory.* - Memory system attributes
• gen_ai.workflow.* - Workflow orchestration attributes
• gen_ai.session.* - Session management attributes
• And more...

Overview

Agent System Architecture

Modern AI agent systems typically consist of:

Session (Conversation)
├── Agent(s)
│   ├── Workflow/Graph (Orchestration)
│   │   ├── Task(s) (Work Units)
│   │   │   ├── LLM Calls (Reasoning)
│   │   │   ├── Tool Executions (Actions)
│   │   │   ├── Memory Operations (Context)
│   │   │   └── Guardrails (Quality)
│   │   └── State Transitions
│   ├── Handoffs (Agent-to-Agent)
│   └── Human Reviews (HITL)
└── Artifacts (Outputs)

Span Types Summary

This specification defines 20 primary span types organized into categories:

• Lifecycle (4): session, agent.create, agent.invoke, agent.terminate
• Orchestration (6): team.create, team.execute, team.coordinate, workflow.execute, workflow.transition, workflow.branch
• Task Execution (4): task.create, task.execute, task.delegate, agent.handoff
• Memory (5): memory.store, memory.retrieve, memory.search, memory.update, memory.delete
• Tools & Integration (3): tool.execute, mcp.connect, mcp.execute
• Context & State (2): context.checkpoint, context.compress
• Quality & Control (3): guardrail.check, eval.execute, human.review

Plus existing gen_ai.client.* spans for LLM operations.

Span Definitions

Naming Convention

All span names follow the pattern: gen_ai.<component>.<operation>

Examples:

• gen_ai.agent.invoke
• gen_ai.memory.retrieve
• gen_ai.workflow.execute

1. Lifecycle Spans

1.1 gen_ai.session

Description: Represents a complete agent session, conversation, or autonomous run. This is the top-level span encompassing all agent activities.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• LangGraph: Session maps to a thread with persistent checkpoint history
• CrewAI: Session encompasses full crew execution
• OpenAI Agents SDK: Session corresponds to SQLiteSession or custom session
• Google ADK: Session managed by SessionService (in-memory, SQL, or Vertex AI)

1.2 gen_ai.agent.create

Description: Agent initialization and configuration. Captures the creation of an agent instance with its configuration.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• CrewAI: @agent decorator with role, goal, backstory, tools
• Autogen: AssistantAgent with name, system_message, tools, max_tool_iterations
• OpenAI SDK: Agent with name, instructions, tools, handoffs, output_type
• Agno: Agent(name, model, instructions, tools, add_history_to_context)

1.3 gen_ai.agent.invoke

Description: A single agent invocation/execution. This is the primary span for agent activity.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• LlamaIndex: agent.run() or agent.chat() invocation
• LangGraph: graph.invoke() or graph.stream() execution
• OpenAI SDK: Runner.run() or Runner.run_sync() call
• Smolagents: agent.run() with ReAct loop

1.4 gen_ai.agent.terminate

Description: Agent cleanup and termination. Captures the end of an agent's lifecycle.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

2. Orchestration Spans

2.1 gen_ai.team.create

Description: Multi-agent team or crew initialization.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• CrewAI: Crew(agents=[...], process=Process.SEQUENTIAL)
• Autogen: GroupChat(participants=[...], max_rounds=10)
• Agno: Multi-agent teams with shared state

2.2 gen_ai.team.execute

Description: Execution of a multi-agent team workflow.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

2.3 gen_ai.team.coordinate

Description: Coordination action between team members (e.g., turn selection, task routing).

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• Autogen: GroupChatManager selecting next speaker
• CrewAI: Hierarchical process with manager delegation

2.4 gen_ai.workflow.execute

Description: Execution of a workflow, graph, or orchestration pattern.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• LangGraph: StateGraph.invoke() execution
• Mastra: Workflow.execute() with .then()/.branch()/.parallel()
• CrewAI: Flow execution with @start, @listen, @router
• Google ADK: SequentialAgent, ParallelAgent, LoopAgent execution

2.5 gen_ai.workflow.transition

Description: State transition between workflow nodes/steps.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• LangGraph: Edge traversal in StateGraph with state updates
• Mastra: .then() or .branch() transitions

2.6 gen_ai.workflow.branch

Description: Conditional branching decision in workflow.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• LangGraph: Conditional edges with routing functions
• Mastra: .branch() with conditional logic
• CrewAI: @router decorator in Flows

3. Task Execution Spans

3.1 gen_ai.task.create

Description: Creation and definition of a task.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes:

Framework Examples:

• CrewAI: @task decorator with description, expected_output, agent
• Google ADK: Task submitted to agent with instructions

3.2 gen_ai.task.execute

Description: Execution of a task by an agent.

Span Kind: INTERNAL

Required Attributes:

Optional Attributes: