Trace ingestion

Sikaru has two ways to get execution evidence. Submitted traces come from an agent you run elsewhere. Managed run trajectories come from runs Sikaru executes. They are separate entry points and separate views.

In short: submit traces from your own agent; managed runs need no upload and appear in their own history.

These examples use the authenticated client and project from the Quickstart.

Trajectory format: Harbor ATIF

Sikaru records every trajectory in the Agent Trajectory Interchange Format (ATIF) from Harbor. An ATIF document is one JSON object holding an agent’s full interaction: user and system messages, agent replies, reasoning, tool calls, tool results, and metrics. One open format means the same trajectory works for inspection, evaluation, and improvement, wherever it came from.

Read the ATIF specification for every field.

Bring traces from LangSmith, Braintrust, Raindrop, and others

Historical traces become trajectories once they are in ATIF. Export them from your current tool, convert each trace to one ATIF document, and submit it.

import json
def to_atif(messages, *, session_id, agent_name, agent_version, model_name=None):
    """Convert OpenAI-style chat messages from an exported trace into an ATIF document."""
    steps = []
    for msg in messages:
        role = msg["role"]
        if role == "tool":
            # A tool result belongs to the agent step that made the call.
            observation = steps[-1].setdefault("observation", {"results": []})
            observation["results"].append(
                {"source_call_id": msg["tool_call_id"], "content": msg.get("content") or ""}
            )
            continue
        step = {
            "step_id": len(steps) + 1,
            "source": {"user": "user", "system": "system"}.get(role, "agent"),
            "message": msg.get("content") or "",
        }
        if role == "assistant":
            if model_name:
                step["model_name"] = model_name
            calls = msg.get("tool_calls") or []
            if calls:
                step["tool_calls"] = [
                    {
                        "tool_call_id": call["id"],
                        "function_name": call["function"]["name"],
                        "arguments": json.loads(call["function"]["arguments"] or "{}"),
                    }
                    for call in calls
                ]
        steps.append(step)
    return {
        "schema_version": "ATIF-v1.7",
        "session_id": session_id,
        "agent": {"name": agent_name, "version": agent_version},
        "steps": steps,
    }

from sikaru_api import TraceMetadata
for trace in exported_traces:
    receipt = client.trace_streams.stream_openinference_spans(
        format="harbor.atif.v1",
        trajectory=to_atif(
            trace["messages"],
            session_id=trace["id"],
            agent_name="support-agent",
            agent_version="2026-10-01",
        ),
        dataset="historical",
        metadata=TraceMetadata(account_id="customer-42", project_id=project, source="langsmith-export"),
        idempotency_key=f"historical-{trace['id']}",
    )

Submit traces

The generated trace method accepts declared wire formats directly. It does not provide a local Experience builder, vendor converter, trajectory class, or agent facade. Normalize source data in your application before you send it. Server-side normalization stays part of the private service.

import json
from pathlib import Path
from sikaru_api import TraceMetadata
trajectory = json.loads(Path("trajectory.json").read_text())
receipt = client.trace_streams.stream_openinference_spans(
    format="harbor.atif.v1", trajectory=trajectory, dataset="baseline",
    metadata=TraceMetadata(account_id="customer-42", project_id=project, source="my-agent"),
    idempotency_key="baseline-trace-001",
)

Reuse trace idempotency keys only for identical batches.

Read a managed run’s trajectory

Use a project API key with runs:read to read retained execution structure and measured token usage:

evidence = client.runs.get_trajectory(project, run_id)
trajectory = evidence["trajectory"]

The response includes runId, harnessVersionId, status, and an ATIF 1.8 trajectory.

• Private messages, reasoning, tool payloads, and provider metadata are omitted and marked in trajectory.extra.
• Embedded subagent trajectories keep their own token totals. Root totals exclude those children.
• Missing metrics mean unknown usage, not zero.
• This export does not include model pricing.

The endpoint reads a committed snapshot. Active or interrupted runs may have partial evidence.

The Python method requires a client generated from the updated API contract and a service that supports this endpoint.

Find runs in the platform

Open your project and go to Conversations. Managed runs appear in their own history. Open a run to inspect its retained trajectory and measured usage. Use Show older managed runs to continue through earlier runs. Agent pages also scope managed history to that agent.

Managed history and submitted traces are separate views:

• A managed run does not need to be uploaded again to appear in managed history.
• Submitted-trace counts can be zero while managed runs exist.
• Do not add their totals together as a unique-run count.

Next steps