External agent traces

Use W3C Trace Context and Data Export to see what happens inside the external agents your Maestro processes invoke, stitched into your observability platform.

Problem statement

Maestro processes increasingly invoke external agents — agents running in platforms such as Azure AI Foundry, Databricks, and others. On its own, an external agent call tells Maestro only that the agent ran and whether it succeeded — not what happened inside it: which model was called, what tools were used, how long each step took, or why a call failed.

Without that visibility, process owners cannot audit, optimize, or troubleshoot the external agent steps in their processes. When an external call fails, the log shows only the outcome at the boundary — leaving teams to log in to each external platform, guess at timestamps, and search through unrelated activity to reconstruct what went wrong. External agent traces close this gap.

How external agent traces help

Maestro participates in distributed tracing using the open W3C Trace Context standard. Every external agent call Maestro makes carries a shared trace ID. Agents that understand the standard record their own activity under that same trace ID, so your observability platform can stitch Maestro's steps and the external agent's internal steps into a single end-to-end view.

Como funciona

1. Maestro generates a trace ID. When a process instance starts, Maestro creates a unique master trace ID for the run.
2. Maestro propagates it on every outbound call. Before invoking an external agent, Maestro injects the trace ID into the request as a W3C traceparent header — for example: traceparent: 00-<trace-id>-<span-id>-01
3. Compliant agents continue the trace. An external agent that supports W3C Trace Context reads the header, keeps the master trace ID, and records its internal work (model calls, tool use, latency, errors) as child spans under that same trace.
4. Spans flow to your observability platform. Maestro's spans reach your platform through Data Export; the external agent's spans arrive through its own telemetry pipeline. Because both carry the same trace ID, your platform assembles them into one waterfall view.

Observação:

Trace propagation is a single, framework-level behavior. It applies to external agent calls across Maestro automatically — there is nothing to enable per connector or per agent.

Pré-requisitos

• You must be an Organization Administrator to configure Data Export, and the tenant must have Insights enabled.
• A supported trace destination: Databricks, Arize, or an OTLP (OpenTelemetry Protocol) endpoint.
• The external agent must emit traces, with tracing enabled on the agent side. Model-only or LLM serving endpoints generally do not produce traces — only agents with tracing enabled do.

Configure Data Export

External agent traces become visible once Maestro's execution traces are exported to your observability platform.

1. Navigate to your organization, select the Admin tab, and then select the Data Export card.
2. Select + Add and complete the configuration wizard.
3. Select the tenant, then choose the Agent and Maestro Traces data source. This data source is exported as OTEL Trace data.
4. Choose your destination — Databricks, Arize, or an OTLP endpoint — provide its connection details, and save.

Once export is active, Maestro traces — including the spans from external agent calls — stream to your destination, where you can search by trace ID to see the full run.

For setup details and destination-specific instructions, see Data Export.

Observação:

Databricks: The Databricks agent API does not honor inbound W3C tracing headers and instead issues its own trace ID per invocation. To correlate Databricks calls, Maestro captures the Databricks trace ID returned by the call and records it on an External Agent Invocation span, nested under the activity span. For this to work on the Databricks side:

• MLflow tracing must be enabled on the agent.
• The agent must be configured to return its trace ID to UiPath.
• A recent version of MLflow is required — older versions do not return the trace ID, so no trace span is generated.

Perguntas frequentes

Do I need to install anything in my external agents?

No. Maestro propagates trace context using the open W3C Trace Context standard. Any external agent that already supports this standard records its spans under the Maestro trace ID automatically — there is nothing to add to the agent's code.

Do I need to configure tracing for each connector or agent?

No. Trace propagation is a single, framework-level behavior that applies to external agent calls across Maestro. The only setup required is configuring a Data Export destination so the traces reach your observability platform.

Why do I see traces for some external agents but not others?

An external agent only contributes traces if it actually emits them. Plain model or LLM serving endpoints generally do not produce traces — only agents with tracing enabled do. For agents that support W3C Trace Context, their spans appear automatically under the Maestro trace ID. For agents that do not, such as Databricks, tracing must be enabled and configured on the agent side so it returns a trace ID to Maestro.

Where do I view the traces?

In your own observability platform. Once Data Export is active, search by the trace ID to see Maestro's spans and the external agent's spans stitched into a single end-to-end view.

Páginas relacionadas

• Observação de execuções
• Noções básicas sobre monitoramento
• Usando agentes no Maestro
• Exportação de dados