Why add OpenLLMetry's @workflow and @task decorators when init already traces model calls?

## The gap the decorators fill Auto-instrumentation is honest but shallow: it records what a *library* did. A single user request in a RAG service might produce an embedding call, a vector-store query, a re-rank call and a generation call — four spans with no notion that they were one "answer_question" operation. Nothing in the OpenAI SDK knows your business steps, so nothing can name them for you. The decorators are how you supply that structure: ``` from traceloop.sdk.decorators import workflow, task, agent, tool ``` Decorating a function starts a span when it is entered and ends it when it returns, and because OpenTelemetry propagates the active context, every auto-instrumented call inside becomes a child of that span. You get a tree instead of a list. ## The four decorators They behave the same mechanically; the difference is the semantic label recorded on the span (the SDK writes a `traceloop.span.kind` attribute), which is what backends use to render and filter the trace. - **`@workflow`** — the outermost unit of work you would name in a product conversation: `answer_question`, `summarize_ticket`. One per request, typically. - **`@task`** — a step inside a workflow: `retrieve_docs`, `rerank`, `format_answer`. - **`@agent`** — an autonomous loop that decides its own next step, rather than a fixed pipeline. - **`@tool`** — a function the model can choose to call. Marking it as a tool makes "which tool did the agent pick, how often, and how long did it take" a query rather than a code read. Each accepts an optional `name`; omit it and the function name is used. Prefer explicit, stable names — they become the identity you compare across deploys, and renaming the Python function should not silently split your latency history in two. ## What it buys you operationally Once the workflow span exists, several things become possible that were not before: 1. **End-to-end latency per operation.** The workflow span's duration is the number users feel. The sum of model-call durations is not, because it excludes your own retrieval, parsing and retries. 2. **Attribution of cost and failure.** Token usage on child spans rolls up under a named parent, so you can say which product feature is expensive, not just which model is. 3. **Comparison across versions.** Filtering by workflow name gives a stable series to compare before and after a prompt or model change. 4. **Agent legibility.** For a tool-calling loop, the trace shows the sequence of tool spans the model chose, which is usually the fastest way to explain a wrong answer. ## Nesting and granularity Nest freely: a `@workflow` calling several `@task`s, one of which calls an `@agent` that calls `@tool`s. The practical limit is judgment, not the SDK — a span per trivial helper produces traces nobody reads and inflates ingest volume. A good rule is to decorate a function when you would want its duration on a dashboard or when it is a unit you might replace. Async code is handled: recent versions of the SDK detect coroutine functions and manage the span across the await rather than closing it at the first suspension. Generators and streaming responses are the case to think about, because the interesting work happens while the caller iterates, not when the function returns. ## What the decorators are not They do not enable tracing. Without `Traceloop.init()` there is no pipeline to export into. They do not add evaluation scores — judging whether the output was any good is a separate concern from recording that it happened. And they are not a replacement for the auto-instrumented LLM spans: the workflow span records that a step happened and how long it took; the model span underneath records which model, which parameters and how many tokens. ## Failure mode to know If a decorated function spawns work onto another thread or an executor without propagating context, the child spans can land outside the workflow span and appear as orphan traces. That is a context-propagation problem in the general tracing sense rather than an OpenLLMetry quirk, but it is the usual reason someone says "my workflow span is empty".