Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt

Use this file to discover all available pages before exploring further.

AI agents may invoke tools, call other agents, or prompt a Generative AI (GenAI) model with multi-step user input. The distributed and non-deterministic nature of agentic workflows can make monitoring and debugging difficult. Instrument your AI agents with OpenTelemetry (OTel) GenAI semantic conventions to get full visibility into agent sessions and see your agents in the Agent Timeline.

​
Enriching your traces with GenAI context

Add the following OTel GenAI attributes to your agent spans.
​
gen_ai.conversation.id
string
required
Unique identifier for the conversation or session. Used to group all traces and spans belonging to the same agent conversation.
​
gen_ai.agent.name
string
required
Name of the agent emitting the span.In multi-agent workflows each agent should have a unique name.
​
gen_ai.operation.name
string
required
Type of agentic operation occurring:
  • chat
  • create_agent
  • embeddings
  • execute_tool
  • generate_content
  • invoke_agent
  • invoke_workflow
  • retrieval
  • text_completion
See naming generative AI operation spans for span naming conventions.
​
gen_ai.usage.input_tokens
int
Number of tokens used in the GenAI input prompt.
​
gen_ai.usage.output_tokens
int
Number of tokens used in the GenAI response.
​
gen_ai.request.model
string
Name of the model requested.
​
gen_ai.response.model
string
Name of the model that generated the response. This can differ from the requested model.
​
gen_ai.response.finish_reasons
string[]
Why the model stopped generating tokens.Examples: ["stop"], ["tool_calls"], ["stop", "length"]
​
gen_ai.tool.name
string
Name of the tool called by the agent.
​
gen_ai.tool.call.id
string
Unique identifier for the tool call.
​
gen_ai.tool.call.arguments
object | json
Parameters passed to the tool call.
​
gen_ai.tool.call.result
string
Result returned by the tool call (if any).See recording errors and exceptions for handling failed tool calls.

​
Span events for input prompts, completions, and evaluations

Full prompts, chat history, and completion responses may be too large or contain personally identifiable information (PII) or other sensitive data. Store prompts, chat history, and completion responses in span events so they can be filtered by your OTel Collector.
​
gen_ai.input.messages
object | json
Chat history or input prompts provided to the model.
GenAI prompts or chats may contain PII or other sensitive data.
​
gen_ai.output.messages
object | json
Messages returned by the model. Each message represents a specific model response.
GenAI responses may contain PII or other sensitive data.
​
gen_ai.evaluation.result
string
Attach gen_ai.evaluation.result events to the GenAI operation span to see evaluations in the GenAI tab.

​
Use unique names for each agent

Each agent should have its own unique gen_ai.agent.name. Sub-agents should use their own distinct name, instead of inheriting the parent agent’s name. The Agent Timeline uses the gen_ai.agent.name value for agent grouping.
If gen_ai.agent.name is omitted on a span, it will show up as "Unknown" on the Agent Timeline.

​
How to instrument one agent calling another agent

When one agent calls or invokes another agent, the calling agent should emit the invoke_agent span, not the agent being called. The called agent then emits its own spans (chat, execute_tool, and so on) under its own unique gen_ai.agent.name. For more information on agent invocation spans, check out the OpenTelemetry documentation:

​
Recording errors and exceptions

Record errors or exceptions following the OTel specification and include as many attributes as you can:
  • error.type / exception.type
  • error.message / exception.message
  • error.stacktrace / exception.stacktrace
For tool call failures, make sure you propogate the error status to the parent span.

​
Naming generative AI operation spans

Generative AI operation spans should follow these naming conventions. Naming your spans this way ensures they render correctly in the Agent Timeline.
Operationgen_ai.operation.nameSpan Name Pattern
Chatchatchat {model}
Create GenAI agentcreate_agentcreate_agent {agent_name}
Tool executionexecute_toolexecute_tool {tool_name}
Agent invocationinvoke_agentinvoke_agent {agent_name}
Embeddingsembeddingsembeddings {model}
RAG retrievalretrievalretrieval {data_source}
Multimodal content generationgenerate_contentgenerate_content {model}
Text completionstext_completiontext_completion {model}