Skip to content

Operation kinds

Use metadata["operation_kind"] to identify what a span does while retaining the existing event_type category. This uses the schema's extensible metadata object; traces remain schema 1.1 and existing 1.0 files need no migration.

Kind Meaning
agent One agent invocation or agent lifecycle operation
workflow Orchestration of multiple steps or agents
model Inference, generation, or embedding computation
tool Invocation of an application tool
retriever Retrieval of relevant documents or records
memory Reading, writing, or managing agent memory
reranker Reordering retrieved candidates by relevance
guardrail Enforcing a safety, validity, or budget constraint
evaluator Evaluating output or task quality
retry Repeating a failed or rejected step

The framework-neutral AgentEvent.operation_kind property normalizes surrounding whitespace and letter case. ExecutionNode.operation_kind exposes the same value. The original label remains in metadata. With no label, model_call maps to model, tool_call to tool, and retry to retry.

An unrecognized, empty, or non-string label is analyzed as unknown; its raw metadata is retained. It does not silently inherit model or tool semantics. Unknown legacy event types also analyze as unknown. Add application-specific details under other metadata keys rather than inventing a near-synonym for a supported kind.

Capture and analysis

Existing tracing helpers accept metadata, so integrations need no framework types or new dependency in the core:

from agentloop import trace_agent, trace_tool_call

with trace_agent("search-workflow") as trace:
    with trace_tool_call("retrieve", metadata={"operation_kind": "retriever"}):
        documents = ["synthetic document"]

assert trace.events[0].event_type == "tool_call"
assert trace.events[0].operation_kind == "retriever"
assert trace.report()["operation_counts"] == {"retriever": 1}

Legacy model/tool/retry counts, token accounting, and elapsed-time metrics still use event_type for compatibility. Reports add operation_counts; replay keeps those counts separately for each condition. Graph nodes and finding evidence carry the normalized kind next to each span ID. This is also available to study consumers through the report and replay JSON.

Parallelization and tool-oscillation rules operate on tool spans, so an agent, workflow, retrieval, or unknown operation does not receive tool-specific savings merely because its legacy category is tool_call. Loop detection separates groups by normalized kind and name. These rules are version 1.1; estimator versions describe the prediction formulas independently. Model and retry rules likewise require their normalized kinds. Repeated-context analysis excludes spans explicitly labeled as another operation kind.

OTLP mapping

The importer maps gen_ai.operation.name values as follows:

Source operation Normalized kind Legacy category
chat, text_completion, generate_content, embeddings model model_call
execute_tool tool tool_call
invoke_agent, create_agent agent tool_call
invoke_workflow workflow tool_call
retrieval retriever tool_call
retry retry retry

These names follow the OpenTelemetry GenAI attribute registry. Explicit operations take precedence over span-name hints. Unknown source operations keep their original label in metadata and analyze as unknown. If the source has no operation, the importer retains its legacy name-based fallback and derives the kind from that category.

AgentLoop exports explicitly supplied labels through agentloop.operation_kind and its metadata namespace. On import, native metadata takes precedence, followed by that explicit attribute and then the GenAI operation. Native agentloop.event_type takes precedence for the legacy category, retaining both fields even when an application deliberately combines them. Repeated native OTLP round trips preserve operation metadata without adding a label to older, unlabeled native events.