# Instrument agentic runtimes with Telemio

Treat an agentic runtime as an application runtime, not as a special analytics feed. The useful trace includes the model and tool work plus the HTTP requests, queues, databases, native/browser clients, workers, and services around it.

## Detect the orchestration boundary

Look for processes that:

- invoke models or embeddings
- execute tools or functions
- host or call MCP servers
- perform retrieval
- schedule durable/background agent work
- coordinate multiple agents or handoffs
- retry model/tool steps
- evaluate or grade outcomes
- maintain conversation, thread, run, or workflow state

Instrument the orchestration boundary first. Then add child spans for model and tool operations while preserving any existing OpenTelemetry HTTP, database, queue, and runtime spans.

## Trace shape

A useful run often looks like:

```text
request / job / user action
  -> agent or workflow run
    -> model invocation
    -> retrieval
      -> datastore
    -> tool execution
      -> MCP / HTTP / RPC dependency
    -> handoff or child agent
      -> model invocation
    -> persistence / side effect
```

The exact framework can change without changing this model.

## OpenTelemetry semantics

Use the current OpenTelemetry GenAI semantic conventions where they apply. Prefer stable, low-cardinality operation names and attributes for model/provider identity, operation type, agent/workflow identity, tool identity/type, status, token usage, cost metadata, retry count, and correlation identifiers.

GenAI semantic conventions continue to evolve. Do not freeze a private Telemio naming scheme over standard attributes when a current OpenTelemetry convention already exists.

## Content capture

Metadata-first is the default.

Do not export prompt bodies, completion bodies, retrieved documents, tool arguments/results, source code, credentials, or customer content by default. These values can be sensitive, large, expensive to retain, and difficult to govern.

Use stable identifiers or fingerprints when you need to correlate repeated context without storing the content itself.

## Long-running and durable agents

Long-running agents need more than a model-call timer. Preserve:

- workflow/run identity
- attempt/retry number
- checkpoint or resume identity
- queue/job identity
- parent/child or handoff relationship
- release/version of the agent definition
- status/outcome
- token and cost totals
- durable step latency

If a workflow resumes in another process or much later, use propagated trace context when practical and span links or stable correlation identifiers when a direct parent/child trace relationship no longer makes sense.

## Multi-agent systems

Represent handoffs explicitly instead of flattening every agent into one generic span. Keep agent/workflow names low-cardinality and use IDs for individual runs. A multi-agent trace should let an operator see which agent made the decision, which agent or tool received control, and where latency or failure entered the workflow.

## Telemio SDK

In trusted JavaScript/TypeScript agent runtimes, `@telemio/sdk` can add explicit Telemio agent, tool, context, usage, feature-flag, and experiment context beside OpenTelemetry instrumentation:

```bash
npm i @telemio/sdk
```

Do not use the SDK as a reason to remove standard OpenTelemetry auto-instrumentation. The two layers are complementary.