Skip to main content
Bring traces you already hold into a Hue project with one instruction to your coding agent. The agent loads Hue’s import guide, runs the import helper on the machine that holds the files, authorizes the delivery through the Hue MCP server, uploads the traces and reports what arrived. No project key is involved: your sign-in connection, or a Read and write key, authorizes the upload, and the traces go from the helper to Hue, never through the MCP connection. The helper runs with npx on the machine that holds the bundle, whatever language your application uses.

​
Ask your agent

Name the file, directory or ZIP archive when it is not in the working directory, and the project when the connection reaches more than one.

​
What the agent does

  1. Loads the guide and chooses the project. load_hue_guide with topic import describes the workflow. On an organization connection, list_projects names the project.
  2. Prepares the bundle on your machine. npx -y @hue-run/sdk@latest traces import prepare <path> --out <directory> --json reads the files, writes the prepared import to the directory and prints a report: the manifest digest and totals, the formats it recognized, the files it could not read, invalid vendor ids it mapped deterministically, and the traces without a history owner. Nothing is sent.
  3. Authorizes the delivery. prepare_trace_import with the report’s manifest digest, totals and source returns the import id, the upload URL and an authorization valid for a day. The agent writes the authorization to a private file and never pastes it into the transcript, a message or a shell history.
  4. Uploads. npx -y @hue-run/sdk@latest traces import upload <directory> --authorization-file <file> --json sends each trace’s values and batches in order, two requests at a time, checks every receipt and completes the import.
  5. Reports. get_trace_import with the import id returns the counts and links in What you get back, and the agent summarizes them for you.

​
Supported formats

A bundle can mix formats, and the prepare report names each file the helper could not read. One import holds up to 25,000 traces, and one trace up to 512 batches, 100,000 spans and 10,000 large values.

​
What you get back

get_trace_import reports the import’s progress and lists its traces. A trace is verified once every declared batch landed with nothing rejected and every declared value is stored. Only then does it add evidence to its owner’s World model; a partial trace adds nothing. Imported traces read like any other: search_traces in the traces’ own time window, get_trace, and verify_trace for a receipt. The report also names the gaps:
  • Traces without a history owner (without_identity). They import and read like any other trace, but no World model retains their evidence: the report counts them as a history gap and as unresolved. See Identity.
  • Unknown origin (unknown_origin). The source did not record whether the trace was production, evaluation or simulation traffic. Hue judges those traces from the records’ own markers: a trace whose records show evaluation or simulation use never adds to a World model, and the rest add evidence like production traffic.
  • Evaluation and simulation traffic. Traces the source recorded as evaluation or simulation traffic are imported but never add to a World model. excluded counts them.
  • Conflicts. A record Hue already holds under the same trace and span id with different content. The stored evidence stays, the batch is reported as conflicted, and resending the same bytes changes nothing.

​
Identity

A user’s World model needs a stable owner per trace. The helper takes it from the source: Sessions group conversations and never stand in for an owner. App accounts bind separately, through the recorded hue.connection.* attributes described in Worlds and traces.

​
Resume an interrupted import

Run the upload command again. The helper resumes from the progress it saved, and Hue acknowledges the batches it already holds. When the authorization has expired, a day after it was issued, ask your agent to call prepare_trace_import again with the same manifest digest and totals: Hue renews the authorization for the same import, and the upload continues. An import stays open for a week after it was prepared, and a renewal within that week extends it.

​
Troubleshooting